Skip to content

Development

Summary

  • Create a branch
  • Make changes
  • Document your change
  • Submit a pull request

Standards and Guidelines. Check before submitting a request!

Create a branch

  • Want to make changes: fork the repo (see installation) and submit pull requests, see creating-a-pull-request-from-a-fork:

  • Only branch from the main branch! Press Branches, press New Branch, give it a name e.g. background-script and press Create new Branch, click on background-script

Make changes

Front-end (UI)

  • interface folder
    • interface/src/routes/moonbase for MoonBase and MoonLight (modules)
  • see Prepare for development about nodejs, npm install
npm install
npm run dev

Back-end (Server)

There are 3 levels to add functionality:

  • Standard ESP32-Sveltekit code, e.g. Connections, Wifi and System. MoonBase files are also made using standard SvelteKit as examples but contain a few components used in MoonLight modules. Might be rewritten as a MoonLight Module in the future.
  • lib folder for Sveltekit back-end
  • Read the ESP32 Sveltekit docs
  • MoonLight Modules e.g. Lights Control, Effects, Info, Channels. They are subclasses of Modules.h/cpp and implement setupDefinition, onUpdate and optional loop. New modules need to be defined in main.cpp and added to menu.svelte. All further UI is generated by Module.svelte.
  • src folder for MoonBase and MoonLight back-end
  • MoonLight Nodes: the easiest and recommended way. See Effects.h, Layouts.h, Modifiers.h and Drivers.h for examples. They match closest WLED usermods. Each node has controls, a setup and a loop and can be switched on and off. For specific purposes hasOnLayout() and hasModifier() can return true.
  • src/MoonLight/nodes

Steps

  • Go to the file(s) you want to change press edit and make the changes.
  • ☑️ and ➡️ to build and or upload
  • Changes made to the UI are not always visible in the browser, clear the browser cache to see latest UI (see connect to MoonLight).
  • MoonLight uses clang-format for c/c++ code and prettier for Svelte, javascript etc. Format your code before submitting! (right-click Format Document on each page you change)
  • Press Commit Changes..., enter a commit message and an extended description, Press Commit Changes

Document your changes

See Documentation

Submit a pull request

* Go back to the homepage of your fork [myfork/MoonLight](https://github.com/ewowi/MoonLight). There is a message inviting to create a Pull Request. Press Compare & pull request.

  <img width="350" alt="Screenshot 2025-04-15 at 14 59 15" src="https://github.com/user-attachments/assets/410aa517-99eb-4907-b1a3-db7f38abb194" />

* Add a title and Description to the Pull Request and press Create Pull Request

* The upstream MoonLight repo can now process this PR

Additional info

Emoji coding

  • Serial Log shows which code is from which library using emoji:

Screenshot 2025-06-07 at 12 09 06

* 🐼: ESP-SvelteKit
* 🔮: PsychicHTTP
* 🐸: Live Scripts
* 🌙: MoonBase
* 💫: MoonLight
🌙 and 💫 is also used in code comments of ESP32-SvelteKit to show where changes to upstream have been made.
  • The following ESP32-SvelteKit features have been switched off in the default builts (they can be switched on if you want to use them, see features.ini)
    • -D FT_SECURITY=0
    • -D FT_SLEEP=0
    • ~~-D FT_BATTERY=1~~ enabled!

UI development server

To ease the front-end development you can deploy the back-end code on an ESP32 board and pass the websocket and REST API calls through the development server's proxy running on your computer.

This very much speeds up UI development, as no flashing to the ESP32 is required to test updated UI. Saving a UI file is enough to see the results.

See Setup Proxy for Development and development-server how to setup.

nodejs

if nodejs is not installed yet: see Prepare for development to install nodejs

After configuring the development server, a local webserver starts on localhost:5173.

Release and merged firmware binaries

Firmware binaries come in 2 flavours: including boot and partition (merged) and MoonLight code only (release). They are stored in the build folder of the MoonLight repo and updated each time a build or upload (☑️ or ➡️) is done. Subfolder merged contains the first type, release the second type.

  • Merged bins are used by the MoonLight Installer, release bins by the System update module (OTA). System update uses the bins stored in GitHub releases.
  • Merged bins starts flashing on address 0x0, release bins on address 0x10000.
  • All MoonLight partition schemes have a firmware size of 3MB. Smaller devices (e.g. ESP32-D0) have no OTA partition. System update is possible in this situation, but there is no fallback if update fails (need to flash using USB in that case) 🚧

flash firmware using esptool

  • [>_] in the statusbar of vscode 
    esptool --port /dev/cu.usbmodem11201 write-flash 0x0 ./build/merged/MoonLight_esp32-s3-devkitc-1-n16r8v_0-6-0_webflash.bin
  • optionally add erase-flash before write-flash
  • use ./build/release/MoonLight_esp32-s3-devkitc-1-n16r8v_0-6-0.bin and address 0x10000 to flash only the MoonLight partition

Adding an ESP32 device Definition

Before starting, ensure you have the datasheet of your particular chip and ESP32-device confirmed and available. Many modules have near-identical markings that can hide varying hardware.

There are 3 files to consider when making a ESP32-device definition.

boards/BOARD_NAME.csv
boards/BOARD_NAME.JSON
firmware/BOARD_TYPE_NAME.ini (e.g. esp32dev, esp32-s3), contains different boards