Debian Codegraph @

TECHNICAL

raw
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>