Difference between revisions of "Scripting"

Latest revision as of 21:51, 2 January 2013

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

Script Editor

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 (normally used for the event counter input or transmit-now function).

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

Sets a counter to the value in another counter.

Set A = C

Sets a counter to the value specified in box C.

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, and any command that changes a value in the tracker's configuration will require a flash write. At 8 script executions per second, an errant script could wear out the flash memory in a few hours. Flash writes also cause the received packet buffer to be discarded. 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. This can be useful when higher timing resolution is required.

Peek C&X=Y?

Reads the contents of memory location C, performs a logical AND with X, and compares the result to Y. Use of this command requires knowledge of the tracker's memory map.

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

This example reads from memory location 3 (the MCU's port D) and tests if bit 2 (the SQL input) is set.

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

This example turns on the RX LED and turns off the TX LED. Bit 0 of port C (at location 2) is the RX LED, and bit 1 is the TX LED. The mask of 3 (00000011 in binary) leaves the high 6 bits of port C unchanged.

Set Flags / Toggle Flags / Clear Flags

Sets, toggles, or clears the selected 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. A grayed-out checkbox indicates a "don't care" condition. This is shown in the code listing with an 'x'.

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 they have no effect on the rest of the system.

Ticks

This counter starts at 0 and increments every timer tick, wrapping back to 0 at the start of each second.

TX Counter

Seconds elapsed since the last automatic transmission.

Second

This counter indicates the second of the current hour (synchronized to GPS time) from 0 to 3599.

Pulse Count

This counter is used by the event counter function described in the Tracker2 manual.

Last Digi

Seconds elapsed since the tracker last heard one of its own packets repeated by a digipeater.

Last Fix

Seconds elapsed since the last valid GPS position fix was received.

Altitude

Current altitude reported by the GPS receiver. Units are 2.56 meters, and 0 indicates an altitude of -10,000 meters. Thus, a value of 5097 is approximately 10,000 feet or 3,048 meters ((3,048 meters + 10,000) / 2.56 = 5096.875).

Result

Return value of the last command prompt (EXEC) command executed. See the user's manual for return values of each command.