Overview

A primitive may be an operation running solely within the host application or it may involve running a TEA program stored within the robot.  The Garcia API transmits commands via the link to launch TEA programs.  It also checks for messages from the robot coming back across the link.  Any host application that can send and receive messages via the link can do the same thing.

Launch Commands

TEA programs for primitives may be found in the aGarcia subdirectory.  The main declaration in each TEA program determines the number of parameter bytes for each program.  Launch commands must provide the declared parameters.  Launch commands are cmdVM_RUN packets.

Parameters must be converted to raw Garcia units.  Sensor indexes, mode codes, and distance and angle conversion factors are supplied in the aGarciaDefs.tea file.  Range threshold conversions are specific to the response of the GP2D12 sensors and 10-bit A2D resolution of the BrainStem controllers.  For example, a GP2D12 outputs roughly 1.4V when detecting an object 20cm away.  The robot converts voltages between 0-5V to an integer in the range 0-1024.  So a range threshold of 20cm would be an integer value of (1.4 / 5) * 1024, or 286.  The GP2D12 sensor does not have a linear response so thresholds must be determined with a curve fit or interpolation.  Here is a summary of the conversions:

Distance - raw encoder ticks
Angle - raw encoder ticks
Range - 10-bit voltage based on GP2D12 curve-fit
Side - index of sensor
Mode - defined code
Time - milliseconds

The following command set is current for Build 22.  It lists commands for launching all primitives that run within the robot.  The first byte is an address byte for the module running the program.  The second byte in parentheses is the size byte, or number of bytes that follow.  The third byte is the command code.  The fourth byte is a VM execution flag byte.  The fifth byte is the TEA file slot.  The sixth byte is the process ID.  The remaining bytes are parameters.  In multiple-byte parameters, the highest order byte always comes first.

Launch Reply

The robot will return a reply packet immediately after launch.  If launch was successful, it will send a cmdVM_RUN packet with a single data byte with the ID of the process that began execution.  If launch was unsuccessful, the reply contents and size may vary but the third byte will be a cmdVM_MSG byte: 128 decimal or 0x80 hex.

Exit Message

The robot will send an exit message when the TEA program terminates.  If the program terminates normally, it will return an exit message with a 2-byte status parameter.  The 2-byte status parameter lets the user know why the program stopped.  If the program terminates abnormally, it will not return the status parameter and the fourth data byte will be a non-zero VM exit code value.  An abnormal termination is usually due to a corrupt file in the robot or improper initialization of the robot.  In practice, an abnormal termination should not occur unless a program is killed by the API.  If a process is killed, the exit message will have the same format as the abnormal termination message.