Todays date: 29-Jul-2004
This is RoBiOS version 6.1

# Library of functions build into RoBiOS

The following describes the RoBIOS operating system library routines.
Newer versions of the RoBIOS software may differ from the functionality described below see the latest software documentation. See also timing information on RoBIOS routines.

#### In application files use:

    #include "eyebot.h"

The following libraries are available in ROM for programming in C and are automatically linked when calling "gcc68" and the like (using librobi.a).
Note that there are also a number of libraries available which are not listed here, since they are not in ROM but in the EyeBot distribution (e.g. elaborate image processing library). They can also be linked with an application program, as shown in the demo programs provided.

- Image Processing
- Key Input
- LCD Output
- Camera
- System Functions
- Multitasking
- Semaphores
- Timer
- Download and RS-232
- Audio
- PSD Sensors
- Servos and Motors
- V-Omega Driving Interface
- Bumper / Infrered Sensors
- Latches
- Parallel Port
- A/D Converter
- Radio Communication
- Compass
- TV Remote Control

### Return Codes

Unless specifically noted otherwise, all routines return 0 when successfull, or a value !=0 when an error has occurred. Only very few routines support multiple return codes.

### Image Processing

Basic image processing functions (library robios):

    Data Types:
            /* image is 80x60 but has a border of 1 pixel */
            #define imagecolumns 82
            #define imagerows 62

            typedef BYTE image[imagerows][imagecolumns];
            typedef BYTE colimage[imagerows][imagecoulmns][3];

    int IPLaplace (image *src, image *dest);
            Input:          (src) source b/w image
            Output:         (dest) destination b/w image
            Semantics:      The Laplace operator is applied to the source image
                            and the result is written to the destination image

    int IPSobel (image *src, image *dest);
            Input:          (src) source b/w image
            Output:         (dest) destination b/w image
            Semantics:      The Sobel operator is applied to the source image
                            and the result is written to the destination image

    int IPDither (image *src, image *dest);
            Input:          (src) source b/w image
            Output:         (dest) destination b/w image
            Semantics:      The Dithering operator with a 2x2 pattern is applied
                            to the source image and the result is written to the
                            destination image

    int IPDiffer (image *current, image *last, image *dest);
            Input:          (current) the current b/w image
                            (last) the last read b/w image
            Output:         (dest) destination b/w image
            Semantics:      Calculate the grey level difference at each pixel
                            position between current and last image, and
                            store the result in destination.

    int IPColor2Grey (colimage *src, image *dest);
            Input:          (src) source color image
            Output:         (dest) destination b/w image
            Semantics:      Convert RGB color image given as source to 8-bit
                            grey level image and store the result in
                            destination.

Advanced image processing functions are available as library improc. For detailed info see Improv web-page.

### Key Input

Using the standard Unix "libc" library, it is possible to use standard C "scanf" commands to read key "characters" from the "keyboard".

    int KEYGetBuf (char *buf);
            Input:          (buf) a pointer to one character
            Output:         (buf) the keycode is written into the buffer
                            Valid keycodes are: KEY1,KEY2,KEY3,KEY4 (keys
                            from left to right)
            Semantics:      Wait for a keypress and store the keycode into the
                            buffer

    int KEYGet (void);
            Input:          NONE
            Output:         (return code) the keycode of a pressed key is returned
                            Valid keycodes are: KEY1,KEY2,KEY3,KEY4 (keys
                            from left to right)
            Semantics:      Wait for a keypress and return keycode

    int KEYRead (void);
            Input:          NONE
            Output:         (return code) the keycode of a pressed key is
                            returned or 0 if no key is pressed.
                            Valid keycodes are: KEY1,KEY2,KEY3,KEY4 (keys
                            from left to right) or 0 for no key.
            Semantics:      Read keycode and return it. Function does not wait.

    int KEYWait (int excode);
            Input:          (excode) the code of the key expected to be pressed
                            Valid keycodes are: KEY1,KEY2,KEY3,KEY4 (keys
                            from left to right) or ANYKEY.
            Output:         NONE
            Semantics:      Wait for a specific key

### LCD Output

Using the standard Unix "libc" library, it is possible to use standard C "printf" commands to print on the LCD "screen". E.g. the "hello world" program works:

    printf("Hello, World!\n");

The following routines can be used for specific output functions:

    int LCDPrintf(const char format[], ...);
            Input:          format string and parameters
            Output:         NONE
            Semantics:      Prints text or numbers or combination of both
                            onto LCD. This is a simplified and smaller
                            version of standard Clib "printf".

    int LCDSetPrintf(int row, int column, const char format[], ...);
            Input:          print position and format string with parameters
            Output:         NONE
            Semantics:      Prints text or numbers or combination of both
                            onto LCD at specified location.
                            Identical to calling LCDSetPos followed by LCDPrintf.

    int LCDClear(void);
            Input:          NONE
            Output:         NONE
            Semantics:      Clear the LCD

    int LCDPutChar (char char);
            Input:          (char) the character to be written
            Output:         NONE
            Semantics:      Write the given character to the current cursor
                            position and increment cursor position

    int LCDSetChar (int row,int column,char char);
            Input:          (char) the character to be written
                            (column) the number of the column
                            Valid values are: 0-15
                            (row) the number of the row
                            Valid values are: 0-6
            Output:         NONE
            Semantics:      Write the given character to the given display position

    int LCDPutString (char *string);
            Input:          (string) the string to be written
            Output:         NONE
            Semantics:      Write the given string to the current cursor position
                            and increment cursor position

    int LCDSetString (int row,int column,char *string);
            Input:          (string) the string to be written
                            (column) the number of the column
                            Valid values are: 0-15
                            (row) the number of the row
                            Valid values are: 0-6
            Output:         NONE
            Semantics:      Write the given string to the given display position

    int LCDPutHex (int val);
            Input:          (val) the number to be written
            Output:         NONE
            Semantics:      Write the given number in hex format at current
                            cursor position

    int LCDPutHex1 (int val);
            Input:          (val) the number to be written (single byte 0..255)
            Output:         NONE
            Semantics:      Write the given number as 1 hex-byte at current
                            cursor position

    int LCDPutInt (int val);
            Input:          (val) the number to be written
            Output:         NONE
            Semantics:      Write the given number as decimal at current cursor
                            position

    int LCDPutIntS (int val, int spaces);
            Input:          (val)    the number to be written
                            (spaces) the minimal number of print spaces
            Output:         NONE
            Semantics:      Write the given number as decimal at current cursor
                            position using extra spaces in front if necessary

    int LCDPutFloat (float val);
            Input:          (val) the number to be written
            Output:         NONE
            Semantics:      Write the given number as floating point number
                            at current cursor position

    int LCDPutFloatS (float val, int spaces, int decimals);
            Input:          (val)      the number to be written
                            (spaces)   the minimal number of print spaces
                            (decimals) the number of decimals after the point
            Output:         NONE
            Semantics:      Write the given number as a floating point number
                            at current cursor position using extra spaces in
                            front if necessary and with specified number of
                            decimals

    int LCDMode (int mode);
            Input:          (mode) the display mode you want
                            Valid values are: (NON)SCROLLING|(NO)CURSOR
            Output:         NONE
            Semantics:      Set the display to the given mode
                            SCROLLING: the display will scroll up one
                                    line, when the right bottom corner is
                                    reached and the new cursor position
                                    will be the first column of the now
                                    blank bottom line
                            NONSCROLLING: display output will resume in
                                    the top left corner when the bottom
                                    right corner is reached
                            NOCURSOR: the blinking hardware cursor is not
                                    displayed at the current cursor position
                            CURSOR: the blinking hardware cursor is
                                    displayed at the current cursor
                                    position

    int LCDSetPos (int row, int column);
            Input:          (column) the number of the column
                            Valid values are: 0-15
                            (row) the number of the row
                            Valid values are: 0-6
            Output:         NONE
            Semantics:      Set the cursor to the given position

    int LCDGetPos (int *row, int *column);
            Input:          (column) pointer to the storing place for current
                            column.
                            (row) pointer to the storing place for current row.
            Output:         (*column) current column
                            Valid values are: 0-15
                            (row) current row
                            Valid values are: 0-6
            Semantics:      Return the current cursor position

    int LCDPutGraphic (image *buf);
            Input:          (buf) pointer to a greyscale image (80*60 pixel)
            Output:         NONE
            Semantics:      Write the given graphic b/w to the display
                            it will be written starting in the top left corner
                            down to the menu line.  Only 80x54 pixels will
                            be written to the LCD, to avoid destroying the
                            menu line.

    int LCDPutColorGraphic (colimage *buf);
            Input:          (buf) pointer to a color image (80*60 pixel)
            Output:         NONE
            Semantics:      Write the given graphic b/w to the display
                            it will be written starting in the top left corner
                            down to the menu line.  Only 80x54 pixels will
                            be written to the LCD, to avoid destroying the
                            menu line.  Note: The current implementation
                            destroys the image content.

    int LCDPutImage (BYTE *buf);
            Input:          (buf) pointer to a b/w image (128*64 pixel)
            Output:         NONE
            Semantics:      Write the given graphic b/w to the whole display.

    int LCDMenu (char *string1, char *string2, char *string3,char *string4);
            Input:          (string1) menu entry above key1
                            (string2) menu entry above key2
                            (string3) menu entry above key3
                            (string4) menu entry above key4
                            Valid Values are:
                              - a string with max 4 characters, which
                                clears the menu entry and writes the new one
                              - "" : leave the menu entry untouched
                              - " " : clear the menu entry
            Output:         NONE
            Semantics:      Fill the menu line with the given menu entries

    int LCDMenuI (int pos, char *string);
            Input:          (pos) number of menu entry to be exchanged (1..4)
                            (string) menu entry above key <pos> a string
                            with max 4 characters
            Output:         NONE
            Semantics:      Overwrite the menu line entry at position pos with
                            the given string

    int LCDSetPixel (int row, int col, int val);
            Input:          (val) pixel operation code
                            Valid codes are:  0 = clear pixel
                                              1 = set pixel
                                              2 = invert pixel
                            (column) the number of the column
                            Valid values are: 0-127
                            (row) the number of the row
                            Valid values are: 0-63
            Output:         NONE
            Semantics:      Apply the given operation to the given pixel
                            position.  LCDSetPixel(row, col, 2) is the same
                            as LCDInvertPixel(row, col).

    int LCDInvertPixel (int row, int col);
            Input:          (column) the number of the column
                            Valid values are: 0-127
                            (row) the number of the row
                            Valid values are: 0-63
            Output:         NONE
            Semantics:      Invert the pixel at the given pixel position.
                            LCDInvertPixel(row, col) is the same as
                            LCDSetPixel(row, col, 2).

    int LCDGetPixel (int row, int col);
            Input:          (column) the number of the column
                            Valid values are: 0-127
                            (row) the number of the row
                            Valid values are: 0-63
            Output:         (return code) the value of the pixel
                            Valid values are:       1 for set pixel
                                                    0 for clear pixel
            Semantics:      Return the value of the pixel at the given
                            position

    int LCDLine(int x1, int y1, int x2, int y2, int col)
            Input:          (x1,y1) (x2,y2) and color
            Output:         NONE
            Semantics:      Draw a line from (x1,y1) to (x2,y2) using the Bresenham Algorithm
                            top    left  is   0, 0
                            bottom right is 127,63
                            color: 0 white
                                   1 black
                                   2 negate image contents

    int LCDArea(int x1, int y1, int x2, int y2, int col)
            Input:          (x1,y1) (x2,y2) and color
            Output:         NONE
            Semantics:      Fill rectangular area from (x1,y1) to (x2,y2)
                            it must hold: x1 < x2 AND y1 < y2
                            top    left  is   0, 0
                            bottom right is 127,63
                            color: 0 white
                                   1 black
                                   2 negate image contents

### Camera

The following functions handle initializing and image reading from either grayscale or color camera:

    int CAMInit (int mode);
            Input:          (mode) camera initialization mode
                            Valid Values are: NORMAL
            Output:         (return code) Cameraversion or Errorcode
                            Valid values: 255     = no camera connected
                                          200..254= camera init error (200 + cam. code)
                                          0       = QuickCam V1 grayscale
                                          16      = QuickCam V2 color
                                          17      = EyeCam-1 (6300)
                                          18      = EyeCam-2 (7620)
                                          19      = EyeCam-3 (6620)
            Semantics:      Reset and initialize connected camera
            Note:           [Previously used to set zoom factor on Quickcam: WIDE,NORMAL,TELE]

    int CAMRelease (void);
            Input:          NONE
            Output:         (return code) 0 = success
                                         -1 = error
            Semantics:      Release all resources allocated using CAMInit().

    int CAMGetFrame (image *buf);
            Input:          (buf) a pointer to a grey scale image
            Output:         NONE
            Semantics:      Read an image size 62x82 from grey scale camera.
                            Return 8 bit gray values 0 (black) .. 255 (white)

    int CAMGetColFrame (colimage *buf, int convert);
            Input:          (buf) a pointer to a color image
                            (convert) flag if image should be reduced to 8 bit gray
                                      0 = get 24bit color image
                                      1 = get 8bit grayscale image
            Output:         NONE
            Semantics:      Read an image size 82x62 from color cam and reduce it
                            if required to 8 bit gray scale.
            Note:           - buf needs to be a pointer to 'image'
                            - enable conversion like this:
                                    image buffer;
                                    CAMGetColFrame((colimage*)&buffer, 1);

    int CAMGetFrameMono (BYTE *buf);
            Note:           This function works only for EyeCam
            Input:          (buf) pointer to image buffer of full size (use CAMGet)
            Output:         (return code) 0 = success
                                         -1 = error (camera not initialized)
            Semantics:      Reads one full gray scale image (e.g. 82x62, 176x144, 320x240)
                            depending on camera module

    int CAMGetFrameRGB (BYTE *buf);
            Note:           This function works only for EyeCam
            Input:          (buf) pointer to image buffer of full size (use CAMGet)
            Output:         (return code) 0 = success
                                         -1 = error (camera not initialized)
            Semantics:      Reads one full color image in RBG format, 3 bytes per pixel,
                            (e.g. 82x62*3, 176x144*3, 320x240*3) depending on camera module

    int CAMGetFrameBayer (BYTE *buf);
            Note:           This function works only for EyeCam
            Input:          (buf) pointer to image buffer of full size (use CAMGet)
            Output:         (return code) 0 = success
                                         -1 = error (camera not initialized)
            Semantics:      Reads one full color image in Bayer format, 4 bytes per pixel,
                            (e.g. 82x62*4, 88x72*4, 160x120*4) depending on camera module

    int CAMSet (int para1, int para2, int para3);
            Note:           parameters have different meanings for different cameras
            Input:QuickCam  (para1) camera brightness
                            (para2) camera offset (b/w camera) / hue (color camera)
                            (para3) contrast (b/w camera) / saturation (color camera)
                            Valid values are: 0-255
                  ---------------------------------------------------
                  EyeCam    (para1) frame rate in frames per second
                            (para2) not used
                            (para3) not used
                            Valid values are: FPS60, FPS30, FPS15,
                             FPS7_5, FPS3_75, FPS1_875, FPS0_9375, and FPS0_46875.
                             For the VV6300/VV6301, the default is FPS7_5.
                             For the OV6620, the default is FPS1_875.
                             For the OV7620, the default is FPS0_48375.
            Output:         NONE
            Semantics:      Set camera parameters

    int CAMGet (int *para1, int *para2 ,int *para3);
            Note:           parameters have different meanings for different cameras
            Input:QuickCam  (para1) pointer for camera brightness
                            (para2) pointer for offset (b/w camera) / hue (color camera)
                            (para3) pointer for contrast (b/w camera) / saturation (color cam)
                            Valid values are: 0-255
                  ---------------------------------------------------
                  EyeCam    (para1) frame rate in frames per second
                            (para2) full image width
                            (para3) full image height
            Output:         NONE
            Semantics:      Get camera hardware parameters

    int CAMMode (int mode);
            Input:          (mode) the camera mode you want
                            Valid values are: (NO)AUTOBRIGHTNESS
            Output:         NONE
            Semantics:      Set the display to the given mode
                            AUTOBRIGHTNESS: the brightness value of the
                              camera is automatically adjusted
                            NOAUTOBRIGHTNESS: the brightness value is not
                              automatically adjusted
                            This function is not implemented in the
                            FIFO-enabled EyeCam driver.

### System Functions

    miscellaneous:
    --------------
    char *OSVersion(void);
            Input:          NONE
            Output:         OS version
            Semantics:      Returns string containing running RoBIOS version.
            Example:        "3.1b"

    int OSError(char *msg,int number,BOOL dead);
            Input:          (msg) pointer to message
                            (number) int number
                            (dead) switch to choose deadend or keywait
                            Valid values are:       0 = no deadend
                                                    1 = deadend
            Output:         NONE
            Semantics:      Print message and number to display then
                            stop processor (deadend) or wait for key

    int OSMachineType(void);
            Input:          NONE
            Output:         Type of used hardware
                Valid values are:
                VEHICLE, PLATFORM, WALKER
            Semantics:      Inform the user in which environment the program runs.

    int OSMachineSpeed(void);
            Input:          NONE
            Output:         actual clockrate of CPU in Hz
            Semantics:      Inform the user how fast the processor runs.

    char* OSMachineName(void);
            Input:          NONE
            Output:         Name of actual Eyebot
            Semantics:      Inform the user with which name the Eyebot is
                            titled (entered in HDT).

    unsigned char OSMachineID(void);
            Input:          NONE
            Output:         ID of actual Eyebot
            Semantics:      Inform the user with which ID the Eyebot is titled
                            (entered in HDT).

    interrupts:
    -----------
    int OSEnable (void);
            Input:          NONE
            Output:         NONE
            Semantics:      Enable all cpu-interrupts

    int OSDisable (void);
            Input:          NONE
            Output:         NONE
            Semantics:      Disable all cpu-interrupts

    variable save to tpuram:
    ------------------------
    int OSGetVar(int num);
    *)
            Input:          (num) number of tpupram save location
                            Valid values are:       SAVEVAR1-4 for word saving
                                                    SAVEVAR1a-4a/1b-4b for byte saving

            Output:         (return code) the value saved
                            Valid values are:       0-65535 for word saving
                                                    0-255 for byte saving
            Semantics:      Get the value from the given save location

    int OSPutVar(int num, int value);
    *)
            Input:          (num) number of tpupram save location
                            Valid values are:       SAVEVAR1-4 for word saving
                                                    SAVEVAR1a-4a/1b-4b for byte saving
                            (value) value to be stored
                            Valid values are:       0-65535 for word saving
                                                    0-255 for byte saving

            Output:         NONE
            Semantics:      Save the value to the given save location

    *) SAVEVAR1-3 already occupied by RoBiOS

### Multitasking

    int OSMTInit(BYTE mode);
            Input:          (mode) operation mode
                            Valid values are: COOP=DEFAULT,PREEMPT
            Output:         NONE
            Semantics:      Initialize multithreading environment

    struct tcb *OSSpawn (char *name, void (*code)(void), int stksiz, int pri, int uid)
            Input:          (name) pointer to thread name
                            (code) thread start address
                            (stksize) size of thread stack
                            (pri) thread priority
                            Valid values are: MINPRI-MAXPRI
                            (uid) thread user id
            Output:         (return code) pointer to initialized thread
                            control block
            Semantics:      Initialize new thread, tcb is initialized and
                            inserted in scheduler queue but not set to
                            READY

    int OSMTStatus(void);
            Input:          NONE
            Output:         PREEMPT, COOP, NOTASK
            Semantics:      returns actual multitasking mode (preemptive,
                            cooperative or sequential)

    int OSReady(struct tcb *thread);
            Input:          (thread) pointer to thread control block
            Output:         NONE
            Semantics:      Set status of given thread to READY

    int OSSuspend(struct tcb *thread);
            Input:          (thread) pointer to thread control block
            Output:         NONE
            Semantics:      Set status of given thread to SUSPEND

    int OSReschedule(void);
            Input:          NONE
            Output:         NONE
            Semantics:      Choose new current thread

    int OSYield(void);
            Input:          NONE
            Output:         NONE
            Semantics:      Suspend current thread and reschedule

    int OSRun(struct tcb *thread);
            Input:          (thread) pointer to thread control block
            Output:         NONE
            Semantics:      READY given thread and reschedule

    int OSGetUID(thread);
            Input:          (thread) pointer to thread control block
                                     (tcb *)0 for current thread
            Output:         (return code) UID of thread
            Semantics:      Get the UID of the given thread

    int OSKill(struct tcb *thread);
            Input:          (thread) pointer to thread control block
            Output:         NONE
            Semantics:      Remove given thread and reschedule

    int OSExit(int code);
            Input:          (code) exit code
            Output:         NONE
            Semantics:      Kill current thread with given exit code and message

    int OSPanic(char *msg);
            Input:          (msg) pointer to message text
            Output:         NONE
            Semantics:      Dead end multithreading error, print message to display
                            and stop processor

    int OSSleep(int n)
            Input:          (n) number of 1/100 secs to sleep
            Output:         NONE
            Semantics:      Let current thread sleep for at least n*1/100
                            seconds.  In multithreaded mode, this will
                            reschedule another thread.  Outside
                            multi-threaded mode, it will call OSWait().

    int OSForbid(void)
            Input:          NONE
            Output:         NONE
            Semantics:      disable thread switching in preemptive mode

    int OSPermit(void)
            Input:          NONE
            Output:         NONE
            Semantics:      enable thread switching in preemptive mode

    In the functions described above the parameter "thread" can always be
    a pointer to a tcb or 0 for current thread.

### Semaphores

    int OSSemInit(struct sem *sem,int val);
            Input:          (sem) pointer to a semaphore
                            (val) start value
            Output:         NONE
            Semantics:      Initialize semaphore with given start value

    int OSSemP(struct sem *sem);
            Input:          (sem) pointer to a semaphore
            Output:         NONE
            Semantics:      Do semaphore P (down) operation

    int OSSemV(struct sem *sem);
            Input:          (sem) pointer to a semaphore
            Output:         NONE
            Semantics:      Do semaphore V (up) operation

### Timer

    int OSSetTime(int hrs,int mins,int secs);
            Input:          (hrs) value for hours
                            (mins) value for minutes
                            (secs) value for seconds
            Output:         NONE
            Semantics:      Set system clock to given time

    int OSGetTime(int *hrs,int *mins,int *secs,int *ticks);
            Input:          (hrs) pointer to int for hours
                            (mins) pointer to int for minutes
                            (secs) pointer to int for seconds
                            (ticks) pointer to int for ticks
            Output:         (hrs) value of hours
                            (mins) value of minutes
                            (secs) value of seconds
                            (ticks) value of ticks
            Semantics:      Get system time, one second has 100 ticks

    int OSShowTime(void);
            Input:          NONE
            Output:         NONE
            Semantics:      Print system time to display

    int OSGetCount(void);
            Input:          NONE
            Output:         (return code) number of 1/100 seconds since last reset
            Semantics:      Get the number of 1/100 seconds since last reset.
                            Type int is 32 bits, so this value will wrap
                            around after ~248 days.

    int OSWait (int n);
            Input:          (n) time to wait
            Output:         NONE
            Semantics:      Busy loop for n*1/100 seconds.

    timer-irq:
    ----------
    TimerHandle OSAttachTimer(int scale, TimerFnc function);
            Input:          (scale) prescale value for 100Hz Timer (1 to ...)
                            (TimerFnc) function to be called periodically
            Output:         (TimerHandle) handle to reference the IRQ-slot
                            A value of 0 indicates an error due to a full list(max. 16).
            Semantics:      Attach irq-routine (void function(void)) to the irq-list.
                            The scale parameter adjusts the call frequency (100/scale Hz)
                            of this routine to allow many different applications.
            Note:           Execution time of any attached routine (and total time of
                            all attached routines) has to be significantly < 10ms.
                            Otherwise timer interrupts will be missed and motor/sensor-
                            timing gets corrupted.

    int OSDetachTimer(TimerHandle handle)
            Input:          (handle) handle of a previous installed timer irq
            Output:         0 = handle not valid
                            1 = function successfully removed from timer irq list
            Semantics:      Detach a previously installed irq-routine from the irq-list.

### Download and RS-232

    int OSDownload(char *name,int *bytes,int baud,int handshake,int interface); **)
            Input:          (name) pointer to program name array
                                    (bytes) pointer to bytes transferred int
                                    (baud) baud rate selection
                                    Valid values are: SER4800,SER9600,SER19200,SER38400,SER57600,
                                    SER115200(only SERIAL2-3, SERIAL1 depending on CPU-Freq.)
                                    (handshake) handshake selection
                                    Valid values are: NONE, RTSCTS, IRDA (IRDA only SERIAL2/3)
                                    (interface): serial interface
                                    Valid values are: SERIAL1-3
            Output:         (return code)
                             0 = no error, download incomplete - call again
                            99 = download complete
                             1 = receive timeout error
                             2 = receive status error
                             3 = send timeout error
                             5 = srec checksum error
                             6 = user canceled error
                             7 = unknown srecord error
                             8 = illegal baud rate error
                             9 = illegal startadr. error
                            10 = illegal interface

            Semantics:      Load user program with the given serial setting
                            and get name of program.  This function must
                            be called in a loop until the return code is
                            !=0. In the loop the bytes that have been
                            transferred already can be calculated from the
                            bytes that have been transferred in this round.

    int OSInitRS232(int baud,int handshake,int interface);
            Input:          (baud) baud rate selection
                                    Valid values are:
                                    SER4800,SER9600,SER19200,SER38400,SER57600,SER115200
                            (handshake) handshake selection
                                    Valid values are: NONE,RTSCTS, IRDA (IRDA only SERIAL2/3)
                            (interface) serial interface
                                    Valid values are: SERIAL1-3
            Output:         (return code)
                             0 = ok
                             8 = illegal baud rate error
                            10 = illegal interface
            Semantics:      Initialize rs232 with given setting

    int OSSendCharRS232(char chr,int interface);
            Input:          (chr) character to send
                            (interface) serial interface
                                        Valid values are: SERIAL1-3
            Output:         (return code)
                             0 = good
                             3 = send timeout error
                            10 = illegal interface
            Semantics:      Send a character over rs232

    int OSSendRS232(char *chr,int interface);
            Input:          (chr) pointer to character to send
                            (interface) serial interface
                                        Valid values are: SERIAL1-3
            Output:         (return code)
                             0 = good
                             3 = send timeout error
                            10 = illegal interface
            Semantics:      Send a character over rs232.  Use OSSendCharRS232()
                            instead.  This function will be removed in the future.

    int OSRecvRS232(char *buf,int interface);
            Input:          (buf) pointer to a character array
                                    (interface) serial interface
                                    Valid values are: SERIAL1-3
            Output:         (return code)
                             0 = good
                             1 = receive timeout error
                             2 = receive status error
                            10 = illegal interface
            Semantics:      Receive a character over rs232

    int OSFlushInRS232(int interface);
            Input:          (interface) serial interface
                                    Valid values are: SERIAL1-3
            Output:         (return code)
                             0 = good
                            10 = illegal interface
            Semantics:      resets status of receiver and flushes its
                            FIFO. Very useful in NOHANDSHAKE-mode to bring
                            the FIFO in a defined condition before
                            starting to receive

    int OSFlushOutRS232(int interface);
            Input:          (interface) serial interface
                                    Valid values are: SERIAL1-3
            Output:         (return code)
                             0 = good
                            10 = illegal interface
            Semantics:      flushes the transmitter-FIFO.  Very useful to abort
                            current transmission to host (ex: in the case
                            of a not responding host)

    int OSCheckInRS232(int interface);
            Input:          (interface) serial interface
                                    Valid values are: SERIAL1-3
            Output:         (return code) >0 : the number of chars currently available in FIFO
                                         <0 : 0xffffff02 receive status error (no chars available)
                                              0xffffff0a illegal interface
            Semantics:      useful to read out only packages of a certain size

    int OSCheckOutRS232(int interface);
            Input:          (interface) serial interface
                                    Valid values are: SERIAL1-3
            Output:         (return code) >0 : the number of chars currently waiting in FIFO
                                         <0 : 0xffffff0a illegal interface
            Semantics:      useful to test if the host is receiving properly
                                    or to time transmission of packages in the speed the
                                    host can keep up with

    int USRStart(void);                                                         **)
            Input:          NONE
            Output:         NONE
            Semantics:      Start loaded user program.

    int USRResident(char *name, BOOL mode);                                     **)
            Input:          (name) pointer to name array
                            (mode) mode
                            Valid values are: SET,GET
            Output:         NONE
            Semantics:      Make loaded user program reset resistant
                            SET     save startaddress and program name.
                            GET     restore startaddress and program name.

    **) this function must not be used in user programs !!!!

### Audio

Sampleformat: WAV or AU/SND (8bit, pwm or mulaw)
Samplerate: 5461, 6553, 8192, 10922, 16384, 32768 (Hz)
Tonerange: 65 Hz to 21000 Hz
Tonelength: 1 msec to 65535 msecs

    int AUPlaySample(char* sample);
            Input:          (sample) pointer to sample data
            Output:         (return code) playfrequency for given sample
                                         0 if unsupported sampletype
            Semantics:      Plays a given sample (nonblocking)
                            supported formats are:
                            WAV or AU/SND  (8bit, pwm or mulaw)
                            5461, 6553, 8192, 10922, 16384, 32768 (Hz)

    int AUCheckSample(void);
            Input:          NONE
            Output:         FALSE while sample is playing
            Semantics:      nonblocking test for sampleend

    int AUTone(int freq, int msec);
            Input:          (freq) tone frequency
                            (msecs) tone length
            Output:         NONE
            Semantics:      Plays tone with given frequency for the given
                            time (nonblocking)
                            supported formats are:
                            freq = 65 Hz to 21000 Hz
                            msecs = 1 msec to 65535 msecs

    int AUCheckTone(void);
            Input:          NONE
            Output:         FALSE while tone is playing
            Semantics:      nonblocking test for toneend

    int AUBeep(void);
            Input:          NONE
            Output:         NONE
            Semantics:      BEEP!

    int AURecordSample(BYTE* buf, long len, long freq);
            Input:          (buf) pointer to buffer
                            (len) bytes to sample + 28 bytes header
                            (freq) desired samplefrequency
            Output:         (return code) real samplefrequency
            Semantics:      Samples from microphone into buffer with given
                            frequency (nonblocking)
                            Recordformat: AU/SND (pwm) with unsigned 8bit samples

    int AUCheckRecord(void);
            Input:          NONE
            Output:         FALSE while recording
            Semantics:      nonblocking test for recordend

    int AUCaptureMic(void);
            Input:          NONE
            Output:         (return code) microphone value (10bit)
            Semantics:      Get microphone input value

### PSD Sensors

Position Sensitive Devices (PSDs) use infrared beams to measure distance. The accuracy varies from sensor to sensor, and they need to be calibrated in the HDT to get correct distance readings.

    PSDHandle PSDInit(DeviceSemantics semantics);
            Input:          (semantics) unique definition for desired PSD (see hdt.h)
            Output:         (return code) unique handle for all further operations
            Semantics:      Initialize single PSD with given semantics
                            Up to 8 PSDs can be initialized

    int PSDRelease(void);
            Input:          NONE
            Output:         NONE
            Semantics:      Stops all measurings and releases all initialized
                            PSDs

    int PSDStart(PSDHandle bitmask, BOOL cycle);

            Input:          (bitmask) bitwise-or of all handles to which parallel
                                      measuring should be applied
                            (cycle)   TRUE  = continuous measuring
                                      FALSE = single measuring
            Output:         (return code) status of start-request
                                      -1 = error (false handle)
                                       0 = ok
                                       1 = busy (another measuring blocks driver)
            Semantics:      Starts a single/continuous PSD-measuring.  Continuous
                            gives new measurement ca. every 60ms.

    int PSDStop(void);
            Input:          NONE
            Output:         NONE
            Semantics:      Stops actual continuous PSD-measuring after
                            completion of the current shot

    BOOL PSDCheck(void);
            Input:          NONE
            Output:         (return code) TRUE if a valid result is available
            Semantics:      nonblocking test if a valid PSD-result is available

    int PSDGet(PSDHandle handle);
            Input:          (handle) handle of the desired PSD
                                     0 for timestamp of actual measure-cycle
            Output:         (return code) actual distance in mm (converted through
                            internal table)
            Semantics:      Delivers actual timestamp or distance measured by
                            the selected PSD.  If the raw reading is out of
                            range for the given sensor, PSD_OUT_OF_RANGE(=9999)
                            is returned.

    int PSDGetRaw(PSDHandle handle);
            Input:          (handle) handle of the desired PSD
                                     0 for timestamp of actual measure-cycle
            Output:         (return code) actual raw-data (not converted)
            Semantics:      Delivers actual timestamp or raw-data measured by
                            the selected PSD

### Servos and Motors

    ServoHandle SERVOInit(DeviceSemantics semantics);
            Input:          (semantics) semantic (see hdt.h)
            Output:         (return code) ServoHandle
            Semantics:      Initialize given servo

    int SERVORelease (ServoHandle handle)
            Input:          (handle) bitwise-or of all ServoHandles which should be released
            Output:         (return code) 0 = ok
                                         errors (nothing is released):
                                          0x11110000 = totally wrong handle
                                          0x0000xxxx = the handle parameter in which only those bits
                                            remained set that are connected to a releasable TPU-channel
            Semantics:      Release given servos

    int SERVOSet (ServoHandle handle,int angle);
            Input:          (handle) bitwise-or of all ServoHandles which should be set in parallel
                            (angle)  servo angle
                                     valid values: 0-255
            Output:         (return code) 0 = ok
                                         -1 = error wrong handle
            Semantics:      Set the given servos to the same given angle

    MotorHandle MOTORInit(DeviceSemantics semantics);
            Input:          (semantics) semantic (see hdt.h)
            Output:         (return code) MotorHandle
            Semantics:      Initialize given motor

    int MOTORRelease (MotorHandle handle)
            Input:          (handle) logical-or of all MotorHandles which should be released
            Output:         (return code) 0 = ok
                                         errors (nothing is released):
                                          0x11110000 = totally wrong handle
                                          0x0000xxxx = the handle parameter in which only those bits
                                          remained set that are connected to a releasable TPU-channel
            Semantics:      Release given motor

    int MOTORDrive (MotorHandle handle,int speed);
            Input:          (handle) logical-or of all MotorHandles which should be driven
                            (speed) motor speed in percent
                            Valid values: -100 - 100 (full backward to full forward)
                                           0 for full stop
            Output:         (return code)  0 = ok
                                          -1 = error wrong handle
            Semantics:      Set the given motors to the same given speed

    QuadHandle QUADInit(DeviceSemantics semantics);
            Input:          (semantics) semantic
            Output:         (return code) QuadHandle or 0 for error
            Semantics:      Initialize given Quadrature-Decoder (up to 8 decoders are possible)

    int QUADRelease(QuadHandle handle);
            Input:          (handle) logical-or of decoder-handles to be released
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Release one or more Quadrature-Decoder

    int QUADReset(QuadHandle handle);
            Input:          (handle) logical-or of decoder-handles to be reseted
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Reset one or more Quadrature-Decoder

    int QUADRead(QuadHandle handle);
            Input:          (handle) ONE decoder-handle
            Output:         32bit counter-value (-2^31 .. 2^31-1)
            Semantics:      Read actual Quadrature-Decoder counter, initially zero.
                            Note: A wrong handle will ALSO result in a 0 counter value!!

    DeviceSemantics QUADGetMotor(DeviceSemantics semantics);
            Input:          (handle) ONE decoder-handle
            Output:         semantic of the corresponding motor
                            0 = wrong handle
            Semantics:      Get the semantic of the corresponding motor

    float QUADODORead(QuadHandle handle);
            Input:          (handle) ONE decoder-handle
            Output:         meters since last odometer-reset
            Semantics:      Get the distance from the last reset point of a single motor.
                            This is not the overall distance driven since the last reset,
                            but the distance to the start point.

    int QUADODOReset(QuadHandle handle);
            Input:          (handle) logical-or of decoder-handles to be reseted
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Resets the simple odometer(s) to define the startpoint

### V-Omega Driving Interface

This is a high level wheel control API using the motor and quad primitives to drive the robot.

    Data Types:
            typedef float meterPerSec;
            typedef float radPerSec;
            typedef float meter;
            typedef float radians;

            typedef struct
            { meter x;
              meter y;
              radians phi;
            } PositionType;

            typedef struct
            { meterPerSec v;
              radPerSec w;
            } SpeedType;

    VWHandle VWInit(DeviceSemantics semantics, int Timescale);
            Input:          (semantics) semantic
                            (Timescale) prescale value for 100Hz IRQ (1 to ...)
            Output:         (return code) VWHandle or 0 for error
            Semantics:      Initialize given VW-Driver (only 1 can be initialized!)
                            The motors and encoders are automatically reserved!!
                            The Timescale allows to adjust the tradeoff between
                            accuracy (scale=1, update at 100Hz) and speed(scale>1, update
                            at 100/scale Hz).

    int VWRelease(VWHandle handle);
            Input:          (handle) VWHandle to be released
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Release VW-Driver, stop motors

    int VWSetSpeed(VWHandle handle, meterPerSec v, radPerSec w);
            Input:          (handle) ONE VWHandle
                            (v) new linear speed
                            (w) new rotation speed
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Set the new speed: v(m/s) and w(rad/s not degree/s)

    int VWGetSpeed(VWHandle handle, SpeedType* vw);
            Input:          (handle) ONE VWHandle
                            (vw) pointer to record to store actual v, w values
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Get the actual speed: v(m/s) and w(rad/s not degree/s)

    int VWSetPosition(VWHandle handle, meter x, meter y, radians phi);
            Input:          (handle) ONE VWHandle
                            (x) new x-position
                            (y) new y-position
                            (phi) new heading
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Set the new position: x(m), y(m) phi(rad not degree)

    int VWGetPosition(VWHandle handle, PositionType* pos);
            Input:          (handle) ONE VWHandle
                            (pos) pointer to record to store actual position (x,y,phi)
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Get the actual position: x(m), y(m) phi(rad not degree)

    int VWStartControl(VWHandle handle, float Vv, float Tv, float Vw, float Tw);
            Input:          (handle) ONE VWHandle
                            (Vv) the parameter for the proportional component of the v-controller
                            (Tv) the parameter for the integrating component of the v-controller
                            (Vw) the parameter for the proportional component of the w-controller
                            (Tv) the parameter for the integrating component of the w-controller
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Enable the PI-controller for the vw-interface and set the parameters.
                            As default the PI-controller is deactivated when the vw-interface is
                            initialized. The controller tries to keep the desired speed (set with
                            VWSetSpeed) stable by adapting the energy of the involved motors.
                            The parameters for the controller have to be choosen carefully!
                            The formula for the controller is:
                                                         t
                            new(t) = V*(diff(t) + 1/T * Int( diff(t)dt )
                                                         0
                            Recommended setting:  VWStartControl(vw, 7.0, 0.3, 7.0, 0.1);
                            V: a value typically around 7.0
                            T: a value typically between 0 and 1.0
                            After enabling the controller the last set speed (VWSetSpeed) is
                            taken as the speed to be held stable.

    int VWStopControl(VWHandle handle);
            Input:          (handle) ONE VWHandle
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Disable the controller immediately. The vw-interface continues normally
                            with the last valid speed of the controller.

    int VWDriveStraight(VWHandle handle, meter delta, meterpersec v)
            Input:          (handle) ONE VWHandle
                            (delta)  distance to drive in m (pos. -> forward)
                                                            (neg. -> backward)
                            (v)      speed to drive with (always positive!)
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Drives distance "delta" with speed v straight ahead (forward or backward)
                            any subsequent call of VWDriveStraight, -Turn, -Curve or VWSetSpeed
                            while this one is still being executed, results in an immediate interruption
                            of this command

    int VWDriveTurn(VWHandle handle, radians delta, radPerSec w)
            Input:          (handle) ONE VWHandle
                            (delta)  degree to turn in radians (pos. -> counter-clockwise)
                                                               (neg. -> clockwise)
                            (w)      speed to turn with (always positive!)
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Turns about "delta" with speed w on the spot (clockwise or counter-clockwise)
                            any subsequent call of VWDriveStraight, -Turn, -Curve or VWSetSpeed
                            while this one is still being executed, results in an immediate interruption
                            of this command

    int VWDriveCurve(VWHandle handle, meter delta_l, radians delta_phi, meterpersec v)
            Input:          (handle)    ONE VWHandle
                            (delta_l)   length of curve_segment to drive in m (pos. -> forward)
                                                                              (neg. -> backward)
                            (delta_phi) degree to turn in radians (pos. -> counter-clockwise)
                                                                  (neg. -> clockwise)
                            (v)         speed to drive with (always positive!)
            Output:          0 = ok
                            -1 = error wrong handle
            Semantics:      Drives a curve segment of length "delta_l" with overall vehicle turn of
                            "delta_phi" with speed v (forw. or backw. / clockw. or counter-clockw.).
                            any subsequent call of VWDriveStraight, -Turn, -Curve or VWSetSpeed
                            while this one is still being executed, results in an immediate interruption
                            of this command

    float VWDriveRemain(VWHandle handle)
            Input:          (handle) ONE VWHandle
            Output:          0.0 = previous VWDriveX command has been completed
                             any other value = remaining distance to goal
            Semantics:      Remaining distance to goal set by VWDriveStraight, -Turn
                            (for -Curve only the remaining part of delta_l is reported)

    int VWDriveDone(VWHandle handle)
            Input:          (handle) ONE VWHandle
            Output:         -1 = error wrong handle
                             0 = vehicle is still in motion
                             1 = previous VWDriveX command has been completed
            Semantics:      Checks if previous VWDriveX() command has been completed

    int VWDriveWait(VWHandle handle)
            Input:          (handle) ONE VWHandle
            Output:         -1 = error wrong handle
                             0 = previous VWDriveX command has been completed
            Semantics:      Blocks the calling process until the previous VWDriveX() command has been completed

    int VWStalled(VWHandle handle)
            Input:          (handle) ONE VWHandle
            Output:         -1 = error wrong handle
                             0 = vehicle is still in motion or no motion command is active
                             1 = at least one vehicle motor is stalled during VW driving command
            Semantics:      Checks if at least one of the vehicle's motors is stalled right now

### Bumper / Infrared Sensors

This is for obsolete sensors only available on older Robot models.

    BumpHandle BUMPInit(DeviceSemantics semantics);
            Input:          (semantics) semantic
            Output:         (return code) BumpHandle or 0 for error
            Semantics:      Initialize given bumper (up to 16 bumpers are possible)

    int BUMPRelease(BumpHandle handle);
            Input:          (handle) logical-or of bumper-handles to be released
            Output:         (return code)
                            0 = ok
                            errors (nothing is released):
                             0x11110000 = totally wrong handle
                             0x0000xxxx = the handle parameter in which only those bits remained
                                          set that are connected to a releasable TPU-channel
            Semantics:      Release one or more bumper

    int BUMPCheck(BumpHandle handle, int* timestamp);
            Input:          (handle) ONE bumper-handle
                            (timestamp) pointer to an int where the timestamp is placed
            Output:         (return code)
                             0 = bump occurred, in *timestamp is now a valid stamp
                            -1 = no bump occurred or wrong handle, *timestamp is cleared
            Semantics:      Check occurrence of a single bump and return the timestamp(TPU).
                            The first bump is recorded and held until BUMPCheck is called.

    IRHandle IRInit(DeviceSemantics semantics);
            Input:          (semantics)   semantics
            Output:         (return code) IRHandle or 0 for error
            Semantics:      Initialize given IR-sensor (up to 16 sensors are possible)

    int IRRelease(IRHandle handle);
            Input:          (handle) logical-or of IR-handles to be released
            Output:         (return code) 0 = ok
                                         errors (nothing is released):
                                          0x11110000 = totally wrong handle
                                          0x0000xxxx = the handle parameter in which only those bits
                                          remained set that are connected to a releasable TPU-channel
            Semantics:      Release one or more IR-sensors

    int IRRead(IRHandle handle);
            Input:          (handle) ONE IR-handle
            Output:         (return code) 0/1 = actual pinstate of the TPU-channel
                                          -1  = wrong handle
            Semantics:      Read actual state of the IR-sensor

### Latches

Latches are low-level IO buffers.

    BYTE OSReadInLatch(int latchnr);
            Input:          (latchnr) number of desired Inlatch (range: 0..3)
            Output:         actual state of this inlatch
            Semantics:      Reads contents of selected inlatch

    BYTE OSWriteOutLatch(int latchnr, BYTE mask, BYTE value);
            Input:          (latchnr) number of desired Outlatch (range: 0..3)
                            (mask)    and-bitmask of pins which should be cleared
                            (inverse!)
                            (value)   or-bitmask of pins which should be set
            Output:         previous state of this outlatch
            Semantics:      Modifies an outlatch and keeps global state consistent
                            example: OSWriteOutLatch(0, 0xF7, 0x08); sets bit4
                            example: OSWriteOutLatch(0, 0xF7, 0x00); clears bit4

    BYTE OSReadOutLatch(int latchnr);
            Input:          (latchnr) number of desired Outlatch (range: 0..3)
            Output:         actual state of this outlatch
            Semantics:      Reads global copy of outlatch

### Parallel Port

    BYTE OSReadParData(void);
            Input:          NONE
            Output:         actual state of the 8bit dataport
            Semantics:      Reads contents of parallelport (active high)

    void OSWriteParData(BYTE value);
            Input:          (value) new output-data
            Output:         NONE
            Semantics:      Writes out new data to parallelport (active high)

    BYTE OSReadParSR(void);
            Input:          NONE
            Output:         actual state of the 5 status pins
            Semantics:      Reads state of the 5 status pins (active-high!)
                            BUSY(4), ACK(3), PE(2), SLCT(1), ERROR(0)

    void OSWriteParCTRL(BYTE value);
            Input:          (value) new ctrl-pin-output (4bits)
            Output:         NONE
            Semantics:      Writes out new ctrl-pin states (active high!)
                            SLCTIN(3), INT(2), AUTOFDXT(1), STROBE(0)

    BYTE OSReadParCTRL(void);
            Input:          NONE
            Output:         actual state of the 4 ctrl-pins
            Semantics:      Reads state of the 4 ctrl-pins (active-high!)
                            SLCTIN(3), INT(2), AUTOFDXT(1), STROBE(0)

### Analog-Digital Converter

    int OSGetAD(int channel);
            Input:          (channel)    desired AD-channel range: 0..15
            Output:         (return code) 10 bit sampled value
            Semantics:      Captures one single 10bit value from specified
                            AD-channel. The return value is stored in the least
                            significant bits of the 32 bit return value.

    int OSOffAD(int mode);
            Input:          (mode) 0 = full powerdown
                                   1 = fast powerdown
            Output:         NONE
            Semantics:      Powers down the 2 AD-converters (saves energy).
                            A call of OSGetAD awakens the AD-converter again

### Radio Communication

Note: Additional hardware and software (Radio-Key) are required to use these library routines.

"EyeNet" network among arbitrary number of EyeBots and optional workstation host. Network operates as virtual token ring and has fault tolerant aspects. A net Master is negotiated autonomously, new EyeBots will automatically be integrated into the net by "wildcard" messages, and dropped out EyeBots will be eliminated from the network. This network uses a RS232 interface and can be run over cable or wireless.

The communication is 8-bit clean and all packets are sent with checksums to detect transmittion errors. The communication is unreliable, meaning there is no retransmit on error and delivery of packets are not guaranteed.

    int RADIOInit(void);
            Input:          NONE
            Output:         (return code) 0 = OK
            Semantics:      Initializes and starts the radio communication.

    int RADIOTerm(void);
            Input:          NONE
            Output:         (return code) 0 = OK
            Semantics:      Terminate network operation.

    int RADIOSend(BYTE id, int byteCount, BYTE* buffer);
            Input:          (id)        the EyeBot ID number of the message destination
                            (byteCount) message length
                            (buffer)    message contents
            Output:         (return code) 0 = OK
                                          1 = send buffer is full or message is too long.
            Semantics:      Send message to another EyeBot. Send is buffered,
                            so the sending process can continue while the
                            message is sent in the background.  Message
                            length must be below or equal to MSGMAXLEN.
                            Messages are broadcasted by sending them to
                            the special id BROADCAST.

    int RADIOCheck(void);
            Input:          NONE
            Output:         returns the number of user messages in the buffer
            Semantics:      Function returns the number of buffered messages.
                            This function should be called before
                            receiving, if blocking is to be avoided.

    int RADIORecv(BYTE* id, int* bytesReceived, BYTE* buffer);
            Input:          NONE
            Output:         (id)            EyeBot ID number of the message source
                            (bytesReceived) message length
                            (buffer)        message contents
            Semantics:      Returns the next message buffered. Messages are
                            returned in the order they are
                            received. Receive will block the calling
                            process if no message has been received until
                            the next one comes in.  The buffer must have
                            room for MSGMAXLEN bytes.

    Data Types:
            struct RadioIOParameters {
              int interface;      /* SERIAL1, SERIAL2 or SERIAL3 */
              int speed;          /* SER4800,SER9600,SER19200,SER38400,SER57600,SER115200 */
              int id;             /* machine id */
              int remoteOn;       /* non-zero if remote control is active */
              int imageTransfer;  /* if remote on: 0 off, 2 full, 1 reduced */
              int debug;          /* 0 off, 1..100 level of debugging spew */
            };

            struct RadioStatus {
              BYTE master;        /* EyeBot ID */
              BOOL active[MAXEYE];/* shows who is active at the moment */
            };

    void RADIOGetIoctl(RadioIOParameters* radioParams);
            Input:          NONE
            Output:         (radioParams) current radio parameter settings
            Semantics:      Reads out current radio parameter settings.

    void RADIOSetIoctl(RadioIOParameters* radioParams);
            Input:          (radioParams) new radio parameter settings
            Output:         NONE
            Semantics:      Changes radio parameter settings.  This should
                            be done before calling RADIOInit().

    int RADIOGetStatus(RadioStatus *status);
            Input:          NONE
            Output:         (status) current radio communication status.
            Semantics:      Return current status info from RADIO communication.

### Compass

These routines provide an interface to a digital compass.

#### Sample HDT Setting

    compass_type compass = {0,13,(void*)OutBase, 5,(void*)OutBase, 6, (BYTE*)InBase, 5};

    HDT_entry_type HDT[] =
    { ...
      {COMPASS,COMPASS,"COMPAS",(void *)&compass},
      ...
    };

#### Functions

    int COMPASSInit(DeviceSemantics semantics);
            Input:          Unique definition for desired COMPASS (see hdt.h)
            Output:         (return code) 0 = OK
                                          1 = error
            Semantics:      Initialize digital compass device

    int COMPASSStart(BOOL cycle);
            Input:          (cycle) 1 for cyclic mode
                                    0 for single measurement
            Output:         (return code) 1 = module has already been started
                                          0 = OK
            Semantics:      This function starts the measurement of the actual heading.
                            The cycle parameter chooses the operation mode of the compass-module.
                            In cyclic mode (1), the compass delivers as fast as possible the
                            actual heading without pause. In normal mode (0) a single measurement
                            is requested and allows the module to go back to sleep mode afterwards.

    int COMPASSCheck();
            Input:          NONE
            Output:         (return code) 1 = result is ready
                                          0 = result is not yet ready
            Semantics:      If a single shot was requested this function allows to check if the result
                            is already available. In the cyclic mode this function is useless because it
                            always indicates 'busy'. Usually a user uses a loop to wait for a result:
                              int heading;
                              COMPASSStart(FALSE);
                              while(!COMPASSCheck());  //In single tasking! Otherwise yield to other tasks
                              heading = COMPASSGet();

    int COMPASSStop();
            Input:          NONE
            Output:         (return code) 0 = OK
                                          1 = error
            Semantics:      To stop the initiated cyclic measurement this function WAITS for the current
                            measurement to be finished and stops the module. This function therefore will
                            return after 100msec at latest or will deadlock if no compass module is
                            connected to the EyeBot!

    int COMPASSRelease();
            Input:          NONE
            Output:         (return code) 0 = OK
                                          1 = error
            Semantics:      This function shuts down the driver and aborts any ongoing measurement
                            directly.

    int COMPASSGet();
            Input:          NONE
            Output:         (return code) Compass heading data: [0..359]
                                          -1 = no heading has been calculated yet
                                               (wait after initializing).
            Semantics:      This function delivers the actual compass heading.

    int COMPASSCalibrate(int mode);
            Input:          (mode) 0 to reset calibration data of compass module (requires about 0.8s)
                                   1 to perform normal calibration.
            Output:         (return code) 0 = OK
                                          1 = error
            Semantics:      This function has two tasks. With mode=0 it resets the calibration data
                            of the compass module. With mode=1 the normal calibration is performed.
                            It has to be called twice (first at any position, second at 180degree
                            to the first position).
                            Normally you will perform the following steps:
                              COMPASSCalibrate(1);
                              VWDriveTurn(VWHandle handle, M_PI, speed);  // turn EyeBot 180deg in place
                              COMPASSCalibrate(1);

### IR Remote Control

These commands allow sending commands to an EyeBot via a standard TV remote.

#### Include

    #include "irtv.h"  /* only required for HDT files */
    #include "IRnokia.h"

#### Sample HDT Setting

    /* infrared remote control on Servo S10 (TPU11)*/
    irtv_type irtv = {1, 11, TPU_HIGH_PRIO, REMOTE_ON, SPACE_CODE, 15,
    0x0000, 0x03FF, DEFAULT_MODE, 1, -1, RC_RED, RC_GREEN, RC_YELLOW, RC_BLUE};

    HDT_entry_type HDT[] =
    { ...
      {IRTV,IRTV,"IRTV",(void *)&irtv},
      ...
    };

#### Functions

    int IRTVInitHDT(DeviceSemantics semantics);
            Input:          (semantics) unique definition for desired IRTV (see hdt.h)
            Output:         (return code) 0 = ok
                                          1 = illegal type or mode (in HDT IRTV entry)
                                          2 = invalid or missing "IRTV" HDT entry for this semantics
            Semantics:      Initializes the IR remote control decoder by calling IRTVInit() with the
                            parameters found in the corresponding HDT entry. Using this function
                            applications are independant of the used remote control since the
                            defining parameters are located in the HDT.

    int IRTVInit(int type, int length, int tog_mask, int inv_mask, int mode, int bufsize, int delay);
            Input:          (type)     the used code type
                                       Valid values are:
                                       SPACE_CODE, PULSE_CODE, MANCHESTER_CODE, RAW_CODE
                            (length)   code length (number of bits)
                            (tog_mask) the bitmask that selects the "toggle bits" in a code
                                       (bits that change when the same key is pressed repeatedly)
                            (inv_mask) the bitmask that selects the inverted bits in a code
                                       (for remote controls with alternating codes)
                            (mode)     operation mode
                                       Valid values are: DEFAULT_MODE, SLOPPY_MODE, REPCODE_MODE
                            (bufsize)  size of the internal code buffer
                            Valid values are: 1-4
                            (delay)    key repetition delay
                                       >0: number of 1/100 sec (should be >20)
                                       -1: no repetition
            Output:         (return code) 0 = ok
                                          1 = illegal type or mode
                                          2 = invalid or missing "IRTV" HDT entry
            Semantics:      Initializes the IR remote control decoder.
                            To find out the correct values for the "type", "length", "tog_mask",
                            "inv_mask" and "mode" parameters, use the IR remote control analyzer
                            program (IRCA).
                            SLOPPY_MODE can be used as an alternative to DEFAULT_MODE.
                            In default mode, at least two consecutive identical code sequences
                            must be received before the code becomes valid. When using sloppy
                            mode, no error check is performed, and every code becomes valid
                            immediately. This reduces the delay between pressing the key and
                            the reaction.
                            With remote controls that use a special repetition coding, REPCODE_MODE
                            must be used (as suggested by the analyzer).

                            Typical parameters | Nokia (VCN 620)          | RC5 (Philips)
                            -------------------+--------------------------+----------------
                            type               | SPACE_CODE               | MANCHESTER_CODE
                            length             | 15                       | 14
                            tog_mask           | 0                        | 0x800
                            inv_mask           | 0x3FF                    | 0
                            mode               | DEFAULT_MODE/SLOPPY_MODE | DEFAULT_MODE/SLOPPY_MODE

                            The type setting RAW_CODE is intended for code analysis only. If RAW_CODE
                            is specified, all of the other parameters should be set to 0. Raw codes
                            must be handled by using the IRTVGetRaw and IRTVDecodeRaw functions.

    void IRTVTerm(void);
            Input:          NONE
            Output:         NONE
            Semantics:      Terminates the remote control decoder and releases the
                            occupied TPU channel.

    int IRTVPressed(void);
            Input:          NONE
            Output:         (return code) Code of the remote key that is currently being pressed
                                          0 = no key
            Semantics:      Directly reads the current remote key code. Does not
                            touch the code buffer. Does not wait.

    int IRTVRead(void);
            Input:          NONE
            Output:         (return code) Next code from the buffer
                                          0 = no key
            Semantics:      Reads and removes the next key code from the code buffer.
                            Does not wait.

    int IRTVGet(void);
            Input:          NONE
            Output:         (return code) Next code from the buffer (!=0)
            Semantics:      Reads and removes the next key code from the code buffer.
                            If the buffer is empty, the function waits until a remote
                            key is pressed.

    void IRTVFlush(void);
            Input:          NONE
            Output:         NONE
            Semantics:      The code buffer is emptied.

    void IRTVGetRaw(int bits[2], int *count, int *duration, int *id, int *clock);
            Input:          NONE
            Output:         (bits)     contains the raw code
                                       bit #0 in bits[0] represents the 1st pulse in code sequence
                                       bit #0 in bits[1] represents the 1st space
                                       bit #1 in bits[0] represents the 2nd pulse
                                       bit #1 in bits[1] represents the 2nd space
                                       ...
                                       A cleared bit stands for a short signal,
                                       a set bit for a long signal.
                            (count)    the number of signals (= pulses + spaces) received
                            (duration) the logical duration of the code sequence
                                       duration = (number of short signals) + 2 * (number of long signals)
                            (id)       a unique ID for the current code (incremented by 1 each time)
                            (clock)    the time when the code was received
            Semantics:      Returns information about the last received raw code.
                            Works only if type setting == RAW_CODE.

    int IRTVDecodeRaw(const int bits[2], int count, int type);
            Input:          (bits)  raw code to be decoded (see IRTVGetRaw)
                            (count) number of signals (= pulses + spaces) in raw code
                            (type)  the decoding method
                                    Valid values are: SPACE_CODE, PULSE_CODE, MANCHESTER_CODE
            Output:         (return code) The decoded value (0 on an illegal Manchester code)
            Semantics:      Decodes the raw code using the given method.

Thomas Bräunl, Klaus Schmitt, Thomas Lampart, Petter Reinholdtsen, 1996-2003