Helium Blog

Scripting Helium with Lua: Bring Your Own Business Logic

The Helium IoT platform is all about making it easy to bring the physical world online. We’ve gone into a lot of detail about what this means in other blog posts, but one of the ways we do this is by using the Lua scripting language that runs on our Atom Wireless Application Module and makes sensors programmable, allowing users to run business logic such as local data analysis on the sensor as well as easily change sensor sample and transmit rates. While a lot goes into keeping IoT deployments running, such as managing security, upgrades, data storage, and battery life, these are only distractions for users – Lua scripts are about the problems you’re actually solving, and the platform can handle the other details behind the scenes.

Lua is designed from the ground up to be accessible and easy to understand. Anyone familiar with Python or JavaScript should be able to pick up Lua quickly, and developers may already know it from scripting games such as World of Warcraft or network tools like nmap or Wireshark. Below is an example excerpt of how to manipulate the sample and transmit rates of a temperature sensor (plugged into our Helium Atom Development Board) using Lua.


-- Give things a chance to turn on.

-- Make sure that the sensor is alive.

-- The delay in milliseconds between each sample we
-- read and report.
local SAMPLE_INTERVAL = 1000

-- Batch up samples before sending them.
local BATCH_SIZE = 5
local temp_samples = {}

local function add_sample(time, temp)
   table.insert(temp_samples, {time=time, temp=temp})

local function number_of_samples()
   return #temp_samples

local function report_samples()
   for k,v in ipairs(temp_samples) do
-- Write the temperature value to the port named "temp". The
-- first parameter is the port name, the second is the time to
-- use for the sample, the third parameter is the format string
-- for all following arguments. In this case, there's only one:
-- the temperature as a floating point value.
      he.log("temp", v.time, "f", v.temp)
   temp_samples = {}

-- Calculate our first target wakeup time
local target = he.now() + SAMPLE_INTERVAL

while true do
   local temp = sample_temp()
   local n = he.now() -- time sample was actually captured

   print("collected sample")
   add_sample(n, temp)

   if number_of_samples() >= BATCH_SIZE then

   -- Calculate our next wakeup time.
   wake_reason = he.wait{time=target}
   target = target + SAMPLE_INTERVAL

Using this script, the sensor will take a reading every second, and send all readings once it has taken 5. To change the sample and transmit rate, just modify SAMPLE_INTERVAL and BATCH_SIZE to whatever suits your needs.

By design, Lua is a self-contained programming language – scripts written for Helium devices in Lua are sandboxed, or kept separate, from the rest of the Helium platform. In case one of those user-created scripts has an error, it will not lead to any security vulnerabilities or other issues with the platform itself. If a script crashes, the Helium Cloud receives an alert from the device, and then a new script can be sent over the air from the Cloud to replace it without needing to service the device in person in the field. If a script runs too long, a timer can cleanly contain the problem by shutting the script down, so that it doesn’t continue to drain the device’s battery. The script timeout can then be reported and addressed.

These Helium-specific enhancements are key to ensuring that devices are conveniently programmed on your desk as well as once they are deployed. After all, you wouldn’t want to endlessly drain the battery on a sensor if it’s already been deployed in the wild and far away from anyone who could perform maintenance.

This self-contained nature also makes it easier for developers to test their business logic on the workbench prior to even deploying the script on a sensor. Because Lua scripts are focused on processing updates rather than where the data comes from, they can receive and react to data in isolation. For example, users can feed scripts historical information and check if they are reacting appropriately without impacting the rest of the development environment. Lua scripts can also test live data when connected to a laptop over USB, without waiting for infrequent readings or scripts to upload via radio.

While many use cases will only need a small subset of the language, Lua is also able to do sophisticated analysis when needed. These processing capabilities can save valuable bandwidth and battery life. For example, a sensor that tracks temperature could consume unneeded battery life sending frequent updates that everything is normal – messages that are not particularly useful. A simple Lua script can determine whether the message is meaningful enough to send immediately – like an alert that temperatures are steadily decreasing – and reduce the need to power on the radio otherwise. Since radio usage can comprise a large amount of overall power consumption on IoT devices, using it thoughtfully significantly improves battery life and can reduce long-term costs substantially.

At Helium, we’re delivering an IoT development platform with excellent battery characteristics and low data usage that can be reliably adapted to suit changing needs for commercial applications in industries such as (but not limited to) manufacturing, food production and distribution, restaurants, and healthcare. One key aspect of such a device is that it be programmable, and the embeddable design of Lua, combined with its small memory footprint, performance, and expressiveness, allows us to deliver this to our customers. We hope this has been informative, and if it has stoked your interest, you can take advantage of all of these features in our Helium Development Kit.

  • If you’re interested in finding out more about Helium, visit www.helium.com for an overview of our products.

  • Development kits and all necessary hardware to start building connected products can be purchased at store.helium.com.

  • Join our Slack community at chat.helium.com and speak directly to the Helium team as well as other Helium developers.

  • If you’d like to discuss an upcoming project with us, let us know and we’ll get in touch soon.