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
Based on Dave's great work I have added
some information on LNP and semaphores that was not so well documented. I'm also
trying to upgrade the refernce to version 0.2.6 Tobias Amnell
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
legOS-0.2.4 is released under the Mozilla
Public License. Original code copyright 1998-1999 by the authors.
Command Reference copyright 2000 by David C. Chen.