Introduction
The history and development of LegOS (now evolved into BrickOS) as been a feat of amazing ingenuity and engineering prowess. However, documentation for LegOS/BrickOS for the novice user has been difficult to come by since it's inception. This is probably rooted in the fact that from the beginning, this has been an "expert's only" development; developed by hardcore hackers/ programmers/hardware gurus for those with the same inclination. Consequently, much of the documentation available has been through the automatically generated API docs, which are often difficult to wade through.

This document hopes to list and outline the basic and most useful C (User level) commands available to the BrickOS programmer to directly control the RCX via BrickOS. Lower level functions are avoided and this reference is by no means comprehensive. The information was distilled down from the Documentation for C coders document. Please consult the BrickOS Documentation at the Source Forge Repository as the definitive reference.

A few function calls and API's have changed since I last released the original version of this document for LegOS 0.2.4. It has been a long time since I've had a chance to play around with BrickOS (switched over to Mac OS X and had a heck of a time getting a working development environment up and running) and I thought going through the API's would get me back up to speed. I thought since I'm doing this for myself, why not update the old command reference? This is work in progress, any contributions/help/suggestions/corrections would be greatly appreciated. Thus, this is my humble contribution to the wonderful BrickOS community.

Enjoy,

Dave Chen
BrickOS (at) DaveChen (dot) org

(Original Document: v1.0-10/29/2000, Updated v2.0-7/28/2004)

Contents

• Main Program and Miscellaneous Information
• Memory Management
• Task Management
• Reading and Controlling Sensors
• Controlling Motors
• Controlling the RCX LCD Display
• Reading RCX Buttons
• Making Sounds

• Index of functions/constants/global variables by header file
  (External link to the BrickOS.SourceForge.Net web site).

ToDo:

1. Provide more code examples, especially code examples for Thread management and Event based program/thread control.
2. Document LegOS Networking Protocol (LNP) and its functions. I haven't used LNP at all so I need some help with if anyone wants to give me a hand.
3. Document Semaphore.h - again, I don't know much about using Semaphores for Inter Process Communications so I would need help writing this section.
4. Document the newer BrickOS features like dirpd.h (Techno-Stuff 2 channel IR Proximity Sensor support), swmux.h (Techno-Stuff sensor multiplexor support), remote.h (LEGO IR Remote subsystem)
5. Provide more crossreferenced links back to the BrickOS Sourceforge documentation

Main Program and Miscellaneous Information

• void main ( )
  Main entry point for BrickOS programs.

• __persistent
  This macro is used to mark initialized data (doesn't apply to uninitialized data) as `persistent' data. This data will be saved across different runs of the program.
  Usage: You should insert __persistent between the variable name and equal sign followed by value, e.g:

  static int counter __persistent = 0; static char data[] __persistent = { 0x32, 0x36, ... };

• int sleep(int sec);
  
• int msleep(int msec);
  Pause for an interval of time before executing next commands in current program thread, other program threads will continue to execute commands. Gives up CPU time for other threads.

• void power_off ( );
  Initiates Software Standby/Low Power mode. On/Off button will reactivate RCX
• void power_init ( );
  Disables Software Standby/Low Power mode so tm_idle_task ( ) can use the sleep

• void reset ( );
  Erases BrickOS and returns control to ROM, ie. Cold Boot
• void rom_reset ( );
  Turns off interrupts, then issues a reset

• int random ( );
  Returns a random integer
• void srandom (int seed);
  Seeds the Random Number Generator

• long int get_system_up_time ( );
  Current System Time (Time up from last firmware d/l and boot up) in msec. This is a 32 bit value which will overflow after 49.7 days of continuous operation

• void program_run (unsigned P);
  Execute Program in slot number P. An Old function, was defined in program.c from LegOS, not sure if it is still present in BrickOS

  References:
  stdlib.h system.h time.h unistd.h

Memory and String Management

• void * calloc (size_t nmemb, size_t size);
  Allocate and return pointer to initialized memory

• void * malloc (size_t size);
  Allocate and return pointer to un-initialized memory

• void free (void * ptr);
  Free up and return the allocated memory to memory management

• void * memcpy (void * dest, const void * src, size_t size);
  Copy Memory block from src to dest

• void * memset (void * s, int c, size_t n);
  Fill Memory block at * s with byte value c, n is the number of bytes of c to fill

• char * strcpy (char *dest, const char *src);
  Copy NULL-terminated string from src to dest, returns pointer to dest

• int strlen (const char *s);
  Returns length of NULL-terminated string

• int strcmp (const char *s1, const char *s2);
  Compare two NULL terminated strings, returns: <0: s10: s1>s2

  References:
  stdlib.h string.h

Task Management

Under BrickOS, what were Processes defined as functions and initialized/run within main( ) are now referred to as Threads. The syntax of defining and using threads can get a bit trick. Refer to this sample code for a working example on how to implement Threads:

---

#include unistd.h
#include dbutton.h
#include dmotor.h


int MotorSpeed = 0;

int RunMotor() {
while (!shutdown_requested())
{
motor_a_dir(MotorSpeed);
}
return 0;
}

int CheckButton() {
while (!shutdown_requested())
{
if (PRESSED(dbutton(),BUTTON_PROGRAM)) MotorSpeed = 1;
else MotorSpeed = 0;
}
return 0;
}

int main() {
execi(&CheckButton, 0, NULL, 1, DEFAULT_STACK_SIZE);
execi(&RunMotor, 0, NULL, 1, DEFAULT_STACK_SIZE);

while(!shutdown_requested())
msleep(1000);

return 0;
}

---

• (int)tid_t execi (&PROCESS_NAME, int argc, char **argv, priority_t priority, size_t stack_size);
  Place function PROCESS_NAME into the Process queue, returns the Process's assigned Thread ID or -1 if thread failed to start
  Example: execi(&RunMotor, 0, NULL, 1, DEFAULT_STACK_SIZE);
  Starts function RunMotor as a thread, with no parameters passed (0, NULL), at the lowest priority (1), with the DEFAULT_STACK_SIZE of 512 being used. The thread ID is passed back, but in this case it is not being stored, but it could have been assigned to a variable type tid_t to keep track of various thread.

• wakeup_t wait_event (wakeup_t (* wakeup)(wakeup_t), wakeup_t data);
  Suspend task until wakeup function returns a non-NULL Parameters:
  • wakeup the function to be called when woken up
  • data the wakeup_t structure to be passed to the called function

• void exit (int code);
  Exits Process, returning code

• void kill (tid_t TID);
  Kill Thread associated with (int)tid_t TID as assigned when it was started by execi ( )

• void killall (priority_t p);
  Kill all Processes with a Priority less than p

• void shutdown_task (tid_t TID);
  Shutdown Thread associated with tid_t TID wakeup_t wait_event(wakeup_t(*wakeup) (wakeup_t), wakeup_t data); Suspend current Process until Event wakeup function is non-null: unistd.h, tm.c

• void yield ( );
  Yield the rest of the current Task's timeslice

• int sleep(int sec);
  
• int msleep(int msec);
  Pause for an interval of time before executing next commands in current program thread, other program threads will continue to execute commands. Gives up CPU time for other threads.

  Predefined Priority Levels:

  • PRIO_LOWEST = 1 The Lowest possible Task Priority
  • PRIO_NORMAL = 10 The Priority of most Tasks
  • PRIO_HIGHEST = 20 The Highest Task Priority

  Task Status

  • T_DEAD = Dead and Gone, Stack Freed
  • T_RUNNING = Running
  • T_SLEEPING = Sleeping, waiting to Run
  • T_WAITING = Waiting for an Event
  • T_ZOMBIE = Terminated, Cleanup Pending
  • T_IDLE = IDLE Task
  • T_KERNEL = Kernel Task
  • T_USER = USER Task

  References:
  tm.h unistd.h

Reading and Controlling Sensor

Setting Sensor Modes - must set sensor mode explicitly before attempting to read Sensors or values may be unreliable.
• void ds_active(volatile unsigned * sensor);
  
• void ds_passive(volatile unsigned * sensor);
  Set sensor (possible values: &SENSOR_1, &SENSOR_2, &SENSOR_3) to active or passive type. Light sensor emits light in active mode, rotation modes requires active mode.

  Rotation Sensor

• void ds_rotation_on(volatile unsigned * sensor);
  
• void ds_rotation_off(volatile unsigned * sensor);
  Start/Stop tracking on the Rotation Sensor sensor (possible values: &SENSOR_1, &SENSOR_2, &SENSOR_3)
• void ds_rotation_set(volatile unsigned * sensor, int pos);
  Set Rotation Sensor sensor to an absolute value pos, the rotation sensor should be stationary during the function call

  Reading Sensor Values (defined Macro) for each sensor pad 1, 2 or 3

• int SENSOR_1
• int SENSOR_2
• int SENSOR_3
  Raw Sensor Input reading

• int LIGHT_1
• int LIGHT_2
• int LIGHT_3
  Value for light sensor on pads 1, 2, or 3. Scaled to a maximum decoded value of LIGHT_RAW_WHITE using the formula (147 - (RAW_LIGHT_READING >> 6) / 7)
  Associated Defined Constants:
  • LIGHT_RAW_BLACK = 0xffc0 (active light sensor raw black value)
  • LIGHT_RAW_WHITE = 0x5080 (active light sensor raw white value)

• boolean TOUCH_1
• boolean TOUCH_2
• boolean TOUCH_3
  Returns value 1=pushed in/on, 0=not pushed/off for a touch sensor on sensor pads 1, 2, or 3

• int ROTATION_1
• int ROTATION_2
• int ROTATION_3
  Rotation Sensor reading

  Older Macros/functions from LegOS (have to check if they're still in BrickOS)

• DS_ALL_ACTIVE
  Macro to set all Sensors ACTIVE: dsensor.c
• DS_ALL_PASSIVE
  Macro to set all Sensors PASSIVE: dsensor.c

• int get_battery_mv();
  Get Battery level in XXXX mV: battery.h, battery.c
• int BATTERY
  Raw Battery Voltage level: dsensor.h

  References:
  dsensor.h

Controlling Motors

Set Motor Direction
• void motor_a_dir(enum MotorDir)
  
• void motor_b_dir(enum MotorDir)
  
• void motor_c_dir(enum MotorDir)
  The direction MotorDir is enumerated as: off/freewheeling = 0, fwd = 1, rev = 2, brake = 3

  Set the motor Speed

• void motor_a_speed(int speed)
  
• void motor_b_speed(int speed)
  
• void motor_c_speed(int speed)
  Set Motor to speed a value between 0-255

  Defined Constants:

  • MAX_SPEED = 255 Constant for upper limit of motor speed
  • MIN_SPEED = 0 Constant for lower limit of motor speed

  References:
  dmotor.h

Controlling the RCX LCD Display

Digit display positions are denumerated from right to left, starting with 0 for the digit right of the running man. Digit 5 is only partially present on the RCXs display.

• void cls ();
  Clear user portion of screen

• void lcd_unsigned(unsigned int u);
  Display unsigned value u in decimal, position 0 not used.

• void lcd_digit(int i);
  Display single digit of integer i at position 0 (right of the man symbol)

• void lcd_clock(int i);
  Displays i with the format XX.XX
• void lcd_number (int i, lcd_number_style n, lcd_comma_style c);
  Displays integer i with the following characteristics:
  • Number Style: digit, sign, unsign
    
  • Comma Style: e0, e_1, e_2, e_3
    

• void delay (unsigned ms);
  Set Display Delay to approximately ms mSec

• void cputs(char * s);
  Write string s to LCD (only forst 5 characters)

• void cputw(unsigned word);
  Write a HEX word to LCD (only forst 5 characters)

• void cputc (char c, int pos);
  Write ASCII character to specified position of LCD. (this is essentially a dispatcher for cputc_[0-5] functions)
  Parameters:
  • c the ASCII char to be displayed
  • pos the location at which to display the ASCII char

• void cputc_0(unsigned c);
  Write ASCII char c to position 0 of LCD
• void cputc_1(unsigned c);
  Write ASCII char c to position 1 of LCD
• void cputc_2(unsigned c);
  Write ASCII char c to position 2 of LCD
• void cputc_3(unsigned c);
  Write ASCII char c to position 3 of LCD
• void cputc_4(unsigned c);
  Write ASCII char c to position 4 of LCD
• void cputc_5(unsigned c);
  Write ASCII char c to position 5 of LCD

• void cputc_hex(char c, int pos);
  Write HEX digit to specified position of LCD. (this is essentially a dispatcher for cputc_hex_[0-5] functions) Parameters:
  • c the HEX digit to be displayed
  • pos the location at which to display the HEX digit

  • void cputc_hex_0(unsigned nibble);
    Write HEX digit nibble to position 0 of LCD
  • void cputc_hex_1(unsigned nibble);
    Write HEX digit nibble to position 1 of LCD
  • void cputc_hex_1(unsigned nibble);
    Write HEX digit nibble to position 1 of LCD
  • void cputc_hex_1(unsigned nibble);
    Write HEX digit nibble to position 1 of LCD
  • void cputc_hex_1(unsigned nibble);
    Write HEX digit nibble to position 1 of LCD

• void cputc_native(char mask, int pos);
  Set/Clear individual segments at specified position of LCD (this is essentially a dispatcher for cputc_native_[0-5] functions)

• macro dlcd_show(char mask); Shows a specific Segment Mask by writing directly to the LCD display buffer
• macro dlcd_hide(char mask); Hides a specific Segment Mask by writing directly to the LCD display buffer The kernel will refresh the display automatically every 100ms. Force display updates with lcd_refresh() after usint these macros.

• void lcd_refresh ( );
  Forces refresh of LCD from buffer contents

  Parameters:

  • mask the segment pattern to be displayed
  • pos the location at which to display the segment pattern

  • void cputc_native_0(char mask);
    Write segment pattern mask to position 0 of LCD
  • void cputc_native_1(char mask);
    Write segment pattern mask to position 1 of LCD
  • void cputc_native_2(char mask);
    Write segment pattern mask to position 2 of LCD
  • void cputc_native_3(char mask);
    Write segment pattern mask to position 3 of LCD
  • void cputc_native_4(char mask);
    Write segment pattern mask to position 4 of LCD
  • void cputc_native_5(char mask);
    Write segment pattern mask to position 5 of LCD

    Segment Masks

    • LCD_0_BOT, LCD_0_BOTL, LCD_0_BOTR, LCD_0_MID, LCD_0_TOP, LCD_0_TOPL, LCD_0_TOPR
    • LCD_1_BOT, LCD_1_BOTL, LCD_1_BOTR, LCD_1_MID, LCD_1_TOP, LCD_1_TOPL, LCD_1_TOPR
    • LCD_2_BOT, LCD_2_BOTL, LCD_2_BOTR, LCD_2_MID, LCD_2_TOP, LCD_2_TOPL, LCD_2_TOPR
    • LCD_3_BOT, LCD_3_BOTL, LCD_3_BOTR, LCD_3_MID, LCD_3_TOP, LCD_3_TOPL, LCD_3_TOPR
    • LCD_4_BOT, LCD_4_BOTL, LCD_4_BOTR, LCD_4_MID, LCD_4_TOP, LCD_4_TOPL, LCD_4_TOPR
    • LCD_5_MID
    • LCD_2_DOT, LCD_3_DOT, LCD_4_DOT
    • LCD_A_LEFT, LCD_A_RIGHT, LCD_A_SELECT
    • LCD_B_LEFT, LCD_B_RIGHT, LCD_B_SELECT
    • LCD_C_LEFT, LCD_C_RIGHT, LCD_C_SELECT
    • LCD_CIRCLE_0, LCD_CIRCLE_1, LCD_CIRCLE_2, LCD_CIRCLE_3
    • LCD_BATTERY_X
    • LCD_ARMS, LCD_1LEG, LCD_2LEGS, LCD_BODY
    • LCD_DOT_0, LCD_DOT_1, LCD_DOT_2, LCD_DOT_3, LCD_DOT_4,
    • LCD_IR_LOWER, LCD_IR_UPPER
    • LCD_EMPTY_1, LCD_EMPTY_2

  References:
  conio.h lcd.h

Reading RCX Buttons

Functions to directly read the state (de-bounced) of the 4 RCX Control buttons
• int getchar( )
  Wait for a Keypress and return the Key Code

• wakeup_t dkey_pressed ( wakeup_t data )
  Wakeup if any of the keys is pressed

• wakeup_t dkey_released ( wakeup_t data )
  Wakeup if any of the keys is released

  Current Key activity can also be derived by checking one of the following variables:

• volatile unsigned char dkey
  The current single key pressed
• volatile unsigned char dkey_multi
  The currently active keys, multiple keys readable as a bitmask

  Values as defined by the following constants:

  
  KEY_ONOFF (0x01) the on/off key is pressed
  KEY_RUN (0x02) the run key is pressed
  KEY_VIEW (0x04) the view key is pressed
  KEY_PRGM (0x08) the program key is pressed
  KEY_ANY (0x0f) any of the keys
  To Read the Raw status of the RCX Control buttons:

• int dbutton(void);
  Get Button States, note: this function does not return a de-bouced output, better to use the functions from dkey.h listed above.
  

  Macros for polling the state of these buttons:

• RELEASED(state, button) ((state) & (button))
  True if any of the specified buttons is released
• PRESSED(state, button) (!RELEASED(state,button))
  True if all of the specified buttons are pressed

  BUTTON_ONOFF (0x0002) the on/off button
  BUTTON_RUN (0x0004) the run button
  BUTTON_VIEW (0x4000) the view button
  BUTTON_PROGRAM (0x8000) the program button

  References:
  dkey.h

Making Sounds

• void dsound_system (SOUND);
  Play Pre Defined System SOUND:Ê DSOUND_BEEP

• int dsound_finished ( );
  Returns a Non-Zero if sound has finished playing.: dsound.h

• int dsound_playing ( );
  Returns nonzero value if a sound is playing: dsound.h

• void dsound_stop ( );
  Stop playing current sound/song

• void dsound_play(const note_t *notes);
  Plays notes an array of note_t as defined below:

  typedef struct {
unsigned char pitch; //!< note pitch, 0 ^= A_0 (~55 Hz)
unsigned char length; //!< note length in 1/16ths
} note_t;


  Pre Defined Note Lengths: WHOLE, HALF, QUARTER, EIGHTH
  Pre Defined Pitches (Octave X = 0-7):

  PITCH_AX, PITCH_AmX, PITCH_CX, PITCH_CmX, PITCH_DX, PITCH_DmX, PITCH_EX, PITCH_FX, PITCH_FmX, PITCH_GX, PITCH_GmX, PITCH_HX, PITCH_END, PITCH_MAX, PITCH_PAUSE

  References:
  dsound.h

Back to Contents

Command Reference copyright 2004 by David C. Chen (all rights reserved).