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.
- Execlib (latest library doc, text file)
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