Primitives and Macros

The following Sections list the available primitives and macros. LLAMA, as FORTH upon which it is based, only recognizes numbers, primitives and macros (called secondaries in FORTH) as valid inputs.  All numbers which are input are placed onto a stack or LIFO (Last-in First-Out) buffer.  Primitives and macros operate upon the numbers on the stack.  Primitives in LLAMA directly execute a C functions.  An assembled macro contains a sequence of numbers, macros and/or primitives.

Instruction Set and Syntax

LLAMA, like FORTH, has two main modes, definition and interpretation.  When first started, LLAMA is in interpretation mode (do not confuse this with “inter” and “work”).

If the system is in “work” mode, then each token received is executed as received.  If it is in “inter” mode one line of  tokens is accumulated and executed once a newline (or carriage return) is given.  A token is an individual entity, which means that joining tokens is not allowed, i.e. :test 3 4 +; must have a space after the colon and a space before the semi-colon, : test 3 4 + ; .

The system can be placed into definition mode in one of two ways: either a colon (:) or an open curly bracket ({) is given.  A colon is used to start a macro definition while an open curly bracket is used to spawn a separate process and is used for G2 performance orders.  Once the system is in definition mode, it can only leave this mode if  a corresponding terminating character is received; for a colon, it is a semi-colon, and for an open curly bracket, it is a closed curly bracket.  This means that a definition can span many lines without any apparent effect until the termination token is given.  If there are any errors within a definition, the definition will not be created and an error message will be given.

Notes:

           1) TOS = Top Of Stack.

           2) Arguments are given as on a command line, TOS is last.

           3) All tokens (names and numbers) must be delimitied by spaces.

           4) Macro names must be less than or equal to 15 characters. See the section on Limitations.

           5) Case is important.

Argument format is as follows: ( n1 n2 n3 — n4 n5 n6 ) where:

           Before Instruction:

           n3 = TOS

           n2 = TOS-1

           n1 = TOS-2 etc

           After Instruction:

           n6 = TOS

           n5 = TOS-1

           n4 = TOS-2

To define a macro, a colon semi-colon pair must delimit the commands contained therein.  Note that the definitions given in this chapter are formatted for readability.  This need not be done when using LLAMA.  Note, over filling a line is not allowed, and 78 characters is the maximum; however, once a definition has been started, it may be continued on following lines until the semi-colon is given.  The following is an example of each definition form:

: addtwo 3 4 + . ;   (colon definition)

{ 3 4 + . }       (spawn definition)

Each accomplishes the same goal, to add two numbers together and print the result.  The difference is that the spawn definition executes the tokens once given.  The colon definition compiles the definition (stores the new macro) until it is requested.  The following command executes the macro:

addtwo

For more restrictive examples that execute at absolute or relative times, see the section on performance orders in the LLAMA Tutorial chapter.

Command Directory

Note: The following macros and primitives are contained in LLAMA 1.1. Version 1.0 contains incomplete line-arc functions and does not have aliases for “!” etc. Every attempt has been made to ensure that every primitive that appears here exists on the boot disk.  Macros can be identified by the colon definition present in their text.

Motion Commands

cles                  ( — )

                                                            CLEAR EMERGENCY STOP

Clears emergency stop.  This is a virtual command because the request to clear the emergency stop condition sometime takes 20 or more tries internally.  If “cles” doesn’t succeed, a time-out error message is generated.

dr                     (drspd — )

                                                            DRIVE AT SPEED

: dr

   ddra     (variable, get current drive acceleration)

   @     (FORTH-like, fetch)

   dra      (motion, and drive at speed and accel)

;

range:

                           drspd:                     -10 to 10

Slews drive motor at speed in tenths of feet per second, using default acceleration.

dr0                   ( -- )

                                                            DRIVE NOT DONE TEST

: dr0

   pldr        (motion, poll drive motor)

   poll        (variable, see if allowed to drive)

   @        (FORTH-like, fetch)

   if       (conditional)

      drop     (FORTH-like)

      1

   endif    (conditional)

;

used in:             drstop

If the variable off is true, then drive not done, otherwise return pldr value.  This function is used to wait until a “move” command has engaged the drive motor.

dr1                   ( -- )

                                                            DRIVE DONE TEST

: dr1

   pldr        (motion, poll drive)

   dup 2 = if  (conditional)

      drop     (FORTH-like)

      0

   endif    (conditional)

   poll        (variable)

   @        (FORTH-like, fetch)

   if       (conditional)

      drop     (FORTH-like)

      0

   endif    (conditional)

;

used in:             drstop

If the variable off is true, then drive is done, otherwise return pldr value.  This function is used to wait until a “move” command has completed.

dra                   (drspd dracc -- )

                                                            DRIVE AT GIVEN PARAMETERS

range:

                           accel:                     1 to 32

                           speed:                    -10 to 10

Slews drive motor at speed in tenths of feet per second and at acceleration in feet per second squared.

drs                   ( — )

                                                            STOP DRIVE MOTOR

Stops drive motor only.

drstop              ( -- )

                                                            WAIT UNTIL MOVE COMPLETE

: drstop

   begin          (conditional)

      dr1            (motion)

   while repeat         (conditional)

   begin          (conditional)

      dr0            (motion)

   until          (conditional)

;

used in:             drive-until macros, etc

This function can determine if a “move” command has completed.  See “ststop” for more details.

drud                 (drdist drspd -- )

                                                            DRIVE UNTIL DISTANCE

: drud

   ddra @         (FORTH-like)

   drudacc        (motion)

;

range:

                           drdist:                     1 to 255

                           drspd:                     -10 to 10

Slews drive motor at speed in tenths of feet per second and for a distance in tenths of feet.  NOTE: Allowed range does not conform to the same format as “move”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

drudacc            (drdist drspd dracc -- )

                                                            DRIVE UNTIL DISTANCE WITH ACCEL

range:

                           dracc:                     1 to 100

                           drdist:                     1 to 255

                           drspd:                     -10 to 10

Slews drive motor at speed in tenths of feet per second and for a distance in tenths of feet and acceleration in tenths of feet per second per second.  NOTE: Allowed range does not conform to the same format as “move”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

drudo               (drdist drspd -- condition)

                                                            DRIVE UNTIL DISTANCE AND RESULT

: drudo

   ddra @         (FORTH-like)

   drudoacc       (motion)

;

range:

                           drdist:                     1 to 255

                           drspd:                     -10 to 10

                           condition:              0 = ok, other = error

Slews drive motor at speed in tenths of feet per second and for a distance in tenths of feet.  Displays condition following completion.  NOTE: Allowed range does not conform to the same format as “move”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

drudoacc          (drdist drspd dracc -- condition)

                                                            DRIVE UNTIL DISTANCE AND RESULT

range:

                           drdist:                     1 to 255

                           drspd:                     -10 to 10

                           dracc:                     1 to 100

                           condition:              0 = ok, other = error

Slews drive motor at speed in tenths of feet per second and for a distance in tenths of feet.  Drive acceleration in tenths of feet per second per second.  Displays condition following completion.  NOTE: Allowed range does not conform to the same format as “move”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

dstat                 ( -- )

                                                            DISPLAY DRIVE MOTOR STATUS

: dstat

   make              (format)

   gdrs              (motion)

   if             (conditional)

      ." dstat "     (FORTH-like)

      space       (FORTH-like)

      2 16 48 numc      (FORTH-like)

      space       (FORTH-like)

      2 16 48 numc      (FORTH-like)

   else              (conditional)

      ." dstaterr "  (FORTH-like)

   endif          (conditional)

   cr             (FORTH-like)

   out               (format)

;

Displays current drive motor status.

dsv                   ( dspd tang — )

                                                            DRIVE @ SPD, TURN @ ANGLE

: dsv

   10 * DSV       (motion)

;

range:

                           drive speed:          -10 to 10

                           angle:                     -179 to 180

Slews the drive motor at the specified speed in tenths of degrees per second while turning the robot the specified angle in degrees using default accelerations.

DSV                 ( dspd tang — )

                                                            DRIVE @ SPD, TURN @ ANGLE

range:

                           drive speed:          -10 to 10

                           angle:                     -1790 to 1800

Slews the drive motor at the specified speed in tenths of degrees per second while turning the robot the specified angle in tenths of degrees using default accelerations.  This is similar to “STUA” except that this command stops the motors once the desired distance has been executed.  A “ststop” is typically used immediately following this command.

eec                   ( -- )

                                                            DISPLAY ENCODER ERRORS 

: eec

   make              (format)

   genc              (motion)

   if             (conditional)

      ." eec "       (FORTH-like)

      space       (FORTH-like)

      0 D.R       (FORTH-like)

      space       (FORTH-like)

      0 D.R       (FORTH-like)

   else              (conditional)

      ." eecerr "    (FORTH-like)

   endif          (conditional)

   cr             (FORTH-like)

   out               (format)

;

Displays current wheel encoder errors.

GANG               ( -- angle)

                                                            GET CURRENT HEAD ANGLE

: GANG

   xytsave              (motion)

   0<                (FORTH-like)

   if                (conditional)

      drop              (FORTH-like)

      0

   else                 (conditional)

      if             (conditional)

         3 deep 3 deep  (FORTH-like)

         2 rem       (FORTH-like)

      else              (conditional)

         0

      endif          (conditional)

   endif             (conditional)

;

Gets current head angle from sensor blackboard.  Note that in this implementation, if a read error occurs, “GANG” returns 0 degrees.  Angle is returned in tenths of degrees.

GANGP            ( -- angle)

                                                            GET CURRENT HEAD ANGLE POSITIVE

: GANG

   xytsave              (motion)

   0<                (FORTH-like)

   if                (conditional)

      drop              (FORTH-like)

      0

   else                 (conditional)

      if             (conditional)

         3 deep 3 deep  (FORTH-like)

         2 rem       (FORTH-like)

         0<          (FORTH-like)

         if          (conditional)

            3600 +      (FORTH-like)

         endif       (conditional)

      else              (conditional)

         0

      endif          (conditional)

   endif             (conditional)

;

Gets current head angle from sensor blackboard.  If angle is negative, it is made positive by adding 360 degrees.  Note that in this implementation, if a read error occurs, “GANGP” returns 0 degrees.  Angle is returned in tenths of degrees.

gdrs                 ( — <drmode> <drcond> count )

                                                            GET DRIVE MOTOR STATUS

Returns two bytes describing drive motor mode and condition.  If count is zero then a packet transmission/receive error occurred, otherwise count is two.

genc                 ( — <drcount> <stcount> count )

                                                            GET ENCODER ERROR COUNTS

Returns the drive and steer encoder errors.  If count is zero then a packet transmission/receive error occurred, otherwise count is two.

gids                 ( — <idrspd> count)

                                                            GET INSTANT DRIVE SPEED

Returns currently executing drive speed in tenths of feet per second. If count is zero then a packet transmission/receive error occurred, otherwise count is one.

giss                  ( — <istspd> count)

                                                            GET INSTANT STEER SPEED

: giss

   GISS        (motion)

   if       (conditional)

      10 /     (FORTH-like)

      1

   else        (conditional)

      0

   endif    (conditional)

;

Returns currently executing steer speed in degrees per second. If count is zero then a packet transmission/receive error occurred, otherwise count is one.

GISS                ( — <istspd> count)

                                                            GET INSTANT STEER SPEED

Returns currently executing steer speed in tenths of degrees per second. If count is zero then a packet transmission/receive error occurred, otherwise count is one.

gpos                ( — <xpos> <ypos> <theta> count)

                                                            GET ROBOT X,Y,TH POSITION

: gpos

   xytsave        (motion)

   0<          (FORTH-like)

   if          (conditional)

      drop        (FORTH-like)

      0

   else           (conditional)

      if       (conditional)

         10 /     (FORTH-like)

         3

      else        (conditional)

         0

      endif    (conditional)

   endif       (conditional)

;

Returns the estimated robot x,y, and theta positions.  X and Y are in tenths of feet and theta is in degrees.  If count is zero then a packet transmission/receive error occurred, otherwise count is three.  Perform and “xyton” before using this command.

gsts                  ( — <stmode> <stcond> count)

                                                            GET STEER MOTOR STATUS

Returns two bytes describing steer motor mode and condition, if count is zero then a packet transmission/receive error occurred, otherwise count is two.

h                      ( — )

                                                            HALT ALL MOTORS

Halts all motors, similar to “stop” except it cannot be filtered out by a “mote” command.  Useful for emergency stop conditions.

home               ( — )

                                                            HOME HEAD TO MATCH BODY

: home

   DSTS        (variable)

   @        (FORTH-like)

   DSTA        (variable)

   @        (FORTH-like)

   HOMEACC     (motion)

;

Homes head (lines up green dots) using default steer velocity and acceleration.  A “ststop” is typically used immediately following this command.

HOMEACC        ( stspd stacc — )

                                                            HOME HEAD TO MATCH BODY

range:

                           accel:                     1 to 4330

                           speed:                    -800 to 800

Homes head (lines up green dots) at speed in tenths of degrees per second and at acceleration in tenths of degrees per second squared.  A “ststop” is typically used immediately following this command.

ids                   ( -- )

                                                            DISPLAY INSTANTANEOUS DRIVE SPEED

: ids

   make              (format)

   gids              (motion)

   if             (conditional)

      ." ids "       (FORTH-like)

      space       (FORTH-like)

      0 D.R       (FORTH-like)

   else              (conditional)

      ." idserr "    (FORTH-like)

   endif          (conditional)

   cr             (FORTH-like)

   out               (format)

;

Display instantaneous drive speed.

iss                    ( -- )

                                                            DISPLAY INSTANTANEOUS STEER SPEED

: iss

   make              (format)

   giss              (motion)

   if             (conditional)

      ." iss "       (FORTH-like)

      space       (FORTH-like)

      0 D.R       (FORTH-like)

   else              (conditional)

      ." isserr "    (FORTH-like)

   endif          (conditional)

   cr             (FORTH-like)

   out               (format)

;

Display instantaneous steer speed.

kai                    ( corridor shepherd ring xpos ypos weight -- )

                                                            INITIALIZE AND START OBSTACLE AVOIDER

range:

                           corridor:                 256 = off, -256 = off & debug, positive = on, negative = on & debug

                           shepherd:              0 - 255, 256 = off

                           ring:                        0 - 255, 256 = off

                           xpos:                      0 - 25

                           ypos:                      0 - 25

                           weight:                   0 - 100

Starts “Obstacle Avoider” demo.  This function is a complex virtual function that allows the robot to either wander on its own or avoid obstacles while going to a goal.  A good example is the following command:

   256 20 256 2 2 25 kai

This will move the robot to (x,y) = (2,2), provided no obstacle exists there. If the corridor parameter is negative and greater than -256 then the obstacle avoider will use the absolute value of the parameter.  The obstacle avoider used (created by Pulka and Cawlfield) has not had its algorithm altered.  In effect, it is a separate process.  The called process is “avoid”. The x, y axes for the primitive are not the same as the command line version. Axis conventionsThe primitive positive x-axis is 90 degrees clockwise from the green body dot and the positive y-axis is in the direction of the green dot. The command line version’s positive x-axis is in the direction of the green dot, the positive y-axis is 90 degrees clockwise from the green dot.

motb                ( maxdrspd -- )

                                                            ENABLE MOTION

range:

                           maxdrspd:            1 - 40

Allows motion primitives and macros to execute.  Sets maximum absolute drive speed in tenths of feet per second.  Note that each spawned process can have a different maximum drive speed.  This command also sets the maximum drive speeds of the “until” commands.  Unfortunately, due to a design error, this value changes with each “motb” command from any spawned interpreter, so it may not be possible to tell the maximum drive speed of the “until” commands.

mote                ( -- )

                                                            DISABLE MOTION

Disable all motion requests.  This is useful for some dry run procedures.

move                (mdis mspd — )

                                                            MOVE DISTANCE

: move

   ddra        (variable)

   @        (FORTH-like)

   movacc      (motion)

;

range:

                           distance:                -250 to 250

                           speed:                    0 to 10

Moves the robot the specified distance in tenths of feet at a speed in tenths of feet per second.  A “drstop” is typically used immediately after this command.

movacc            (mdis mspd macc — )

                                                            MOVE AT PARAMETERS

range:

                           macc:                     1 to 32                  

                           mspd:                     0 to 10

                           mdis:                      -250 to 250

Moves the robot the specified distance in tenths of feet at a speed in tenths of feet per second and acceleration in feet per second squared.  A “drstop” is typically used immediately after this command.

pldr                  ( — drstat)

                                                            POLL DRIVE MOTOR STAT

Returns drive motor status as follows:

2        = motors in emergency stop

1        = drive motor off

0        = drive motor on

-1       = packet error (expert module not responding)

-2       = frame error (expert module is probably not downloaded)

plst                  ( — ststat)

                                                            POLL STEER MOTOR STAT

Returns steer motor status as follows:

2        = motors in emergency stop

1        = steer motor off

0        = steer motor on

-1       = packet error (expert module not responding)

-2       = frame error (expert module is probably not downloaded)

pos                  ( -- )

                                                            DISPLAYS CURRENT THETA Y X POSITION

: pos

   xytsave           (motion)

   make              (format)

   0<             (FORTH-like)

   if             (conditional)

      ." poserr "    (FORTH-like)

      drop           (FORTH-like)

   else              (conditional)

      if          (conditional)

         ." pos "    (FORTH-like)

         3 0 do      (conditional)

            space (FORTH-like)

            0 D.0 (FORTH-like)

         loop        (conditional)

      else           (conditional)

         ." posoff " (FORTH-like)

      endif       (conditional)

   endif          (conditional)

   cr             (FORTH-like)

   out               (format)

;

Displays the current x, y, theta estimator position. Axis conventionsPositive x is in the direction of the green dot if a home was followed by a 0 0 0 spos and positive y is 90 degrees clockwise from positive x. Positive theta is in a clockwise direction. Note that this is not a standard Cartesian coordinate system configuration.

runtil                ( -- )

                                                            RESET STEER UNTIL ANGLE TO START

This function initializes steer until angle to initial values and is used for the “until” commands.  This function is typically used at the start of a complex motion performance order to confirm proper motion behavior. This command does not alter the wheel encoder estimators.

s                      ( — )

                                                            STOP ALL MOTORS

Stops all motors unless a “mote” has been executed.  See “halt”. This function will not work if a line-arc function is executing in a spawned interpreter—a halt must be used instead.

sdda                 (dracc — )

                                                            SET DEFAULT DRIVE ACCEL

: sdda

   dup         (FORTH-like)

   ddra        (variable)

   !        (FORTH-like)

   setdda      (motion)

;

range:               1 to 32

Sets default acceleration of drive motor to degrees per second squared.

sdds                 (drspd — )

                                                            SET DEFAULT DRIVE SPEED

: sdds

   dup         (FORTH-like)

   ddrs        (variable)

   !        (FORTH-like)

   setdds      (motion)

;

range:               1 - 10

Sets default drive speed of drive motor to tenths of feet per second.

sdsa                 (stacc — )

                                                            SET DEFAULT STEER ACCEL

: sdsa

   100 *    (FORTH-like)

   dup         (FORTH-like)

   DSTA        (variable)

   !        (FORTH-like)

   SETDSA      (motion)

;

range:               1 to 43

Sets default acceleration of steer motor to tens of degrees per second squared.

SDSA               (stacc — )

                                                            SET DEFAULT STEER ACCEL

: SDSA

   dup         (FORTH-like)

   DSTA        (variable)

   !        (FORTH-like)

   SETDSA      (motion)

;

range:               1 to 4330

Sets default acceleration of steer motor to tenths of degrees per second squared.

sdss                 (stspd — )

                                                            SET DEFAULT STEER SPEED

: sdss

   10 *        (FORTH-like)

   dup         (FORTH-like)

   DSTS        (variable)

   !        (FORTH-like)

   SETDSS      (motion)

;

range:               1 - 80

Sets default steer speed of steer motor to degrees per second.

SDSS               (stspd — )

                                                            SET DEFAULT STEER SPEED

: SDSS

   dup         (FORTH-like)

   DSTS        (variable)

   !        (FORTH-like)

   SETDSS      (motion)

;

range:               1 - 800

Sets default steer speed of steer motor to tenths of degrees per second.

setdda              (dracc — )

                                                            SET MOTOR DRIVE ACCEL

range:               1 to 32

Sets default acceleration of drive motor to degrees per second squared.

setdds              (drspd — )

                                                            SET MOTOR DRIVE SPEED

range:               1 - 10

Sets default drive speed of drive motor to tenths of feet per second.

SETDSA           (stacc — )

                                                            SET MOTOR STEER ACCEL

range:               1 to 4330

Sets default acceleration of steer motor to tenths of degrees per second squared.

SETDSS           (stspd — )

                                                            SET MOTOR STEER SPEED

range:               1 - 800

Sets default steer speed of steer motor to tenths of degrees per second.

SPOS               ( xpos ypos theta — )

                                                            SET X,Y,TH ROBOT POSITION

range:

                           angle (theta):                                        -1800 to 1799

                           y-position (ypos):                                -32768 to 32767

                           x-position (xpos):                                -32768 to 32767

Sets estimator to desired values to tenths of feet and tenths of degrees. Assuming the robot has been homed and a  0 0 0 SPOS  was given, positive x  is in the direction of the green dot, positive y is 90 degrees clockwise from the green dot.

SPOSO            ( xpos ypos theta — condition)

                                                            SET X,Y,TH ROBOT POSITION AND RESULT

range:

                           angle (theta):                                        -1800 to 1799

                           y-position (ypos):                                -32768 to 32767

                           x-position (xpos):                                -32768 to 32767

                           condition:                                              0 = ok, other = error

Sets estimator to desired values to tenths of feet and tenths of degrees.  This function is similar to “SPOS” but also returns a status if the setting was successful. Assuming the robot has been homed and a  0 0 0 SPOSO  was given, positive x  is in the direction of the green dot, positive y is 90 degrees clockwise from the green dot.

spos                 ( xpos ypos theta — )

                                                            SET X,Y,TH ROBOT POSITION

: spos

   10 *        (FORTH-like)

   SPOS        (motion)

;

range:

                           angle:                     -180 to 179

                           y-position:             -32768 to 32767

                           x-position:             -32768 to 32767

Sets estimator to desired values to tenths of feet and degrees. Assuming the robot has been homed and a  0 0 0 spos  was given, positive x  is in the direction of the green dot, positive y is 90 degrees clockwise from the green dot.

sstat                 ( -- )

                                                            DISPLAY STEER MOTOR STATUS

: sstat

   make              (format)

   gsts              (motion)

   if             (conditional)

      ." sstat "     (FORTH-like)

      space       (FORTH-like)

      2 16 48 numc      (FORTH-like)

      space       (FORTH-like)

      2 16 48 numc      (FORTH-like)

   else              (conditional)

      ." sstaterr "  (FORTH-like)

   endif          (conditional)

   cr             (FORTH-like)

   out               (format)

;

Displays current steer motor status.

st                     (stspd — )

                                                            STEER AT SPEED

: st

   10 *        (FORTH-like)

   ST       (motion)

;

range:               -80 to 80

Slews steer motor at speed in degrees per second, using default acceleration.

ST                    (stspd — )

                                                            STEER AT SPEED

: ST

   DSTA        (variable)

   @        (FORTH-like)

   STA         (motion)

;

range:               -800 to 800

Slews steer motor at speed in tenths of degrees per second, using default acceleration.

st0                    ( -- )

                                                            STEER NOT DONE TEST

: st0

   plst        (motion)

   dup 2 = if  (conditional)

      drop     (FORTH-like)

      0

   endif    (conditional)

   poll        (variable)

   @        (FORTH-like)

   if       (conditional)

      drop     (FORTH-like)

      1

   endif    (conditional)

;

used in:             ststop

If the variable off is true, then steer not done, otherwise return plst value.  This function is used to wait until a “turn” command has engaged the steer motor.

st1                    ( -- )

                                                            STEER DONE TEST

: st1

   plst        (motion)

   poll        (variable)

   @        (FORTH-like)

   if       (conditional)

      drop     (FORTH-like)

      0

   endif    (conditional)

;

used in:             ststop

If the variable off is true, then steer is done, otherwise return plst value.  This function is used to wait until a “turn” command has completed.

STA                  (stspd stacc — )

                                                            STEER AT GIVEN PARAMETERS

range:

                           accel:                     1 to 4330

                           speed:                    -800 to 800

Slews steer motor at speed in tenths of degrees per second and at acceleration in tenths of degrees per second squared.

sts                    ( — )

                                                            STOP STEER MOTOR

Stops steer motor.

ststop               ( -- )

                                                            WAIT UNTIL TURN COMPLETE

: ststop

   begin       (conditional)

      st1         (motion)

   while repeat      (conditional)

   begin       (conditional)

      st0         (motion)

   until       (conditional)

;

used in:             bfall, lfall

This function can determine if a “turn” or “home” command has completed.  The original macro checked only for turn-complete but sometimes it would return complete immediately.  The problem was that poll-steer returned done before the motor had begun to turn.  Adding a check for motor-turning solved the problem.

STUA   (drspd stang stspd -- )

                        STEER UNTIL ANGLE NO CORRECTION

: STUA

   ddra @               (FORTH-like)

   DSTA @               (FORTH-like)

   STUAACC              (motion)

;

range:

           drspd:     -10 to 10

           stang:     1 to 3400 (typical)

           stspd:     -800 to 800

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second. Default drive and steer accelerations are used. NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

STUAACC         (drspd stang stspd dracc stacc -- )

                        STEER UNTIL ANGLE NO CORRECTION

range:

           drspd:     -10 to 10

           stang:     1 to 3400 (typical)

           stspd:     -800 to 800

           dracc:     1 to 100

           stacc:     1 to 4330

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second.  Drive acceleration in tenths of feet per second per second, steer acceleration in tenths of degrees per second per second.  NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

STUAC             (drspd stang stspd -- )

                                                            STEER UNTIL ANGLE WITH CORRECTION

: STUAC

   ddra @         (FORTH-like)

   DSTA @         (FORTH-like)

   CRCTANG @      (FORTH-like)

   STUACACC       (motion)

;

range:

                           drspd:                     -10 to 10

                           stang:                     1 to 3400 (typical)

                           stspd:                     -800 to 800

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second. Corrects turn angle at end of motion.  Default drive and steer accelerations are used. NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.  It is always used at the end of a sequence of “STUAE” functions to correct for accumulated error.  If only one “STUAE”, or arc, is needed, use this function alone.  A “drud” should not be used between “STUAE” and “STUAC” as the system may behave unpredictably.

STUACACC      (drspd stang stspd dracc stacc crct -- )

                                                            STEER UNTIL ANGLE WITH CORRECTION

range:

                           drspd:                     -10 to 10

                           stang:                     1 to 3400 (typical)

                           stspd:                     -800 to 800

                           dracc:                     1 to 100

                           stacc:                     1 to 4330

                           crct:                        0 to 900                

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second.  Drive acceleration in tenths of feet per second per second, steer acceleration in tenths of degrees per second per second.  Correction in tenths of degrees.  Corrects turn angle at end of motion.  NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.  It is always used at the end of a sequence of “STUAE” functions to correct for accumulated error.  If only one “STUAE”, or arc, is needed, use this function alone.  A “drud” should not be used between “STUAE” and “STUAC” as the system may behave unpredictably.

STUACO           (drspd stang stspd -- condition)

                                                            STEER UNTIL ANGLE WITH CORRECTION AND RESULT

: STUACO

   ddra @         (FORTH-like)

   DSTA @         (FORTH-like)

   CRCTANG @      (FORTH-like)

   STUACOACC      (motion)

;

range:

                           drspd:                     -10 to 10

                           stang:                     1 to 3400 (typical)

                           stspd:                     -800 to 800          

                           condition:              0 = ok, other = error.

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second. Corrects turn angle at end of motion.  Displays condition following completion.  Default drive and steer accelerations are used. NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.  It is always used at the end of a sequence of “STUAE” functions to correct for accumulated error.  If only one “STUAE”, or arc, is needed, use this function alone.  A “drud” should not be used between “STUAE” and “STUAC” as the system may behave unpredictably.

STUACOACC    (drspd stang stspd dracc stacc crct -- condition)

                                                            STEER UNTIL ANGLE WITH CORRECTION AND RESULT

range:

                           drspd:                     -10 to 10

                           stang:                     1 to 3400 (typical)

                           stspd:                     -800 to 800

                           dracc:                     1 to 100

                           stacc:                     1 to 4330

                           crct:                        0 to 900                

                           condition:              0 = ok, other = error.

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second.  Drive acceleration in tenths of feet per second per second, steer acceleration in tenths of degrees per second per second.  Correction in tenths of degrees.  Corrects turn angle at end of motion.  Displays condition following completion.  NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.  It is always used at the end of a sequence of “STUAE” functions to correct for accumulated error.  If only one “STUAE”, or arc, is needed, use this function alone.  A “drud” should not be used between “STUAE” and “STUAC” as the system may behave unpredictably.

STUAE             (drspd stang stspd -- )

                                                            STEER UNTIL ANGLE ERROR ACCUMULATE

: STUAE

   ddra @         (FORTH-like)

   DSTA @         (FORTH-like)

   STUAEACC       (motion)

;

range:

                           drspd:                     -10 to 10

                           stang:                     1 to 3400 (typical)

                           stspd:                     -800 to 800

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second. Accumulates internal error count of desired versus actual turn angle.  A “STUAC” is used following a sequence of these commands.  Default drive and steer accelerations are used. NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

STUAEACC      (drspd stang stspd dracc stacc -- )

                                                            STEER UNTIL ANGLE ERROR ACCUMULATE

range:

                           drspd:                     -10 to 10

                           stang:                     1 to 3400 (typical)

                           stspd:                     -800 to 800

                           dracc:                     1 to 100

                           stacc:                     1 to 4330

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second.  Drive acceleration in tenths of feet per second per second, steer acceleration in tenths of degrees per second per second.  Accumulates internal error count of desired versus actual turn angle.  A “STUAC” is used following a sequence of these commands.  NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

STUAEO           (drspd stang stspd -- condition)

                                                            STEER UNTIL ANGLE ERROR AND RESULT

: STUAEO

   ddra @         (FORTH-like)

   DSTA @         (FORTH-like)

   STUAEOACC      (motion)

;

range:

                           drspd:                     -10 to 10

                           stang:                     1 to 3400 (typical)

                           stspd:                     -800 to 800

                           condition:              0 = ok, other = error.

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second. Accumulates internal error count of desired versus actual turn angle.  Displays condition following completion.  A “STUAC” is used following a sequence of these commands.  Default drive and steer accelerations are used. NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

STUAEOACC    (drspd stang stspd dracc stacc -- condition)

                                                            STEER UNTIL ANGLE ERROR AND RESULT

range:

                           drspd:                     -10 to 10

                           stang:                     1 to 3400 (typical)

                           stspd:                     -800 to 800

                           dracc:                     1 to 100

                           stacc:                     1 to 4330

                           condition:              0 = ok, other = error.

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second.  Drive acceleration in tenths of feet per second per second, steer acceleration in tenths of degrees per second per second.  Accumulates internal error count of desired versus actual turn angle.  Displays condition following completion.  A “STUAC” is used following a sequence of these commands.  NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

STUAO             (drspd stang stspd -- condition)

                                                            STEER UNTIL ANGLE NO CORRECTION AND RESULT

: STUAO

   ddra @         (FORTH-like)

   DSTA @         (FORTH-like)

   STUAOACC       (motion)

;

range:

                           drspd:                     -10 to 10

                           stang:                     1 to 3400 (typical)

                           stspd:                     -800 to 800

                           condition:              0 = ok, other = error.

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second. Displays condition following completion.  Default drive and steer accelerations are used. NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

STUAOACC      (drspd stang stspd dracc stacc -- condition)

                                                            STEER UNTIL ANGLE NO CORRECTION AND RESULT

range:

                           drspd:                     -10 to 10

                           stang:                     1 to 3400 (typical)

                           stspd:                     -800 to 800

                           dracc:                     1 to 100

                           stacc:                     1 to 4330

                           condition:              0 = ok, other = error.

Slews drive motor at speed in tenths of feet per second and slews steer motor for an angle in tenths of degrees and at a velocity in tenths of degrees per second.  Drive acceleration in tenths of feet per second per second, steer acceleration in tenths of degrees per second per second.  Displays condition following completion.  NOTE: Allowed range does not conform to the same format as “TURN”.  This is a “Virtual” function in that it behaves like a primitive yet it is composed of various C functions.

tmout               (time — )

                                                            SET DRIVE SHUTOFF TIMEOUT

range: time:     0 - 255

Shuts off drive motor if a drive command was not received for time specified and drive motor was on.  If zero is specified, time-out is disabled.

turn                  (tang tspd — )

                                                            TURN DISTANCE

: turn

   swap     (FORTH-like)

   10 *     (FORTH-like)

   swap     (FORTH-like)

   10 *     (FORTH-like)

   TURN     (motion)

;

range:

                           tang:                       -360 to 360

                           tspd:                       1 to 80

Turns the robot the specified distance in degrees at a speed in degrees per second.  A “ststop” is typically used immediately following this command.

TURN               (tang tspd — )

                                                            TURN DISTANCE

: TURN

   DSTA        (variable)

   @        (FORTH-like)

   TURNACC     (motion)

;

range:

                           tang:                       -3600 to 3600

                           tspd:                       1 to 800

Turns the robot the specified distance in tenths of degrees at a speed in tenths of degrees per second with default acceleration.  A “ststop” is typically used immediately following this command.

turnacc             (tang tspd tacc — )

                                                            TURN AT PARAMETERS

: turnacc

   rot         (FORTH-like)

   10 *        (FORTH-like)

   rot         (FORTH-like)

   10 *        (FORTH-like)

   rot         (FORTH-like)

   100 *    (FORTH-like)

   TURNACC     (motion)

;

range:

                           tacc:                       1 to 43

                           tspd:                       1 to 80

                           tang:                       -360 to 360

Turns the robot the specified distance in degrees at a speed in degrees per second and acceleration in tens of degrees per second squared.  A “ststop” is typically used immediately following this command.

TURNACC         (tang tspd tacc — )

                                                            TURN AT PARAMETERS

range:

                           tacc:                       1 to 4330

                           tspd:                       1 to 800

                           tang:                       -3600 to 3600

Turns the robot the specified distance in tenths of degrees at a speed in tenths of degrees per second and acceleration in tenths of degrees per second squared.  A “ststop” is typically used immediately following this command.

xytclr                ( -- )

                                                            TURN OFF XY POSITION DATA AND LINK=0

This will turn off the XY position data.  It is mainly used for development work where a xytoff may have been forgotten.  This function restores the link to a known state.

xytoff                ( -- )

                                                            UNLINK XY POSITION DATA

This command turns off the XY position data if the current xyt link count is one, is ignored if the link count is zero and decrements the xyt link count by one otherwise.

xyton                ( -- )

                                                            TURN ON AND LINK XY POSITION DATA

Turns on XY position data and increments the xyt link count by one.

xytsave             ( — xpos ypos theta count )

                                                            XY READ POSITION DATA

Returns x position in tenths of feet, y position in tenths of feet and theta head angle in tenths of degrees.  Count is three on valid data or zero on error.

Ultrasonic Commands

ug                    ( — )

                                                            GET ALL ULTRASONICS

: ug

   ulsave               (ultrasonics)

   make                 (format)

   0<                (FORTH-like)

   if                (conditional)

      ." uerr "         (FORTH-like)

      drop              (FORTH-like)

   else                 (conditional)

      if             (conditional)

         ." ug "        (FORTH-like)

         24 0 do        (conditional)

            space    (FORTH-like)

            2 16 48 numc   (FORTH-like)

         loop           (conditional)

      else              (conditional)

         ." uoff "      (FORTH-like)

      endif          (conditional)

   endif             (conditional)

   cr                (FORTH-like)

   out                  (format)

;

Reads ultrasonics in compact form, i.e. ug 22 F2 32 0E...32 3A.   Where there are 24 8-bit hexadecimal (base 16) values displayed.  The last value is ultrasonic number 0.  If a reading is returned as zero, then that sonar is disabled.  A “ulon” must precede this command.

ulclr                 ( -- )

                                                            TURN OFF ULTRASONICS AND LINK=0

This will turn off ultrasonics.  It is mainly used for development work where a uloff may have been forgotten.  This function restores the links to a known state.

uloff                 ( -- )

                                                            UNLINK ULTRASONICS

This command turns off ultrasonics if the current ultrasonic link count is one, is ignored if the link count is zero and decrements the ultrasonic link count by one otherwise.

ulon                 ( -- )

                                                            TURN ON AND LINK ULTRASONICS

Turns on ultrasonics and increments the ultrasonic link count by one.

ulparar             ( -- maxrange fm2 fm1 fm0 ifdelay count )

                                                            ULTRASONICS PARAMETER TABLE READ

Reads the current values of the ultrasonic parameters table.  Refer to “ulparas” for specific details on the parameters.  “Count” is zero on error and five otherwise.

ulparas             ( ifdelay fm0 fm1 fm2 maxrange -- )

                                                            ULTRASONIC PARAMETER TABLE STORE

range:

                           ifdelay:                  1 - 255                   (default = 18)

                           fm0:                       0 - 255                   (default = 255)

                           fm1:                       0 - 255                   (default = 255)

                           fm2:                       0 - 255                   (default = 255)

                           maxrange:            1 - 255                   (default = 255)

Stores values into ultrasonic parameter table.  Ifdelay is the interfire delay in milliseconds.  This refers to the amount of time between each firing sequence.  Fm0 is the fire mask for sensors 0 - 7, fm1 is for 8 - 15, and fm2 is for 16- 23.  If a bit is set (equal to one) then that sensors fires, otherwise it is disabled.  The following table gives the sensor number assignment:

           fm0: 0b7 = 7, 0b6 = 6, 0b5 = 5, 0b4 = 4, 0b3 = 3, 0b2 =2, 0b1 = 1, 0b0 = 0

           fm1: 1b7 = 15, 1b6 = 14, 1b5 = 13, 1b4 = 12, 1b3 = 11, 1b2 = 10, 1b1 = 9, 1b0 = 8

           fm2: 2b7 = 23, 2b6 = 22, 2b5 = 21, 2b4 = 20, 2b3 = 19, 2b2 = 18, 2b1 = 17, 2b0 = 16

For example, if we want sensors 3, 6, 10 and 20 to fire with and we wish to have an interfire delay of 20 ms and a max range of 10 feet we would give the command:

   20 72 4 16 100 ulparas

Which would automatically update the sensor blackboard.

ulsave              ( — ur0 ur1 ... ur23 count )

                                                            READ ALL ULTRASONICS FROM BBRD

Puts ultrasonic range data from blackboard on stack with #23 on TOS.  Range of values for each reading is 0 and 3 to 255.  Count is zero if off, -1 if error, such as ultrasonics not linked to, otherwise twenty-four.  If a reading has zero value, that implies that sensor is off.

ulseqr              ( -- #tofire #first ilvfact ifspace count )

                                                            ULTRASONICS SEQUENCE TABLE READ

Reads the current values of the ultrasonic sequence table.  Refer to “ulseqs” for specific details on the parameters.  “Count” is zero on error and four otherwise.

ulseqs              ( ifspace ilvfact #first #tofire -- )

                                                            ULTRASONIC SEQUENCE TABLE STORE

range:

                           ifspace:                  1 - 24                      (default = 6)

                           ilvfact:                   1 - ifspace             (default = 3)

                           #first:                     0 - 23                      (default = 0)

                           #tofire:                   1 - 24                      (default = 24)

Stores values into ultrasonic sequence table.  Ifspace is the interfire spacing and refers to the distance in sensor number that simultaneously fire.  Ilvfact is the interleave factor which defines how much to increment each sensor-to-fire number for each successive firing simultaneous firing.  #first is the number of the first sensor to fire while #tofire is the number of sensors to fire from the first sensor to fire.  Note: This is technically a virtual function since if the ultrasonics are on and a set of the parameters is attempted, the sensors will remain on with new firing parameters;  this is not the case with the “raw” function which will turn off the sensors whenever the parameters are set.

up                    ( -- )

                                                            DISPLAY ULTRA PARAMETER BLACKBRD

: up

   make              (format)

   ulparar           (ultra)

   0<             (FORTH-like)

   if             (conditional)

      ." uperr "     (FORTH-like)

      drop           (FORTH-like)

   else              (conditional)

      if          (conditional)

         upr         (ultra)

      else           (conditional)

         ." uperr "  (FORTH-like)

      endif       (conditional)

   endif          (conditional)

   cr             (FORTH-like)

   out               (format)

;

Displays the current ultrasonic parameter blackboard.

upr                   ( -- )

                                                            GENERATE ULTRA PARA DISPLAY

: upr

   ." up "           (FORTH-like)

   5 0 do            (conditional)

      space       (FORTH-like)

      0 D.R       (FORTH-like)

   loop              (conditional)

;

used in:             up

Used for making a valid ultrasonics parameter blackboard output.

us                    ( -- )

                                                            DISPLAY ULTRA SEQUENCE BLACKBOARD

: us

   make              (format)

   ulseqr            (ultra)

   0<             (FORTH-like)

   if             (conditional)

      ." userr "     (FORTH-like)

      drop           (FORTH-like)

   else              (conditional)

      if          (conditional)

         usr         (ultra)

      else           (conditional)

         ." userr "  (FORTH-like)

      endif       (conditional)

   endif          (conditional)

   cr             (FORTH-like)

   out               (format)

;

Displays the current ultrasonic sequence blackboard.

usr                   ( -- )

                                                            GENERATE ULTRA SEQUENCE DISPLAY

: usr

   ." us "           (FORTH-like)

   4 0 do            (conditional)

      space       (FORTH-like)

      0 D.R       (FORTH-like)

   loop              (conditional)

;

used in:             us

Used for making a valid ultrasonics sequence blackboard output.

Bumper Commands

bpg                  ( -- )

                                                            PRINT CURRENT PRESSED BUMPER SWITCHES

: bpg

   make              (format)

   bpgs              (bumper)

   dup               (FORTH-like)

   ." bpg "          (FORTH-like)

   if             (conditional)

      0 do           (conditional)

         space    (FORTH-like)

         0 D.0    (FORTH-like)

      loop           (conditional)

   else              (conditional)

      space       (FORTH-like)

         0 D.0    (FORTH-like)

   endif          (conditional)

   cr             (FORTH-like)

   out               (format)

;

Displays status of pressed bumper switches

bpgs                ( -- <sw0> <sw1> ... <sw6> count )

                                                            PUT PRESSED SWITCHES ONTO STACK

Places the currently pressed switches onto the stack.  Count is zero if no switches are pressed.

bpma               ( -- )

                                                            MAKE CURRENTLY ACTIVE BUMPERS TACTILE

This command is useful in that typically an emergency-stop condition sets a bumper switch to active and this command will allow that switch to be transformed into the tactile mode.  Note that “cles” will have to be executed also.

bpme               ( -- )

                                                            MAKE EVERY BUMPER INTO TACTILE MODE

Set all bumper switches into tactile mode.

bpr                   ( -- )

                                                            RESET BUMPER SWITCHES

Resets bumper switches and sets to emergency-stop mode.  This command must be executed prior to a “cles” if the bumpers caused an emergency stop condition.

bps                  ( -- )

                                                            SHOW TACTILE BUMPER SWITCHES

: bps

   make              (format)

   bpss              (bumper)

   dup               (FORTH-like)

   ." bps "          (FORTH-like)

   if             (conditional)

      0 do           (conditional)

         space    (FORTH-like)

         0 D.0    (FORTH-like)

      loop           (conditional)

   else              (conditional)

      space       (FORTH-like)

         0 D.0    (FORTH-like)

   endif          (conditional)

   cr             (FORTH-like)

   out               (format)

;

This command displays those bumper switches which are currently in tactile mode ( the remainder are in emergency-stop mode ).

bpss                 ( -- <sw1> <sw2> ... <sw6> count )

                                                            PUT INACTIVE SWITCHES ONTO STACK.

This command places the values of the inactive bumper switches onto the stack.  The count is zero if all are active.

Speech Commands

hello                ( -- )

                                                            SAY “Hello”

   : hello

      0 53 15 45 7 27 6

      ts       (speech)

   ;

Useful for checking if speech systems are functional.

tc                     ( <extra_func> func — )

                                                            CONTROL SPEECH COMPUTER

Sends a control sequence to the speech computer to perform administrative tasks.  The following is a list of the controls available:

0 tc    Resets Speech E-Mod (equivalent to “tr”).

1 tc    Gets Speech E-Mod status (equivalent to “tg”).

2 tc    Flush Speech E-Mod’s input buffer (Not implemented yet).

3 tc    Turn on return messages (LLAMA text format using ^).

4 tc    Turn off return messages from Speech Computer.

5 tc    Turn on all voice outputs from Speech Computer.

6 tc    Turn off all voice outputs from Speech Computer.

XX 7 tc             Turn on voice output for ‘X’ computer (0-9).

XX 8 tc             Turn off voice output for ‘X’ computer (0-9).

9 tc    Get voice output status.

10 tc  Turn on all text outputs from Speech Computer.

11 tc  Turn off all text outputs from Speech Computer.

XX 12 tc           Turn on text output for ‘X’ computer (0-9).

XX 13 tc           Turn off text output for ‘X’ computer (0-9).

14 tc  Get text output status.

15 tc  Turn on all error outputs from Speech Computer.

16 tc  Turn off all error outputs from Speech Computer.

XX 17 tc           Turn on error output for ‘X’ computer (0-9).

XX 18 tc           Turn off error output for ‘X’ computer (0-9).

19 tc  Get error output status.

20 tc  Turn on message voice.

21 tc  Turn off message voice.

22 tc  Turn on message text.

23 tc  Turn off message text.

te                     ( error processtype processid — )

                                                            ERROR GENERATOR

range:

                           processid:              0 - 32

                           processtype:         0 - 99

                           error:                      0 - 99

Useful for debugging only, the messages are actually generated internally to LLAMA.

tg                     ( — )

                                                            GET STATUS

Get number of bytes in S.P.’s buffer and speech status.  Format: tg yes/no XX, where yes/no tells whether talking, and XX refers to bytes in buffer waiting to be spoken.

tm                    ( message group — )

                                                            MESSAGE GENERATOR

range:

                           group:                    0 - 99

                           message:               0 - 99

Useful for debugging only. The messages are actually generated internally to LLAMA.

tq                     ( — )

                                                            SEND “QUIET” ALLOPHONE

: tq

   0 1 ts      (speech)

;

Used mainly for debugging to quiet the speech processor if a “hanging” allophone was generated previously.  (Sends a pa1 allophone)

tp                     ( — stat )

                                                            GET STATUS TO STACK

Returns 0 if speech processor is talking, 1 if it is idle.

tr                      ( — )

                                                            RESET SPEECH EXPERT MODULE

Resets speech expert module to initial condition:

           1) Performed by speech computer on boot-up.

           2) Clears Speech Modules buffer.

ts                     ( lastallo allo ... allo firstallo count — )

                                                            SPEAK

range:

                           allo:                                                        0 - 63

                           count:                    1 - 128

Speaks allophones on stack for length given at TOS.  Useful for defining words for the macro generator.  See “hello”.

Beacon Commands

bcok                 ( currang int alt ang code —  )

                                                            BEACON GENERATE DATA OUTPUT FORMAT

: bcok

   2 D.0    (FORTH-like)

   space    (FORTH-like)

   swap        (FORTH-like)

   0 D.R    (FORTH-like)

   space    (FORTH-like)

   swap        (FORTH-like)

   0 D.R    (FORTH-like)

   space    (FORTH-like)

   angst    (variable)

   @        (FORTH-like)

   +        (FORTH-like)

   0 D.R    (FORTH-like)

   cr       (FORTH-like)

   out         (format)

;

range:

                           currang:                 output from “xytsave” in tenths of degrees

                                                           refer to bfall for typical values

used in:             bdsp

Finishes formating beacon data for output to terminal.

bdisp               ( — )

                                                            DISPLAY BEACON DATA

: bdisp

   make                 (format)

   besave               (beacon)

   0<                (FORTH-like)

   if                (conditional)

      drop              (FORTH-like)

      ." berr "         (FORTH-like)

   else                 (conditional)

      if             (conditional)

         dup            (FORTH-like)

         1 >            (FORTH-like)

         if          (conditional)

            bdsp        (beacon)

         else           (conditional)

            5 rem    (FORTH-like)

            ." bnone "  (FORTH-like)

         endif       (conditional)

      else              (conditional)

         ." boff "

      endif          (conditional)

   endif             (conditional)

   cr                (FORTH-like)

   out                  (format)

;

Displays current beacon data and status.  Used as a “one-of” for quick checks.  Use “bfdisp” for macros.  Note that “beon” must be used before this command.

bdsp                ( currang int azi ang code cond —  )

                                                            DISPLAY FOUND BEACON VALUES

: bdsp

   make              (format)

   ." bef "          (FORTH-like)

   space          (FORTH-like)

   0 D.0          (FORTH-like)

   space          (FORTH-like)

   dup               (FORTH-like)

   if             (conditional)

      bcok           (beacon)

   else              (conditional)

      4 0 do         (conditional)

         drop        (FORTH-like)

      loop           (conditional)

      make           (format)

      ." bbad "

   endif          (conditional)

;

range:

                           currang:                 output from “xytpos” in tenths of degrees

                                                           refer to bfall for typical values

used in:             bfdisp

Displays resulting beacon data provided that the values received are valid.

beclr                ( -- )

                                                            TURN OFF BEACON SENSOR AND LINK=0

This will turn off the beacon sensor.  It is mainly used for development work where a beoff may have been forgotten.  This function restores the link to a known state.

beoff                ( -- )

                                                            UNLINK BEACON SENSOR

This command turns off the beacon sensors if the current beacon link count is one, is ignored if the link count is zero and decrements the beacon link count by one otherwise.

beon                ( -- )

                                                            TURN ON AND LINK BEACON SENSOR

Turns on beacon sensor and increments the beacon link count by one.

besave             ( — <int> <alt> <azi> <code> <cond> count )

                                                            BEACON STORE

Returns beacon data to the stack, if any.  Count is zero if an error has occurred.  This instruction select the average beacon data expert module function.

bfall                 ( — )

                                                            FIND ALL BEACONS

: bfall

   xyton       (motion)

   beon           (beacon)

   sts            (motion)

   home           (motion)

   ststop         (motion)

   0 0 0 spos     (motion)

   3600 DSTS @    (FORTH-like)

   TURN           (motion)

   bhead       (beacon)

   begin       (conditional)

      GANGP    (motion)

      angst    (variable)

      !        (FORTH-like)

      bfdisp      (beacon)

      plst        (motion)

   until       (conditional)

   btail       (beacon)

   0 angst        (variable)

   !           (FORTH-like)

   beoff       (beacon)

   xytoff         (motion)

;

Finds all beacons in a 360 degree sweep at default turn velocity.

Output format:

bstart

bef COND CODE ALT INT ANG

.

.

.

bef COND CODE ALT INT ANG

bstop

Where:

           COND = 8 bit hex value of return status.

           CODE = beacon code in 8 bit hex.

           ALT = beacon altitude in signed tenths of degrees.

           INT = beacon intensity, in counts.

           ANG = angle to beacon in signed tenths of degrees.

bfdisp              ( -- )

                                                            BEACON GET AND DISPLAY READINGS

: bfdisp

   besave               (beacon)

   0<                (FORTH-like)

   if                (conditional)

      drop              (FORTH-like)

      make

      ." berr "         (FORTH-like)

      cr             (FORTH-like)

      out               (format)

      s              (motion)

   else                 (conditional)

      if             (conditional)

         dup            (FORTH-like)

         1 >            (FORTH-like)

         if          (conditional)

            bdsp        (beacon)

            64 sl2      (schedule)

         else           (conditional)

            5 rem    (FORTH-like)

         endif       (conditional)

      else              (conditional)

         make           (format)

         ." boff "      (FORTH-like)

         cr          (FORTH-like)

         out            (format)

         s           (motion)

      endif          (conditional)

   endif             (conditional)

;

used in:             bfall

Finds and displays all beacon data until steer motor stops.

bhead               ( -- )

                                                            BEACON BUILD HEADER

: bhead

   make           (format)

   ." bstart "    (FORTH-like)

   cr          (FORTH-like)

   out            (format)

;

used in:             bfall

Creates and displays a “starting beacon search” message.

btail                 ( -- )

                                                            BEACON BUILD CLOSING

: bhead

   make           (format)

   ." bstop "     (FORTH-like)

   cr          (FORTH-like)

   out            (format)

;

used in:             bfall

Creates and displays a “ending beacon search” message.

Laser Commands

laclr                 ( -- )

                                                            TURN OFF LASER SENSOR AND LINK=0

This will turn off the laser sensor.  It is mainly used for development work where a laoff may have been forgotten.  This function restores the link to a known state.

laoff                 ( -- )

                                                            UNLINK LASER SENSOR

This command turns off the laser sensors if the current laser link count is one, is ignored if the link count is zero and decrements the laser link count by one otherwise.

laon                 ( -- )

                                                            TURN ON AND LINK LASER SENSOR

Turns on laser sensor and increments the laser link count by one.  If the link count becomes one, a “lreset” is performed by the EXDVR process.  Thus the uses for “lreset” are very limited.

lasave              ( — <ang #n>...<ang #0> count )

                                                            LASER READ ANGLE DATA

Returns laser angles in tenths of degrees.  Count can be up to eight, 0 if not enabled or -1 on error.  If no lasers are seen, one target is returned with angle of -450 tenths of degrees.

ldisp                ( — )

                                                            LASER DISPLAY DATA

: ldisp

   make                 (format)

   lasave               (laser)

   0<                (FORTH-like)

   if                (conditional)

      drop              (FORTH-like)

      ." lerr "         (FORTH-like)

   else                 (conditional)

      dup               (FORTH-like)

      if             (conditional)

         swap           (FORTH-like)

         dup            (FORTH-like)

         -450 =         (FORTH-like)

         if          (conditional)

            2 rem    (FORTH-like)

            ." lnone "  (FORTH-like)

         else           (conditional)

            swap        (FORTH-like)

            ." lf "     (FORTH-like)

            0 do        (conditional)

               space (FORTH-like)

               angst (variable)

               @     (FORTH-like)

               +     (FORTH-like)

               0 D.R (FORTH-like)

            loop        (conditional)

         endif       (conditional)

      else              (conditional)

         drop           (FORTH-like)

         ." loff "      (FORTH-like)

      endif          (conditional)

   endif             (conditional)

   cr                (FORTH-like)

   out                  (format)

;

Displays current laser reflector angles and status.  Used as a “one-of” for quick checks.  Use “lfdisp” inside macros.  Note that “laon” must be used before this command to initialize blackboard.

lfall                  ( — )

                                                            FIND ALL REFLECTORS

: lfall

   1 sl           (schedule)

   laon           (laser)

   xyton       (motion)

   sts            (motion)

   home           (motion)

   ststop         (motion)

   0 0 0 spos     (motion)

   3600 DSTS @    (FORTH-like)

   TURN           (motion)

   lhead       (laser)

   begin       (conditional)

      GANGP    (motion)

      angst    (variable)

      !        (FORTH-like)

      lfdisp      (laser)

      plst        (motion)

   until       (conditional)

   ltail       (laser)

   0 angst        (variable)

   !           (FORTH-like)

   laoff       (laser)

   xytoff         (motion)

;

Finds all laser reflectors in 360 degree sweep.  Returns angles to leading edge of reflector in signed tenths of degrees added to head angle.  Up to eight reflectors may be listed on one line with at least one.

lfdisp               ( -- )

                                                            LASER DISPLAY ALL FOUND REFLECTORS

: lfdisp

   lasave               (laser)

   0<                (FORTH-like)

   if                (conditional)

      drop              (FORTH-like)

      make              (format)(this is missing from v1.0)

      ." lerr "         (FORTH-like)

   else                 (conditional)

      dup               (FORTH-like)

      if             (conditional)

         swap           (FORTH-like)

         dup            (FORTH-like)

         -450 =         (FORTH-like)

         if          (conditional)

            2 rem    (FORTH-like)

         else           (conditional)

            swap        (FORTH-like)

            make        (format)

            ." lf "     (FORTH-like)

            0 do        (conditional)

               space (FORTH-like)

               angst (variable)

               @     (FORTH-like)

               +     (FORTH-like)

               0 D.R (FORTH-like)

            loop        (conditional)

            cr       (FORTH-like)

            out         (format)

            128 sl2     (schedule)

         endif       (conditional)

      else              (conditional)

         drop           (FORTH-like)

      endif          (conditional)

   endif             (conditional)

   cr                (FORTH-like)

   out                  (format)

;

used in:             lfall

Finds laser reflectors while steer motor is activated.

lhead                ( -- )

                                                            MAKE LASER HEADER

: lhead

   make           (format)

   ." lstart "    (FORTH-like)

   cr          (FORTH-like)

   out            (format)

;

used in:             lfall

Makes a header to indicate that laser reflector search is commencing.

lreset    ( -- )

                                                            LASER RESET

Resets laser expert module.  Since “laon” performs this function, its only use is for debugging.

ltail                  ( -- )

                                                            MAKE LASER TAILER

: ltail

   make           (format)

   ." lstop "     (FORTH-like)

   cr          (FORTH-like)

   out            (format)

;

used in:             lfall

Makes a tailer to indicate that laser reflector search has completed.

 

Format Commands

clrs                  ( <num> ... <num> — )

                                                            CLEAR STACK

Clears all numbers from stack.  A command useful for debugging.

make                ( -- )

                                                            INITIALIZE OUTPUT BUFFER

Initializes output buffer.

out                   ( -- )

                                                            WRITE OUTPUT BUFFER TO TERMINAL

Sends current output buffer contents to the terminal.

ss                     ( — )

                                                            SHOW STACK

Displays formatted listing of stack contents in decimal to terminal.  Useful for debugging.

FORTH-Like Commands

.                       ( prval — )

                                                            PRINT TOS

: .

   make        (format)

   0 D.R    (FORTH-like)

   BL       (constant)

   emit        (FORTH-like)

   out         (format)

;

Prints value on TOS.

."                      ( ." <STRING1>  <STRING2> ... <STRINGn> " )

                                                            DOT QUOTE

Adds the text strings contained within the quotes to the output buffer.  This is a special command in that it operates on text strings following itself.  Note: this is a compile-only command!  Refer to the LLAMA tutorial chapter for more information.

@                     ( addr — num )

                                                            FETCH

Gets contents at address and places onto stack.

!                       ( num addr — )

                                                            STORE

Store num at address.  DANGER: improper use will corrupt system causing system failure.

+!                     ( num addr — )

                                                            ADD STORE

Adds number to number at address.  DANGER: improper use will corrupt system causing system failure.

?                      ( addr — )

                                                            PRINT CONTENTS OF ADDRESS

: ?

   @     (FORTH-like)

   .     (FORTH-like)

;

Prints contents at specified address.

+                      ( n1 n2 — sum )

                                                            ADD INTEGERS

range:               allowed integer range.

Adds two numbers from TOS and TOS-1 as such: n1 + n2.

-                       ( n1 n2 — diff )

                                                            SUBTRACT INTEGERS

range:               allowed integer range.

Subtracts two numbers from TOS and TOS-1 as such: n1 - n2.

-dup                 ( num — num <num> )

                                                            DUPLICATE CONDITIONAL

Duplicates num if not equal to zero.

*                       ( n1 n2 — prod )

                                                            MULTIPLY INTEGERS

range:               allowed integer range / 216.

Multiplies two numbers from TOS and TOS-1 as such: n1 * n2.

/                       ( n1 n2 — quot )

                                                            DIVIDE INTEGERS

range:               allowed integer range / 216.

Divides two numbers from TOS and TOS-1 as such: n1 / n2.

<                      ( n1 n2 — flag )

                                                            LESS THAN

If n1 < n2 then flag=1 else flag=0.

>                      ( n1 n2 — flag )

                                                            GREATER THAN

If n1 > n2 then flag=1 else flag=0.

=                      ( n1 n2 — flag )

                                                            EQUAL TO

If n1 = n2 then flag=1 else flag=0.

0<                    ( num — num flag )

                                                            TOP NEGATIVE

If num is negative, flag=1 else flag=0.

0=                    ( num — num flag )

                                                            TOP ZERO

If num is zero, flag=1 else flag=0.

abs                   ( +/-num -- +num )

                                                            ABSOLUTE VALUE

Return the absolute value of num.

and                  ( n1 n2 — and )

                                                            LOGICAL AND

Performs logical and of two numbers.

at                     ( addr — num )

                                                            FETCH

Gets contents at address and places onto stack. Alias for @.

constant           ( VAL constant NAME )

                                                            INITIALIZE AND DEFINE CONSTANT

This is a special function in that it operates on a text string following it.  A constant is defined and given the name NAME.  It is assigned the value VAL which is on the stack.  Whenever the name is used, it acts much like a primitive and places its address on the stack.  The function “constant” can only be used in the system interpreter.  The constants it defines can be used elsewhere.

cr                     ( — )

                                                            OUTPUT A CARRIAGE RETURN

: cr

   13 emit  (FORTH-like)

   10 emit  (FORTH-like)

;

Print a carriage return, but not automatically, must use within make/out.

D.0                   ( num blksize — )

                                                            LEADING ZEROS NUMBER PRINT

: D.0

   10 48 numc  (FORTH-like)

;

range:

                           num:                      0 - 255

                           blksize:                  0 - 32

Standard output form with leading zeros.

D.R                   ( num blksize — )

                                                            LEADING SPACE NUMBER PRINT

: D.R

   10 32 numc  (FORTH-like)

;

range:

                           num:                      0 - 255

                           blksize:                  0 - 32

Standard output form with leading spaces.

deep                 ( <num1> <num2> ... <numn> depth — <numn> <num2> ... <num1>)

                                                            ROTATE TO DEPTH

range:

                           depth:                    0 to 512

Removes element from position <depth> and places it onto top of stack.

drop                 ( num — )

                                                            DROP TOS

Removes top of stack.

dup                  ( num — num num )

                                                            DUPLICATE TOS

Duplicates top of stack;

emit                 ( val -- )

                                                            PRINT A CHARACTER

range:

                           val:                         1 - 255

Add ASCII character val to output buffer.

max                  ( n1 n2 -- max )

                                                            MAXIMUM

Returns the maximum of n1 and n2.

min                  ( n1 n2 -- min )

                                                            MINIMUM

Returns the minimum of n1 and n2.

mod                 ( n1 n2 -- rem )

                                                            MODULUS

Returns the remainder of n1 / n2.

not                   ( num — notn )

                                                            LOGICAL NOT

Performs logical not on TOS.

numc               ( num blksize base fillchar — )

                                                            PRINTS A FORMATTED CHARACTER

range:

                           num:                      0 - 255

                           blksize:                  0 - 32

                           base:                      2 - 64

                           fillchar:                  0 - 255

Writes a the ASCII string version of desired number into output buffer according to the format specifications.  Blksize is the size of space used by the output in printing.  Base is the number base to print.  Fillchar is the leading char ASCII code.

or                     ( n1 n2 — or )

                                                            LOGICAL OR

Performs logical or of two numbers.

over                 ( n1 n2 — n1 n2 n1 )

                                                            COPY TOS-1 TO TOS

Copies TOS-1 to the TOS.

qb                    ( qb <STRING1>  <STRING2> ... <STRINGn> qe )

                                                            DOT QUOTE

Adds the text strings contained within the quotes to the output buffer. Alias for ."  This is a special command in that it operates on text strings following itself.  Note: this is a compile-only command!.  Refer to the LLAMA tutorial chapter for more information.

rem                  ( <num1> <num2> ... <numn> depth — )

                                                            REMOVE ITEMS

range:

                           depth:                    0 to 512

Removes “depth” numbers from top of stack.  If “depth” is greater then the number of items on the stack then all items are removed.

rep                   ( quantity — <num1> <num2> ... <numn> )

                                                            REPLICATE NUMBERS

range:

                           quantity:               0 to 256

Replicates numbers from stack onto stack.  The top <quantity> will be replicated and placed in the same order onto the top of stack.

rot                    ( n1 n2 n3 — n2 n3 n1 )

                                                            ROTATE TOS-2 TO TOS

Rotates top three items on stack.

space               ( — )

                                                            OUTPUTS A SPACE CHARACTER

: space

   BL    (constant)

   emit     (FORTH-like)

;

For use in formating output, prints a blank character, 20 hex.

store                ( num addr — )

                                                            STORE

Store num at address. Alias for !. DANGER: improper use will corrupt system causing system failure.

swap                ( n1 n2 — n2 n1 )

                                                            SWAPS TOP TWO STACK ITEMS

Swap (exchange) top two stack items.

variable            ( INITVAL variable NAME )

                                                            INITIALIZE AND DEFINE VARIABLE

This is a special function in that it operates on a text string following it.  A variable is defined and given the name NAME.  It is assigned the value INITVAL which is on the stack.  Whenever the name is used, it acts much like a primitive and places its address on the stack.  The function “variable” can only be used in the system interpreter.  The variables it defines can be used elsewhere.

Conditionals

These are a special class of functions in that they expect certain logical grouping, such as an “if” must be complemented with an “endif” with and optional “else”.  Groupings must not be meshed!  Also: conditionals are not allowed in the System Interpreter and may be present only in macros and performance orders.

begin               ( -- )

                                                            START BOOLEAN CONDITIONAL

This command can be nested and must appear in the following groupings:

           begin .... until

           begin .... while .... repeat

where “....” represents valid LLAMA commands.  The standard grouping is:

           begin - while          begin - until

do                    ( index end -- )

                                                            EXECUTE COUNTING LOOP

range:

                           index:                     any valid integer

                           end:                        any valid integer <= index

Executes a loop based on the given indices.  Nesting is only allowed two levels deep.  If the indices are the same, the loop is executed once.  The standard groupings are:

           do - loop                do - +loop

else                  ( -- )

                                                            NOT TRUE EXECUTE

If “if” is not true then code that follows is executed until grouped “endif” occurs.  Standard grouping:

           if - else - endif

An “if” must appear before “else”.

endif                ( -- )

                                                            TERMINATE BOOLEAN TEST

Completes, or encloses, code that represents the true or false test using “if”.  The standard groupings are:

           if - endif                 if - else - endif

if                      ( boolean -- )

                                                            TEST AND EXECUTE BOOLEAN

range:

                           boolean:                false = 0, true = non-zero

If boolean is true then code that immediately follows “if” is executed until a grouped “endif”, “then” or “else” is encountered; if an “else” is then encountered, control skips to the grouped “endif” or “then”.  If boolean is false then control goes to the code following a grouped “else”, if it exists or to code following “endif” or “then” otherwise.  The standard groupings are:

           if - endif        if - else - endif        if - then        if - else - then

I                       ( -- currcount )

                                                            RETURN CURRENT INDEX OUTER LOOP

Returns the current index within the top-level do loop.  Must be within a do loop but is not explicitly grouped, i.e. “meshing” is allowed.

J                      ( -- currcount )

                                                            RETURN CURRENT INDEX INNER LOOP

Returns the current index within the bottom-level do loop.  Must be within a do loop but is not explicitly grouped, i.e. “meshing” is allowed.

leave                ( -- )

                                                            SET LOOP INDICES EQUAL

Useful for exiting do loops.  Sets loop indices equal to allow exiting.  Note: control does not pass to code following “loop” or “+loop”.  Must be within a do loop but is not explicitly grouped, i.e. “meshing” is allowed.

loop                 ( -- )

                                                            LOOP UNTIL INDICES EQUAL

Must be grouped with a “do”.  This command  checks if the index count is less than or equal to the end count and decrements the index and loops back to code following a grouped “do”.  It passes control to the following code if  the indices are equal.  Standard grouping:

           do -- loop

+loop               ( incr -- )

                                                            LOOP UNTIL INDICES DIVERGE OR EQUAL

range:

                           incr:                        any valid positive integer

Must be grouped with a “do”.  This command  checks if the index count is less than or equal to the end count and decrements the index by incr and loops back to code following a grouped “do”.  It passes control to the following code if  the indices are equal or divergent.  Standard grouping:

           do -- +loop

quit                  ( -- )

                                                            EXIT NESTED MACROS

Inserting this command anywhere in a macro will cause that macro and all others it is nested from to terminate immediately.

repeat               ( -- )

                                                            RETURN TO BEGIN

Used within a “while” loop to loop back to the begin statement.  Standard grouping:

           begin - while - repeat

then                 ( -- )

                                                            TERMINATE BOOLEAN TEST

This is an alias for “endif”, useful for FORTH compatibility.

until                 ( boolean -- )

                                                            LOOP UNTIL TRUE

range:

                           boolean:                0 = false, non-zero = true

This command is a conditional loop that returns control to code following a grouped begin as long as boolean is zero.  Standard grouping:

           begin - until

while                ( boolean -- )

                                                            LOOP WHILE TRUE

range:

                           boolean:                0 = false, non-zero = true

This command is a conditional loop that gives control to code following the grouped “repeat” if boolean is zero, otherwise control continues to the next instruction.  One structure supports both standard “while” and “do-while” constructs.  Standard grouping:

           begin - while - repeat

Note: Code between “begin” and “while” is executed at least once.

System Commands

NOTE: The following cannot be executed from a spawned interpreter!

{                       ( — )

                                                            SPAWN INTERPRETER

Enter allowed tokens to execute procedure in background.  End spawn definition by ending with a }.

:                       ( — )

                                                            COMPILE MACRO

Enter allowed tokens to compile new macro.  End with a ;.  The format requires a name composed of any characters except “space”.  Example:

: add_2 + . ;

adds two numbers and displays result.

bye                   ( — )

                                                            QUIT LLAMA

Quits LLAMA while waiting for interpreters to finish tasks.

dump               ( -- )

                                                            DISPLAY CURRENT DICTIONARY ENTRIES

This will list the names of every macro and primitive currently in the system.  Mainly used for DEBUG purposes.

exit                   ( intno -- )

                                                            TERMINATE SPAWNED MACRO

range:

                           intno:                     1 - 31

This command is used to stop executing a performance order.  This is the preferred method of stopping a process since it causes the process to gracefully exit.  If this doesn’t work, first try “flush”, then “kill”.  It is typically used if an interpreter locks due to improper performance order construction.  Note: although the range is as given, only valid interpreter numbers will be accepted while other will be ignored.

flush                ( intno -- )

                                                            STOP EXECUTING SPAWNED INTERPRETER

range:

                           intno:                     1 - 31

This command is used to stop executing a performance order.  This command does not support graceful exiting which means it may cause a protected function to fail, such as any inter-process communication.  It is typically used if an interpreter locks due to performance order construction.  The current interpreter will be paused awaiting the next performance order.  This is the “soft” version of “killspec”.    Note: although the range is as given, only valid numbers will be accepted while other will be ignored.

garbc               ( remnum — )

                                                            GARBAGE COLLECT

range:

                           remnum:               0 - 32

Turns off selected number of interpreters.  This function is used internally to do a sort of garbage collection, removing unused interpreters.  This function waits for completion of the interpreters.  This function is called by LLAMA when a “bye” is entered.

gettime             ( — )

                                                            GET TIME

Returns system time as follows: gt Sat April 21 9:02:32 1991

inter                 ( — )

                                                            INTERACTIVE MODE

Puts LLAMA into interactive mode.  This mode is useful for development work with full echo on, etc.

killspec            ( intno -- )

                                                            STOP AND KILL SPAWNED INTERPRETER

range:

                           intno:                     1 - 31

This command is used to terminate an interpreter immediately.  This command does not support graceful exiting which means it may cause a protected function to fail, such as any inter-process communication.  It should only be used if a unrecoverable failure of an interpreter has occurred.  This is the singular version of “kill”.  Note: although the range is as given, only valid numbers will be accepted while other will be ignored.

numi                ( — )

                                                            NUMBER OF RUNNING INTERPRETERS

Returns number of interpreters working: numinuse and number of interpreters available including those that are working, numcount.

settime             ( yr mo dy hr mn sc — )

                                                            SET TIME

range:

                           year:                       1900 - 2037

                           month:                   1 - 12

                           day:                        1 - 31 (as appropriate)

                           hour:                      0 - 23

                           minute:                  0 - 59

                           second:                  0 - 59

Sets system clock to time specified.

stat                   ( -- )

                                                            GET CURRENT OPERATING MODE

Displays “workmode” or “intermode” depending on current entry mode.  This function is useful in determining if there is an active communication link between LLAMA and G2.

work                 ( — )

                                                            WORK MODE

Puts LLAMA into work mode.  This is the mode used for normal G2-LLAMA operation.  Terminal echo is turned off and should also be turned off at the G2 end.  Only requested data and unsolicited messages/data is returned.  Note that if LLAMA were to hang up unexpectedly, G2 would have to request some form of known status to determine this.

Scheduling Commands

gt                     ( -- year month day hour miniute second )

                                                            PLACE CURRENT TIME ON STACK

Places the current time on the stack in the same format as “txabs” and “settime”.

pause               ( -- )

                                                            PUT  CURRENT PROCESS TO SLEEP

Makes the current process inactive.  Typically, a “wake” command will restart the process.

pid                   ( -- procid )

                                                            GET PROCESS ID NUMBER

Returns the current process id number.  This is useful in inter-process signalling for commands such as “wake”.

sec                   ( -- seconds )

                                                            GET NUMBER OF SECONDS SINCE 1900

Places an integer on the stack that represents the number of seconds since the year 1900.  Since this representation in 32 bits can rollover (change from a large negative number directly to a large positive number) every 100 years or so, care should be used during these times.

sl                     ( time — )

                                                            SLEEP

Sleeps (waits) for time seconds or until a signal is generated.

sl2                    ( time — )

                                                            SLEEPS FOR 256THS SEC

Sleeps (waits) for time 256ths seconds, i.e. 256 = 1 second, or until a signal is generated.

txabs                ( <yr> <mth> <dy> <hr> <min> <sec> count — )

                                                            TIME EXECUTE ABSOLUTE

range:

                           year:                       1900 - 2037

                           month:                   1 - 12

                           day:                        1 - 31 (as appropriate)

                           hour:                      0 - 23

                           minute:                  0 - 59

                           second:                  0 - 59

                           number of arguments:                        0 - 6 (zero implies ignore command)

Execution at time absolute.  Clock must be set to a proper time prior to using this command.  This is similar to sleep with more detailed specifications.

txrel                 ( <hour> <min> <sec> count — )

                                                            TIME EXECUTE RELATIVE

range:

                           hour:                      0 - 23

                           minute:                  0 - 59

                           second:                  0 - 59

                           number of arguments:                        0 - 3 (zero implies ignore command)

Execution at time relative to current time.

wake                ( intno -- )

                                                            WAKE UP PROCESS

range:

                           intno:                     1 - 31

Attempts to wake up selected process.  Great for inter-process control.

Oddities

There is no proper place to put these commands so they have been grouped here.

[                       ( -- )

                                                            SPAWN AN EMBEDDED PROCESS

This open bracket is used only in the bootup list to spawn a sequence of instructions.  There is no way currently to spawn a process from a spawned process.  The reason is that the System Interpreter must manage the spawning of processes and so it would be difficult to enable this to occur within a spawned definition.  This feature should only be used with discretion and its use minimized.  The following is an example of creating a “safety” function and making it sleep until another process wakes it up:

[ pid procid ! pause stopit

This would be a string within the “PARSER.C” file.  This command is not recognized at run time!

bm                   ( -- )

                                                            DISPLAYS EXECUTE TIME OF BENCHMARK

: bm

   sec            (schedule)

   1000 0 do      (conditional)

      add2        (See below)

   loop           (conditional)

   sec            (schedule)

   -           (FORTH-like)

   abs            (FORTH-like)

   make           (format)

   ." benchmark " (FORTH-like)

   0 D.R       (FORTH-like)

   space       (FORTH-like)

   ." seconds "      (FORTH-like)

   cr          (FORTH-like)

   out            (format)

;

: add2

   50 0 do        (conditional)

      3 4 +    (FORTH-like)

      drop        (FORTH-like)

   loop           (conditional)

;

Displays the time of execution of a dummy delay loop in seconds.  This is useful in determining performance gains and losses if hardware or software is altered.  LLAMA 1.0 executes this benchmark in 12 to 14 seconds, typically.

RADIO              ( -- )

                                                            IGNORE RADIO COMMANDS

Note: “RADIO” is not a valid command but refers to any of the following inputs which will cause the system to go into work mode (no echo).  These are considered “valid” commands because if the packet radio communication is disconnected, a number of packet radio messages will be sent to LLAMA and they should be ignored.  Recognized and invalid commands:

           cmd:

           EH?

           ***

           DISCONNECTED

           CONNECTED

To return to interactive mode, an “inter” must be sent.

Variables

Variables are given by name and their initial value.  These values may change without notice due to improvements in the system.

angst                ( 0 )

used in:             lfall

Used as a temporary variable for angles.

count               ( 0 )

used in:             safety

Useful for counting though ultrasonic readings.

CRCTANG        ( 0 )

used in:             “STUAC”-type functions.

Used to specify a steer overshoot check angle.

ddra                 ( 10 )

used in:             dr

Sets a system default drive acceleration.

ddrs                 ( 1 )

Sets a system default drive speed.

distance           ( 0 )

used in:             safety

Used as storage for safety ring distance.

DSTA               ( 2000 )

used in:             st

Sets a system default steer acceleration.

DSTS               ( 200 )

Sets a system default steer speed.

off                    ( 0 )

used in:             stopit, st1, st0, dr1, dr0

Global variable used to stop motion in system.

poll                  ( 0 )

used in:             st1, st0, dr1, dr0

Global variable used to switch ststop and drstop functions on and off remotely.

procid              ( 0 )

used in:             initialization functions

Provided it was set, it contains one Spawned Interpreter’s process id.  This function allows a spawned process to be activated at some time by another process.

set                    ( 10 )

used in:             stopit

Used to set safety ring distance in high level.  Sets distance in tenths of feet.

waittime           ( 256 )

used in:             stopit

Used to determine wait interval for checking distances to objects.

ult                    ( 0 )

Used as a temporary variable for holding an ultrasonic reading.

Constants

Constant names are given with their values.

BL                    ( 32 )

Used as an alias for the ASCII “space” character.

head                 ( 94 )

Used as an alias for the ASCII “caret” symbol.  This is the symbol that precedes any text messages output from LLAMA.  These can be created within macros.  See the function “make”.  The result will be text as in the following example:

^robot turning now<carriage return>