NodeMCU Device

• NodeMCU Device
  • What is possible?
  • How to use it this repo?
  • Image building instructions
    • Additional building details
  • Working with Lua modules

This is a repository of NodeMCU Lua modules.

These modules can be built into SPIFFS and LFS images.

There are unit and even integration tests but coverage is on the lower ends.

What is possible?

Using WeMos D1 Mini, one can run following and still have about 30kB free RAM:

• Wifi manager
• Http server with Captive portal, OTA and Home Assistant integration
• Telnet
• Thermostat control loop
• PID controller

Browse lua_modules folder to explore available functionality.

Example booting sequence is listed docs/boot-log.txt.

Captive portal web page looks like this

Integration with Home Assistant looks like this

How to use it this repo?

Build an image and flash the device. Image content (list of needed C and Lua modules) is defined in build.config file. See building instructions.

Hack lua_modules to add/remove/modify whatever functionality is needed and build new images.

Image building instructions

Prerequisites:

Internally the build is using nodemcu-firmware to create actual images (firmware, SPFFS and LFS).

Make sure your env can compile it locally!

Build steps:

• Clone this repo.
• Modify build.config (if you find a need).
  • modules and lua-modules list modules which will be packaged in the images.
    • Make sure you account for all module dependencies, there is no automatic tracking!
  • Other settings are not recommended to change, do so on your own discretion.
• make config to generate the build config input.
  • The file is stored under vendor folder.
• make prepare-firmware to patch firmware headers with needed into:
  • And to prepare nodemcu-firmware/local folder content.
• make build to build the images.
  • In vendor/nodemcu-firmware/bin folder:
    • 0x*.bin are NodeMCU firmware images.
    • 0x*.img is the SPIFFS image, packaging also LFS.img.
  • In vendor/nodemcu-firmware/local/fs are located all files included in SPIFFS image.
    • Any of the files, including actual LFS.img, can also be uploaded to the device manually.
• Flash the images to NodeMCU device.
  • make flash would flash firmware and SPIFFS (including prepackaged LFS) to ttyUSB device.
• On first boot, the device will auto-flash LFS.img, packaged inside SPIFFS and reboot again.
  • This is facilitated by bootprotect, init and lfs-init modules.
• After that, on second boot, the device will run its normal boot init sequence.

Note: if many Lua modules are included in the LFS, one might have to patch ./vendor/nodemcu-firmware/app/lua*/lopcodes.h (./vendor/nodemcu-firmware/components/lua/lua-5.*/lopcodes.h for ESP32 branch) setting for LFIELDS_PER_FLUSH from 50 to a bigger value:

#define LFIELDS_PER_FLUSH	200

Additional building details

Internally build would:

• use vendor folder as working location for data cloning and output generation
• clone nodemcu-firmware:dev branch under vendor/nodemcu-firmware.
  • it is used to generate all images
  • one can pre-clone different source tree there manually!
  • Beware that build process modifies files in this source tree (user_modules.h, user_config.h)!
• clone nodemcu-custom-build under vendor/nodemcu-custom-build
  • it is used to modify the firmware files prior to image building
  • one can pre-clone different source tree if there is a need.
• clone nodemcu-lua-mocks to run tests

Working with Lua modules

Each optionally installable module is placed in own folder.

In each module, <module>/lua/ sub-dir contains files which are to be placed in LFS image. And <module>/fs/ contains files to be placed directly in SPIFFS.

By default build.config is including most if not all modules.

Look at the docs/boot-log.txt to see what it looks like the default boot sequence.

Be mindful of module dependencies to include explicitly, there is no automatic build-time checking for this.

Integration test can be used to test that.