Tue, 26 Aug 2008 22:00:24 +0100
fix typo in makefile that broke 'make clean'
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_NO_KEYS = -1, ///< No keys in input buffer
70 LPFK_E_PORT_OPEN = -2, ///< Could not open comm port.
71 LPFK_E_NOT_PRESENT = -3, ///< LPFK not present on specified port.
72 LPFK_E_COMMS = -4, ///< Communication error.
73 LPFK_E_PARAM = -5, ///< Invalid function parameter.
74 LPFK_E_NOT_ENABLED = -6 ///< Attempt to read key when LPFK disabled
75 };
77 /**
78 * @brief Open a serial port and attempt to connecct to an LPFK on that
79 * port.
80 * @param port Serial port path (e.g. /dev/ttyS0).
81 * @param ctx Pointer to an LPFK_CTX struct where LPFK context will be
82 * stored.
83 * @return LPFK_E_OK on success, LPFK_E_PORT_OPEN if port could not be
84 * opened, LPFK_E_NOT_PRESENT if no LPFK present on specified port.
85 */
86 int lpfk_open(LPFK_CTX *ctx, const char *port);
88 /**
89 * @brief Close the LPFK.
90 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
91 * @return LPFK_E_OK
92 */
93 int lpfk_close(LPFK_CTX *ctx);
95 /**
96 * @brief Enable or disable LPFK input
97 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
98 * @param val true to enable the LPFK's keys, false to disable.
99 * @return LPFK_E_OK on success, LPFK_E_COMMS on comms error.
100 */
101 int lpfk_enable(LPFK_CTX *ctx, const int val);
103 /**
104 * @brief Set or clear an LED in the cached LED mask buffer.
105 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
106 * @param num LED/key number, from 0 to 31.
107 * @param state State, true for on, false for off.
108 * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
109 * on comms error.
110 */
111 int lpfk_set_led_cached(LPFK_CTX *ctx, const int num, const int state);
113 /**
114 * @brief Set or clear all the LEDs in the shadow register.
115 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
116 * @param state State, true for on, false for off.
117 * @return LPFK_E_OK on success.
118 */
119 int lpfk_set_leds_cached(LPFK_CTX *ctx, const int state);
121 /**
122 * @brief Set the LPFK's LED state from the cached LED mask.
123 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
124 * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
125 * on comms error.
126 */
127 int lpfk_update_leds(LPFK_CTX *ctx);
129 /**
130 * @brief Set or clear an LED on the LPFK.
131 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
132 * @param num LED/key number, from 0 to 31.
133 * @param state State, true for on, false for off.
134 * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
135 * on comms error.
136 * @note Equivalent to a call to lpfk_set_led_cached() followed by a call
137 * to lpfk_update_leds().
138 */
139 int lpfk_set_led(LPFK_CTX *ctx, const int num, const int state);
141 /**
142 * @brief Set or clear all the LEDs on the LPFK.
143 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
144 * @param state State, true for on, false for off.
145 * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
146 * on comms error.
147 * @note Equivalent to a call to lpfk_set_leds_cached() followed by a call
148 * to lpfk_update_leds().
149 */
150 int lpfk_set_leds(LPFK_CTX *ctx, const int state);
152 /**
153 * @brief Get the status of an LED on the LPFK.
154 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
155 * @param num LED/key number, from 0 to 31.
156 * @return true if LED is on, false otherwise.
157 */
158 int lpfk_get_led(LPFK_CTX *ctx, const int num);
160 /**
161 * @brief Read a key from the LPFK
162 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
163 * @return LPFK_E_NO_KEYS if no keys in buffer, 0-31 for key 1-32 down.
164 */
165 int lpfk_read(LPFK_CTX *ctx);
167 #endif // _liblpfk_h_included