STorM32 Scripts

descriptions refer to firmware v0.77a and later

With firmware version v0.51 the possibility of downloading scripts to the STorM32 controller, which are then executed online, 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 then later adopted by others.

The on-board scripts bring great possibilities, but also allow us to do great nonsense. So, it needs some understanding of the user. This article gives some background, but mainly presents examples.

Overview of Script Types

It is important to not confuse the STorM32's on-board scripts with other types of scripts, thus a short overview:

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

• Motion Control Scripts: The GUI has also incorporated a dedicated Motion Control processor, which can be accessed via the [Motion Control Tool] in the [Tools] menu. These scripts are executed on the PC, allowing us to send commands to the STorM32 controller via e.g. the 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 which file is which 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.

This article focuses exclusively on the on-board scripts in the following.

Technical Background

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

The workflow is thus such, that 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 each [Write]. The pseudo code is permanently executed online by the STorM32 controller with the help of a pseudo code processor.

STorM32 on-board Scripting Language

The on-board scripting language has a relatively rich set of commands, which allow you to modify the controllers behavior upon inputs, as well as to control the camera for motion control.

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

SET parametername(string) value(int)
SETMINMAX parametername(string) minvalue(int) maxvalue(int)
RESTORE
RESTOREALL
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°)
SETSTANDBY 0/1
DOCAMERA 0/1/2/3/4
DORECENTER
SETPWM pwmvalue(int)

Examples

Changing a Parameter via the Transmitter

To change 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. It can be achieved in two ways, depending on the goal.

Let's consider GekoCH's application (see here): He's using the 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. For controlling the pitch axis he uses a poti on the transmitter and hence the absolute mode to adjust the pitch orientation. 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 is used, i.e. 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
  SET "Rc Pitch Speed Limit" 400
  STOP
CASE#1
  SET "Rc Pitch Speed Limit" 50
  STOP

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

This way one can realize in total four different settings, as there are four cases CASE#DEFAULT, CASE#1, CASE#2, CASE#3.

At this point one might ask, which input values correspond to which of the four cases, and at which position the poti has to be for a case. The full answer isn't short and needs a good familiarity with the STorM32 controller. In the given example, the default case would be selected then the poti is below 0% (< 1500 us) and case #1 then the switch is at ca 100% (> 1830 us).

Method B:

 SETMINMAX "Rc Pitch Speed Limit" 50 400
 REPEAT

The SETMINMAX commands linearly interpolates between the minimum value (50 or 5.0 °/s) and maximum value (400 or 40.0 °/s), depending on the input value. For instance, for an input value of 200 the pitch speed limit is set to 200 * (400-50)/1000 + (400+50)/2 = 295 or 29.5°/s. Hence, method B allows to adjust the speed limit continuously within the range of 5.0 °/s to 40.0 °/s. The REPEAT command at the end ensures, that the SETMINMAX command is not executed only once, but repeated again in the next and all following cycle, so that any change in the input value is quickly tracked.

A video by GekoCH, where he used this feature, is shown here.

Of course, one is not limited to only the Rc Pitch Speed Limit parameter, but ANY other available parameter can be used in the SET and SETMINMAX commands (enclosed by ""). Also, of course more than one command can follow a case statement.

Method C:

CASE#DEFAULT
  RESTORE "Rc Pitch Speed Limit"
  STOP
CASE#1
  SET "Rc Pitch Speed Limit" 50
  STOP

This example is pretty much like that in method A, but overcomes a minor point which might be annoying. The disadvantage of method A is, that the parameter value specified in the respective tab of the GUI is overwritten immediately by the script, and hence becomes obsolete. In most cases one would however like to determine the default values by the GUI's fields, and not in the scripts. This issue is resolved by the RESTORE command, which sets the parameter to the value stored in the EEPROM.

A similar command RESTOREALL exists, which sets all parameters to their value stored in the EPPROM. However, for efficiency reasons it should be used with outmost care and only when it is absolutely needed. Using several RESTORE commands should be preferred over using one RESTOREALL.

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.