Programming OpenTx - getting to grips with Lua

Not so long ago, the idea of an R/C operating system with a built-in programming language would have seemed but a dream. Well it's time to change that notion, as OpenTx is now available with an embedded Lua interpreter. Such is the pace of progress that last year's dream is today's reality!

For those unfamiliar with this Brazilian-born computer lingo, Lua is a lightweight, embedded, pre-compiled/interpreted scripting language. As computer languages go, it's fairly easy to learn if not quite as simple as Basic.

Lua scripts can do all manner of interesting stuff, from enhanced mixers, to custom telemetry screens, to intelligent voltage alarms using telemetry to detect the cell count. Bear in mind though, that the Lua interpreter is currently only available with the Taranis version of OpenTx.

So, is the sky really the limit with Lua? There was only one way to find out, and that was to write some scripts myself. But first I would have to learn the ropes...

1. Initial research

Some people seem happy to learn by tinkering with example scripts. I preferred to have a basic grounded in the language before attempting anything. Two sources which I found useful are the Lua.org, site, and the Lua page in Wikipedia.

With some basic knowledge under my belt, the next task was to install a Lua interpreter to practice with.

2. Lua for Windows

Following some more research, I installed Lua for Windows (LfW). This comprises a Lua interpreter, a programming editor (SciTE), and a "quick tour" of Lua. These are all open source projects, independent of OpenTx.

The key component is the interpreter. This can be used to check your scripts for the correct syntax, before transfer to the transmitter. You can run the interpreter from a command window, however it makes much more sense to use it via the SciTE programming editor. SciTE offers all the little features that distinguish a programming editor from a mere text editor, such as highlighting of language elements and tagging of syntax errors. If you get stuck, the Help button takes you to the Lua Reference Manual.

Scripts are saved as text files with .lua extension. Scripts destined for the Taranis are simply copied to the transmitter's SD card.

A slight drawback is that LfW supports Lua 5.1, whereas the Lua interpreter in OpenTx is version 5.2. Not a showstopper, just something to be aware of.  (For differences between Lua 5.1 and 5.2, refer to section 8 of the Lua 5.2 Reference Manual.)

Developing a script in SciTE

3. Using the Quick Tour

LfW comes with a "Quick Lua Tour". Although the presentation is a little rough (it runs in a command window) it provides a useful introduction to the language.

There are 36 examples to work through. I worked through them all, with the Quick Tour open in one window, and the editor in a second window. After a couple of hours I was confident enough to tackle my first OpenTx project.

Quick Tour in action

4. The OpenTx documentation

Before writing my first script for OpenTx, I needed to know about the different types of script which OpenTx supports and how they interfaced. The relevant information can be found in Lua Scripting in OpenTx. If you get stuck, help is at hand on the Lua thread on RC Groups.

5. Writing my first script

It was time to write my first script! This is an enhanced snapflap (i.e. elevator-to-flap mix) for F3F sailplanes. The mix incorporates a variable deadband about neutral, which can be controlled via knob S1. Experimenting with deadband seems to be in vogue at the moment, but it can be a pain unless the pilot can adjust it in the air. This kind of thing cannot be achieved easily if at all using regular curves - essentially it involves dynamically moving a single curve point on a curve.

I won't go into the details of the solution here, but I was impressed at how few lines of code were required, and how neatly the script integrates with OpenTx. The script is now tested and working in the simulator. Which brings us neatly to...

6. Testing scripts in the simulator.

Scripts can be tested in the OpenTx Companion simulator. Scripts must be installed in the appropriate directory according to the OpenTx documentation. Currently, script settings aren't saved, so you have to re-enter them each time you invoke the sim.

Sim capture of the script menu. Note extra outputs for debugging.

Beware that scripts may be syntactically correct, but still generate run time errors (e.g. divide by zero). Errors are alerted by an "(error)" warning in the list of scripts, but it's up to you to find the cause of the error.

Final thoughts for now

The developers have done a great job in integrating Lua into OpenTx! I am looking forward to developing my Lua skills, and will update this post as my experience develops.

Postscript

You can see my Enhanced Snapflap Mix here.