STorM32 Scripts
descriptions refer to firmware v0.95e and later
With firmware version v0.51 the possibility of downloading 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 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: 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 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 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 [Scripts] tab, e.g. for Script1 these are:
- Script1 Control
- Script1
The first parameter field allows 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. It 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)
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°) 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°) DOPANO pitchangle(int, in degree°) steps(int) REMOTEENABLE REMOTEDISABLE
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 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 a "default" value, then the pitch speed limit is set to 400 or 40.0 °/s, respectively, while when the input value is such to trigger CASE#1, then the speed limit is set to 50 or 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 SET 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 good 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
SETMINMAX "Rc Pitch Speed Limit" 50 400 REPEAT
The SETMINMAX command 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 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 SETMINMAX 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 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 "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 this entry, and not 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 EPPROM. However, for efficiency reasons it should be used with outmost care and only if it is absolutely required. Using several RESTORE commands is much preferred over using 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 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.