TILT!Audio features a lua runtime 5.2 to control additional extensions like shakers, LED-lights and also servos.
To make this possible TILT!Audio firmware embeds a lua runtime (lua virtual machine) and loads a “init.lua” script from the sound directory.
The init.lua script already has access to all core lua language features and also the TILT!Audio bindings see lua reference. The binding allows access to the sound engine, communicate via i2c, logging messages and get information about the current installation.
Lua in its language ecosystem also offers modules and package managers that allows installing and managing modules that extend lua features. One of this package managers is luarocks.
Luarocks
Using luarocks as package manager to install a new module together with TILT!Audio is not so straight forward as you can read it on most websites, because the linux running on a TILT!Audio card is tailored down to a minimum to run as efficient as it should to produce sound and nothing else.
What is missing for example is a c compiler that most lua modules require as they come as a combination of lua code and c code.
Also luarocks requires a certain directory structure that is aware of the different lua versions and different places in the system where the lua runtime should look for “modules” (which is *.so and *.lua files).
The TILT!Audio start script does set the required environment variables to let lua runtime find modules, but still not in that way that a module installed by luarocks would expect.
General approach
To make use of luarocks and lua modules we need a second raspberry pi or more precisely a second linux installation on a sd card. Easiest is to use the latest dietpi as this is also the distribution TILT!Audio uses. Other distribution like rasbian or armbian should also work.
For this example I choose a simple module cjson for json decoding and encoding as this module has no further dependencies but still requires native code. You need to use version cjson 2.1.0-1 as the newest is not compatible with lua 5.2 anymore.
Step by Step
- install gcc
- install lua 5.2 (including dev dependencies)
- download latest luarocks tarball
- build and configure luarocks
- create a private lua module directory /boot/data/lua (same name as it will be in the TA installation)
- install a module with luarocks into that directory using –tree option
- zip installed modules and copy them over to the TA-installation
- adjust LUA_PATH and LUA_CPATH in tiltaudio.sh to match the luarocks config
Alternatively to step 8 you do not change the LUA_PATH and LUA_CPATH in the tiltaudio.sh start script, but instead copy the installed module files into the right directories.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# skipped gcc / lua install $ wget https://luarocks.org/releases/luarocks-3.7.0.tar.gz $ tar zxpf luarocks-3.7.0.tar.gz $ cd luarocks-3.7.0 $ ./configure --lua-version=5.2 $ make $ ./luarocks --version $ mkdir -p /boot/data/lua $ ./luarocks install --tree /boot/data/lua lua-cjson 2.1.0-1 $ zip -r lua-cjson.zip /boot/data/lua $ ./luarocks path --tree /boot/data/lua export LUA_PATH='/boot/data/lua/share/lua/5.2/?.lua;/boot/data/lua/share/lua/5.2/?/init.lua;/root/luarocks-3.7.0/src/?.lua;/usr/local/share/lua/5.2/?.lua;/usr/local/share/lua/5.2/?/init.lua;/usr/local/lib/lua/5.2/?.lua;/usr/local/lib/lua/5.2/?/init.lua;/usr/share/lua/5.2/?.lua;/usr/share/lua/5.2/?/init.lua;./?.lua' export LUA_CPATH='/boot/data/lua/lib/lua/5.2/?.so;/usr/local/lib/lua/5.2/?.so;/usr/lib/arm-linux-gnueabihf/lua/5.2/?.so;/usr/lib/lua/5.2/?.so;/usr/local/lib/lua/5.2/loadall.so;./?.so' # only remove the local tree from this set of paths |
Then copy over the zip file created in line 10 and extracting everything on the TA installation into /boot/data/lua and replace the two export LUA_PATH / LUA_CPATH lines in tiltaudio.sh with the output of the the luarocks path command from line 11 (the line 12 and 13 with the export commands).
After that everything should be ready to use the new cjson module and we can try it out be adding some lua code in the init.lua in /boot/data/sound
|
1 2 3 4 5 6 7 |
local cjson = require "cjson" local json = cjson.encode({ foo = "bar", some_object = {}, some_array = cjson.empty_array }) print(json) |
Now restart the TILT!Audio service and you should see in the logfile something like this:
|
1 2 3 4 5 |
[lua_init] [lua_binding.c:627] lua_init. lua version 'Lua 5.2' [main] [despi.c:1080] looking for /home/pi/despi/init.lua [main] [despi.c:1084] looking for /boot/data/sound/init.lua [lua_runfile] [lua_binding.c:643] running lua script: '/boot/data/sound/init.lua' [print] [lua_binding.c:172] {"some_object":{},"foo":"bar"} |
As you can see the code gets executed, modules gets loaded and json encode call is executed successfully.
How does luarocks install modules
When you look at the contents of the zip file …
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
lua/lib/ lua/lib/luarocks/ lua/lib/luarocks/rocks/ lua/lib/luarocks/rocks-5.2/ lua/lib/luarocks/rocks-5.2/lua-cjson/ lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/ lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/rock_manifest lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/bin/ lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/bin/lua2json lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/bin/json2lua lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/ lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/README lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/TestLua.pm lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/agentzh.t lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/bench.lua lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/example1.json lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/example2.json lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/example3.json lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/example4.json lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/example5.json lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/genutf8.pl lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/numbers.json lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/octets-escaped.dat lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/rfc-example1.json lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/rfc-example2.json lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/test.lua lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/tests/types.json lua/lib/luarocks/rocks-5.2/lua-cjson/2.1.0.6-1/lua-cjson-2.1.0.6-1.rockspec lua/lib/luarocks/rocks-5.2/manifest lua/lib/lua/ lua/lib/lua/5.2/ lua/lib/lua/5.2/cjson.so lua/bin/ lua/bin/json2lua lua/bin/lua2json lua/share/ lua/share/lua/ lua/share/lua/5.2/ lua/share/lua/5.2/cjson/ lua/share/lua/5.2/cjson/util.lua lua/share/lua/5.2/lua2json.lua lua/share/lua/5.2/json2lua.lua |
… you see there is a lot of overhead due to luarocks versioned package management and also example code. When you simply want to use the module it comes down to one *.so file and three lua files.
So the alternative instead of copying all that luarocks stuff you could simply only use these five files:
|
1 2 3 4 5 6 7 8 9 10 11 |
# ls -lR /boot/data/lua /boot/data/lua: total 56 drwxr-xr-x 2 root root 8192 May 18 08:33 cjson -rwxr-xr-x 1 root root 29312 May 18 08:33 cjson.so -rwxr-xr-x 1 root root 304 May 18 08:33 json2lua.lua -rwxr-xr-x 1 root root 387 May 18 08:33 lua2json.lua /boot/data/lua/cjson: total 8 -rwxr-xr-x 1 root root 6837 May 18 08:33 util.lua |
While trying this I discovered a bug in the normal lua path that was set in the start script so far. So also the simple unversioned paths need a minor tweak:
|
1 2 |
export LUA_PATH=$BASEPATH/data/lua/?.lua export LUA_CPATH=$BASEPATH/data/lua/?.so |
The ?.so and ?.lua at the end was missing, sorry for that, will be fixed in the upcoming versions.
Final note or advice
As you can see with this example “module cjson” (json decoding / encoding) there is already native code involved (the cjson.so file) even though it is a rather simple module.
Native code (also complex lua code) can do all kind of thing like complex computation, consuming a lot of memory, doing high latency network communication so the chance to bring you TILT!Audio down increases the more you do with lua and lua modules. So please keep things as simple and lightweight as possible.
I also cannot provide further programming or debugging support, if you run into problems with lua. Try to get things tested and working outside of the TILT!Audio environment first.
Hope this post helps the more enthusiastic lua programmers in the TILT!Audio world to get something cool to work!