Tue, 26 Aug 2008 12:45:33 +0100
initial commit
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 };
75 /**
76 * @brief Open a serial port and attempt to connecct to an LPFK on that
77 * port.
78 * @param port Serial port path (e.g. /dev/ttyS0).
79 * @param ctx Pointer to an LPFK_CTX struct where LPFK context will be
80 * stored.
81 * @return LPFK_E_OK on success, LPFK_E_PORT_OPEN if port could not be
82 * opened, LPFK_E_NOT_PRESENT if no LPFK present on specified port.
83 */
84 int lpfk_open(const char *port, LPFK_CTX *ctx);
86 /**
87 * @brief Close the LPFK.
88 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
89 * @return LPFK_E_OK
90 */
91 int lpfk_close(LPFK_CTX *ctx);
93 /**
94 * @brief Enable or disable LPFK input
95 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
96 * @param val true to enable the LPFK's keys, false to disable.
97 * @return LPFK_E_OK on success, LPFK_E_COMMS on comms error.
98 */
99 int lpfk_enable(LPFK_CTX *ctx, int val);
101 /**
102 * @brief Set or clear an LED on the LPFK.
103 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
104 * @param num LED/key number, from 0 to 31.
105 * @param state State, true for on, false for off.
106 * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
107 * on comms error.
108 */
109 int lpfk_set_led(LPFK_CTX *ctx, const int num, const int state);
111 /**
112 * @brief Set or clear all the LEDs on the LPFK.
113 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
114 * @param state State, true for on, false for off.
115 * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
116 * on comms error.
117 */
118 int lpfk_set_leds(LPFK_CTX *ctx, const int state);
120 /**
121 * @brief Get the status of an LED on the LPFK.
122 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
123 * @param num LED/key number, from 0 to 31.
124 * @return true if LED is on, false otherwise.
125 */
126 int lpfk_get_led(LPFK_CTX *ctx, const int num);
128 /**
129 * @brief Read a key from the LPFK
130 * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open().
131 * @return -1 if no keys in buffer, 0-31 for key 1-32 down.
132 */
133 int lpfk_read(LPFK_CTX *ctx);
135 #endif // _liblpfk_h_included