LUA 501 – Introduction to Lua Scripts
Your instructor: Isaac Davis (Fig Newton on RCGroups)
So, you have read about Lua scripts and are interested in what can be done. I think it’s fair to say that we don’t need to define what a script is in this day and age. I also will not be going over the finer points of your Taranis, as that is covered on other portions of this website. With that being said we aren’t going to leave you out in the cold. This course is intended to get you familiar with what a Lua script is and the different types of scripts. Actually running, using, and creating Lua scripts will be covered in a later course. The fact that you are here shows that you have an interest in scriptinh, so let’s go ahead and get started.
I will include some links at the end of this document to websites to help further your journey into Lua scripting at the end of the course. For now, let’s talk about what kinds of Lua scripting are available for the Taranis.
The first thing that I want to point out is that the Lua scripts are a brand new addition to OpenTX with v2.0.0, and as of v2.0.3, some changes have been made in anticipation of further use of scripts with the radio and things are being improved with each new version of OpenTX. I will cover that here in a minute. With that being said, we are not going to run any scripts in this introductory class. That will be covered beginning with Lua 502. This is just to get you familiar with Lua scripting and how it integrates with OpenTX and the Taranis.
The first thing we want to cover is that there are two types of Lua scripts. We have one-time scripts which are meant to be run one-time (obviously). A perfect example of this is the setup wizard that has been distributed with the 2.0.0 firmware. This script, when run on the radio, goes through setting up a model. Now, the nice part about this is that we aren’t locked into one particular model setup. If someone wants to add on, or write their own custom setup script (say for their F3J sailplane) and distribute it, they are free to do so. There have been some other ideas proposed such as using a one-time script to go find certain conditions in model setups, and possibly making global model changes, etc. Like our hobby, the sky’s the limit. One-time scripts are chosen and run by the user whenever they select the script and have it run.
Now that we know what the wizard can do and that when it runs is controlled by the user, let’s move to the next type of script available to us, the model script.
A little background first. The Taranis you are holding in your hands (you are holding your Taranis right now aren’t you?) is fundamentally a computer with a couple of sticks and a bunch of switches and knobs. In the past radios were custom built by the manufacturer with the logic for what function each switch, knob and stick would perform built in and in most cases not upgradeable. What the manufacturer decided could be done with each switch is what you were, for a lack of better words, stuck with. And most of the time, it was completely reasonable and functional. Now, with the progression of technology, we have come to the point where instead of hardwiring or designing custom chips to handle the switching and logic required to make all of these components control a plane, we have a computer in our hands.
The computer in our Taranis is basically running in a loop. Multiple times a second it is running through a core loop of code that checks all of the switches, knobs, and sticks, processes their state and then sends everything to the receiver. Each time this loop is run it’s called a cycle. It’s in this basic loop that model scripting has been injected. Since the processor is fast enough in the Taranis, there is enough time every cycle to run some extra code, and this is where model scripting comes into play.
Some limits needed to be placed on the model scripts because while, we have some time, it’s not unlimited and neither is the memory. The programmers have it set up to where each model script runs in a window. Like the Twilight Zone, this window is a dimension of time and space. In other words as long as the model script is playing nice and staying within its parameters it will continue to be run every cycle. If it takes too much time, or too much memory, it is subject to being killed. If you are a fan of Survivor, the script is voted off the island.
If you haven’t figured out why this is important to note, take a look at your Taranis. Remember all of those sticks and knobs? They are usually controlling what is probably an expensive piece of equipment that is most likely near and dear to your heart. You do not want to be in the situation where you are trying to fly your {insert your favorite model here} when all of the sudden the Lua script that’s trying to calculate a battery value goes into an infinite loop, or starts using up too much memory. Squirrel!! (If you didn’t get that last reference, watch the movie Up). “Squirrel!!” is a very good analogy as to what these model scripts are doing.
Remember, the main goal of the software in the Taranis should be to get the stick, knob, and switch information to the receiver as fast and as often as possible. What the OpenTX programmers have to do is maintain a balance so that this minor distraction doesn’t interrupt the main core loop of activity. Lua model scripts have a basic set of rules that we will get into in further classes on actually writing these scripts.
So summing all of that up, you have scripts that are chosen and run by the user at his or her command. The other type of Lua scripts are squeezed into the processing loop and given just enough room to play to keep from impacting the more important processes that the transmitter is working on. With version 2.0.3 we were told that the model scripts would be further broken up into Function and Telemetry scripts. I noticed that Bertrand did stipulate that there would be a total of 7 scripts per model. You will be able to mix and match but not exceed the total.
In further courses we will explore the ways to run a script and then, if you are interested, delve into writing your own Lua scripts. Take out your #2 pencils and a sheet of paper. It’s pop quiz time.
Question #1
I need a script that can take my altitude and divide it by the number of times I have blinked in the last two minutes. Which script should I look for:
A) A One-time script
B) A model script
Question #2
Is it possible for a script to crash my plane?
A) Yes
B) No
Question #3
It’s hard enough to figure this radio out with all of the logical switches and special functions. Am I ever going to get this Lua scripting figured out?
A) Of course you will. It’s not as daunting as it seems.
B) Of course you will. It’s pretty daunting, but take it one step at a time.
Question #4
Is it true there is a video game you can play on your transmitter?
A) No way, that would be ridiculous.
B) Yes. But be careful playing it while you are flying your scale P-51D. It has been known to cause the retracts to come down at random.
C) Yes. Unfortunately right now there’s no place to plug in a joystick.
D) Yes. It will keep you busy while batteries are charging.
Question #5
Should I spend more time with these Lua scripts?
A) Not really. Especially if you aren’t interested in being able to do things with your transmitter that have previously been impossible.
B) Yes. This is a game changing development in the world of R.C. and I want to be able to say “I was there.”
Answers:
Time to put down your pencils and lets get your paper graded. Here are the answers.
1) B – Any calculations you want performed while a plane, helicopter, or quad is in the air should be done with a model script.
2) A – Trick question huh, but the answer is actually Yes. You have to go out of your way for this to happen, which will be discussed in further model scripting classes. It cannot happen if a script runs out of control or has an error though. The basic rules of model scripting will be covered and this explained further. Do not let this deter you from using Lua scripts.
3) Your choice.
4) D – There is a snake game available that is a One-time script you can fire off when you are not flying.
5) Again, your choice, but I would highly recommend at least exploring it a little more because as we have mentioned in the past, this will be a game changer.
Links and Resources:
Here are some links to help you:
- http://www.rcgroups.com – There is a fair amount of discussion on Lua scripting but you have to dig for it.
- http://www.rcgroups.com/forums/showthread.php?t=2180477 – The Lua Scripting thread on RCGroups.
- https://github.com/opentx/opentx/wiki/Lua-scripting-in-OpenTX – This will be the official Lua script docs for OpenTX
- http://en.wikipedia.org/wiki/Lua_%28programming_language%29 – The Wikipedia entry on Lua programming.
- http://www.lua.org/ – The official Lua website. Couldn’t leave this one out.
Class dismissed! Now go out and fly!