TopoBasic (Programming Language)

From Archive of Vintage Robotics & Technology Companies
A simple TopoBasic program for turning a Topo in a circular loop with X sides.

TopoBasic is an extended version of the BASIC programming language to add support for the Topo line of robots starting in 1983.

All BASIC functions and programming concepts apply to TopoBasic.

Language Introduction[edit | edit source]

Program Requirements[edit | edit source]

  • During startup, the routine GOSUB 6000 needs to be ran to start up communication with the transmitter interface card.
  • All programs should start with GOSUB 7000 to reset all start-up values that may have been changed from previous programs being run.
  • Programs also must end with an END line.
  • Programs can be run with the RUN command.
  • Routines will use the N variable as a parameter for the current function being executed, meaning N may need to be set before executing certain functions, such as movement and turn controls.
  • The SAVE TOPOBASIC command will save programs written in TopoBasic to the diskette holding the program. This does not save any of the variables used, such as calibration settings. These must be recorded in the INIT routine to properly be saved between reboots of the software.

Apple II & Basic Notes[edit | edit source]

  • A program can be stopped by pressing CTRL+C if ran on an Apple II PC
  • The : character is used as a separator, allowing multiple statements (or comments) to be put on one line.
  • The REM keyword is used to denote remarks, also known as a comment.

Topo Calibration[edit | edit source]

Some Topo robots may need calibration out of the box or after use to provide accurate function. Multiple parts can be calibrated.

Zeroing the Motors[edit | edit source]

Each motor may have a tendency to lean forwards or backwards when on, and will need to be adjusted to stay still. After identifying the motor to calibrate, set its corresponding Neutral Value to the calibration value. For the Left Motor, this is 7005 Z1 = A. For the Right Motor, this is 7010 Z2 = A. Due to the nature of the calibration program, it is best to set only one motor at a time to this value.

Entering GOSUB 7200 will trigger the Calibration Program. In this, Topo's motors and indication lights will be turned on using the current default value. Topo must be put on a surface where it cannot touch the ground, such as its original stand, to calibrate correctly. The user then must identify if either indication light for the motor is on or off. Both being on or off for one side means that the motor is already calibrated. The front light being on means the robot is calibrated leaning forward, and the back light being on means its calibrated leaning backwards.

A prompt will appear on the screen for entering the new value to be inserted into the Z1 or Z2 values marked for calibration. The default factory value is 1024, meaning a forward leaning state must be corrected with a smaller number, and a backward leaning state must be corrected with a higher number. This should be done in increments of 10 for quick results.

After finding a value that has the motor calibrated, enter 0 to exit the calibration program. The Z1 and Z2 values still need to be manually set after this step, so the value found to be correct during calibration needs to be set: 7005 Z1 =____ or 7010 Z2 = ____.

Distance & Angle Calibration[edit | edit source]

TODO:

Basic GOSUB Routines[edit | edit source]

Routines that can be called using the GOSUB function.

Line Number Function Summary Description
5000 JOYSTICK Makes joystick run Topo Puts Topo under joystick control. To exit, hit any key on the keyboard. Uses none of the calibration variables.
5100 TFD: Moves Topo forward Такев input М and makes Topo go forward М steps at full speed, typically going N centimeters, then stop. Uses speed variables Fi and F2, and distance factor SFD.
5200 TBK: Moves Topo back Takes input М and makes Торо go backward М steps at full speed, typically going М centimeters, then stop. Uses speed variables В1 and B2, and distance +ас ог SBK.
5300 TLT: Moves Topo left Такев input М and makes Торо turn М steps to the left at full speed, typically going М degrees, then stop. Uses Speed values В1 and F2, and angle factor SLT.
5400 TRT: Moves Topo right Такев input М and makes Topo turn N steps to the right at full speed, typically going N degrees, then stop. Uses speed values Ғі and B2, and angle factor SRT.
5500 TSTOP: Stops Topo Makes Торо stop. Uses neutral values 71 and 22. Typically used after a TSET or TSTEP.
5600 TSTEP: Makes Topo step Combines the functions of TSET and TCOUNT. Sets control channels to Ci-4, and waits for а number of frames equal to STP before returning. Note that the motors will not be stopped on return.
5700 TSTEPSTOP: Makes Topo step, stop Combines the functions of TSTEP and TSTOP. Sets control channels, waits for a number of frames equal to STP, and then stops motors.
5800 TCOUNT: Generates a delay Takes ав input the variable STP апа generates a delay equal to that number of time frames (1/50 second per frame, so STP=50:GOSUB 5800 delays 1 second).
5900 TSET: Sets all channels Sets Торо control channels to the values of Сі, C2, C3, and Са. Appropriate values for C1 or C2 will engage the motors. Note that they will continue to run until a command is given to stop.
6000 TRESET: Resets all channels Resets the interface card to its wake-up state, with all control channels set to neutral values. Must be executed once after system power-up to start data transmission to Topo.
6300 HOLD: Stores channel values Utility routine, used to pass values C1-C4 to the machine language Topo driver program.
6450 STORESTP: Stores step value Utility routine, used to pass the value of STP (step delay time) to the machine language Торо driver program.
6500 TFDX: Extended forward move Similar to TFD, but with smoother and more precise motion. Takes input N and moves Topo forward N centimeters. Correction factors FS and RF together with XFD adjust the distance travelled. Variables FUP, FDN, and E1-E4 control orientation and smoothness during starting and stopping.
6600 TBKX: Extended back move Similar to TBK, but with smoother and more precise motion. Takes input N and moves Topo backward centimeters. Correction factors BS and RB together with ХЕК adjust the distance travelled. | Variables BUP, BDN, and А1-А4 control orientation and smoothness during starting and stopping.
6700 TLTX: Extended left turn Similar to TLT, but with more precise turning for any given angle. Takes input N and turns Topo М degrees to the left. Correction factor CL and scale factor XLT adjust the turning angle.
6800 TRTX: Extended right turn Similar to TRT, but with more precise turning for any given angle. Takes input N and turns Topo N degrees to the right. Correction factor CR and scale factor XRT adjust the turning angle.
7000 INIT: Sets initial values Resets all motion variables to their correct start-up values. | Should be called at the start of each user program. Latest calibration values should be saved into this routine.
7200 CALIBRTE NEURAL VALUES Calibrates neural values Interactive calibration routine for setting the neutral values 21-74, one at a time.
7300 CALIBRATE LINEAR MOTION Calibrates linear motion Interactive routine for setting the speeds on both wheels. Normally used to determine the values that yield straight-line motion.

Basic Variables[edit | edit source]

The following variable names аге reserved. The ones with descriptions сап bе calibrated by the user, others are used internally by the various routines Remember that BASIC only "sees" the first two characters of any name. All variables are saved onto the TopoBasic program for use in each reboot of the software.

Variable Description
AS ----
A1 Backward left ramp speed, startup
A2 Backward right ramp speed, startup
A3 Backward left ramp speed, stopping
A4 Backward right ramp speed, stopping
BDN Backward ramp stopping time
BS Backward short distance slippage
BUP Backward ramp starting time
B1 Backward full speed, left wheel
B2 Backward full speed, right whee
CD ----
CH% ----
CL Left turn correction factor
CR Right turn correction factor
C1 Channel one (left wheel) storage
C2 Channel two (right wheel) storage
C3 Channel three storage
C4 Channel four storage
DI Directional Horizontal Input state for Joystick, type 5050 DI = 255 for reversed controls, and 5050 DI = 0 to revert to normal.
DT ----
DL ----
DH% ----
E1 Forward left ramp speed, startup
E2 Forward right ramp speed, startup
E3 Forward left ramp speed, stopping
E4 Forward right ramp speed, stopping
FDN Forward ramp stopping time
FS Forward short distance slippage
FUP Forward ramp starting time
F1 Forward full speed, left wheel
F2 Forward full speed, right wheel
HN% ----
HS% ----
H1% ----
H2% ----
H3% ----
H4% ----
LN ----
L1 ----
L2 ----
L3 ----
L4 ----
L5 ----
N Command variable set by user
RB Minimum ramp distance, backward
RF Minimum ramp distance, forward
SBK Backward distance scale factor
SFD Forward distance scale factor
SLT Left turn scale factor
SRT Right turn scale factor
STP Step increment, 50 = 1 second
SYNC ----
XBK Extended backward scale factor
XFD Extended forward scale factor
XLT Extended left turn scale factor
XRT Extended right turn scale factor
Z1 Channel one neutral value (Left Motor)
Z2 Channel two neutral value (Right Motor)
Z3 Channel three neutral value
Z4 Channel four neutral value

Assembly Program Memory Map[edit | edit source]

Start End Description
$300 $3DB Торо machine language routines
$3EA $3FF Торо machine language variables (see below)
$3EA $3EB STEPS counter - Lo, Hi: used by TCOUNT
$3EC $3FS Neutral values storage: set by HOLD (see below)
$3EC $3ED CH4 Neutral - Hi, Lo
$3EF $3EF CH3 Neutral - Hi, Lo
$3F0 $3F1 CH2 Neutral - Hi, Lo
$3F2 $3F3 CH1 Neutral - Hi, Lo
$3F4 $3F5 SYNC Neutral - Hi, Lo
$3F6 $3FF Running values storage: set by HOLD (see below)
$3F6 $3F7 CH4 Running - Hi, Lo
$3F8 $3F9 CHS Running - Hi, Lo
$3FA $3FB CH2 Running - Ні, Lo
$3FC $3FD СН! Running - Hi, Lo
$3FE $3FF SYNC Running - Hi, Lo