descriptions refer to firmware v2.55e 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.
- 1 Overview of Script Types
- 2 Technical Background
- 3 Usage
- 4 Scripting Language
- 5 Examples
- 6 User 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 tab.
- Motion Control Scripts: The GUI has also incorporated a dedicated Motion Control processor, which can be accessed via the Perl scripts, with some convenience functions added. in the 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
- 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.
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. 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 is called a cycle. Two situations can hence occur in the execution of the pseudo code, namely - first - that the next pseudo command should be executed in the same cycle as the previous one, or - second - 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.
In total four scripts, named Script1 to Script4, can be run simultaneously and independently. For each script, two fields are available in thetab, e.g. for Script1 these are:
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 five cases (see below).
The second parameter field holds the code. It can be edited via thebutton. It opens the script editor window, which allows you to write, load and save code. Its syntactic correctness may be checked by doing a . For accepting the code use .
Script1 is the master script in the sense that it allows us to modify the, , and parameters and hence to affect the behavior of the other scripts, while the other three scripts cannot modify any of script control parameters.
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 CASE#4 STOP REPEAT WAIT time(int, in 0.1secs) RESTART
The cases are determined by the value of the input selected with the Inputs and Functions: Overview Diagram):parameter. The value ranges for the CASE statements are (see also
- CASE#DEFAULT: -166 ... +166
- CASE#1: +333 ... +500
- CASE#2: -500 ... -333
- CASE#3: +223 ... +267
- CASE#4: -267 ... -223
Note that the ranges for CASE#1 and CASE#2 start at +333 and -333, respectively, which corresponds to ca 1833 us and 1167 us (roughly, this is very transmitter dependent). Default transmitter settings may not reach there. Note also that the ranges for CASE#3 and CASE#4 are relatively narrow, and thus can easily be missed.
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 commandsand are identical function-wise, namely set a parameter to a value, but differ in the second argument: In 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 the new value is specified by its internal integer representation. For instance, if the parameter should be set to “GoPro Hero5”, then the command would be , and the command would be (since the option "GoPro Hero5" is internally represented by the integer 10) (you can check this with ).
Similar holds for the second and third parameters in theand commands.
Theand commands are still existing for compatibility, but should not be used in new scripts (in fact, the script compiler replaced them with the newer and 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 DORECENTERPITCH DORECENTERROLL DORECENTERYAW 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.
The script function commands modify the very same set of internal variables which are also modified by the serial RC commands and MAVLink messages. This can lead to conflicts when the latter are used in combination with scripts, which can be resolved with the/ script commands. With the scripts are given priority over the serial RC and MAVLink commands. With the default behavior is restored.
SENDMAVTEXT text(string) SENDCAMTEXT text(string)
The STATUSTEXT message. The text is the specified string, prepended by a label "STorM32:". The text string can be 24 characters long, and contain the characters '0'-'9', 'a'-'z', 'A'-'Z', ' '.command triggers the emission of a MAVLink
Thecommand sends the specified string, appended by a '\n' char, on the . The text string can be 24 characters long, and contain the characters '0'-'9', 'a'-'z', 'A'-'Z', ' '. Only for = “Serial Api”.
Prefer short text strings, in order to not exhaust the limited code space for scripts.
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 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:
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 theparameter 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 , then the speed limit is set to 5.0 °/s. Every CASE statement needs to be finished with either a or . Here the command is used, which means that the preceding 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).
SETPMINMAX "Rc Pitch Speed Limit" 5.0 40.0 REPEAT
Thecommand 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 command at the end ensures, that the 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.
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 thecommand, which sets the “Rc Pitch Speed Limit” parameter to the value stored in the EEPROM.
A similarcommand exists, which sets all parameters to their values stored in the EEPROM. However, for efficiency reasons it should not be used, except then it is really absolutely needed. Using several commands is much preferred over using . In short, avoid if you can.
Of course, one is not limited to only theparameter. ANY other available parameter (except of the parameters as discussed before), can be used in the and 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 Inputs and Functions., , , and statements. A case is chosen dependent on the value of the input selected by the parameter, in close analogy to all the other available functions such as the Rc Inputs, Pan Control or IR Camera Control, see also
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
Thecommand sets the yaw angle to 45°, and waits 3.0 secs in addition to the predicted time for the turn.
Theand 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.
Thecommands finally run the pano sequence. The first 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 commands.
In the above example, the pano cannot be terminated during execution. That is, the script is executed command by command until it reaches thecommand, and only then it is tested if the input has changed and whether it should jump to CASE#DEFAULT. Often this is the desired behavior, e.g. when the pano is triggered with a momentary push button. Often it is however desired that the pano runs for as long as the input is set but is terminated then it is cleared. A typical use case would be when the pano is triggered with a transmitter switch, there one might want it to run when the switch is flipped but be stopped when the switch is cleared, even if the pano is not yet completed. This can be accomplished with the command. An example script would be
CASE#DEFAULT STOP CASE#1 SETANGLEYAW_W 45 30 SETPANOWAITS 30 30 10 SETPANORANGE 90 SETPANOALLOWEXIT DOPANO 30 -8 WAIT 10 DOPANO -30 8 DORECENTER STOP
Note that here only thecommands are cut short if the input becomes different from CASE#1, but that the other commands are still executed until the command is reached. That is, in the example, if the input changes while the first command is executed, the and commands would be still executed.
Running a Script in Combination with other Serial Commands
Serial commands in this context are the serial RC commands and the MAVLink messages. They all set the very same internal variables which also are also set by the scripts, and conflicts can accordingly occur.
Such a situation can occur, e.g., when the STorM32 controller is connected to an ArduPilot flight controller and a continuous stream of DO_MOUNT_CONFIGURE MAVLink command is sent to the STorM32 controller. In this case a pano script for instance would appear to not work since the commands for setting the angle of the gimbal emitted by the script would be nearly instantaneously overwritten by the DO_MOUNT_CONFIGURE MAVLink commands.
Such situations can be resolved by using theand script commands. gives the script priority and essentially disables the serial commands. With the default behavior is restored.
A script using this mechanism would typically look as
CASE#DEFAULT STOP CASE#1 REMOTEDISABLE ... REMOTEENABLE STOP
CASE#DEFAULT REMOTEENABLE STOP CASE#1 REMOTEDISABLE ... STOP
Both achieve essentially the same, but the first version might be better to read.
Switching Between Two Alternate Functions of a Continuous RC Channel Using a "Shift Key"
by Hb121280, see also 
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 Inputs and Functions: Overview Diagram, the value ranges for the CASE statements are: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
- 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. is accordingly set to “off”. Pressing the button reverses the assignments: The analog channel on input “Virtual-8” is now used for , and the control of pitch is deactivated.