{"id":13830198,"url":"https://github.com/MicroLua/MicroLua","last_synced_at":"2025-07-09T11:32:18.322Z","repository":{"id":205345098,"uuid":"707704237","full_name":"MicroLua/MicroLua","owner":"MicroLua","description":"Lua for the RP2040 microcontroller","archived":false,"fork":false,"pushed_at":"2024-04-12T16:38:35.000Z","size":2215,"stargazers_count":148,"open_issues_count":0,"forks_count":9,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-04-13T16:36:32.441Z","etag":null,"topics":["lua","microlua","raspberry-pi-pico","rp2040"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MicroLua.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-10-20T13:26:23.000Z","updated_at":"2024-04-14T18:38:09.544Z","dependencies_parsed_at":"2024-01-04T20:32:08.128Z","dependency_job_id":"da6f1429-463c-4a58-a268-97a04fc603bb","html_url":"https://github.com/MicroLua/MicroLua","commit_stats":null,"previous_names":["microlua/microlua"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MicroLua/MicroLua","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroLua%2FMicroLua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroLua%2FMicroLua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroLua%2FMicroLua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroLua%2FMicroLua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MicroLua","download_url":"https://codeload.github.com/MicroLua/MicroLua/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroLua%2FMicroLua/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264450556,"owners_count":23610194,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lua","microlua","raspberry-pi-pico","rp2040"],"created_at":"2024-08-04T10:00:57.203Z","updated_at":"2025-07-09T11:32:18.316Z","avatar_url":"https://github.com/MicroLua.png","language":"C","readme":"\u003c!-- Copyright 2023 Remy Blank \u003cremy@c-space.org\u003e --\u003e\n\u003c!-- SPDX-License-Identifier: MIT --\u003e\n\n# MicroLua - Lua for the RP2040 microcontroller\n\nMicroLua allows **programming the\n[RP2040 microcontroller](https://www.raspberrypi.com/documentation/microcontrollers/silicon.html#rp2040)\nin [Lua](https://www.lua.org/)**. It packages the latest Lua interpreter with\nbindings for the [Pico SDK](https://github.com/raspberrypi/pico-sdk) and a\ncooperative threading library.\n\nMicroLua is licensed under the [MIT](LICENSE.txt) license.\n\n- Mailing list:\n  [microlua@freelists.org](https://www.freelists.org/list/microlua)\n\n## Why\n\n- Lua is a small, embeddable language. It is easy to learn and reasonably fast.\n\n- The RP2040 is a small, powerful microcontroller with a nice set of\n  peripherals and an active developer community. Besides the official\n  [Pico](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#technical-specification)\n  and\n  [Pico W](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-w-and-pico-wh)\n  boards from\n  [Raspberry Pi](https://www.raspberrypi.com/), a variety of cheap modules in\n  various shapes and configurations are readily available for purchase.\n\nBut to be honest, it's just an excuse for me to play with Lua and the RP2040,\nand see how far I can push them.\n\n## Features\n\n- **Pristine, unpatched Lua interpreter:** MicroLua runs the latest,\n  unmodified Lua interpreter, imported as a git submodule. All customization is\n  done through [`luaconf.h`](core/luaconf.in.h).\n- **Per-core interpreter instances:** MicroLua runs a separate Lua interpreter\n  in each core. They don't share state except through C libraries.\n- **Cooperative multithreading through Lua coroutines:** MicroLua implements\n  cooperative threads as coroutines. This enables multitasking without the need\n  for locks. Blocking library calls (e.g. `mlua.time.sleep_for()`) yield to\n  other threads.\n- **Thin bindings to C libraries:** MicroLua exposes a growing subset of the\n  functionality provided by the Pico SDK. The bindings are designed with a\n  straightforward and consistent [mapping](docs/core.md#binding-conventions) to\n  their underlying C implementation.\n- **Support for [Fennel](https://fennel-lang.org/):** Fennel sources are\n  transpiled to Lua.\n- **Comprehensive suite of unit tests:** They not only test the binding layer,\n  but when possible also the underlying functionality of the Pico SDK.\n\n### Performance\n\nPerformance is adequate for applications that don't require very low latency.\nEvent dispatch latency is on the order of 20 microseconds when running from\nflash at 250 MHz. So it probably isn't realistic to try bit-banging high-speed\nserial protocols or PWM in Lua, but that's what the PIO and PWM peripherals are\nfor. Anything that requires precise timings should probably be implemented in C.\nBut Lua is a great glue language for the non timing-critical logic, and very\neasy to interface to C code.\n\n### Roadmap\n\n- **Add more bindings for the Pico SDK.** Next on the list are USB and\n  Bluetooth. Eventually, most SDK libraries will have a binding.\n- **Improve cross-core communication.** Each core runs its own Lua interpreter,\n  so they cannot communicate directly through shared Lua state. Currently, the\n  only way for the cores to communicate is the SIO FIFOs, which is fairly\n  limited. A form of memory-based cross-core channel would be useful.\n- **Add multi-chip communication.** As an extension of cross-core channels,\n  cross-chip channels could enable fast communication between multiple RP2040\n  chips.\n\n## Examples\n\nThe [MicroLua-examples](https://github.com/MicroLua/MicroLua-examples)\nrepository contains example programs that demonstrate how to use the features of\nthe RP2040 from Lua.\n\nHere's the `blink` example in MicroLua, a direct translation of the\n[`blink`](https://github.com/raspberrypi/pico-examples/tree/master/blink)\nexample from the [`pico-examples`](https://github.com/raspberrypi/pico-examples)\nrepository.\n\n```lua\nlocal gpio = require 'hardware.gpio'\nlocal pico = require 'pico'\nlocal time = require 'pico.time'\n\nfunction main()\n    local LED_PIN = pico.DEFAULT_LED_PIN\n    gpio.init(LED_PIN)\n    gpio.set_dir(LED_PIN, gpio.OUT)\n    while true do\n        gpio.put(LED_PIN, 1)\n        time.sleep_ms(250)\n        gpio.put(LED_PIN, 0)\n        time.sleep_ms(250)\n    end\nend\n```\n\n## Documentation\n\n- [Core functionality](docs/core.md) of MicroLua.\n- [`mlua.*`](docs/mlua.md): MicroLua libraries.\n- [`hardware.*`](docs/hardware.md): Bindings for the `hardware_*` libraries of\n  the Pico SDK.\n- [`pico.*`](docs/pico.md): Bindings for the `pico_*` libraries of the Pico SDK.\n- [`lwip.*`](docs/lwip.md): Bindings for the lwIP library.\n\n## Test suite\n\nHere's how to build and run the test suite.\n\n```shell\n# Clone the repository and initialize submodules.\n$ git clone https://github.com/MicroLua/MicroLua.git\n$ cd MicroLua\n$ git submodule update --init\n$ git -C ext/pico-sdk submodule update --init\n\n# Build the test suite for the host and run it.\n$ tools/run -l -t bin/mlua_tests -p host\n\n# Build the test suite for a \"pico\" board, flash it with picotool and connect\n# to its virtual serial port with socat to view the test results. The target\n# should be in BOOTSEL mode.\n$ tools/run -l -t bin/mlua_tests -p pico -c -DPICO_BOARD=pico\n```\n\n## Contributing\n\nWhile I'm happy to accept bug reports, feature requests and other suggestions on\nthe [mailing list](https://www.freelists.org/list/microlua), I am not actively\nlooking for code contributions. In particular, **please do not send pull\nrequests** on Github. MicroLua is developed in a private\n[Mercurial](https://www.mercurial-scm.org/) repository, which is mirrored to\nGithub.\n\n## FAQ\n\n### Why Lua? Why the RP2040?\n\nBoth Lua and the RP2040 evolve at a velocity that can be followed by a single\ndeveloper in their spare time. Lua is developed by a small team: the language\nitself evolves very slowly and the interpreter has a couple of minor releases\neach year. Similarly, the RP2040 is developed by a small company, and a new chip\nmay be released every few years.\n\nContrast this with e.g. Python: the language evolves rather quickly nowadays,\nand the interpreter gets contributions from dozens (hundreds? thousands?) of\ndevelopers. Similarly, large semiconductor companies release new chips and\nvariants every year. Developing for these targets is a game of catch-up that I\ndon't want to play.\n\n### Does MicroLua support other microcontroller families?\n\nCurrently it doesn't, but it shouldn't be too difficult to add. The build system\nis already multi-platform, as it can create binaries for the RP2040 and for the\nbuild host. However, adding support for more platforms isn't a high priority.\n\nMicroLua will likely support later RP devices if / when they get released.\n\n### How does MicroLua compare to other Lua projects for the Pico?\n\n- [picolua](https://github.com/kevinboone/luapico) is based on a patched Lua 5.4\n  interpreter, and aims to provide a full embedded development environment,\n  including a shell and an editor. It exposes a limited subset of Pico-specific functionality.\n\n  MicroLua uses an unpatched Lua interpreter at the latest version, and aims to\n  expose most of the functionality provided by the Pico SDK through a thin\n  binding layer.\n\n### What's the relationship with MicroLua DS?\n\n[MicroLua DS](https://sourceforge.net/projects/microlua/) was a development\nenvironment for building apps for the Nintendo DS in Lua. It was last released\nin January 2014. MicroLua has no relationship with MicroLua DS.\n\nWhile the naming conflict is unfortunate, I felt that almost 10 years of\ninactivity was long enough that it was fair game to re-use the name.\n","funding_links":[],"categories":["C"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMicroLua%2FMicroLua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMicroLua%2FMicroLua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMicroLua%2FMicroLua/lists"}