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 when later adopted by others.
The on-board scripts bring great possibilities, but needs 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 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, 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, 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 using a pseudo code processor.
For understanding the internal working one should realize, that the controller code is essentially an endless loop, which is triggered and repeated every 1.5 ms (at least in the case of the STorM32). 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 control flow commands belong to the latter case, while otherwise the commands are of the first kind.
Usage
In total four scripts can be run simultaneously and independently. They are managed by the fields in the [Scripts] tab. For each script, two fields are available, e.g. for Script1 these are:
- Script1 Control
- Script1
The first parameter field allows to select an input channel, those value can be used in the script to e.g. trigger one of up to four cases (see below). The second parameter field holds the code.
Script1 is the master script in the sense, that it allows to modify the Script2 Control, Script3 Control, and Script4 Control parameters and hence to affect the others script behavior, while the other scripts can't modify any of these parameters.
Scripting Language
The on-board scripting language has a relatively rich set of commands, which allows you to modify the controllers 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)
Parameter value commands:
SET parametername(string) value(int) SETMINMAX parametername(string) minvalue(int) maxvalue(int) RESTORE RESTOREALL
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°) SETSTANDBY 0/1 DOCAMERA 0/1/2/3/4 DORECENTER SETPWM pwmvalue(int)
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 (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, which uses this feature, is found here.
Method C
CASE#DEFAULT RESTORE "Rc Pitch Speed Limit" STOP CASE#1 SET "Rc Pitch Speed Limit" 50 STOP
This example is essentially method A, but overcomes a minor yet potentially annoying issue. In method A, the parameter value specified in the respective 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 GUI, and not in the scripts. This issue is resolved by the RESTORE command, which sets the a parameter to the value stored in the EEPROM.
A similar RESTOREALL command 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 if it is absolutely needed. Using several RESTORE commands is preferred over using one RESTOREALL.
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 SETMINMAX commands and hence modified by the scripts. Furthermore, a case statement can of course be followed by more than one command, such that complex situations can be tackled.
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.