<html><head><title>libirman 0.4.5 reference</title></head><body><pre>

Programmers' Reference to libirman v0.4.5
by Tom Wheeley <tomw@tsys.demon.co.uk> 

(for more information, read irman.h)

Overview

libirman is a general purpose library for programs to use in order to
receive infra red signals via irman compatible hardware.  It is designed
to be portable across Unices but is so far only known to work under Linux.


Architecture

 . layers

libirman is split into 3 layers: io, function and command.  User programs
can access functions in any of these 3 layers.

 . data structures

Data from the irman is read by the io layer and assembled into `codes' by
the function layer.  The function layer also contains routines to convert
`codes' to and from `text'.  `text' is a 12 character string representing
the 6 byte code in hexadecimal.

The command layer then contains functions which can bind meaningful `names'
to `text' entries, with functions to convert to and from.  It also allows
aliases to be made linking `names' to `names'.  Binding and Aliasing of
codes is specified in an rc file, typically `/usr/local/etc/irman.conf'

The command layer then lets you register integer values, `commands', with
`names'.



Function Layer

The function layer (middle) is the simplest to explain and understand and
so is presented first.

  int ir_init(char *filename);

    This function opens the serial port and sets up communication between
    the computer and the irman hardware.  `filename' is the name of the
    device file to which the Irman is connected (eg "/dev/ttyS1")

    Returns the port's file descriptor on success, and -1 on error.
    Earlier versions of libirman returned 0 on success, so if you are not
    planning to use the FD then check for >= 0 for maximum compatibility.

  
  unsigned char *ir_get_code(void);
  unsigned char *ir_poll_code(void);

    These two functions return a pointer to an array of IR_CODE_LEN (ie 6)
    bytes long filled with the ir code on success or NULL on failure (with
    errno set).
    
    They return a pointer to static data, so you should not attempt to
    free() it.  You should also note that it will be overwritten next time
    you call *either* of these functions.  
    
    You can not print this data directly as it is raw binary data, not text.
    
    ir_get_code() blocks until the next ir code is received
    ir_poll_code() returns immediately. (returning NULL if no data avilable) 
    
    New for v0.4.2:
    Especially with the later generation Irman hardware, many remotes
    generate two identical codes for each keypress.  To cope with this, if
    libirman receives two identical codes within a certain timescale, then
    it will return NULL on the second code, and set errno to IR_EDUPCODE.

    This means you *cannot* just bail out if ir_X_code() returns NULL.
    In the event of this occurrence, you may still use the old pointer
    received from the last calling of ir_X_code(), which will obviously
    still refer to the code received. 


  char *ir_code_to_text(unsigned char *code);
  unsigned char *ir_text_to_code(char *text);

    These two functions convert `codes' to `text' and vice versa.  A `text'
    item is simply a `code' item but written in hexadecimal.
    
    These functions return pointers to static data, so standard caveats
    apply.

  
  int ir_valid_code(char *text);
  
    Perhaps slightly misnamed, this function reports whether `text' is a
    valid text representation of a code.  Returns 1 for yes, 0 for no.


  int ir_finish(void);

    Call this to close the port and perform any other tidying up.



Command layer

The command layer serves to abstract user programs away from the actual
codes sent by the remote controls.  It lets programs use different remotes
without either maintaining their own config file or needing recompiling.

It achieves this in two ways:
 
 a) By implementing its own config file which binds IR codes to meaningful
    names.

 b) By providing a command level abstraction which lets programs register
    names with action codes.
    
    
 . name support
 
  int ir_init_commands(char *rcname, int warn);

    Initialises memory and reads in the config file.  The config file is
    searched for in the following order, and *only* the first match is read.
    
      `rcname'		(call this with NULL if none specified)
      ${HOME}/.irmanrc
      /etc/irman.conf
      
    Call with `warn' set to 1 if you want errors and warnings printed on
    stderr if there are mistakes in the irman config file. 
    
    
  char *ir_default_portname(void);

    This returns the value set in the config file for the default location
    of the irman device, or NULL if none is set.
    
    This value is set in the config file using the `port' directive.
    
    
  int ir_bind(char *name, char *text);

    This function binds a name to the text representation of a code.
    
    It returns 0 on success or -1 on error.  errno is set to EEXIST if
    either `name' or `text' is already bound to somethign else.
    
    
  int ir_alias(char *newname, char *name);
  
    This function links one name to another.
    
    errno is set to ENOENT if `name' does not already exist, or EEXIST if
    `newname' does already exist.


  char *ir_text_to_name(char *text);
  char *ir_name_to_text(char *name);

    These two functions convert between text representation of codes and
    names.
    
    Obviously due to aliases more than one name can be linked to the same
    code; ir_text_to_name() returns the name to which it is bound.
    
    If there is no name linked to the text, ir_text_to_name() returns the
    text passed as the parameter.  (command functions which expect a name as
    a parameter also accept text).
    
    ir_name_to_text() returns NULL and sets errno to IR_ENOKEY if `name' does
    not exist.
    

void ir_free_commands(void);


    This function frees the internal data structures used to keep track of
    the names and commands.


 . commands
 
Commands are represented by an integer value which is linked to a name when
registered with libirman.

  int ir_register_command(char *name, int command);

    This function registers the integer value `command' with `name'.  `name'
    can also be a `text' representation of a `code'.
    `command' must be greater than 1.
    
    
  int ir_remove_command(char *name);

    This removes the command `name' from the register.  At the moment it is
    not possible to remove commands by `command'.
    
    
  int ir_get_command(void);
  int ir_poll_command(void);

    These two functions either block or poll for an IR code which is then
    matched to a registered command.
    
    They either return the command number if successful, IR_CMD_UNKNOWN if
    the code does not have a command registered to it, or IR_CMD_ERROR on
    error.
    
    
 . miscellaneous


  unsigned char *ir_ask_for_code(char *name, int display);

    If you want to ask someone to enter an IR code using their remote, then
    this is the lazy way to do so.  For quick hacks only.

  char *ir_strerror(int eno);

    The preferred alternative to strerror.  This will also return error
    strings for the internal errors:
     
      IR_EENABLED	"Irman already initialised"
      IR_EDISABLED	"Irman not yet initialised"
      IR_EHANDSHAKE	"Irman handshake failed"
      IR_EBADCMD	"Invalid command code"
      IR_ENOKEY		"Key not found"
      IR_EDUPKEY	"Key already exists"


IO layer

These functions are not really meant for use by user programs, but are
available for those who wish to use them.  If you open the port manually,
then you will not be able to use the higher level functions to read data
from the port (although technically you can, read irman.h for details)

Most functions return 0 on success or -1 on error and set errno.

  int ir_open_port(char *filename);

    Opens the device `filename' and sets the control lines and terminal
    settings appropriately.  returns the port's file descriptor (use this
    *only* for select(), please) on success, or < 0 on error.
    
  
  
  int ir_close_port(void);
  
    closes the port and restores the old terminal settings.
    
    
  int ir_write_char(unsigned char data);
  
    writes one byte of data to the port.
    
    
  int ir_read_char(long timeout);

    reads a byte of data from the port, with timeout `timeout'.
    
    timeout < 0  -  block indefinitely
    timeout = 0  -  return immediately
    timeout > 0  -  timeout after `timeout' microseconds
                    use the nice macros in irman.h to define sec, msec, usec

    returns -1 and sets errno on timeout or error.


  void ir_clear_buffer(void);

    reads and swallows any data in the buffer.


  void ir_usleep(unsigned long usec);

    same as usleep(), except that I know where it is :)



Interface specification for the Irman
-------------------------------------
(Author: unknown)


Serial settings

The settings of the serial port must be 9600 Baud, no parity, 1 stop
bit and no flow-control.
 
Initialization

The device is powered up by setting RTS and DTR high on the host.
After a few milliseconds the microcontroller is up and running.
During powerup the output pins of the microcontroller are not yet stable.
This gives some garbage on the RXD line of the host.
So clear the input fifo on the host, a few milliseconds after setting
RTS and DTR high. Next the host must send a character 'I' and a
character 'R' with at least a 500 microsecond delay in between. The
microntroller responds with sending the characters 'O' and 'K'. Now
the initialization is done and the microcontroller will start sending
decoded infrared-trains to the host from this point on.


Receiving Remote Keypresses

Once the device is initialized, the microcontroller sends 6 bytes to
the host, every time a decodable infrared pulsetrain comes in from the
infrared receiver. These 6 bytes are pseudorandom, but constant for
every specific key on a remote.
If more information is needed, please let me know.


</pre></body></html>
