This is a reference project for NodeMCU Lua development. It aims to help developers with NodeMCU module development setup. This repository contains a few helper scripts and tools which I like to use during development for my ESP-32 modules. The tools are not yet fully defined and I'm still working on a better local development environment for NodeMCU. So all PR's are welcome.
- NodeMCU firmware building and flash setup
- Lua Code Quality tools
- Lua NodeMCU unit tests
- NodeMCU LFS setup
- NodeMCU OTA setup
- Lua
- Lua Rocks
- For static code analysis LuaCheck
- Python and PIP
- Docker
- NPM and Yarn
- For NodeMCU development I prefer to use the following software:
This part will explain the following NodeMCU development steps: Building the firmware, flashing the firmware and uploading / executing Lua code on the NodeMCU module.
To make any custom edits to the NodeMCU firmware settings edit ./docker-bin/nodemcu/app/include/user_config.h and ./docker-bin/nodemcu/app/include/user_modules.h
Building a new version of the NodeMCU firmware can be done by following these few steps:
- Run
docker-compose run nodemcu build- This starts the NodeMCU docker image and builds the firmware
- The new firmware will be placed in the
./docker-bin/nodemcu/nodemcu-firmware/binfolder
Flashing the firmware is also quite easy:
- Make sure the NodeMCU module is connected
- Use the NodeMCU-Tool to determine which serial is your NodeMCU module run:
yarn devices - Once you've located your device, execute the following command to flash the new version
esptool.py --port <serial-port> write_flash -fm dio 0x00000 ./docker-bin/nodemcu/nodemcu-firmware/bin/nodemcu_float_master_<version>.binoryarn flash <serial-port> <firmware>- See the ESPTool Github repository for more information.
To upload custom code we use NodeMCU Uploader Uploading code can be done by using the following command:
nodemcu-uploader --port <serial-port> upload *.lua or yarn upload <serial-port> this uploads all files ending with .lua in the current directory
Executing code is done in a similar manner:
nodemcu-uploader --port <serial-port> file do <filename>.lua
Todo
To start Lua development make sure to first run yarn install in the root directory.
The following commands have been defined in the package.json file to assist with LUA code style
| Command | Description |
|---|---|
yarn format |
Formats the code according to the defined Lua prettier config |
yarn lint:prettier |
Validates the code against the defined Lua prettier config Lua |
yarn lint:luacheck |
Runs LuaCheck based on the local .luacheckrc file |
yarn lint |
Runs all configured linting tools |
yarn test |
Runs all tests defined in ./tests |
yarn devices |
Gets all connected devices using nodemcu-tool |
yarn upload <serial-port> |
Uploads all files using nodemcu-uploader ending with .lua to the specified device |
yarn terminal <serial-port> |
Connects to the specified device using nodemcu-uploader |
yarn exec <serial-port> |
Executes init.lua using Lua file do on the specified device |
yarn build-firmware |
Builds the NodeMCU firmware via Docker Compose |
yarn flash <serial-port> <firmware> |
Flashes the specified device with the specified firmware using esptool.py |
- Switch to 1 global tool for commands such as format, validate and etc
- Github CI/CD
- Better unit test integration
- Unit tests to run directly on the NodeMCU modules
- Fully working OTA setup
- Easier to use tooling for flashing and building the firmware
- Nikolay Fiykov (NodeMCU Lua API Mocks)
- Vladimir Dronnikov (Lua HTTP Server module)
See CONTRIBUTE.md