| 1 |
<html><head><title>libirman 0.4.5 reference</title></head><body><pre> |
| 2 |
|
| 3 |
Programmers' Reference to libirman v0.4.5 |
| 4 |
by Tom Wheeley <[email protected]> |
| 5 |
|
| 6 |
(for more information, read irman.h) |
| 7 |
|
| 8 |
Overview |
| 9 |
|
| 10 |
libirman is a general purpose library for programs to use in order to |
| 11 |
receive infra red signals via irman compatible hardware. It is designed |
| 12 |
to be portable across Unices but is so far only known to work under Linux. |
| 13 |
|
| 14 |
|
| 15 |
Architecture |
| 16 |
|
| 17 |
. layers |
| 18 |
|
| 19 |
libirman is split into 3 layers: io, function and command. User programs |
| 20 |
can access functions in any of these 3 layers. |
| 21 |
|
| 22 |
. data structures |
| 23 |
|
| 24 |
Data from the irman is read by the io layer and assembled into `codes' by |
| 25 |
the function layer. The function layer also contains routines to convert |
| 26 |
`codes' to and from `text'. `text' is a 12 character string representing |
| 27 |
the 6 byte code in hexadecimal. |
| 28 |
|
| 29 |
The command layer then contains functions which can bind meaningful `names' |
| 30 |
to `text' entries, with functions to convert to and from. It also allows |
| 31 |
aliases to be made linking `names' to `names'. Binding and Aliasing of |
| 32 |
codes is specified in an rc file, typically `/usr/local/etc/irman.conf' |
| 33 |
|
| 34 |
The command layer then lets you register integer values, `commands', with |
| 35 |
`names'. |
| 36 |
|
| 37 |
|
| 38 |
|
| 39 |
Function Layer |
| 40 |
|
| 41 |
The function layer (middle) is the simplest to explain and understand and |
| 42 |
so is presented first. |
| 43 |
|
| 44 |
int ir_init(char *filename); |
| 45 |
|
| 46 |
This function opens the serial port and sets up communication between |
| 47 |
the computer and the irman hardware. `filename' is the name of the |
| 48 |
device file to which the Irman is connected (eg "/dev/ttyS1") |
| 49 |
|
| 50 |
Returns the port's file descriptor on success, and -1 on error. |
| 51 |
Earlier versions of libirman returned 0 on success, so if you are not |
| 52 |
planning to use the FD then check for >= 0 for maximum compatibility. |
| 53 |
|
| 54 |
|
| 55 |
unsigned char *ir_get_code(void); |
| 56 |
unsigned char *ir_poll_code(void); |
| 57 |
|
| 58 |
These two functions return a pointer to an array of IR_CODE_LEN (ie 6) |
| 59 |
bytes long filled with the ir code on success or NULL on failure (with |
| 60 |
errno set). |
| 61 |
|
| 62 |
They return a pointer to static data, so you should not attempt to |
| 63 |
free() it. You should also note that it will be overwritten next time |
| 64 |
you call *either* of these functions. |
| 65 |
|
| 66 |
You can not print this data directly as it is raw binary data, not text. |
| 67 |
|
| 68 |
ir_get_code() blocks until the next ir code is received |
| 69 |
ir_poll_code() returns immediately. (returning NULL if no data avilable) |
| 70 |
|
| 71 |
New for v0.4.2: |
| 72 |
Especially with the later generation Irman hardware, many remotes |
| 73 |
generate two identical codes for each keypress. To cope with this, if |
| 74 |
libirman receives two identical codes within a certain timescale, then |
| 75 |
it will return NULL on the second code, and set errno to IR_EDUPCODE. |
| 76 |
|
| 77 |
This means you *cannot* just bail out if ir_X_code() returns NULL. |
| 78 |
In the event of this occurrence, you may still use the old pointer |
| 79 |
received from the last calling of ir_X_code(), which will obviously |
| 80 |
still refer to the code received. |
| 81 |
|
| 82 |
|
| 83 |
char *ir_code_to_text(unsigned char *code); |
| 84 |
unsigned char *ir_text_to_code(char *text); |
| 85 |
|
| 86 |
These two functions convert `codes' to `text' and vice versa. A `text' |
| 87 |
item is simply a `code' item but written in hexadecimal. |
| 88 |
|
| 89 |
These functions return pointers to static data, so standard caveats |
| 90 |
apply. |
| 91 |
|
| 92 |
|
| 93 |
int ir_valid_code(char *text); |
| 94 |
|
| 95 |
Perhaps slightly misnamed, this function reports whether `text' is a |
| 96 |
valid text representation of a code. Returns 1 for yes, 0 for no. |
| 97 |
|
| 98 |
|
| 99 |
int ir_finish(void); |
| 100 |
|
| 101 |
Call this to close the port and perform any other tidying up. |
| 102 |
|
| 103 |
|
| 104 |
|
| 105 |
Command layer |
| 106 |
|
| 107 |
The command layer serves to abstract user programs away from the actual |
| 108 |
codes sent by the remote controls. It lets programs use different remotes |
| 109 |
without either maintaining their own config file or needing recompiling. |
| 110 |
|
| 111 |
It achieves this in two ways: |
| 112 |
|
| 113 |
a) By implementing its own config file which binds IR codes to meaningful |
| 114 |
names. |
| 115 |
|
| 116 |
b) By providing a command level abstraction which lets programs register |
| 117 |
names with action codes. |
| 118 |
|
| 119 |
|
| 120 |
. name support |
| 121 |
|
| 122 |
int ir_init_commands(char *rcname, int warn); |
| 123 |
|
| 124 |
Initialises memory and reads in the config file. The config file is |
| 125 |
searched for in the following order, and *only* the first match is read. |
| 126 |
|
| 127 |
`rcname' (call this with NULL if none specified) |
| 128 |
${HOME}/.irmanrc |
| 129 |
/etc/irman.conf |
| 130 |
|
| 131 |
Call with `warn' set to 1 if you want errors and warnings printed on |
| 132 |
stderr if there are mistakes in the irman config file. |
| 133 |
|
| 134 |
|
| 135 |
char *ir_default_portname(void); |
| 136 |
|
| 137 |
This returns the value set in the config file for the default location |
| 138 |
of the irman device, or NULL if none is set. |
| 139 |
|
| 140 |
This value is set in the config file using the `port' directive. |
| 141 |
|
| 142 |
|
| 143 |
int ir_bind(char *name, char *text); |
| 144 |
|
| 145 |
This function binds a name to the text representation of a code. |
| 146 |
|
| 147 |
It returns 0 on success or -1 on error. errno is set to EEXIST if |
| 148 |
either `name' or `text' is already bound to somethign else. |
| 149 |
|
| 150 |
|
| 151 |
int ir_alias(char *newname, char *name); |
| 152 |
|
| 153 |
This function links one name to another. |
| 154 |
|
| 155 |
errno is set to ENOENT if `name' does not already exist, or EEXIST if |
| 156 |
`newname' does already exist. |
| 157 |
|
| 158 |
|
| 159 |
char *ir_text_to_name(char *text); |
| 160 |
char *ir_name_to_text(char *name); |
| 161 |
|
| 162 |
These two functions convert between text representation of codes and |
| 163 |
names. |
| 164 |
|
| 165 |
Obviously due to aliases more than one name can be linked to the same |
| 166 |
code; ir_text_to_name() returns the name to which it is bound. |
| 167 |
|
| 168 |
If there is no name linked to the text, ir_text_to_name() returns the |
| 169 |
text passed as the parameter. (command functions which expect a name as |
| 170 |
a parameter also accept text). |
| 171 |
|
| 172 |
ir_name_to_text() returns NULL and sets errno to IR_ENOKEY if `name' does |
| 173 |
not exist. |
| 174 |
|
| 175 |
|
| 176 |
void ir_free_commands(void); |
| 177 |
|
| 178 |
|
| 179 |
This function frees the internal data structures used to keep track of |
| 180 |
the names and commands. |
| 181 |
|
| 182 |
|
| 183 |
. commands |
| 184 |
|
| 185 |
Commands are represented by an integer value which is linked to a name when |
| 186 |
registered with libirman. |
| 187 |
|
| 188 |
int ir_register_command(char *name, int command); |
| 189 |
|
| 190 |
This function registers the integer value `command' with `name'. `name' |
| 191 |
can also be a `text' representation of a `code'. |
| 192 |
`command' must be greater than 1. |
| 193 |
|
| 194 |
|
| 195 |
int ir_remove_command(char *name); |
| 196 |
|
| 197 |
This removes the command `name' from the register. At the moment it is |
| 198 |
not possible to remove commands by `command'. |
| 199 |
|
| 200 |
|
| 201 |
int ir_get_command(void); |
| 202 |
int ir_poll_command(void); |
| 203 |
|
| 204 |
These two functions either block or poll for an IR code which is then |
| 205 |
matched to a registered command. |
| 206 |
|
| 207 |
They either return the command number if successful, IR_CMD_UNKNOWN if |
| 208 |
the code does not have a command registered to it, or IR_CMD_ERROR on |
| 209 |
error. |
| 210 |
|
| 211 |
|
| 212 |
. miscellaneous |
| 213 |
|
| 214 |
|
| 215 |
unsigned char *ir_ask_for_code(char *name, int display); |
| 216 |
|
| 217 |
If you want to ask someone to enter an IR code using their remote, then |
| 218 |
this is the lazy way to do so. For quick hacks only. |
| 219 |
|
| 220 |
char *ir_strerror(int eno); |
| 221 |
|
| 222 |
The preferred alternative to strerror. This will also return error |
| 223 |
strings for the internal errors: |
| 224 |
|
| 225 |
IR_EENABLED "Irman already initialised" |
| 226 |
IR_EDISABLED "Irman not yet initialised" |
| 227 |
IR_EHANDSHAKE "Irman handshake failed" |
| 228 |
IR_EBADCMD "Invalid command code" |
| 229 |
IR_ENOKEY "Key not found" |
| 230 |
IR_EDUPKEY "Key already exists" |
| 231 |
|
| 232 |
|
| 233 |
IO layer |
| 234 |
|
| 235 |
These functions are not really meant for use by user programs, but are |
| 236 |
available for those who wish to use them. If you open the port manually, |
| 237 |
then you will not be able to use the higher level functions to read data |
| 238 |
from the port (although technically you can, read irman.h for details) |
| 239 |
|
| 240 |
Most functions return 0 on success or -1 on error and set errno. |
| 241 |
|
| 242 |
int ir_open_port(char *filename); |
| 243 |
|
| 244 |
Opens the device `filename' and sets the control lines and terminal |
| 245 |
settings appropriately. returns the port's file descriptor (use this |
| 246 |
*only* for select(), please) on success, or < 0 on error. |
| 247 |
|
| 248 |
|
| 249 |
|
| 250 |
int ir_close_port(void); |
| 251 |
|
| 252 |
closes the port and restores the old terminal settings. |
| 253 |
|
| 254 |
|
| 255 |
int ir_write_char(unsigned char data); |
| 256 |
|
| 257 |
writes one byte of data to the port. |
| 258 |
|
| 259 |
|
| 260 |
int ir_read_char(long timeout); |
| 261 |
|
| 262 |
reads a byte of data from the port, with timeout `timeout'. |
| 263 |
|
| 264 |
timeout < 0 - block indefinitely |
| 265 |
timeout = 0 - return immediately |
| 266 |
timeout > 0 - timeout after `timeout' microseconds |
| 267 |
use the nice macros in irman.h to define sec, msec, usec |
| 268 |
|
| 269 |
returns -1 and sets errno on timeout or error. |
| 270 |
|
| 271 |
|
| 272 |
void ir_clear_buffer(void); |
| 273 |
|
| 274 |
reads and swallows any data in the buffer. |
| 275 |
|
| 276 |
|
| 277 |
void ir_usleep(unsigned long usec); |
| 278 |
|
| 279 |
same as usleep(), except that I know where it is :) |
| 280 |
|
| 281 |
|
| 282 |
|
| 283 |
Interface specification for the Irman |
| 284 |
------------------------------------- |
| 285 |
(Author: unknown) |
| 286 |
|
| 287 |
|
| 288 |
Serial settings |
| 289 |
|
| 290 |
The settings of the serial port must be 9600 Baud, no parity, 1 stop |
| 291 |
bit and no flow-control. |
| 292 |
|
| 293 |
Initialization |
| 294 |
|
| 295 |
The device is powered up by setting RTS and DTR high on the host. |
| 296 |
After a few milliseconds the microcontroller is up and running. |
| 297 |
During powerup the output pins of the microcontroller are not yet stable. |
| 298 |
This gives some garbage on the RXD line of the host. |
| 299 |
So clear the input fifo on the host, a few milliseconds after setting |
| 300 |
RTS and DTR high. Next the host must send a character 'I' and a |
| 301 |
character 'R' with at least a 500 microsecond delay in between. The |
| 302 |
microntroller responds with sending the characters 'O' and 'K'. Now |
| 303 |
the initialization is done and the microcontroller will start sending |
| 304 |
decoded infrared-trains to the host from this point on. |
| 305 |
|
| 306 |
|
| 307 |
Receiving Remote Keypresses |
| 308 |
|
| 309 |
Once the device is initialized, the microcontroller sends 6 bytes to |
| 310 |
the host, every time a decodable infrared pulsetrain comes in from the |
| 311 |
infrared receiver. These 6 bytes are pseudorandom, but constant for |
| 312 |
every specific key on a remote. |
| 313 |
If more information is needed, please let me know. |
| 314 |
|
| 315 |
|
| 316 |
</pre></body></html> |