LegOS Command Reference 1.0 + epsilon

(for LegOS Version 0.2.4 + epsilon)

The history and development of LegOS as been a feat of amazing ingenuity and engineering prowess. However, documentation for LegOS 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 main C (User level) commands available to the LegOS programmer to directly control the RCX via LegOS. This is a distilled down list obtained from the LegOS File Members document. Please consult the LegOS Source Forge Repository as the definitive reference.

Hopefully, when the new Extreme Mindstorms book is available, this document will be made obsolete as we will now have a really professionally written and definitive listing and explanation of the inner workings of LegOS. In the meantime, this is my humble contribution to the LegOS community for giving me such an intriguing new toy to play with.

Enjoy,
Dave Chen 10/29/2000

Display

Display positions

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

Native segment masks

In these bitmasks, bit 0 toggles the middle segment. Bit 1 toggles the top right segment, and the remaining segments are denumerated counterclockwise. The dot isn't encoded.

• void cls ()
  Clear user portion of screen.: conio.h, conio.c
• void cputs (char * s)
  Parameters: s the string
  Display an ASCIIZ string, only the first 5 characters will be displayed. if there are less than 5 characters, the remaining display positions will be cleared. : conio.h, conio.c
• void cputw (unsigned word)
  Parameters: word the hexword
  Display a hexword, position 0 not used.: conio.h, conio.c
• void cputc_hex_X (unsigned nibble c)
  void cputc_hex (char c, int X)
  Parameters: c hex number to display at position X.: conio.h
• void lcd_int (int i)
  Parameter: i integer to display, position 0 not used.: lcd.h
• void lcd_unsigned(unsigned int u)
  Parameter: u integer to display, position 0 not used.
  Display an unsigned value in decimal.: lcd.h
• void lcd_digit(int i)
  Parameter: i integer to display at position 0.: lcd.h
• void lcd_clock(int i)
  Parameter: i will be displayed with the format XX.XX
• void lcd_number (int i, lcd_number_style n, lcd_comma_style c)
  Number Style:  digit, sign, unsign
  Comma Style:  e0, e_1, e_2, e_3
  Parameters: i the integer to be shown, n the number style, c the comma style.: lcd.h
• void lcd_hide(char mask)
  void lcd_show(char mask)
  Parameters:  mask see Mask listing below
  Display native mode segment mask at display position X.: lcd.h
  LCD mask definitions:
  • 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

LNP - LegOS Network Protocol

Currently the best documentation on LNP is in Louis Villas LegOS HOWTO.

LNP has two layers, the lower integrity layer provides uncorrupted transmission of messages, the upper adressing layer adds adressing of packages to ports. Arriving packages are handled by packet handlers that the user must provide. A packet handler for adressing layer has the general form
void my_addr_handler(const unsigned char *data, unsigned char length, unsigned char src)
and for the logical level
void my_int_handler(const unsigned char *data, unsigned char length).

• void lnp_integrity_set_handler (lnp_integrity_handler_t handler)
  set the integrity layer packet handler.
• void lnp_addressing_set_handler (unsigned char port, lnp_addressing_handler_t handler)
  set an addressing layer packet handler for a port.
• int lnp_integrity_write (const unsigned char *data, unsigned char length)
  send a LNP integrity layer packet of given length.
• int lnp_addressing_write (const unsigned char *data, unsigned char length, unsigned char dest, unsigned char srcport)
  send a LNP addressing layer packet of given length.
• void lnp_logical_fflush()
  Flush the Input Buffer: lnp-logical.h
• void lnp_logical_range(int i)
  Parameter: i sets Range for IR:  0 = Short Range, 1 = Long Range
  : lnp-logical.h
• int lnp_logical_range_is_far()
  Returns the IR Range setting.: lnp-logical.h
• int lnp_logical_write(const void* buf,size_t len)
  Parameter: buf string of length len is written to the IR Port: lnp-logical.h

Memory Management and String Operations

• void free(void *the_ptr)
  Free block of memory pointed to by the_ptr.: stdlib.h, mm.c
• void *calloc(size_t nmemb, size_t size)
  Allocate adjacent blocks of memory, nmemb number of blocks of size individual block size.: stdlib.h, mm.c
• void *malloc(size_t size)
  Allocate a block of memory.: stdlib.h, mm.c
• void *memcpy(void *dest, const void *src, size_t size)
  dest = destionation address, src = source address, size number of bytes to copy : string.h
• void *memset(void *s, int c, size_t n)
  Fill memory block at address s with byte value c, n is the number of bytes of c to fill. string.h
• int strcmp(const char *s1, const char *s2)
  Compare two NULL terminated strings, returns: <0: s1<s2, = 0: s1==s2, >0: s1>s2 : string.h
• char *strcpy(char *dest, const char *src)
  Copy NULL-terminated string from src to dest, returns pointer to dest.: string.h
• int strlen(const char *s)
  Returns length of NULL-terminated string s : string.h
• NULL
  Null memory pointer constant.: mem.h

Motor Control

• void motor_a_dir(enum MotorDir)
  void motor_b_dir(enum MotorDir)
  void motor_c_dir(enum MotorDir)
  Parameter: MotorDir Enumerated as:  off = 0, fwd = 1, rev = 2, brake = 3
  Set the motor direction.: dmotor.h
• void motor_a_speed(int speed)
  void motor_b_speed(int speed)
  void motor_c_speed(int speed)
  Parameter: speed sets the PWM output to the specified motor.
  MAX_SPEED = Constant for upper limit of motor speed
  MIN_SPEED = Constant for lower limit of motor speed.: dmotor.h

RCX Button Input

• char getchar()
  Returns one of the Enumerated KEY types:  KEY_ONOFF, KEY_PRGM, KEY_RUN, KEY_VIEW
  Input is debounced in dkey routines (unlike dbutton).: dkey.h, dkey.c
• event wakeup_t dkey_pressed() : dkey.h, dkey.c
• event wakeup_t dkey_released() : dkey.h, dkey.c
• Enumerated KEY types:  KEY_ANY, KEY_ONOFF, KEY_PRGM, KEY_RUN, KEY_VIEW

Semaphores

This section was updated by Tobias Amnell since the original author did not write anything here. Semaphores are counters that can be used to guard resources shared between threads. The implementation of semaphores in legOS follows the standard POSIX 1003.1b.

• int sem_destroy(sem_t* sem)
  Destroy a semaphore sem. Not actually implemented in legOS (only for compatibility with POSIX): semaphore.h
• int sem_getvalue(sem_t * sem, int *sval)
  stores in the location pointed to by sval the current count of the semaphore sem.: semaphore.h
• int sem_init(sem_t * sem, int pshared, unsigned int value)
  Initialise the semaphore pointed to by sem with value. pshared ignored (present for compatibility with POSIX): semaphore.h
• int sem_post(sem_t * sem)
  atomically increases the count of the semaphore pointed to by sem. This function never blocks and can safely be used in asynchronous signal handlers.: semaphore.h, semaphore.c
• typedef unsigned char sem_t
  the semaphore type : semaphore.h
• int sem_trywait(sem_t * sem)
  is a non-blocking variant of sem_wait. If the semaphore pointed to by sem has non-zero count, the count is atomically decreased and sem_trywait immediately returns 0. If the semaphore count is zero, sem_trywait immediately returns with error EAGAIN. : semaphore.h, semaphore.c
• int sem_wait(sem_r* sem)
  suspends the calling thread until the sempahore pointed to by sem has non-zero count. It then atomically decreases the semaphore count.: semaphore.h, semaphore.c
• EAGAIN=Constant returned by sem_trywait when count is zero.semaphore.h

Sensors

Defined Constants:  LIGHT_RAW_BLACK =  0xffc0 (active light sensor raw black value), LIGHT_RAW_WHITE = 0x5080 (active light sensor raw white value).  LIGHT_MAX = maximum decoded value at LIGHT_RAW_WHITE using the formula SCALED_LIGHT_READING = (147 - (RAW_LIGHT_READING >> 6) / 7).

• DS_ALL_ACTIVE
  Macro to set all Sensors ACTIVE: dsensor.c
• DS_ALL_PASSIVE
  Macro to set all Sensors PASSIVE: dsensor.c
• void ds_active(SENSOR)
  void ds_passive(SENSOR)
  Parameter: SENSOR = (&SENSOR_1, &SENSOR_2, &SENSOR_3) to active or passive type: dsensor.h
• void ds_rotation_off(SENSOR)
• void ds_rotation_on(SENSOR)
  Parameter: SENSOR = (&SENSOR_1, &SENSOR_2, &SENSOR_3) turns Rotation track off/on: dsensor.h
• void ds_rotation_set(SENSOR, int i)
  Sets Rotation SENSOR to arbitrary reading i : dsensor.h, dsensor.c
• boolean TOUCH_1, TOUCH_2, TOUCH_3
  Processed Touch Sensor reading: dsensor.h
• int LIGHT_1, int LIGHT_2, int LIGHT_3
  Scaled SENSOR reading.: dsensor.h
• int ROTATION_1, ROTATION_2, ROTATION_3
  Processed Rotation Sensor reading: dsensor.h
• int SENSOR_1, SENSOR_2, SENSOR_3
  Raw Sensor Input reading: dsensor.h
• int get_battery_mv()
  Get Battery level in XXXX mV: battery.h, battery.c
• int BATTERY
  Raw Battery Voltage level: dsensor.h

Sound

• void dsound_system(SOUND)
• Pre Defined System SOUND:  DSOUND_BEEP : dsound.h
• Event 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.: dsound.h
• void dsound_play(const note_t *notes)
  Parameter: notes array of note_t as defined below:
  Note Data Type:
  typedef struct {
    unsigned char pitch;      //!< note pitch, 0 ^= A_0 (~55 Hz)
    unsigned char length;     //!< note length in 1/16ths
  } note_t;: dsound.h
  • 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 : dsound.h

Task Management

• void tm_start()
  Start Task Manager: tm.h, tm.c
• typedef size_t pid_t
  the process (thread) id type: tm.h
• pid_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 PID.: unistd.h, tm.c
• void exit(int code)
  Exits Process, returning code.: unistd.h, tm.c
• void kill(pid_t PID)
  Kill Process associated with PID as assigned when it was started by execi(): unistd.h, tm.c
• void killall(priority_t p)
  Kill all Processes with a Priority less than p: unistd.h, tm.c
• 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.: unistd.h, tm.c
• Predefined Priority Levels:  P_DEAD, P_RUNNING, P_SLEEPING, P_WAITING, P_ZOMBIE, PRIO_HIGHEST, PRIO_LOWEST, PRIO_NORMAL : tm.h

Miscellaneous

• void main()
  Main entry point into the User Program.: kmain.c
• unsigned int sleep(unsigned int sec)
  Pause for sec seconds.
  (NOT IMPLEMENTED: Returns 0 if uninterrupted, otherwise returns number of sec until interrupted): unistd.h, tm.c.
• unsigned int msleep(unsigned int msec)
  Pause for msec milliseconds before executing next commands in current thread, other thread will continue to execute commands uneffected.
  (NOT IMPLEMENTED: Returns 0 if uninterrupted, otherwise returns number of msec until interrupted): unistd.h, tm.c
• void delay (unsigned d)
  uncalibrated (busy) delay loop: conio.h
• void power_off()
  Initiates Software Standby/Low Power mode.  On/Off button will reactivate.: system.h
• void program_run(unsigned P)
  Execute Program in slot number P.: program.c
• void reset()
  Returns control to ROM, ie. Cold Boot.: system.h
• long int random()
  Returns a random integer.: stdlib.h
• void srandom(unsigned int seed)
  Seeds the Random Number Generator.: stdlib.h
• long int sys_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: time.h, systime.c