Control your Raspberry Pi with Lua

Lua is a sometimes misunderstood language. It’s different from other languages, like Python, but it’s a versatile extension language that’s widely used in game engines, frameworks, and more. Overall, I find Lua to be a valuable tool for developers, letting them enhance and expand their projects in some powerful ways.

You can download and run stock Lua as Seth Kenlon explained in his article Is Lua worth learning, which includes simple Lua code examples. However, to get the most out of Lua, it’s best to use it with a framework that has already adopted the language. In this tutorial, I demonstrate how to use a framework called Mako Server, which is designed for enabling Lua programmers to easily code IoT and web applications. I also show you how to extend this framework with an API for working with the Raspberry Pi’s GPIO pins.

Requirements

Before following this tutorial, you need a running Raspberry Pi that you can log into. While I will be compiling C code in this tutorial, you do not need any prior experience with C code. However, you do need some experience with a POSIX terminal.

Install

To start, open a terminal window on your Raspberry Pi and install the following tools for downloading code using Git and for compiling C code:

$ sudo apt install git unzip gcc make

Next, compile the open source Mako Server code and the Lua-periphery library (the Raspberry Pi GPIO library) by running the following command:

$ wget -O Mako-Server-Build.sh \
https://raw.githubusercontent.com/RealTimeLogic/BAS/main/RaspberryPiBuild.sh

Review the script to see what it does, and run it once you’re comfortable with it:

$ bash ./Mako-Server-Build.sh

The compilation process may take some time, especially on an older Raspberry Pi. Once the compilation is complete, the script asks you to install the Mako Server and the lua-periphery module to /usr/local/bin/. I recommend installing it to simplify using the software. Don’t worry, if you no longer need it, you can uninstall it:

$ cd /usr/local/bin/
$ sudo rm mako mako.zip periphery.so

To test the installation, type mako into your terminal. This starts the Mako Server, and see some output in your terminal. You can stop the server by pressing CTRL+C.

IoT and Lua

Now that the Mako Server is set up on your Raspberry Pi, you can start programming IoT and web applications and working with the Raspberry Pi’s GPIO pins using Lua. The Mako Server framework provides a powerful and easy API for Lua developers to create IoT applications and the lua-periphery module lets Lua developers interact with the Raspberry Pi’s GPIO pins and other peripheral devices.

Start by creating an application directory and a .preload script, which inserts Lua code for testing the GPIO. The .preload script is a Mako Server extension that’s loaded and run as a Lua script when an application is started.

$ mkdir gpiotst
$ nano gpiotst/.preload

Copy the following into the Nano editor and save the file:

-- Load periphery.so and access the LED interface
local LED = require('periphery').LED

local function doled()
  local led = LED("led0") -- Open LED led0
  trace"Turn LED on"
  led:write(true)   -- Turn on LED (set max brightness)
  ba.sleep(3000)    -- 3 seconds
  trace"Turn LED off"
  led:write(false)  -- Turn off LED (set zero brightness)
  led:close()
end

ba.thread.run(doled) -- Defer execution
                     -- to after Mako has started

The above Lua code controls the main Raspberry Pi LED using the Lua-periphery library you compiled and included with the Mako Server. The script defines a single function called doled that controls the LED. The script begins by loading the periphery library (the shared library periphery.so) using the Lua require function. The returned data is a Lua table with all GPIO API functions. However, you only need the LED API, and you directly access that by appending .LED after calling require. Next, the code defines a function called doled that does the following:

1. Opens the Raspberry Pi main LED identified as led0 by calling the LED function from the periphery library and by passing it the string led0.
2. Prints the message Turn LED on to the trace (the console).
3. Activates the LED by calling the write method on the LED object and passing it the Boolean value true, which sets the maximum brightness of the LED.
4. Waits for 3 seconds by calling ba.sleep(3000).
5. Prints the message Turn LED off to the trace.
6. Deactivates the LED by calling the write method on the LED object and passing it the Boolean value false, which sets zero brightness of the LED.
7. Closes the LED by calling the close function on the LED object.

At the end of the .preload script, the doled function is passed in as argument to function ba.thread.run. This allows the execution of the doled function to be deferred until after Mako Server has started.

To start the gpiotst application, run the Mako Server as follows:

$ mako -l::gpiotst

The following text is printed in the console:

Opening LED:
opening 'brightness': Permission denied.

Accessing GPIO requires root access, so stop the server by pressing CTRL+C and restart the Mako Server as follows:

$ sudo mako -l::gpiotst

Now the Raspberry Pi LED turns on for 3 seconds. Success!

Lua unlocks IoT

In this primer, you learned how to compile the Mako Server, including the GPIO Lua module, and how to write a basic Lua script for turning the Raspberry Pi LED on and off. I’ll cover further IoT functions, building upon this article, in future articles.

You may in the meantime delve deeper into the Lua-periphery GPIO library by reading its documentation to understand more about its functions and how to use it with different peripherals. To get the most out of this tutorial, consider following the interactive Mako Server Lua tutorial to get a better understanding of Lua, web, and IoT. Happy coding!