lua-periphery
Linux Peripheral I/O (GPIO, SPI, I2C, MMIO, Serial) with Lua
lua-periphery is a library for GPIO, SPI, I2C, MMIO, and Serial peripheral I/O interface access in userspace Linux.it is useful in embedded Linux environments (including BeagleBone, Raspberry Pi, etc. platforms) for interfacing with external peripherals.lua-periphery is compatible with Lua 5.1 (including LuaJIT), Lua 5.2, and Lua 5.3, has no dependencies outside the standard C library and Linux, is portable across architectures, and is MIT licensed.
Using Python or C? Check out the python-periphery and c-periphery projects.
Examples
GPIOlocal GPIO =require('periphery').GPIO-- Open GPIO 10 with input directionlocal gpio_in =GPIO(10, "in")-- Open GPIO 12 with output directionlocal gpio_out =GPIO(12, "out")local value = gpio_in:read()
gpio_out:write(not value)
gpio_in:close()
gpio_out:close()
SPIlocal SPI =require('periphery').SPI-- Open spidev1.0 with mode 0 and max speed 1MHzlocal spi =SPI("/dev/spidev1.0", 0, 1e6)local data_out = {0xaa, 0xbb, 0xcc, 0xdd}local data_in = spi:transfer(data_out)print(string.format("shifted out {0x%02x, 0x%02x, 0x%02x, 0x%02x}", unpack(data_out)))print(string.format("shifted in {0x%02x, 0x%02x, 0x%02x, 0x%02x}", unpack(data_in)))
spi:close()
I2Clocal I2C =require('periphery').I2C-- Open i2c-0 controllerlocal i2c =I2C("/dev/i2c-0")-- Read byte at address 0x100 of EEPROM at 0x50local msgs = { {0x01, 0x00}, {0x00, flags = I2C.I2C_M_RD} }
i2c:transfer(0x50, msgs)print(string.format("0x100: 0x%02x", msgs[2][1]))
i2c:close()
MMIOlocal MMIO =require('periphery').MMIO-- Open am335x real-time clock subsystem pagelocal rtc_mmio =MMIO(0x44E3E000, 0x1000)-- Read current timelocal rtc_secs = rtc_mmio:read32(0x00)local rtc_mins = rtc_mmio:read32(0x04)local rtc_hrs = rtc_mmio:read32(0x08)print(string.format("hours: %02x minutes: %02x seconds: %02x", rtc_hrs, rtc_mins, rtc_secs))
rtc_mmio:close()-- Open am335x control module pagelocal ctrl_mmio =MMIO(0x44E10000, 0x1000)-- Read MAC addresslocal mac_id0_lo = ctrl_mmio:read32(0x630)local mac_id0_hi = ctrl_mmio:read32(0x634)print(string.format("MAC address: %04x%08x", mac_id0_lo, mac_id0_hi))
ctrl_mmio:close()
Seriallocal Serial =require('periphery').Serial-- Open/dev/ttyUSB0 with baudrate 115200, and defaults of 8N1, no flow controllocal serial =Serial("/dev/ttyUSB0", 115200)
serial:write("Hello World!")-- Read up to 128 bytes with 500ms timeoutlocal buf = serial:read(128, 500)print(string.format("read %d bytes: _%s_", #buf, buf))
serial:close()
Error Handling
lua-periphery errors are descriptive table objects with an error code string, C errno, and a user message.-- Example of error caught with pcall()> status, err =pcall(function () spi = periphery.SPI("/dev/spidev1.0", 0, 1e6) end)>=statusfalse>dump(err)
{
message ="Opening SPI device "/dev/spidev1.0": Permission denied [errno 13]",
c_errno =13,
code ="SPI_ERROR_OPEN"}>-- Example of error propagated to user> periphery =require('periphery')> spi = periphery.SPI('/dev/spidev1.0', 0, 1e6)
Opening SPI device"/dev/spidev1.0": Permission denied [errno 13]>Note about Lua 5.1
Lua 5.1 does not automatically render the string representation of error objects that are reported to the console, and instead shows the following error message :> periphery =require('periphery')> gpio = periphery.GPIO(14)
(error object is not a string)>
These errors can be caught with pcall() and rendered in their string representation with tostring(), print(), or by evaluation in the interactive console :> periphery =require('periphery')> gpio, err =pcall(periphery.GPIO, 14)>=tostring(err)
Exporting GPIO: opening'export': Permission denied [errno 13]>print(err)
Exporting GPIO: opening'export': Permission denied [errno 13]>=err
Exporting GPIO: opening'export': Permission denied [errno 13]>
This only applies to Lua 5.1.LuaJIT and Lua 5.2 onwards automatically render the string representation of error objects that are reported to the console.
Documentation
man page style documentation for each interface is available in docs folder.
InstallationBuild and install with LuaRocks$ sudo luarocks install lua-peripheryBuild and install from source
Clone lua-periphery recursively to also fetch c-periphery, which lua-periphery is built on.$ git clone --recursive https://github.com/vsergeev/lua-periphery.git$ cd lua-periphery$ make clean all$ cp periphery.so/path/to/lua/libs/
Place periphery.so in a directory searched by the Lua package.cpath variable.for example : /usr/lib/lua/5.2/, the same directory as other Lua sources, etc.
lua-periphery can then be loaded in lua with periphery = require('periphery').Cross-compiling from Source
To cross-compile, set the CC environment variable with the cross-compiler when calling make :CC=arm-linux-gnueabihf-gcc make clean all. your target's sysroot must provide the Lua includes.$ CC=arm-linux-gnueabihf-gcc make clean allcd c-periphery && make cleanmake[1]: Entering directory '/home/anteater/projects-software/lua-periphery/c-periphery'rm -rf periphery.a obj tests/test_serial tests/test_i2c tests/test_mmio tests/test_spi tests/test_gpiomake[1]: Leaving directory '/home/anteater/projects-software/lua-periphery/c-periphery'rm -rf periphery.socd c-periphery; makemake[1]: Entering directory '/home/anteater/projects-software/lua-periphery/c-periphery'mkdir objarm-linux-gnueabihf-gcc -std=gnu99 -pedantic -Wall -Wextra -Wno-unused-parameter -Wno-pointer-to-int-cast -fPIC -c src/gpio.c -o obj/gpio.oarm-linux-gnueabihf-gcc -std=gnu99 -pedantic -Wall -Wextra -Wno-unused-parameter -Wno-pointer-to-int-cast -fPIC -c src/spi.c -o obj/spi.oarm-linux-gnueabihf-gcc -std=gnu99 -pedantic -Wall -Wextra -Wno-unused-parameter -Wno-pointer-to-int-cast -fPIC -c src/i2c.c -o obj/i2c.oarm-linux-gnueabihf-gcc -std=gnu99 -pedantic -Wall -Wextra -Wno-unused-parameter -Wno-pointer-to-int-cast -fPIC -c src/mmio.c -o obj/mmio.oarm-linux-gnueabihf-gcc -std=gnu99 -pedantic -Wall -Wextra -Wno-unused-parameter -Wno-pointer-to-int-cast -fPIC -c src/serial.c -o obj/serial.oar rcs periphery.a obj/gpio.o obj/spi.o obj/i2c.o obj/mmio.o obj/serial.omake[1]: Leaving directory '/home/anteater/projects-software/lua-periphery/c-periphery'arm-linux-gnueabihf-gcc -std=c99 -pedantic -D_XOPEN_SOURCE=700 -Wall -Wextra -Wno-unused-parameter -fPIC -I. -I/home/anteater/sandbox/buildroot-nmt/output/host/usr/arm-buildroot-linux-uclibcgnueabihf/sysroot/usr/include -shared src/lua_periphery.c src/lua_mmio.c src/lua_gpio.c src/lua_spi.c src/lua_i2c.c src/lua_serial.c c-periphery/periphery.a -o periphery.so$ file periphery.soperiphery.so: ELF 32-bit LSB shared object, ARM, EABI5 version 1 (SYSV), dynamically linked, not stripped$
Testing
The tests located in the tests folder may be run under Lua to test the correctness and functionality of lua-periphery.some tests require interactive probing (e.g.with an oscilloscope), the installation of a physical loopback, or the existence of a particular device on a bus.see the usage of each test for more details on the required setup.
License
lua-periphery is MIT licensed. see the included LICENSE file.