Tue, 26 Aug 2008 13:18:18 +0100
added: Vim folding markers to all functions
added: Cached LED write (TODO: add to test app)
added: LPFK keys no longer active by default
TODO: build Doxyfile for Doxygen documentation generation
1 /****************************************************************************
2 * Project: liblpfk
3 * Purpose: Driver library for the IBM 6094-020 Lighted Program Function
4 * Keyboard.
5 * Version: 1.0
6 * Author: Philip Pemberton <philpem@philpem.me.uk>
7 *
8 * The latest version of this library is available from
9 * <http://www.philpem.me.uk/code/liblpfk/>.
10 *
11 * Copyright (c) 2008, Philip Pemberton
12 * All rights reserved.
13 *
14 * Redistribution and use in source and binary forms, with or without
15 * modification, are permitted provided that the following conditions
16 * are met:
17 *
18 * * Redistributions of source code must retain the above copyright
19 * notice, this list of conditions and the following disclaimer.
20 * * Redistributions in binary form must reproduce the above copyright
21 * notice, this list of conditions and the following disclaimer in
22 * the documentation and/or other materials provided with the
23 * distribution.
24 * * Neither the name of the project nor the names of its
25 * contributors may be used to endorse or promote products derived
26 * from this software without specific prior written permission.
27 *
28 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
29 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
30 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
31 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
32 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
33 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
34 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
35 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
36 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
37 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
38 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 ****************************************************************************/
41 /**
42 * @file liblpfk.h
43 * @brief liblpfk library header
44 */
46 #ifndef _liblpfk_h_included
47 #define _liblpfk_h_included
49 #include <termios.h>
51 /**
52 * @brief LPFK context
53 *
54 * Do not change any variables inside this struct, they are for liblpfk's
55 * internal use only.
56 */
57 typedef struct {
58 int fd; ///< serial port file descriptor
59 struct termios oldtio; ///< old termios setup
60 int enabled; ///< LPFK enabled
61 unsigned long led_mask; ///< lit LEDs mask
62 } LPFK_CTX;
64 /**
65 * @brief liblpfk error codes
66 */
67 enum {
68 LPFK_E_OK = 0, ///< No error, success.
69 LPFK_E_PORT_OPEN, ///< Could not open comm port.
70 LPFK_E_NOT_PRESENT, ///< LPFK not present on specified port.
71 LPFK_E_COMMS, ///< Communication error.
72 LPFK_E_PARAM, ///< Invalid function parameter.
73 LPFK_E_NOT_ENABLED ///< Attempt to read key when LPFK disabled
74 };
76 /**
77 * @brief Open a serial port and attempt to connecct to an LPFK on that
78 * port.
79 * @param port Serial port path (e.g. /dev/ttyS0).
80 * @param ctx Pointer to an LPFK_CTX struct where LPFK context will be
81 * stored.
82 * @return LPFK_E_OK on success, LPFK_E_PORT_OPEN if port could not be
83 * opened, LPFK_E_NOT_PRESENT if no LPFK present on specified port.
84 */
85 int lpfk_open(const char *port, LPFK_CTX *ctx);
87 /**
88 * @brief Close the LPFK.
89 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
90 * @return LPFK_E_OK
91 */
92 int lpfk_close(LPFK_CTX *ctx);
94 /**
95 * @brief Enable or disable LPFK input
96 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
97 * @param val true to enable the LPFK's keys, false to disable.
98 * @return LPFK_E_OK on success, LPFK_E_COMMS on comms error.
99 */
100 int lpfk_enable(LPFK_CTX *ctx, int val);
102 /**
103 * @brief Set or clear an LED in the cached LED mask buffer.
104 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
105 * @param num LED/key number, from 0 to 31.
106 * @param state State, true for on, false for off.
107 * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
108 * on comms error.
109 */
110 int lpfk_set_led_cached(LPFK_CTX *ctx, const int num, const int state);
112 /**
113 * @brief Set or clear all the LEDs in the shadow register.
114 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
115 * @param state State, true for on, false for off.
116 * @return LPFK_E_OK on success.
117 */
118 int lpfk_set_leds_cached(LPFK_CTX *ctx, const int state);
120 /**
121 * @brief Set the LPFK's LED state from the cached LED mask.
122 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
123 * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
124 * on comms error.
125 */
126 int lpfk_update_leds(LPFK_CTX *ctx);
128 /**
129 * @brief Set or clear an LED on the LPFK.
130 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
131 * @param num LED/key number, from 0 to 31.
132 * @param state State, true for on, false for off.
133 * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
134 * on comms error.
135 * @note Equivalent to a call to lpfk_set_led_cached() followed by a call
136 * to lpfk_update_leds().
137 */
138 int lpfk_set_led(LPFK_CTX *ctx, const int num, const int state);
140 /**
141 * @brief Set or clear all the LEDs on the LPFK.
142 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
143 * @param state State, true for on, false for off.
144 * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
145 * on comms error.
146 * @note Equivalent to a call to lpfk_set_leds_cached() followed by a call
147 * to lpfk_update_leds().
148 */
149 int lpfk_set_leds(LPFK_CTX *ctx, const int state);
151 /**
152 * @brief Get the status of an LED on the LPFK.
153 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
154 * @param num LED/key number, from 0 to 31.
155 * @return true if LED is on, false otherwise.
156 */
157 int lpfk_get_led(LPFK_CTX *ctx, const int num);
159 /**
160 * @brief Read a key from the LPFK
161 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
162 * @return -1 if no keys in buffer, 0-31 for key 1-32 down.
163 */
164 int lpfk_read(LPFK_CTX *ctx);
166 #endif // _liblpfk_h_included