LegOS Commands Reference 1.0-0.2.4

(for LegOS Version 0.2.4)

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.

LNP - LegOS Network Protocol

Don't have much information about this section yet, anyone who can shed some light on what LNP functions are present and how they work, please let me know.
  • 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

    I'm not really familiar with Posix Semaphores, if someone is willing to shed light on this it would be helpfull.
  • sem_destroy() : semaphore.h
  • sem_event_wait() : semaphore.c
  • sem_getvalue() : semaphore.h
  • sem_init() : semaphore.h
  • sem_post() : semaphore.h, semaphore.c
  • sem_t : semaphore.h
  • sem_trywait() : semaphore.h, semaphore.c
  • sem_wait() : semaphore.h, semaphore.c

    • 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).

    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
  • (int)pid 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(int 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

    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.