Today's date: 08-09-2008
This is EyeBotM6 RoBiOS version 0.6

RoBIOS Library Functions

The following describes the RoBIOS operating system library routines for the Eyebot M6 controllers.

In application files use:

#include "eyebot.h"
 

The following libraries are available for programming the Eyebot M6 board in C or C++. In application program, include "eyebot.h" and the library will be automatically linked when calling "gccarm" (refer to the example makefile provided).
Note that there are also a number of libraries available which are not listed here but are included in the EyeBot distribution (e.g. elaborate image processing library). They can also be linked with an application program. Some of the library functions (in gray text) are not finalized yet and they are not included in this distribution.

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

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 352x288 but has a border of 1 pixel */ 
 #define imagecolumns 354
  #define imagerows 290
 
 typedef BYTE image[imagerows][imagecolumns];
 typedef BYTE colimage[imagerows][imagecoulmns][3];
 
int IPLaplace (image *imageIn, image *imageOut);
 Input: (imageIn) source b/w image
  Output: (imageOut) 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 * imageIn, image * imageOut);
 Input:  (imageIn) source b/w image
 Output: (imageOut) 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 * imageIn, image * imageOut);
 Input: (imageIn) source b/w image
 Output: (imageOut) 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 * image1, image * image2, image * imageOut);
 Input: (image1) the current b/w image
 (image2) the last read b/w image
 Output: (imageOut) 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 * imageIn, image * imageOut);
 Input: (imageIn) source color image
 Output: (imageOut) 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".

 
See also Appendix 1 for definitions and data types for the key library functions.
 
 
int KEYInit(void);
 Input: None
 Output: 0 on success
 Negative value on failure
 Semantics: Open the evdev device file for reading touch 
 events. Load the key configuration file (if 
 found), else use the hardcoded default value.
 
int KEYIdle(int idle);
 Input: (idle) user request
  Valid values:
  KEY_GOIDLE - deactivate event checking
  KEY_NOIDLE - activate event checking  KEY_STATE - request current status
 Output: Idle status of event checking procedure
 Semantics: Enable/disable event checking procedure
 
int KEYRelease(void);
 Input: None
 Output: 0 on success
 Negative value on failure
 Semantics: Close the evdev device file and stop checking any 
 key touch event
 
keycode_t KEYGet(void);
 Input: None
 Output: Keycode value
 Semantics: Wait for a touch event and return keycode 
  (including KEY_INVALID - undefined keycode).
 
keycode_t KEYRead(void);
 Input: None
 Output: Keycode value
 Semantics: Read a keycode and returns. Function does not 
 wait, thus includes KEY_TIMEOUT.
 
keycode_t KEYWait(keycode_t excode);
 Input: Expected keycode values (bit XORed)
 Output: Keycode value
 Semantics: Wait for specific keys only.
 
coord_pair_t KEYGetXY(void);
 Input: None
 Output: Coordinate pair
 Semantics: Wait for a touch event and return the XY-
 coordinate.
 
keymode_t KEYSetTM(keymode_t mode);
 Input: (mode) Requested touch map mode
 Output: Current touch map mode
 Semantics: Set mode for key touch map.
 
keymode_t KEYGetTM(touch_map_t** ptouch_map);
 Input: (ptouch_map) Pointer to a touch_map_t structure
 Output: Current touch map mode
 Semantics: Get current mode and touch map (region map).
 
int KEYSetRegion(int index, m6key_box_t *region);
 Input: (index) Index for region
 (region) Pointer to a region data
 Output: 0 on success
 Negative value on failure 
 Semantics: Manually set region data into current touch map.
 Only used in KEYTM_REGIONS mode. If region is
 0x0, resets the touch map (mode becomes 
 KEYTM_UNKNOWN).
 
int KEYGetRegion(int index, m6key_box_t *region); 
 Input: (index) Index for region
 (region) Pointer to a storage for region data
 Output: 0 on success
 Negative value on failure
 Semantics: Copy specific region data out from the current 
 touch map. Only used in KEYTM_REGIONS mode.
 
int KEYNoTouch(touch_event_t* rawtouch);
 Input: (rawtouch) pointer to touch_event_t structure
 this is optional! only if raw data needed! else, 
 use 0x0!
 Output: 0 - being touched
 1 - not touched
 Semantics: Validate there's no touch on screen surface
 
int KEYGetRAW(touch_event_t* rawtouch);
 Input: (rawtouch) pointer to touch_event_t structure
 Output: 0 if sync signal received!
 Negative value if otherwise 
 Semantics: Gets raw touch info - a non-blocking function.
 Mainly used for calibration and testing.
 
keycode_t KEYDecode(touch_event_t* rawtouch);
 Input: (rawtouch) pointer to touch_event_t structure
 Output: Status of touch data (variable in rawtouch)
 Semantics: Decode raw touch info into a keycode based on the 
  current touch map. Mainly used for testing.
 
 

LCD Output

The following routines is used to print texts or graphics on the LCD screen:

Note that the standard C printf() function will print to the console, it is mainly used for debugging during the program development. A similar printf function to print to the LCD screen is called LCDPrintf().

E.g. the "hello world" program below:

printf("Hello, World!\n");   //This will print to the console
LCDPrintf("Hello, World!\n");   //This will print to the LCD screen
 

See also Appendix 2 for definitions and data types for the LCD library functions.

 
 
LCD functions:
 
int LCDClear(void);
 Input: None
 Output: Always 0
 Semantics: Clear the LCD display and all display buffers.
 
int LCDGetFBInfo(fbinfo_t* pinfo);
 Input: (pinfo) Pointer to storage for screen & cursor 
 info
 Output: 0 on success
 Negative value on failure
 Semantics: Get display information and save to structure 
 pointed by pinfo. Cursor info needs LCDInit() for 
 textsize.
 
int LCDSetMode(hword_t mode);
 Input: (mode) LCD Mode flag
 See Appendix 2 for details of possible LCD modes
 Output: Always 0
 Semantics: Update the internal mode flag bits.
 
hword_t LCDGetMode(void);
 Input: None
 Output: Current mode flag bits
 Semantics: Get the internal mode flag bits.
 
int LCDResetMode(hword_t mode);
 Input: (mode) Mode flag - bit XORed
 Valid values: LCDGetMode return values
 Output: Always 0
 Semantics: Reset the internal mode flag bits to a previously 
 saved mode.
 
int LCDRefresh(void);
 Input: None
 Output: Always 0
 Semantics: Refresh the screen (i.e write display buffers to
 the framebuffer device).
 
 
Functions for graphics mode:
 
int LCDSetPixel(int x, int y, rgb_t color);
 Input: (x,y) XY-coordinate of the pixel
 (color) RGB color value for the pixel
 Output: Always 0
 Semantics: Sets the color of the pixel at (x,y) coordinate 
 to color.
 
 
int LCDInvertPixel(int x, int y);
 Input: (x,y) XY-coordinate of the pixel
 Output: Always 0
 Semantics: Bit-invert the color of the pixel at (x,y) 
 coordinate.
 
 
rgb_t LCDGetPixel(int x, int y);
 Input: (x,y) XY-coordinate of the pixel
 Output: RGB color value
 Semantics: Get the RGB color value of the pixel at (x,y) 
 coordinate.
 
 
int LCDLine(int x1, int y1, int x2, int y2, rgb_t color);
 Input: (x1,y1) XY-coordinate of first pixel
 (x2,y2) XY-coordinate of second pixel
 (color) RGB color value for the pixel
 Output: Always 0
 Semantics: Draw a color line from (x1,y1) to (x2,y2).
 
 
int LCDLineInvert(int x1, int y1, int x2, int y2);
 Input: (x1,y1) XY-coordinate of first pixel
 (x2,y2) XY-coordinate of second pixel
 Output: Always 0
 Semantics: Draw a line from (x1,y1) to (x2,y2). The line 
 pixels will invert the color of existing pixels.
 
 
int LCDArea(int x1, int y1, int x2, int y2, rgb_t color);
 Input: (x1,y1) XY-coordinate of top-left pixel
 (x2,y2) XY-coordinate of bottom-right pixel
 (color) RGB fill color value
 Output: Always 0
 Semantics: Draw a color-filled rectangle with (x1,y1) as 
 top-left coordinate and (x2,y2) as the bottom-
 right coordinate.
 
 
int LCDAreaInvert(int x1, int y1, int x2, int y2);
 Input: (x1,y1) XY-coordinate of top-left pixel
 (x2,y2) XY-coordinate of bottom-right pixel
 Output: Always 0
 Semantics: Draw a rectangle with (x1,y1) as top-left 
 coordinate and (x2,y2) as the bottom-right 
 coordinate. The pixels in the specified area will 
 invert the color of existing pixels.
 
 
int LCDFrame(int x1, int y1, int x2, int y2, rgb_t color);
 Input: (x1,y1) XY-coordinate of top-left pixel
 (x2,y2) XY-coordinate of bottom-right pixel
 (color) RGB frame color value
 Output: Always 0
 Semantics: Draw a color rectangle frame with (x1,y1) as top-
 left coordinate and (x2,y2) as the bottom-right 
 coordinate.
 
 
int LCDPutImageRGB(int xpos, int ypos, int xsize, int ysize, 
  byte_t *data);
 Input: (xpos,ypos) XY-coordinate of top-left image 
 position
 (xsize,ysize) Image width & height
 (data) Pointer to image data (24-bit per pixel)
 Output: Always 0
 Semantics: Place a RGB color image (24bpp) at (xpos,ypos) 
 position on the LCD screen.
 
 
int LCDPutImageGray(int xpos, int ypos, int xsize, int ysize, 
  byte_t *data);
 Input: (xpos,ypos) XY-coordinate of top-left image 
 position 
 (xsize,ysize) Image width & height
 (data) Pointer to image data (8-bit per pixel)
 Output: Always 0
 Semantics: Place a grayscale image (8bpp) at (xpos,ypos) 
 position on the LCD screen.
 
int LCDPutImagePPM(int xpos, int ypos, char* filename)
 Input: (xpos,ypos) XY-coordinate of top-left image 
 position
 (filename) PPM image filename
 Output: Return value: 0=OK, 1=error
 Semantics: Place a PPM image at (xpos,ypos) position on
 the LCD screen
 
Functions for text mode:
 
int LCDTextColor(rgb_t fgcol, rgb_t bgcol, char colorflags);
 Input: (fgcol) Default color for text
 (bgcol) Default color for text background
 (colorflags) Mode flag for text color
 Valid values:
  LCD_BGCOL_TRANSPARENT
  LCD_BGCOL_INVERSE
   LCD_FGCOL_INVERSE
  LCD_BGCOL_NOTRANSPARE
  LCD_BGCOL_NOINVERSE
    LCD_FGCOL_NOINVERSE
 Output: Always 0
 Semantics: Set the default color for text (including 
 background) and related flags (e.g. for 
 transparent background).
 
 
int LCDPrintf(const char *format, ...);
 Input: (format) Formatted string
 Output: Always 0
 Semantics: Print formatted string to LCD and refresh LCD (if
 AUTOREFRESH flag is set). Cursor position is 
 updated.
 
 
int LCDSetPrintf(int row, int column, const char *format, ...);
 Input: (row,column) Cursor position
 (format) Formatted string
 Output: Always 0
 Semantics: LCDPrintf with text position specified.
 
 
int LCDPutChar(char c);
 Input: (c) Character to be displayed
 Output: Always 0
 Semantics: Write a character to LCD and refresh LCD (if
 AUTOREFRESH flag is set). Cursor position is 
 updated.
 
 
int LCDSetChar(int row, int column, char c);
 Input: (row,column) Cursor position
 (c) Character to be displayed
 Output: Always 0
 Semantics: LCDPutChar with text position specified.
 
 
int LCDPutCharBuffer(char c);
 Input: (c) Character to be displayed
 Output: Always 0
 Semantics: Write a character to current cursor-position. 
 Update cursor position accordingly.
 
 
int LCDPutString(char *string);
 Input: (string) String to be displayed
 Output: Always 0
 Semantics: Print string to LCD and refresh LCD (if 
 AUTOREFRESH flag is set). Cursor position is 
 updated.
 
 
int LCDSetString(int row, int column, char *string);
 Input: (row,column) Cursor position
 (string) String to be displayed
 Output: Always 0
 Semantics: LCDPutString with text position specified.
 
 
int LCDPutHex(int val);
 Input: (val) Hex number to be displayed
 Output: Always 0
 Semantics: Print hexadecimal number to LCD and refresh LCD 
 (if AUTOREFRESH flag is set). Cursor position is 
 updated. Utilize LCDPrintf for conversion.
 
 
int LCDPutHex1(int val);
 Input: (val) Hex number to be displayed
 Output: Always 0
 Semantics: Print hexadecimal number to LCD and refresh LCD 
 (if AUTOREFRESH flag is set). Cursor position is 
 updated. Utilize local Hex-map for conversion.
 
 
int LCDPutInt(int val);
 Input: (val) Integer to be displayed
 Output: Always 0
 Semantics: Print integer to LCD and refresh LCD (if 
 AUTOREFRESH flag is set). Cursor position is 
 updated.
 
 
int LCDPutIntS(int val, int spaces);
 Input: (val) Integer to be displayed
 (spaces) Text space for the integer
 Output: Always 0
 Semantics: Print integer to LCD and refresh LCD (if 
 AUTOREFRESH flag is set). Cursor position is 
 updated. Text space usage can be specified 
 (formatting).
 
 
int LCDPutFloat(float val);
 Input: (val) Floating-point value to be displayed
 Output: Always 0
 Semantics: Print floating-point value to LCD and refresh LCD 
 (if AUTOREFRESH flag is set). Cursor 
 position is updated.
 
 
int LCDPutFloatS(float val, int spaces, int decimals);
 Input: (val) Floating-point value to be displayed
 (spaces) Text space for the integer
 (decimals) Number of decimal points to display
 Output: Always 0
 Semantics: Print floating-point value to LCD and refresh LCD 
 (if AUTOREFRESH flag is set). Cursor position is 
 updated. Text space usage can be specified 
 (formatting).
 
 
int LCDSetPos(int row, int column);
 Input: (row) Text cursor row index
 (column) Text cursor column index
 Output: Always 0
 Semantics: Set the text cursor position to (row, column).
 
 
int LCDGetPos(int *row, int *column);
 Input: (*row) Pointer to cursor row index
 (*column) Pointer to cursor column index
 Output: Always 0
 Semantics: Get the current text cursor position.
 
 
rect_t LCDTextBar(int row, int column, int length, int fill, rgb_t 
 color);
 Input: (row,column) Start text cursor position
 (length) Text length of the bar
 (fill) Percentage of textbar to be filled
 (color) Fill color for the textbar
 Output: rect_t structure for the textbar's frame
 Semantics: Draw a textbar for text starting at position 
 (row,column) until (row,column+length). The 
 textbar will take about 25%-50% of text height & 
 width to draw its frame. The fill parameter will 
 define how much of the text bar should be 
 'filled' with color (like a progress bar).
 
 
Functions for menu:
 
int LCDMenu(char *string1, char *string2, char *string3, char *string4);
 Input: (string1) Menu entry for KEY1 in classic mode
 (string2) Menu entry for KEY2 in classic mode
 (string3) Menu entry for KEY3 in classic mode
 (string4) Menu entry for KEY4 in classic mode
 Output: Always 0
 Semantics: Set menu entries in KEY_CLASSIC mode (4-
 buttons). Also sets the LCD_SHOWMENU flag and 
 refresh the LCD (if AUTOREFRESH flag is set).
 
 
int LCDMenuI(int pos, char *string, rgb_t fgcol, rgb_t bgcol, void* 
  userp);
 Input: (pos) Select menu entry in classic mode
 Valid values: 0-3
 (string) Menu entry for the key at specified 
 index
 (fgcol) Textcolor for the menu
 (bgcol) Background color for the menu
 (userp) A general purpose pointer for user-
 specific data
 Output: Always 0
 Semantics: Set specific menu entry in KEY_CLASSIC mode 
 (index given by pos). Color customization for 
 specific key is now possible (fgcol/bgcol). A 
 user-specific data can be linked to the menu 
 using userp pointer. Will also set the 
 LCD_SHOWMENU flag and refresh the LCD (if
 AUTOREFRESH flag is set).
 
 
int LCDList(listmenu_t *menulist);
 Input: (menulist) Listmenu to be used for display
 Output: Always return menulist value in form of an int 
 (typecast)
 Semantics: Setup the list menu display and update 
 appropriate info in the listmenu_t structure 
 pointed by menulist (e.g. scroll, count). 
 Will also set the LCD_LISTMENU flag and refresh 
 the LCD (if AUTOREFRESH flag is set).
 
 
int LCDSetList(listmenu_t *menulist);
 Input: (menulist) Listmenu to be used for display
 Output: Always 0
 Semantics: Unlike LCDList(), this will blindly assign 
 menulist to the mainlist for display. Doesn't 
 update anything in the menulist structure, nor 
 modify any internal flags. Useful to maintain 
 multiple lists fo menu display.
 
 
listmenu_t* LCDGetList(void);
 Input: None
 Output: Pointer to listmenu_t structure.
 Semantics: Get the currently active list menu.
 
 
menurect_t* LCDListBox(int pos);
 Input: (pos) Index of list item
 Output: Pointer to a menurect_t structure
 Semantics: Get the frame info of a specific list item in 
 form of a menurect_t structure.
 
 
menuitem_t* LCDListActiveItem(void);
 Input: None
 Output: Pointer to a menuitem_t structure
 Semantics: Get the selected menuitem in the list menu – 
 using index & start variable in listmenu_t. Will 
 return 0x0 (NUL) if no item is currently 
 selected.
 
 
int LCDListCount(void);
 Input: None
 Output: Number of list items (including title box)
 Semantics: Get the number of list items supported by the 
 current display (text) configuration. This 
 includes the item for title bar - thus, different 
 from count variable in listmenu_t as updated by 
 an LCDList() call.
 
int LCDListScroll(void);
 Input: None
 Output: 0 if scroll buttons are visible
 Non-zero if scroll buttons are visible
 Semantics: Get scroll visibility.
 
int LCDListIndex(int index);
 Input: (index) List index
 Output: List index
 Semantics: Set the list index.
 
int LCDListScrollUp(void);
 Input: None
 Output: Always 0
 Semantics: Scrolls the list display up. Menu index is not 
 altered. If the active menu item goes out of 
 focus, the index becomes negative (no item 
 selected).
 
int LCDListScrollDown(void);
 Input: None
 Output: Always 0
 Semantics: Scrolls the list display down. Menu index is not 
 altered. If the active menu item goes out of 
 focus, the index becomes negative (no item 
 selected).
 
 
Misc. LCD functions: 
 
rgb_t RGB2Col(byte_t R, byte_t G, byte_t B);
 Input: (R,G,B) 8-bit color data for respective channels
 Output: Single 24-bit RGB value (packed 32-bit)
 Semantics: Assemble given R,G,B data into 32-bit packed RGB 
 value.
 
 
void Col2RGB(rgb_t color, byte_t *R, byte_t *G, byte_t *B);
 Input: (color) 24-bit RGB color value
 (*R, *G, *B) pointers to separate R,G,B data 
 storage
 Output: None
 Semantics: Separate 32-bit packed RGB color data into 
 respective R, G, B channels.
 

Camera

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

 
Data types:
 
typedef struct _CAMSettings
{
 /* cam status - let the system manage these! */
 int width, height, length; /* frame info */
 int connected; /* availability */
}
CAMSettings;
 
 
CamHandle CAMInit (DeviceSemantics semantics);
 Input: (handle) handle of the desired camera
 Output: (return code) 
  255 = no camera connected
  240 = camera config error (ac97 gpio)
  220 = fpga mapping error
  200 = camera run/hold error
  0 = at least 1 camera connected
 Semantics: Configure & Initialize camera
 
int CAMRelease (CAMHandle handle);
 Input: NONE
 Output: (return code) 
  0 = success
 -1 = error
 Semantics: Release all resources allocated using CAMInit().
 
int CAMSelect (int cam);
 Input: (cam) camera number: 0 = LEFTCAM, 1 = RIGHTCAM
 Output: (return code) selected camera if OK, ERRORCAM on 
 error
 Semantics: Select active camera for next camera command
 
int CAMWhich (void);
 Input: NONE
 Output: (return code) selected camera 
 Valid values:  RIGHTCAM, 
 LEFTCAM
 Semantics: get the currently selected camera.
 
int CAMSet (CamHandle handle, CAMSettings *camset);
 Input:  (handle) handle of the desired camera
  (camset) pointer to structure containing frame
 and cam infos - width, height, length, 
 connected
 Output:  (return code): 
  Valid values: -1 = error
 0 = success
 Semantics:  Set camera hardware parameters
 
 
int CAMGet (CamHandle handle, CAMSettings *camset);
 Input:  (handle) handle of the desired camera
 (camset) pointer to CAMSettings structure
 Output:  (camset) pointer points to frame and cam infos – 
 width, height, length, connected
  (return code): -1 = error
  0 = success
 Semantics:  Get camera hardware parameters
 
 
int CAMGetFrameGray (CamHandle handle, BYTE *buf);
 Input: (handle) handle of the desired camera
  (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 
 
int CAMGetFrameRGB (CamHandle handle, BYTE *buf);
 Input: (handle) handle of the desired camera
 (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 
 
int CAMGetFrameBayer (CamHandle handle, BYTE *buf);
 Input: (handle) handle of the desired camera 
 (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
 
int CAMSetFPGA (FPGASettings *fpgaset);
 Input: (fpgaset) pointer to structure containing the 
 desired fpga image processing settings
 Output:  ??
 Semantics: Set the image processing functions on the fpga
 
int CAMGetFPGA (CamHandle handle, BYTE *buf);
 Input: (handle) handle of the desired camera
 (buf) pointer to image buffer 
 Output:  
 Semantics: Read the processed image from the fpga
 
 
int CAMMode (CamHandle handle, int mode);
 Input: (handle) handle of the desired camera
 (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

Data types:
 
typedef struct {
 char name[40];
 char mhz[20]; 
 char arch[20]; 
 char bogomips[20];
} info_cpu_t;
 
typedef struct {
 char total[40];
 char free[40]; 
} info_mem_t;
 
typedef struct {
 char num[20];
} info_proc_t;
 
typedef struct {
 char uptime[20];
 char vbatt[20];
 int vbatt_8;
} info_misc_t;
 
 
OS Functions:
 
char *OSVersion(void);
 Input: NONE
 Output: OS version
 Semantics: Returns string containing running RoBIOS 
  version.
 Example: "3.1b"
 
 
int OSMachineSpeed(void);
 Input: NONE
 Output: actual clockrate of CPU in Hz
 Semantics: Inform the user how fast the processor runs.
 
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.
 
char* OSMachineName(void);
 Input: NONE
 Output: Name of actual Eyebot
 Semantics: Inform the user with which name the Eyebot is
 titled
 
unsigned char OSMachineID(void);
  Input: NONE
 Output: ID of actual Eyebot
 Semantics: Inform the user with which ID the Eyebot is 
 titled
 
int OSError(char *msg, int number,BOOL deadend);
 Input: (msg) pointer to message
 (number) int number
 (deadend) switch to choose deadend or keywait
 Valid values are: 0 = no deadend
 1 = deadend
  Output: Always 0
 Semantics: Print message and number to display then
 stop processor (deadend) or wait for key
 
info_cpu_t *OSInfoCPU (void);
 Input: NONE
 Output: pointer to a structure (info_cpu_t) containing 
 the cpu infos
 Semantics: Collects infos about the CPU – name, speed, 
 architecture and bogusMips
 
info_mem_t *OSInfoMem (void);
 Input: NONE
  Output: pointer to a structure (info_mem_t) which 
 contains the memory infos
 Semantics: Collects infos about the memory
 
info_proc_t *OSInfoProc (void);
 Input: NONE
 Output: pointer to a structure (info_proc_t) which 
 contains the process infos
 Semantics: Collects infos about processes
 
info_misc_t *OSInfoMisc (void);
 Input: NONE
 Output: pointer to a structure (info_misc_t) which 
 contains the misc infos
 Semantics: Collects system’s miscellaneous infos – uptime, 
 vbatt
 
 

Multitasking

Data types:
 
// Thread control block
struct tcb {
 struct list_head list;
 pthread_t hThread;
 void code;     /* pointer to code */
 int pri; /* thread priority */
 int stat; /* thread status */
 char *name; /* thread name */
 int uid; /* UserID */
};
 
Functions:
 
int OSMTInit(BYTE mode);
 Input: (mode) operation mode
 Valid values are: COOP=DEFAULT,PREEMPT
 Output: Always 0
 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: Always 0
 Semantics: Set status of given thread to READY
 
int OSSuspend(struct tcb *thread);
 Input: (thread) pointer to thread control block
 Output: Always 0
 Semantics: Set status of given thread to SUSPEND
 
int OSReschedule(void);
 Input: NONE
 Output: Always 0
 Semantics: Choose new current thread
 
int OSYield(void);
 Input: NONE
 Output: Always 0
  Semantics: Suspend current thread and reschedule
 
int OSRun(struct tcb *thread);
 Input: (thread) pointer to thread control block
 Output: Always 0
 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: Always 0
 Semantics: Remove given thread and reschedule
 
int OSExit(int code);
 Input: (code) exit code
 Output: Always 0
 Semantics: Kill current thread with given exit code and 
 message
 
int OSPanic(char *msg);
 Input: (msg) pointer to message text
 Output: Always 0
 Semantics:  Multithreading error, print message to display 
 and stop multitasking 
 
int OSSleep(int n)
 Input: (n) number of 1/100 secs to sleep
 Output: Always 0
 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: Always 0
 Semantics: disable thread switching in preemptive mode
 
int OSPermit(void)
 Input: NONE
 Output: Always 0
 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:
----------
 
Data types:
 
typedef int TimerHandle;
typedef void (*TimerFnc)(void);
 
 
TimerHandle OSAttachTimer(int scale, TimerFnc function);
 Input: (scale) prescale value for 100Hz Timer (value 
 must be>0)
 (TimerFnc) function to be called periodically
 Output: (TimerHandle) handle to reference the IRQ-slot
 A value of 0 indicates an error 
 Semantics: Attach user functions (void function(void)) to 
  a 100Hz timer. 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 user function 
  from the 100Hz timer

RS-232

Valid serial port:
 SERIAL1
 SERIAL2
 
Valid serial speed:
 SER9600 
 SER19200 
 SER38400 
 SER57600 
 SER115200 
 SER230400 
 SER460800 
 SER1200  
 SER2400  
 SER4800 




Valid serial handshake options:
 NONE 
 RTSCTS
 
Functions:
 
int OSInitRS232(int baud,int handshake,int interface);
 Input: (baud) baud rate selection
 Valid values are: 
  SER1200, SER2400, 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-2
 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-2
 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-2
 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-2
 Output: (return code)
 0 = good
 1 = receive timeout error
 10 = illegal interface
 Semantics: Receive a character over rs232
 
int OSFlushInRS232(int interface);
 Input: (interface) serial interface
 Valid values are: SERIAL1-2
 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-2
 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 OSCloseRS232(int interface);
 Input: (interface) serial interface
 Valid values are: SERIAL1-2
 Output: (return code) 
 0 = good
 10 = illegal interface
 Semantics: Close the given serial port
 
 
int OSCheckInRS232(int interface);
 Input:  (interface) serial interface
  Valid values are: SERIAL1-2
 Output:  (return code) 
 >=0 = the number of chars currently available 
 in FIFO
  -1 = illegal interface
 Semantics:  Return number of chars currently available in the
  input buffer
 
int OSCheckOutRS232(int interface)
  Input:  (interface) serial interface
  Valid values are: SERIAL1-2
  Output: (return code)
   >=0 = the number of bytes in the output buffer
 -1 = illegal interface
  Semantics:  Return the number of chars currently in the 
 output buffer
 
 
int OSSetRTSRS232(int interface)
  Input:  (interface) serial interface
  Valid values are: SERIAL1-2
  Output:  (return code)
   0 = good
   10 = illegal interface
   Semantics:  Set the RTS hw flow control pin of the given 
 comport
 
 
int OSClearRTSRS232(int interface)
  Input: (interface) serial interface
  Valid values are: SERIAL1-2
  Output: (return code)
    0 = good
   10 = illegal interface
  Semantics: Clear the RTS hw flow control pin of the given
    comport
 
 
int OSGetCDRS232(int interface) 
  Input:  (interface) serial interface
  Valid values are: SERIAL1-2
  Output:  (return code)
   0 = no carrier detected
   1 = carrier detected
   10 = illegal interface
  Semantics:  Get carrier detect status of the given comport

Audio

Valid sample format: WAV or AU/SND (8bit, pwm or mulaw)
Valid sample rate: 5461, 6553, 8192, 10922, 16384, 32768 (Hz)
Valid tone range: 65 Hz to 21000 Hz
Valid tone length: 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 sample end
 
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 tone end
 
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 record end
 
 
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.

HDT entry:

# PSD Name | RegAddr | TableName
 
e.g.
 
PSD "FRT 1" 24 "PSD Table"
PSD "LEFT" 25 "PSD Table"

Functions

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 PSDGet(int psd);
 Input: (psd) the number of the psd to read
 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(int psd);
 Input: (psd) the number of the psd to read
 Output:  (return code) actual raw-data (not converted)
 Semantics: Delivers actual timestamp or raw-data measured 
 by the selected PSD
 

Servos and Motors

HDT entry for servos:

# Servo Name | Register | Cycle-time | Min-time | Max-time
 
e.g.
 
SERVO "KICKER" 2 20000 700 1700
SERVO "CAM-PAN" 3 20000 1700 700
 

HDT entry for motors:

# MOTOR Name | RegAddr | PWM cycle time | TableName
 
e.g.
 
MOTOR "Left Motor" 16 8000 "Motor Table"
MOTOR "Right Motor" 17 8000 "Motor Table"
 

HDT entry for encoders:

# ENCODER Name | RegAddr | Clicks per meter | MotorName
 
e.g.
 
ENCODER "Enc-L" 20 6540 "Left Motor"
ENCODER "Enc-R" 21 6540 "Right Motor
 
 
Functions for servos:
 
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
 
 
Functions for motors:
 
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. >0 error
 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
 
 
Functions for encoders:
 
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(QuadHandle handle);
 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 
 meter
 (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

Latches

Latches are low-level IO buffers. Eyebot M6 board has 16 latches (LATCH0 to LATCH15). LATCH0 to LATCH7 are connected to IOBANK0 of the IO buffer while LATCH8 to LATCH15 are connected to IOBANK1. The direction of each bank can be individually configured as input or output. However, the direction of the latches has to be configured to the same direction as the buffer bank it connected to.

Definitions and constants:

 
//IO buffer banks

#define IOBANK0 0

#define IOBANK1 1

//IO directions

#define IN 0

#define OUT 1

//IO signal levels

#define HIGH 1

#define LOW 0

#define SET HIGH

#define CLEAR LOW

int OSLatchInit(void);
 Input: NONE
 Output: Return code:
 0 = ok
 -1 = Initialization error
 Semantics: Initialize the digital IO, call this 
 before using any digital IO functions

int OSLatchSetup(int latchnum, int direction)
 Input: (latchnum) latch number. 
 Valid values:
 (direction) signal direction 
 Valid values:
 0 = input
 1 = output
 Output: Return code:
 0 = set latch successful
 -1 = error 
 Semantics: Setup the given latch as input or output
 
 
int OSLatchBankSetup(int banknum, int direction);
 Input: (banknum) bank number.
 Valid values:
  IOBANK0 (for LATCH0..LATCH7)
  IOBANK1 (for LATCH8..LATCH15)
 (direction) signal direction
 Valid values:
 IN = input
 OUT = output
 Output:  Return code:
 0 = set latch successful
 -1 = Unrecognized IO bank
 -2 = Error setting buffer direction
 Semantics: Setup the given io buffer bank as input or 
  output. Note: 
  LATCH0..LATCH7 are connected to IOBANK0
  LATCH8..LATCH15 are connected to IOBANK1

int OSLatchRead(int latchnum)
 Input: (latchnum) latch number to read
 Valid values:
  Output: Return latch status
 0 = low
 1 = high
 -1 = error 
 Semantics: Read content of the selected input latch
 
int OSLatchWrite(int latchnum, int state)
 Input: (latchnum) latch number to write
 Valid values:
 (state) state to be set to the selected out
 latch
 Valid values:
  0 = low
 1 = high
 Output: Return previous state of the selected output
 latch
 0 = low
 1 = high
 -1 = error 
 Semantics: Write to the selected output latch
 
 
int OSLatchCleanup(void)
 Input: NONE
 Output: NONE
 Semantics: Unmap the memory for digital IOs, call these 
 when the digital IOs functions are no longer 
 needed
 
 

Analog-Digital Converter

There are four ADC channels available on the EyebotM6 board. The ADC input pins are exposed at connector J5. ADC3 is used for battery level monitoring and should not be used for other measurement.

ADCHandle OSInitADC(char *devsemantics);
 Input: (devsemantics) desired ADC channel
  Valid values: “ADC0”, “ADC1”, “ADC2”, “ADC3”
 Output: (return code) >0: Handler for the adc channel
  0: Initialization error
 Semantics: Captures one single 10bit value from the 
  specified adc channel
 
 
int OSGetADC(ADCHandle adchandle);
 Input: (adchandle) Handler for the adc channel
 Output:  (return code) >0: 10 bit sampled value
 -1: invalid channel
 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 OSReleaseADC(ADCHandle adchandle);
 Input: (adchandle) Handler for the adc channel
 Output: (return code) Always 0
 Semantics: Release the adc channel

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.

 
Data Types:
 
   struct RadioIOParameters {
  int interface; /* SERIAL1, SERIAL2 or SERIAL3 */
  int speed; /* SER1200, SER2400, 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 */
 };
 
int RADIOInit(void);
 Input: NONE
 Output: (return code) 0 = OK
  255 = Error: Radio functions not 
 enabled (Radio-Key required)
 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.
 
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 "libM6irtv.h" 
#include "IRsupportplus.h"; /* depending on remote control used, e.g. 
 also "IRnokia.h" */
 
Definitions
 
/* Code types */
#define RAW_CODE 0 /* normally only used by the analyzer */
#define SPACE_CODE 1
#define PULSE_CODE 2
#define MANCHESTER_CODE 3
 
/* Modes */
#define DEFAULT_MODE 0
#define SLOPPY_MODE 1
#define REPCODE_MODE 2
 
#define PULSE 0 
#define SPACE 1
#define START_TTL 50 /* default "time to live" value *10ms */

HDT entry

#IRTV Name | Type | Length | TogMask | InvMask | Mode | BuffSize | Delay | TableName
 
e.g.
 
IRTV "SupportPlus" 3 14 0x1c00 0x000 1 1 50 " "
IRTV "Nokia VCN620" 1 15 0x0000 0x3FF 1 1 50 " "

Functions

int IRTVInit(char *semantics);
 Input:  (semantics) IRTV device name 
 (e.g. “SupportPlus”)
 Output: (return code) 0 = ok
 1 = HDT file error
 2 = invalid or missing "IRTV" HDT 
 entry for this semantics
 Semantics: Initializes the IR remote control decoder by 
 calling IRTVInit() with the device name found in 
 the corresponding HDT entry. 
 
int IRTVInitParam(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 = irtv initialization error
 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 IRTVRelease(void);
 Input: NONE
 Output: NONE
 Semantics: Terminates the remote control decoder and 
 releases the irtv thread.
 
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.
 
 
 

Appendix 1

Definitions and data types for Key functions:
 
/* pre-defined key constants - usable for standard & region map */
 
#define KEY1 0x00000001
#define KEY2 0x00000002
#define KEY3 0x00000004
#define KEY4 0x00000008
 
/* special keys (escape & list menu)! */
 
#define KEY_ESCAPE 0x80000000
#define KEY_LISTTL 0x40000000
#define KEY_LISTUP 0x20000000
#define KEY_LISTDN 0x10000000
 
/* special pre-defined key constants for standard list menu! */
 
#define KEY_LIST1 0x00000010
#define KEY_LIST2 0x00000020
#define KEY_LIST3 0x00000040
#define KEY_LIST4 0x00000080
#define KEY_LIST5 0x00000100
#define KEY_LIST6 0x00000200
#define KEY_LIST7 0x00000400
#define KEY_LIST8 0x00000800
 
/* key touchmap types/key modes */
 
#define KEYTM_UNKNOWN 0x00
#define KEYTM_CLASSIC 0x01
#define KEYTM_STANDARD 0x02
#define KEYTM_REGIONS 0x03
 
/* max keys (keycode_t <= 32-bit) */
#define KEYTM_MAX_REGIONS 32
 
/* key library states - arg for KEYIdle() */
 
#define KEY_GOIDLE 1
#define KEY_NOIDLE 0
#define KEY_STATE -1
 
/* reserve 0x0 for timed-out keycode! no key pressed! */
#define KEY_TIMEOUT 0x00000000
/* i assume 32 simultaneous keys is impossible! :p */
#define KEY_INVALID 0xFFFFFFFF
 
Data Types:
 
typedef unsigned char keymode_t;
typedef unsigned long keycode_t;
typedef struct timeval m6time_t;
 
typedef struct _coord_pair {
 int x, y;
} coord_pair_t;
 
typedef struct _m6key_box {
 int active;
 coord_pair_t tl; //top left
 coord_pair_t br; //bottom right
} m6key_box_t;
 
typedef struct _touch_map {
 keymode_t mode;
 m6key_box_t rect[KEYTM_MAX_REGIONS];
} touch_map_t;
 
typedef struct _touch_event {
 coord_pair_t point, value;
 struct timeval instant;
 int sync, status;
} touch_event_t;
 
 

Appendix 2

Definitions and data types for LCD functions:
 
/* constants for text colorflags */
 
#define LCD_BGCOL_TRANSPARENT 0x01
#define LCD_BGCOL_NOTRANSPARENT 0x10
 
#define LCD_BGCOL_INVERSE 0x02
#define LCD_BGCOL_NOINVERSE 0x20
 
#define LCD_FGCOL_INVERSE 0x04
#define LCD_FGCOL_NOINVERSE 0x40
 
/* constants for lcd modes */
 
#define LCD_AUTOREFRESH 0x0001
#define LCD_NOAUTOREFRESH 0x0100
 
#define LCD_SCROLLING 0x0002
#define LCD_NOSCROLLING 0x0200
 
#define LCD_LINEFEED 0x0004
#define LCD_NOLINEFEED 0x0400
 
#define LCD_SHOWMENU 0x0008
#define LCD_HIDEMENU 0x0800
 
#define LCD_SYSMENU 0x0010
#define LCD_STDMENU 0x1000
 
#define LCD_FB_ROTATE 0x0080
#define LCD_FB_NOROTATION 0x8000
 
/* constants for basic colors - https://www.w3.org/TR/CSS21/syndata.html */
 
#define LCD_WHITE 0xffffff /* ww3name */
#define LCD_SILVER 0xc0c0c0 /* ww3name */
#define LCD_LIGHTGRAY 0xc0c0c0
#define LCD_LIGHTGREY 0xc0c0c0
#define LCD_GRAY 0x808080 /* ww3name */
#define LCD_DARKGRAY 0x808080
#define LCD_DARKGREY 0x808080
#define LCD_BLACK 0x000000 /* ww3name */
 
#define LCD_BLUE 0x0000ff /* ww3name */
#define LCD_NAVY 0x000080 /* ww3name */
#define LCD_AQUA 0x00ffff /* ww3name */
#define LCD_CYAN 0x00ffff
#define LCD_TEAL 0x008080 /* ww3name */
#define LCD_FUCHSIA 0xff00ff /* ww3name */
#define LCD_MAGENTA 0xff00ff
#define LCD_PURPLE 0x800080 /* ww3name */
 
#define LCD_RED 0xff0000 /* ww3name */
#define LCD_MAROON 0x800000 /* ww3name */
#define LCD_YELLOW 0xffff00 /* ww3name */
#define LCD_OLIVE 0x808000 /* ww3name */
#define LCD_LIME 0x00ff00 /* ww3name */
#define LCD_GREEN 0x008000 /* ww3name */
 
/* constants - info for users */
 
#define LCD_MENU_ITEMCOUNT 4 /* classic menu! should sync with key lib! */
#define LCD_MENU_STRLENGTH 32 /* for storage declaration */
#define LCD_MENU_ROWHEIGHT 3 /* text rows used for classic menu! */
#define LCD_LIST_STRLENGTH 64 /* for storage declaration */
#define LCD_MENU_BGCOL LCD_BLUE /* default menu bgcolor */
#define LCD_MENU_FGCOL LCD_SILVER /* default menu fgcolor */
 
Data types:
 
/* basic typedefs */
 
typedef unsigned char byte_t;
typedef unsigned short hword_t;
typedef unsigned int word_t;
typedef unsigned int rgb_t;
 
/* data structures' typedefs */
 
typedef struct {
 int xres, yres;
 int bpp;
} screen_t;
 
typedef struct {
 int x, y;
 int xmax, ymax;
} cursor_t;
 
typedef struct {
 screen_t screen;
 cursor_t cursor; 
} fbinfo_t;
 
typedef struct {
 int x1, y1, x2, y2;
} rect_t;
 
typedef rect_t menurect_t;
 
typedef struct {
 char label[LCD_MENU_STRLENGTH];
 rgb_t fgcol, bgcol;
 void *plink; /* link to user data/function! */
} menuitem_t;
 
typedef struct {
 char title[LCD_LIST_STRLENGTH];
 rgb_t fgcol, bgcol;
 int size, start, width, left, scroll; /* configure these! */
 int index, count; /* the library will set & manage these! */
 menuitem_t *pitems; /* pointer to array of 'size' menuitems */
} listmenu_t;
 
 
 
 

---

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