Development

Developing

• Read the ESP32 Sveltekit docs
• Read Customizing Sveltekit
• Create a fork so you have your own environment to make changes to. See also Pull Requests below.
• Changes made to the UI are not always visible in the browser, clear the browser cache to see latest UI (see connect to MoonLight).
• Serial Log shows which code is from which library using emoji:

* 🐼: 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=1~~ enabled!
  • ~~-D FT_BATTERY=1~~ enabled!

Where you can help

• Improve the web installer
• Improve the UI (Svelte 5, DaisyUI 5, TailWind 4)
• Mutli row layout
• Tune FastLED, add FastLED 2D effects
• CI automation (Generate daily builds in Github and use by installer)
• Palettes: more, custom, audio reactive

Contact us in the MoonLight channels on Discord MoonModules

Pull Requests

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

  • Login to your own github account
  • Fork: go to MoonModules/MoonLight and press Fork, uncheck 'Copy the main branch only' and press Create Fork. You will be moved to your fork of MoonLight
  • Press Branches, press New Branch, give it a name e.g. background-script and press Create new Branch, click on background-script

  

  • Go to the file you want to change press edit and make the changes. E.g. change executable.execute("main") to executable.executeAsTask("main")
  • Press Commit Changes..., enter a commit message and an extended description, Press Commit Changes
  • Go back to the homepage of your fork myfork/MoonLight. There is a message inviting to create a Pull Request. Press Compare & pull request.

  

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

  • The upstream MoonLight repo can now process this PR

Adding functionality

• lib folder for Sveltekit back end
• src folder for MoonBase and MoonLight back end

• interface folder for front end development

  • interface/src/routes/moonbase for MoonBase and MoonLight (modules)

• ☑️ and ➡️ to build and or upload

Front End (UI)

🚧

• interface folder
• see Prepare for development about nodejs, npm install

npm install
npm run dev

• see Troubleshooting about WWWData.h

Back End (Server)

There are 3 levels to add functionality:

• Standard ESP32-Sveltekit code, e.g. Connections, Wifi and System. MoonBase files is also made using standard sveltekit as example but contains a few components used in MoonLight modules. Might be rewriteen as MoonLight Module in the future.
• 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.
• 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 hasLayout() and hasModifier() can return true.

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

Technical notes

LED drivers

• Switch off to see the effect framerate in System Status/Metrics
• Switch on to see the effect framerate throttled by a LED driver in System Status/Metrics (800KHz, 256 LEDs, 24 bits is 130 fps theoretically - 120 practically)

Live Scripts

• Uses ESPLiveScripts, see compileAndRun. compileAndRun is started when in Nodes a file.sc is choosen
  • To do: kill running scripts, e.g. when changing effects

File Manager

Technical

• filesState: all files on FS
• folderList: all files in a folder
• editableFile: current file
• getState / postFilesState: get filesState and post changes to files (update, delete, new)
• addFile / addFolder: create new items
• breadcrumbs(String): folder path as string array and as string, stored in localStorage
• folderListFromBreadCrumbs: create folderList of current folder
• handleEdit: when edit button pressed: navigate back and forward through folders, edit current file
• confirmDelete: when delete button pressed
• socket files / handleFileState (->folderListFromBreadCrumbs)

Using component FileEdit, see Components