STorM32 Scripts

descriptions refer to firmware v2.51e and later

With firmware version v0.51 the possibility of uploading scripts to the STorM32 controller, which are then executed on-board, without connection to a PC, has been introduced. It allows you to programmatically affect the behavior of the controller in order to achieve user specific needs and tasks with unprecedented flexibility. The STorM32 controller was the first of its kind to offer this innovative feature, which was when later adopted by others.

The on-board scripts bring great possibilities, but need some understanding to avoid doing nonsense. This article gives some background, and presents the concepts by means of examples.

Overview of Script Types

The STorM32 on-board scripts should not be confused with other types of scripts, thus a short overview:

• On-board Scripts: These scripts are uploaded and stored into the controller, and are executed permanently by the controller. They are programmed by the user via the GUI's [GUI:Scripts] tab.

• Motion Control Scripts: The GUI has also incorporated a dedicated Motion Control processor, which can be accessed via the [GUI:Motion Control Tool] in the [GUI:Tools] menu. These scripts are executed on the PC, sending commands to the STorM32 controller via e.g. USB, Bluetooth, or any other serial connection between the PC and the controller. The Motion Control scripts are essentially Perl scripts, with some convenience functions added.

• Mission Planner Scripts: The ArduPilot's Mission Planner allows to run Python scripts, which, akin to the STorM32 Motion Control scripts, are executed on the PC, sending messages to the autopilot.

For all these scripts, the source code is stored in plain ASCII text files (and could hence be edited by any text editor), but the script type can be determined from the default file extension:

.scr = STorM32 on-board script
.mcs = STorM32 Motion Control script
.py  = Mission Planner Python script

When using the respective tools for handling the scripts, only the correct scripts, i.e. files with the correct file extension, should be accessible with the tools, avoiding confusion.

This article focuses exclusively on the STorM32 on-board scripts.

Technical Background

Since the code space on the STorM32 controller is very limited (currently only 128 bytes in total are available for the on-board scripts), and especially because of performance reasons the scripts are stored in the controller as binary pseudo code.

The workflow is thus such: The scripts written in the STorM32 on-board scripting language are translated into the pseudo code with a home-brewed compiler, which is integrated into the GUI. The pseudo code is then stored into the STorM32 controller board with a [Write]. The pseudo code is permanently executed online by the STorM32 controller using an internal pseudo-code processor.

For understanding the internal working one should realize, that the STorM32 controller code is essentially an endless loop, which is triggered and repeated every 1.5 ms. This shall be called a cycle. Two situations can hence occur in the execution of the pseudo code, namely that the next pseudo command should be executed in the same cycle as the previous one, or be postponed and executed in the next cycle. Generally, the function commands are of the first kind, while for the control flow commands it depends.

Usage

In total four scripts, named Script1 to Script4, can be run simultaneously and independently. For each script, two fields are available in the [GUI:Scripts] tab, e.g. for Script1 these are:

• Script1 Control
• Script1

The first parameter field allows us to select the input channel, to which the script should "listen", i.e., which input value is used in the script for e.g. triggering one of the up to four cases (see below).

The second parameter field holds the code. It can be edited via the [Edit Script1] button. It opens the script editor window, which allows you to write, load and save code. Its syntactic correctness may be checked by doing a [Compile]. For accepting the code use [Accept and Edit].

Script1 is the master script in the sense that it allows us to modify the Script2 Control, Script3 Control, and Script4 Control parameters and hence to affect the behavior of the other scripts, while the other scripts can't modify any of script control parameters.

Scripting Language

The on-board scripting language has a relatively rich set of commands, which allows us to modify the controller behavior in reaction to inputs, as well as to control the camera for motion control.

Control flow commands:

CASE#DEFAULT
CASE#1
CASE#2
CASE#3
STOP
REPEAT
WAIT time(int, in 0.1secs)
RESTART

Parameter value commands:

SETP parametername(string) option(int, float or string)
SETPMINMAX parametername(string) option(int, float or string) option(int, float or string)
RESTORE
RESTOREALL
SET parametername(string) value(int)
SETMINMAX parametername(string) minvalue(int) maxvalue(int)

The commands SETP and SET are identical function-wise, namely set a parameter to a value, but they differ in the second argument: In SETP the set-to value of the parameter is specified as it is displayed in the GUI (except of the unit in value fields), while in SET the new value is specified by its internal integer representation. For instance, if the parameter Camera Model should be set to “GoPro Hero5”, then the SETP command would be SETP "Camera Model" "GoPro Hero5", and the SET command would be SET "Camera Model" 10 (since the option "GoPro Hero5" is internally represented by the integer 10) (you can check this with [GUI:Share Settings]).

Similar holds for the second and third parameters in the SETPMINMAX and SETMINMAX commands.

The SET and SETMINMAX commands are still existing for compatibility, but should not be used in new scripts (in fact, the script compiler will replace them with the newer SETP and SETPMINMAX commands).

Function commands:

SETANGLEPITCH angle(float, in degree°)
SETANGLEROLL angle(float, in degree°)
SETANGLEYAW angle(float, in degree°)
SETANGLE pitchangle(float, in degree°) rollangle(float, in degree°) yawangle(float, in degree°)
SETANGLEPITCH_W angle(float, in degree°) time(int, in 0.1secs)
SETANGLEROLL_W angle(float, in degree°) time(int, in 0.1secs)
SETANGLEYAW_W angle(float, in degree°) time(int, in 0.1secs)
SETSTANDBY 0/1
DOCAMERA 0/1/2/3/4
DORECENTER
SETPWM pwmvalue(int)
SETPANOWAITS pitchtime(int, in 0.1secs) yawtime(int, in 0.1secs) shottime(int, in 0.1secs)
SETPANORANGE yawangle(int, in degree°)
SETPANOALLOWEXIT
DOPANO pitchangle(int, in degree°) steps(int)
BEEP

Most function commands mirror serial RC commands (both in fact call the same internal functions). For further info thus please see Serial Communication - RC Commands.

Additional commands:

REMOTEENABLE
REMOTEDISABLE

The script function commands modify the very same set of internal variables which are also modified by the serial RC commands, MAVLink messages, and UAVCAN messages. This can lead to conflicts when the latter are used in combination with scripts, which can be resolved with the REMOTEDISABLE/REMOTEENABLE script commands. With REMOTEDISABLE the scripts are given priority over the serial RC, MAVLink, and UAVCAN commands, with REMOTEENABLE the default behavior is restored.

Examples

Changing a Parameter via the Transmitter

Adjusting the value of a parameter during operation by e.g. tuning a knob on a transmitter is probably the most basic use-case of the scripts.

Let's consider GekoCH's application as an example (see here): He's using a gimbal on a copter, and asked for the possibility to change the speed by which the camera turns upon a rc signal via another rc signal. He used a poti on the transmitter and the absolute mode to adjust the pitch orientation of the camera. It's obviously not possible to simultaneously fly the copter and to move the poti that precisely that a smooth camera motion is obtained, hence the Speed Limit feature was used. That is, the poti is quickly moved to the target orientation, and thanks to the speed limiter a smooth turn of the camera results. However, only one speed was possible before. Three solutions shall be discussed:

Method A

CASE#DEFAULT
  SETP "Rc Pitch Speed Limit" 40.0
  STOP
CASE#1
  SETP "Rc Pitch Speed Limit" 5.0
  STOP

When the input specified in the Script Control parameter field yields a "default" value, then the pitch speed limit is set to 40.0 °/s, respectively, while when the input value is such to trigger CASE#1, then the speed limit is set to 5.0 °/s. Every CASE statement needs to be finished with either a STOP or a REPEAT. Here the STOP commands is used, which means that the preceding SETP command is executed only once when the input value changes, and not every cycle again.

At this point one may ask, which input values triggers which case? The full answer isn't trivial and needs a familiarity with the STorM32 controller. In the given example, the default case is selected then the poti is below ca. 33% (< 1633 us), and case #1 is triggered then the switch is above ca. 83% (> 1830 us).

Method B

 SETPMINMAX "Rc Pitch Speed Limit" 5.0 40.0
 REPEAT

The SETPMINMAX command linearly interpolates between the minimum value (5.0 °/s) and maximum value (40.0 °/s), depending on the input value. For instance, for an input value of 200 the pitch speed limit is set to 200 * (40.0-5.0)/1000 + (40.0+5.0)/2 = 29.5°/s. Hence, method B allows us to adjust the speed limit continuously in the range of 5.0 °/s to 40.0 °/s. The REPEAT command at the end ensures, that the SETPMINMAX command is executed at every cycle anew, and not just once, so that any change in the input value is quickly tracked.

A video by GekoCH using this feature is here.

Method C

CASE#DEFAULT
  RESTORE "Rc Pitch Speed Limit"
  STOP
CASE#1
  SETP "Rc Pitch Speed Limit" 5.0
  STOP

This example is essentially method A, but overcomes a minor yet potentially annoying issue. In method A, the parameter value specified in the “Rc Pitch Speed Limit” field of the GUI is overwritten immediately by the script, and hence becomes obsolete. In most cases one would however prefer that the default value is determined by the entry in the GUI, and not by that in the script. This issue is resolved by the RESTORE command, which sets the “Rc Pitch Speed Limit” parameter to the value stored in the EEPROM.

A similar RESTOREALL command exists, which sets all parameters to their values stored in the EEPROM. However, for efficiency reasons it should usually not be used, except then it is really absolutely needed. Using several RESTORE commands is much preferred over using RESTOREALL. In short, avoid RESTOREALL if you can.

Concluding Remarks

Of course, one is not limited to only the Rc Pitch Speed Limit parameter. ANY other available parameter (except of the Script Control parameters as discussed before), can be used in the SET and SETPMINMAX commands and hence be modified by the scripts. Furthermore, any case statement can of course be followed by more than one command, such that complex situations can be tackled (it is though not possible to have another case statement within a case statement).

Up to four cases can be distinguished, via the CASE#DEFAULT, CASE#1, CASE#2, CASE#3 statements. A case is chosen dependent on the value of the input selected by the Script Control parameter, in close analogy to all the other available functions such as the Rc Inputs, Pan Control or IR Camera Control, see also Inputs and Functions.

Running a Motion Control Sequence

CASE#DEFAULT
  STOP
CASE#1
  SETANGLE -22.5 0 31.5
  WAIT 20
  DOCAMERA 1
  SETANGLEYAW 0
  WAIT 20
  DOCAMERA 1
  SETANGLEYAW -31.5
  WAIT 20
  DOCAMERA 1
  SETANGLE 22.5 0 -31.5
  WAIT 20
  DOCAMERA 1
  SETANGLEYAW 0
  WAIT 20
  DOCAMERA 1
  SETANGLEYAW 31.5
  WAIT 20
  DOCAMERA 1
  DORECENTER
  STOP

This short sequence consumes already 62 of the 128 bytes, which shows that only relatively short motion control sequences are possible with the on-board scripts.

Running a Pano Sequence

The previous motion control sequence allows to record a pano, which however is severely limited by the maximal possible script code size. Thus, more powerful commands were introduced, which allow quite extensive pano shots.

CASE#DEFAULT
  DORECENTER
  STOP
CASE#1
  SETANGLEYAW_W 45 30
  SETPANOWAITS 30 30 10
  SETPANORANGE 90
  DOPANO 30 -8
  DOPANO 0 8
  DOPANO -30 -8
  STOP

The SETANGLEYAW_W command sets the yaw angle to 45°, and waits 3.0 secs in addition to the predicted time for the turn. The SETPANOWAITS and SETPANORANGE commands set some "global" parameters of the pano, namely the time to wait after each pitch movement, the time to wait after each yaw step, the time to wait before each shot, and the total yaw angle range which shall be covered. The DOPANO commands finally run the pano sequence. The first DOPANO command, e.g., sets the pitch angle to 30°, and then does 8 yaw steps in counterclockwise direction. In each step the yaw axis is progressed by 90°/8 = 11.25°. Similarly for the next two DOPANAO commands.

User Examples

Switching Between Two Alternate Functions of a Continuous RC Channel Using a "Shift Key"

by Hb121280, see also [1]

Imagine you want to control gimbal pitch and gimbal yaw using an analog dial on the remote control, but only one analog dial is available. This example uses a button channel to switch between alternate functions of one continuous channel.

 CASE#DEFAULT
   SETP "Rc Pitch" "Virtual-8"
   SETP "Rc Yaw" "off"
   STOP
 CASE#1
   SETP "Rc Pitch" "Virtual-8"
   SETP "Rc Yaw" "off"
   STOP
 CASE#2
   SETP "Rc Pitch" "Virtual-8"
   SETP "Rc Yaw" "off"
   STOP
 CASE#3
   SETP "Rc Pitch" "off"
   SETP "Rc Yaw" "Virtual-8"
   STOP

The Script Control variable is set to the button channel, e.g. “Virtual-8”. In the present case the button channel delivers a value 0 in case it is not pressed and 254 if it is pressed. According to Inputs and Functions: Overview Diagram, the value ranges for the CASE statements are:

• CASE#DEFAULT: -166 ... +166
• CASE#1: +333 ... +500
• CASE#2: -500 ... -333
• CASE#3: +223 ... +267

Thus, the cases CASE#DEFAULT and CASE#3 have to be used, because the button values 0 (not pressed) and 254 (pressed) fall into their value ranges. The script language does not allow 'missing' case statements, and CASE#1 and CASE#2 need also to be specified (they can be filled with any commands, since they never would be triggered).

In the above script, the standard behavior (button not pressed) uses the analog channel, or input “Virtual-8”, for Rc Pitch. Rc Yaw is accordingly set to “off”. Pressing the button reverses the assignments: The analog channel on input “Virtual-8” is now used for Rc Yaw, and the control of pitch is deactivated.