include/liblpfk.h

Wed, 28 Jul 2010 15:14:54 +0100

author
Philip Pemberton <philpem@philpem.me.uk>
date
Wed, 28 Jul 2010 15:14:54 +0100
changeset 12
f8996e336619
parent 4
81d49d42ad6a
permissions
-rw-r--r--

Fixed omission: lpfkbinclock wasn't compiled by default.

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