Libraries

The following describes the RoBIOS operating system library routines in RoBIOS version 1.1. Please note, that newer versions of the RoBIOS software may differ from the functionality described below. Please refer to the latest software documentation. The following libraries are available in ROM for programming in C.
Please 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.

Return Codes

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

Image Processing

Basic image processing functions (library robios):
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 ist 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 ist 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 ist 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:      The Laplace operator is applied to the source image
                        and the result ist written to the destination image


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

Datatypes:

        /* image is 80x60 but has a border of 1 pixel */
        #define imagerows 82
        #define imagelines 62

        typedef BYTE image[imagelines][imagerows];
        typedef BYTE colimage[imagelines][imagerows][3];
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 a character buffer
        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 buffer

int KEYGet (void);
        Input:          NONE
        Output:         (returncode) 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:         (returncode) keycode of a pressed key is returned or 0
                        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 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 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
                                        botton corner ist 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 LCDPutGraphic ( image *buf);
        Input:          (buf) pointer to a b/w image
        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.

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 LCDSetPixel (int row,int col,BOOL 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

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

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:         (returncode) 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

Camera

The following functions handle initializing and image reading from either grayscale or color camera:
int CAMInit (void);
        Input:          NONE
        Output:         (returncode) Cameraversion or Errorcode
                        Valid values are:       255 = nocamera connected
                                                254 = camera init error
                                                0-15 = version of b/w camera
                                                16-31 = version of color camera
        Semantics:      Reset and initialize connected Quickcam


int CAMGetFrame ( image *buf);
        Input:          (buf) a pointer to a b/w image
        Output:         NONE
        Semantics:      Read an image from b/w cam

int CAMGetColFrame ( colimage *buf);
        Input:          (buf) a pointer to a color image
        Output:         NONE
        Semantics:      Read an image from color cam

int CAMSet (int bright,int para1,int para2);
        Input:          (bright) a value for the camera brightness
                        (para1) a value for offset (b/w cam)/hue (color cam)
                        (para2) a value for contrast (b/w cam)/saturation (color cam)
                        Valid values are: 0-255
        Output:         NONE
        Semantics:      Set camera hardware parameters

int CAMGet (int *bright,int *offsetORhue,int *contrastORsaturation);
        Input:          (bright) a pointer to the storing place for camera brightness
                        (para1) a pointer to the storing place for offset (b/w cam)/hue (color cam)
                        (para2) a pointer to the storing place for contrast (b/w cam)/saturation (color cam)
        Output:         (bright) the current brightness value
                        (para1) the current offset (b/w cam)/hue (color cam) value
                        (para2) the current contrast (b/w cam)/saturation
(color cam) value
                        Valid values are: 0-255
        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

System Functions

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 OSEnable ( void );
        Input:          NONE
        Output:         NONE
        Semantics:      Enable all interrupts

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


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:         (returncode) 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

Multi-Tasking

int OSMTInit(BYTE mode);
        Input:          (mode) operation mode
                        Valid values are: COOP=DEFAULT,PREEMT
        Output:         NONE
        Semantics:      Initialize multithreading environment
                        NOTE: PREEMT does not work yet.

tcb *OSSpawn(char *name,int code,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:         (returncode) pointer to initialized thread control block
        Semantics:      Initialize new thread, tcb is init. and inserted in
                        scheduler queue but not set to READY

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();
        Input:          NONE
        Output:         NONE
        Semantics:      Choose new current thread

int OSYield();
        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
        Output:         (returncode) 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 n*1/100 seconds

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

int OSPermit()
        Input:          NONE
        Output:         NONE
        Semantics:      enable thread switching in preemtive 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 P operation

int OSSemV(struct sem *sem);
        Input:          (sem) pointer to a semaphore
        Output:         NONE
        Semantics:      Do V 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:         (returncode) number of 1/100 seconds since last reset
        Semantics:      Get the number of 1/100 seconds since last reset

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

Download and RS-232

int OSDownload(char *name,int *bytes,int baud,int handshake,int interface);
 **)
        Input:          (name) pointer to programm name array
                        (bytes) pointer to bytes transferred int
                        (baud) baud rate selection
                        Valid values are: SER9600,SER19200,SER38400,SER57600
                        (handshake) handshake selection
                        Valid values are: NONE,RTSCTS
                        (interface): serial interface
                        Valid values are: SERIAL1-3
        Output:         (returncode)    99 = download good
                                         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
        Semantics:      Load user program with the given serial setting
                        and get name of program
                        this functions must be called in a loop until
                        the returncode is !=0. In the loop the bytes
                        that have been transfered already can be calculated
                        from the bytes that have been transfered in this
                        round

int OSInitRS232(int baud,int handshake,int interface);
        Input:          (baud) baud rate selection
                        Valid values are: SER9600,SER19200,SER38400,SER57600
                        (handshake) handshake selection
                        Valid values are: NONE,RTSCTS
                        (interface) serial interface
                        Valid values are: SERIAL1-3
        Output:         NONE
        Semantics:      Initialize rs232 with given setting

int OSSendRS232(char *chr,int interface);
        Input:          (chr) pointer to a charakter
                        (interface) serial interface
                        Valid values are: SERIAL1-3
        Output:         (returncode)     0 = good
                                         3 = send timeout error
        Semantics:      Send a charakter over rs232

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

int OSFlushInRS232();
        Input:          NONE
        Output:         NONE
        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();
        Input:          NONE
        Output:         NONE
        Semantics:      flushes the trasnmitter-FIFO
                        very useful to abort current transmission to host
                        (ex: in the case of a not responding host)

int OSCheckInRS232();
        Input:          NONE
        Output:         (returncode) the number of chars currently
                        available in FIFO
        Semantics:      useful to only read out packages of a certain size

int OSCheckOutRS232();
        Input:          NONE
        Output:         (returncode) the number of chars currently waiting
                        in FIFO
        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();
 **)
        Input:          NONE
        Output:         NONE
        Semantics:      Start loaded user programm,

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 programmname
                        GET     restore startaddress and programmname

**) 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 date
        Output:         NONE
        Semantics:      Play given sample
                        supported formats are:
                        WAV or AU/SND  (8bit, pwm or mulaw)
                        5461, 6553, 8192, 10922, 16384, 32768 (Hz)


int AUCheckSample();
        Input:          NONE
        Output:         NONE
        Semantics:      Check for sample end
                        returns false while sample is playing


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

int AUCheckTone();
        Input:          NONE
        Output:         NONE
        Semantics:      Check for tone end
                        returns false while tone is playing


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

int AURecordSample(BYTE* buf, long len, long freq);
        Input:          (buf) pointer to buffer
                        (len) bytes to sample
                        (freq) sample frequency
        Output:         NONE
        Semantics:      Sample from microphone into buffer with given
                        frequency
                        Recordformat: AU/SND (pwm) with unsigned 8bit samples


int AUCheckRecord();
        Input:          NONE
        Output:         NONE
        Semantics:      Check for record end
                        returns FALSE while recording

int AUCaptureMic();
        Input:          NONE
        Output:         (returncode) microphone value
        Semantics:      Get microphone input value

PSD

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

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

int PSDStart(PSDHandle bitmask, BOOL cycle);
        Input:          (bitmask) sum of all handles to which parallel mesuring should be applied
                        (cycle)   TRUE  = continous measuring
                                  FALSE = single measuring
        Output:         (returncode) status of start-request
                                  -1 = error (false handle)
                                   0 = ok
                                   1 = busy (another measuring blocks driver)
        Semantics:      Starts a single/cont. PSD-measuring (ca. 60ms per shot)

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

BOOL PSDCheck();
        Input:          NONE
        Output:         (returncode) 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:         (returncode) actual distance in mm (converted through internal table)
        Semantics:      Delivers actual timestamp or distance measured by the selected PSD

int PSDGetRaw(PSDHandle handle);
        Input:          (handle) handle of the desired PSD
                                 0 for timestamp of actual measure-cycle
        Output:         (returncode) 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
        Output:         (returncode) ServoHandle
        Semantics:      Initialize given servo

int SERVOSet (ServoHandle handle,int angle);
        Input:          (handle) handle for servo
                        (ankle) servo angle
                        Valid values: 0-210
        Output:         NONE
        Semantics:      Set the given servo to the given angle

MotorHandle MOTORInit(DeviceSemantics semantics);
        Input:          (semantics) semantic
        Output:         (returncode) MotorHandle
        Semantics:      Initialize given motor

int MOTORDrive (MotorHandle handle,int speed);
        Input:          (handle) handle for motor
                        (speed) motor speed
                        Valid values: -100 0 +100
        Output:         NONE
        Semantics:      Set the given motor to the given speed

Latches

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

A/D Converter

int OSGetAD(int channel);
        Input:          (channel) desired AD-channel range: 0..15
        Output:         (returncode) 10 bit sampled value
        Semantics:      Captures one single 10bit value from specified
                        AD-channel

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


Thomas Bräunl, Thomas Lampart, and Klaus Schmitt, 1997