Tracker Script Engine

The Tracker2, Tracker3, and OpenTracker USB include a simple script engine to allow some customization and automation. The scripting language is still under development and information here may change frequently.

See the Script Examples page for more example scripts.

Scripting Overview

Scripts are created in otwincfg and uploaded to flash memory in the tracker. When the SCRIPT option is enabled, the script is executed 8 times per second. If the 'Quick' command is used in the script, the script will execute again in one timer tick — 1/1024 second for the Tracker2, and 1/1200 second for the Tracker3 and OpenTracker USB.

Scripts cannot be remotely edited directly, but the script editor can generate a list of PATCH commands that will allow a prepared script to be uploaded to a remote tracker. Make sure the SCRIPT option is turned off while the script is being uploaded. Turn the script option on when you are ready to run scripts.

Creating a Script

To start the script editor, click the 'Script Editor' button in otwincfg. The editor screen is divided into three main parts. The top left portion is the script listing, the bottom left portion allows data entry, and the right side provides buttons for all script commands.

The highlighted line in the script listing shows where the next command will be inserted. The 'Delete Line' button deletes the currently selected line, and the 'Up' and 'Down' buttons move the line in the listing. Conditional commands cause automatic indentation in the listing. The numbers directly under the listing show the amount of scripting memory used.

Commands that accept one or more parameters use the values in the A, B, C, T, X, Y, area corners, and flags fields. A and B allow selection of three general-purpose 16-bit counters that are used only within the scripting engine, as well as a number of other system variables. C allows entry of numeric constants, T is for text entry, the area corners allow a geographic area to be defined in terms of northwest and southeast corner coordinates, and the flag checkboxes represent "set", "clear", and "don't care" states.

To compare the current altitude to a fixed value, for example, you can select "Altitude" in box A and enter "10000" in box C, and click the "If A > C" button to create the line If Altitude > 10000. The next command entered will be indented, indicating that it will only be executed if that condition is true. The End Block command ends the conditional statement. Else reverses the sense of the last conditional statement and should be used before the closing End Block.

Commands

Do Once

This command is used in conjunction with a conditional statement to execute a block of code once once for each time that the condition becomes true. This makes it very useful for ensuring that a command is not executed repeatedly.

The Do Once command can be used at most 16 times in one script. (If you don't see "DO Once" on the script editor GUI, download the latest OTWINCFG)

If Profile 1
 Do Once
  Exec "SETFREQ 144.390 144.390"
 End Block
Else
 Do Once
  Exec "SETFREQ 144.990 144.990"
 End Block
End Block

This example for a T2-301 executes the command to set the radio's transmit and receive frequencies depending on the profile. Without the Do Once command, the SETFREQ command would execute continuously and would eventually wear out the radio's configuration memory.

Macro T / Macro Out

The following block is executed when the command named in T is entered at the command line, through the FMI interface, or by APRS message. The Macro Out (which actually creates a Macro Write line) responds to the macro through the same channel.

Macro FOO
  Macro Write "Bar"
End Block

Typing FOO at the command line will generate the response Bar. Likewise, a remote command CMD FOO will receive the response Bar by APRS message.

If In Area

Executes the following block if the tracker's current location is within the defined geographic area. Coordinates are entered in degrees and decimal minutes, but are displayed in decimal degrees.

If In Area (35.00000,-120.50000)(34.86667,-120.36667)
  PrintA "Welcome to Santa Maria!"

If Profile 1 / If Profile 2

Executes code based on the currently active profile.

If Profile 1
  PrintA "This executes only in profile 1."
End Block

If A = B / If A < B / If A > B

Compares two 16-bit counters.

If Altitude > Counter 1
  Set Counter 1 = Altitude
End Block

This example records the highest altitude attained in counter 1.

If A = C / If A < C / If A > C

Compares a counter to a constant value.

If Pulse Count = 100
  PrintA "100 input pulses have been recorded."
End Block

On Startup

Executes a block of code only once, immediately after the tracker is powered on.

On Startup
  Exec "BEACON Tracker is alive!"
End Block

On Second

Executes a block of code once per second.

On Second
  PrintA "Tick!"
End Block

On Interrupt

Executes a block of code whenever a low-going edge is detected on the IRQ pin.

On Interrupt
  Decrement Counter 1
End Block

On GPS Fix

Executes the following block whenever a valid GPS position fix is obtained.

On GPS Fix
  PrintA "Got fix."
End Block

Set A = B / Set A = C

Sets a counter to the value of another counter or constant.

Increment A / Decrement A

Increments or decrements the specified counter by one.

Port A Print / Port B Print

Sends a string to the specified serial port.

Execute T

Executes the text in T as if it was entered at the command line.

Exec "PATH WIDE1-1,WIDE2-2"

Use this command carefully — the tracker's flash memory has a write endurance of about 100,000 cycles. Use flags or Do Once to avoid executing the same command repeatedly.

Quick

Causes the script engine to start again in 1/1024 second instead of 1/8 second.

Peek C&X=Y?

Reads the contents of memory location C, performs a logical AND with X, and compares the result to Y.

If Peek 3 and 4 = 4
  PrintA "SQL input is high"
End Block

Poke C,X&Y

Sets the contents of memory location C with the value in X, using Y as a bit mask.

Poke 2, 1&3

Set Flags / Toggle Flags / Clear Flags

Set Flags 00000111
PrintA "Flags are now 00000111"
Toggle Flags 00000001
PrintA "Flags are now 00000110"
Clear Flags 00000010
PrintA "Flags are now 00000100"
Toggle Flags 00000001
PrintA "Flags are now 00000101"

If Flags

Executes the following code block if the flags match the specified pattern.

If Flags xxxxx101
  PrintA "Two flags are set and one is clear"
End Block

Counters

Three general-purpose counter variables are reserved only for scripting use, and other system values are also accessible. All counters are unsigned 16-bit integers and will wrap from 65535 back to 0.

Counter 1 - Counter 3

These general-purpose counters have no predefined meaning and no effect on the rest of the system.

Ticks

Increments every timer tick, wrapping back to 0 each second.

TX Counter

Seconds since the last automatic transmission.

Second

Second of the current hour (0–3599).

Pulse Count

Used by the event counter function.

Last Digi

Seconds since last heard own packet repeated.

Last Fix

Seconds since last valid GPS fix.

Altitude

Current GPS altitude in units of 2.56 meters. 0 = –10,000 meters. 5097 ≈ 10,000 ft or 3,048 m.

Result

Return value of last EXEC command. See user manual.