https://github.com/MicroLua/MicroLua Skip to content Toggle navigation Sign up * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code Explore + All features + Documentation + GitHub Skills + Blog * Solutions For + Enterprise + Teams + Startups + Education By Solution + CI/CD & Automation + DevOps + DevSecOps Resources + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} MicroLua / MicroLua Public * Notifications * Fork 0 * Star 13 Lua for the RP2040 microcontroller License MIT license 13 stars 0 forks Activity Star Notifications * Code * Pull requests 0 * Actions * Security * Insights More * Code * Pull requests * Actions * Security * Insights MicroLua/MicroLua This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags Name already in use A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? Cancel Create 1 branch 0 tags Code * Local * Codespaces * Clone HTTPS GitHub CLI [https://github.com/M] Use Git or checkout with SVN using the web URL. [gh repo clone MicroL] Work fast with our official CLI. Learn more about the CLI. * Open with GitHub Desktop * Download ZIP Sign In Required Please sign in to use Codespaces. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit @rblank rblank docs: Set the README title. ... b72dac6 Nov 3, 2023 docs: Set the README title. b72dac6 Git stats * 365 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time core Add copyright notices and license identifiers to all files. November 3, 2023 16:34 docs docs: Document how to set up a minimal project. November 3, 2023 18:18 ext Update Lua to 5.4.6. June 3, 2023 10:14 lib Add copyright notices and license identifiers to all files. November 3, 2023 16:34 tools Add copyright notices and license identifiers to all files. November 3, 2023 16:34 .gitignore Add a .gitignore. October 20, 2023 18:43 .gitmodules Add a git submodule config. October 20, 2023 17:55 .hgignore Add a .gitignore. October 20, 2023 18:43 CMakeLists.txt Add copyright notices and license identifiers to all files. November 3, 2023 16:34 LICENSE.txt Make the license a plain text file. November 3, 2023 16:38 README.md docs: Set the README title. November 3, 2023 19:17 mlua_import.cmake Add copyright notices and license identifiers to all files. November 3, 2023 16:34 mlua_init.cmake Add copyright notices and license identifiers to all files. November 3, 2023 16:34 pico_sdk_import.cmake Add a minimal test executable. February 25, 2023 17:17 rules.cmake Add copyright notices and license identifiers to all files. November 3, 2023 16:34 View code [ ] MicroLua - Lua for the RP2040 microcontroller Why Features Performance Roadmap Building Examples Documentation Contributing FAQ Why Lua? Why the RP2040? Can MicroLua support other microcontroller families? How does MicroLua compare to other Lua projects for the Pico? What's the relationship with MicroLua DS? README.md MicroLua - Lua for the RP2040 microcontroller MicroLua allows programming the RP2040 microcontroller in Lua. It packages the latest Lua interpreter with bindings for the Pico SDK and a cooperative threading library. MicroLua is licensed under the MIT license. * Mailing list: microlua@freelists.org Why * Lua is a small, embeddable language. It is easy to learn and reasonably fast. * The RP2040 is a small, powerful microcontroller with a nice set of peripherals and an active developer community. Besides the official Pico and Pico W boards from Raspberry Pi, a variety of cheap modules in various shapes and configurations are readily available for purchase. I had been wanting to play with Lua for a very long time, without having a concrete use case for it. Similarly, I wanted to explore the RP2040 but didn't have a concrete project for it. MicroLua served as an excuse to get started with both. Features * Pristine, unpatched Lua interpreter: MicroLua runs the latest, unmodified Lua 5.4.x interpreter, imported as a git submodule. All customization is done through luaconf.h. * Per-core interpreter instances: MicroLua runs a separate Lua interpreter in each core. They don't share state except through C libraries. * Cooperative multithreading through Lua coroutines: MicroLua implements cooperative threads as coroutines. This enables multitasking without the need for locks. Blocking library calls (e.g. pico.time.sleep_us()) yield to other threads. * Thin bindings to C libraries: MicroLua exposes a growing subset of the functionality provided by the Pico SDK. The bindings are designed with a straightforward and consistent mapping to their underlying C implementation. * Comprehensive suite of unit tests: They not only test the binding layer, but when possible also the underlying functionality of the Pico SDK. Performance Performance is adequate for applications that don't require very low latency, but it could be better. Event dispatch latency is currently in the hundreds of microseconds, which is fairly slow. This is mainly due to a naive threading implementation, and it can be improved. So it probably isn't realistic to try bit-banging high-speed serial protocols or PWM in Lua, but that's what the PIO and PWM peripherals are for. Anything that requires precise timings should probably be implemented in C. But Lua is a great glue language for the non timing-critical logic, and very easy to interface to C code. Roadmap * Add more bindings for the Pico SDK. SPI and PIO are high on the list, followed by USB, Wifi and Bluetooth. Eventually, most SDK libraries should have a binding. * Improve threading performance. A C implementation of the mlua.thread module, with a less naive timer list, could significantly improve event dispatch latency. * Add a filesystem (probably littlefs) with support for loading Lua modules and updating them over USB. This will enable simpler development workflows similar to e.g. MicroPython & Thonny. * Tune garbage collection. Garbage collection parameters are currently left at their default value, which may not be ideal for a memory-constrained target. * Improve cross-core communication. Each core runs its own Lua interpreter, so they cannot communicate directly through shared Lua state. Currently, the only way for the cores to communicate is the SIO FIFOs, which is fairly limited. A form of memory-based cross-core channel would be useful. * Add multi-chip communication. As an extension of cross-core channels, cross-chip channels could enable fast communication between multiple RP2040 chips. Building Here's how to build and run the test suite on a Raspberry Pi Pico module. # Configure the location of the Pico SDK. Adjust for your setup. $ export PICO_SDK_PATH="${HOME}/pico-sdk" # Clone the repository and initialize submodules. $ git clone https://github.com/MicroLua/MicroLua.git $ cd MicroLua $ git submodule update --init # Connect a Picoprobe to the target, on the UART and optionally on the debug # port. Then view the Picoprobe's UART connection in a separate terminal. # The "term" script uses socat. $ tools/term /dev/ttyACM0 # Build the unit tests. $ cmake -s . -B build -DPICO_BOARD=pico $ make -j9 -C build/lib # Start the target in BOOTSEL mode and flash it with picotool. $ picotool load -v -x build/lib/mlua_tests.elf # Alternatively, start the target in BOOTSEL mode and copy to its boot drive. $ cp build/lib/mlua_tests.uf2 /mnt/RPI-RP2/ Examples The MicroLua-examples repository contains example programs that demonstrate how to use the features of the RP2040 from Lua. Here's the blink example in MicroLua, a translation of the blink example from the pico-examples repository. _ENV = mlua.Module(...) local gpio = require 'hardware.gpio' local pico = require 'pico' local time = require 'pico.time' function main() local LED_PIN = pico.DEFAULT_LED_PIN gpio.init(LED_PIN) gpio.set_dir(LED_PIN, gpio.OUT) while true do gpio.put(LED_PIN, 1) time.sleep_ms(250) gpio.put(LED_PIN, 0) time.sleep_ms(250) end end Documentation * Core functionality of MicroLua. * hardware.*: Bindings for the hardware_* libraries of the Pico SDK. * pico.*: Bindings for the pico_* libraries of the Pico SDK. * mlua.*: MicroLua libraries. Contributing While I'm happy to accept bug reports, feature requests and other suggestions on the mailing list, I am not actively looking for code contributions. In particular, please do not send pull requests on Github. MicroLua is developed in a private Mercurial repository, which is mirrored to Github. FAQ Why Lua? Why the RP2040? Both Lua and the RP2040 evolve at a velocity that can be followed by a single developer in their spare time. Lua is developed by a small team: the language itself evolves very slowly and the interpreter has a couple of minor releases each year. Similarly, the RP2040 is developed by a small company, and a new chip may be released every few years. Contrast this with e.g. Python: the language evolves rather quickly nowadays, and the interpreter gets contributions from dozens (hundreds? thousands?) of developers. Similarly, large semiconductor companies release new chips and variants every year. Developing for these targets is a game of catch-up that I don't want to play. Can MicroLua support other microcontroller families? No, that's an explicit non-goal. Supporting multiple microcontroller families inevitably leads to either limiting features to the common denominator, or introducing a complex configuration system. Moreover, MicroLua integrates directly with the build system of the Pico SDK, which is strongly tied to the RP2040. Supporting other microcontrollers would require a different build system. MicroLua will likely support later RP devices if / when they get released, but until then, the RP2040 is the only supported target. How does MicroLua compare to other Lua projects for the Pico? * picolua is based on a patched Lua 5.4 interpreter, and aims to provide a full embedded development environment, including a shell and an editor. It exposes a limited subset of Pico-specific functionality. MicroLua uses an unpatched Lua interpreter at the latest stable version, and aims to expose most of the functionality provided by the Pico SDK through a thin binding layer. What's the relationship with MicroLua DS? MicroLua DS was a development environment for building apps for the Nintendo DS in Lua. It was last released in January 2014. MicroLua has no relationship with MicroLua DS. While the naming conflict is unfortunate, I felt that almost 10 years of inactivity was long enough that it was fair game to re-use the name. About Lua for the RP2040 microcontroller Topics lua rp2040 raspberry-pi-pico microlua Resources Readme License MIT license Activity Stars 13 stars Watchers 3 watching Forks 0 forks Report repository Languages * C 51.4% * Lua 39.1% * CMake 9.2% * Shell 0.3% Footer (c) 2023 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time.