LuatOS is a Lua firmware platform sized for 16K of RAM

A Lua engine, not a framework on top of one

LuatOS is described as a powerful embedded Lua engine for IoT devices, with many components and low memory requirements, given as 16K of RAM and 128K of flash. The primary language of the repository is C, and the licence is MIT.

That footprint number is the whole design brief. A Lua virtual machine plus a runtime framework plus a set of hardware drivers, all fitting in 16K of RAM, is a very different proposition from an RTOS with a scripting shell bolted on. It means the scripts are the application, not a convenience layer over a C program, and it means the module firmware in the repository has to be built to fit rather than to be convenient.

The Chinese-language README describes the goal directly: LuatOS, based on a powerful Lua engine architecture, with Lua script development so that business logic can be implemented quickly. The headline claim is that LuatOS now supports 74 core libraries, 55 extension libraries, more than a thousand APIs and over a hundred scenario-based demos, with the phrase that developing a smart device becomes as easy as making a slide deck.

The audience is embedded developers working on AirM2M modules. The topic list names the hardware it targets, including Air101, Air103, Air105, Air600E, Air601, Air780E, Air780EG and esp32c3, along with 4G LTE, NB-IoT, WiFi and RTOS. The homepage is wiki.luatos.com, and the last push to the repository was on 2026-10-17.

Two generations: LuatOS-Air and LuatOS-SoC

The README explains the project's history in two stages, and the naming is a real usability issue for anyone following older documentation.

LuatOS-Air was the earlier form, with typical hardware of the Air724UG, belonging to the previous generation of AirM2M products. LuatOS, formerly named LuatOS-SoC, is the current main development approach.

The current supported hardware is listed in series. The Air8000 series covers Air8000, Air8000W, Air8000G, Air8000T, Air8000A and Air8000D. The Air8101 series covers Air8101 and Air8101A. The Air780Exx series covers Air780EPM, Air780EHM, Air780EHV and Air780EGH.

The practical consequence is that there are two generations of documentation, tutorials and example code in circulation, and the older material refers to a product line and a file layout that no longer describe the current platform. The repository still carries olddemo/ and oldmodule/ directories next to the current ones, which makes the split visible in the tree rather than hidden.

The repository also retains a module directory for AirM2M modules and mainstream industrial engine models, holding firmware, demos and project reference code, so the reference implementations for a given board live with the board.

For an evaluator, the first question is therefore not which library to use but which hardware line you are on, because that determines which documentation set, which firmware build and which API surface apply.

The tree separates the VM, the framework and the components

The folder list in the README is the clearest description of the architecture, and it is worth reading as a layered design.

The lua/ directory holds the source of the Lua 5.3 series virtual machine, optimised and tested by AirM2M. The luat/ directory holds the LuatOS core framework code. The components/ directory holds the series of libraries that LuatOS extends on top of Lua. The script/ directory holds the LuatOS extension libraries, and the module/ directory holds firmware, demos and project reference code for AirM2M modules and mainstream industrial engine models.

The .github/ directory holds the GitHub Actions configuration used for automated build and test, and tools/ holds the auxiliary tooling. The top level of the repository also carries an app_engine/ directory, a bsp/ directory for board support packages, docs/, testcase/, and, in the current tree, .gitee/, .claude/, .codegraph/, skill-packs/, olddemo/ and oldmodule/.

The split between components/ and script/ is the one to notice. Components are the libraries that extend Lua itself and are compiled into the firmware, while the script/ directory holds extension libraries that live in the Lua side of the system, which is the layer you can change without reflashing. For a product team, that boundary determines how much of your application you can iterate on quickly and how much is baked into the image.

The bsp/ directory also contains a PC simulator path, bsp/pc/, which is what the quick start points at as the way to work without a physical board.

Getting started: a board, a flashing tool, or the PC simulator

The quick start section is four steps, and the first one is a hardware decision.

You use or buy a supported development board. The README links the official AirM2M Taobao store for that, and it also points at the PC simulator, bsp/pc/, described as a simulator that needs no development board. That second option is the cheapest way to find out whether the API model suits you, and it is worth taking before committing to hardware.

The second step is mastering the flashing process, with the Luatools tool as the reference. The third step is learning the LuatOS framework, with links to the framework documentation, the API reference at docs.openluat.com/osapi/, and a set of 30 minute Lua syntax introduction videos. The fourth step, unromantically, is writing the business code.

The README closes with a short Lua greeting that doubles as a reminder of where the code ends up, since the English half of it looks like this once it is on the device:

print("Thank you for using LuatOS ^_^")

What is missing from that sequence is a build of your own firmware, and that is deliberate. The intended model is that you take a released firmware image for your module and write Lua scripts that run on it, not that you build a custom image. The module/ directory with its firmware, demos and project reference code is what you start from, and the tools/ directory and the separate luatos-cli project are what you use to work with the device afterwards.

luatos-cli is described as a cross-platform command line tool, and it lives in its own repository rather than in this one, which is a pattern worth noticing: the platform and the workflow tooling are versioned apart.

Where the documentation actually lives

The resources section of the README points to docs@luatos, the documentation site, and lists luatos-cli as the cross-platform command line tool. The Chinese README also links wiki.luatos.com as the homepage, and the tool links themselves point at docs.openluat.com for the framework guide, the API reference and the flashing tool.

So there are at least three documentation surfaces in play: the wiki, the docs site with the API reference and the video tutorials, and the source of the framework in this repository. None of them is optional if you are working with the platform, because the API reference is the only place the thousand APIs are described, and the wiki is where the board specific instructions live.

The repository's own docs/ directory sits alongside those, so a copy of the material is versioned with the code, and the AGENTS.md file at the root suggests the project has been through some effort to describe its conventions for tooling.

For anyone planning a project on this, the practical point is that the documentation is not self-contained in the repository, and it is spread across a wiki, a docs site, a gitee-hosted tool repository and the code itself. That is a normal pattern for a vendor-led embedded platform, but it does mean the time you spend reading is a real part of the cost of adoption.

Release artefacts stopped in 2023 while the repository kept moving

The release history is the one piece of the record that needs careful reading, because it describes firmware builds rather than the platform as a whole.

The three listed tags are all from 2023-04-24, and each names a per-SoC firmware build: v0007.ec618.v1106 for EC618 covering Air780E, Air780EG and Air600E, v0007.air103.v0016 as the Air103 official firmware, and v0007.air101.v0016 as the Air101 official firmware. The naming pattern makes the versioning scheme clear, a board family plus a platform version plus a build sequence.

Against that, the last push was on 2026-10-17, and the tree contains directories such as .gitee/, .claude/, .codegraph/ and skill-packs/ that are not part of a 2023 firmware build. The repository is being worked on; the tagged artefacts in it are old.

That gap matters when you plan a project. If you need a specific firmware build for your module, you should expect to get it from the module vendor's distribution rather than from the tags in this repository, and you should confirm which firmware your module ships with before assuming that any particular API is present. The MIT licence applies to the source in the repository, which is the part that matters if you intend to read the framework, study the components or reuse the code.

The most defensible way to evaluate the platform is on a specific module, with the API documentation for that module open, rather than on the repository's version numbers.

Editorial conclusion

Adopt LuatOS if you are building a connected device on AirM2M hardware and you want to write business logic in Lua rather than C, and you are prepared to work in an ecosystem whose documentation, tooling and firmware releases are split across several sites. Do not adopt it if your device uses a different vendor's module, or if you need a build system and a release process you can run yourself, because the tagged firmware artefacts in this repository stopped in 2023. Before you start, confirm your module family is one of the supported lines, get the flashing workflow set up, and read the API documentation for your board rather than assuming the general LuatOS behaviour applies.

Frequently asked questions

Official sources

1. License: MIT
2. openLuat/LuatOS on GitHub
3. Project website
4. README
5. Releases