Installation

The development environment consists of

• VSCode

  • Platformio IDE
  • nodejs
  • git
  • python

• Github manager

  • GitKraken (recommended)
  • GitHub Desktop
  • No Github manager (not recommended)

Summary

Install VSCode with the platformIO IDE extension. Download the MoonLight repo. Open it in VSCode and build or upload to an ESP32 device.

supporting tools

• Optionally you need to install git and nodejs, run npm install and make sure python > v3.10 in VSCode.
• Instead of Platformio IDE, the pioarduino IDE extension might be needed in VSCode

Install Visual Studio Code

Step 1: Download the MoonLight repository

• Use GitKraken or GitHub Desktop (or manually)

  • Create a folder to download to: e.g. Developer/GitGub/MoonModules/MoonLight
  • Press + / New tab and select Clone a Repo
  • Copy MoonLight.git and paste in the URL field of GitKraken
  • Press clone the repo

  

  • The main branch will be checked out per default. To run / test latest developments, switch to the dev branch

Step 2: Download Visual Studio Code

• Windows: download from the Microsoft Store

  

• MacOS: Visual Studio download

Step 3: Install PlatformIO IDE

• Open the MoonLight repository folder created in step 1

• In VSCode, search for the extension

  

• Install the extension. Please note it can take a while before Configuring project is finished. Do not cancel. Don't change anything in the code yet. Drink a ☕️.

  

pioarduino IDE

PlatformIO IDE is default but as we are using latest esp-idf, pioarduino IDE is needed when PlatformIO IDE fails.

Step 4: Build MoonLight

• Press ☑️ in the bottom statusbar

  

• When git is not installed on your system, download git and install, restart VSCode and press ☑️ again

  • Windows:

    

  • MacOS

    

Install git on MacOS

• Install homebrew: will take a while: ☕️
• Install git using homebrew (replace with your user name):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

echo >> /Users/<user>/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/<user>/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

brew install git

• If you compile for the first time it take some time to finish (☕️)

  

MacOS: Python and LZMA

In some cases LZMA support must be installed

• Run in VSCode / pio shell ([>_])

brew install xz

python -V

• python -V should show a version > 3.10 (e.g. 3.11.7)

Step 5: Upload MoonLight to an esp32-device

• Connect an ESP32-device via USB and select the device using the (second) 🔌 icon in the staturbar. See Hardware.

USB-to-serial chip drivers

In some cases, ESP32-devices won't show connected. See USB-to-serial chip drivers at MoonLight Web Installer

• Erase the device if it is a new device or the device has not been used for MoonModules before: go to 👽 in the left menu and select Erase Flash

  

• Press upload (➡️) in the status bar

  

• The firmware is now flashed to your ESP32 device, after flashing the ESP32 device will reboot

Serial Monitor

Recommended: Press PlatformIO:Serial Monitor to see the debug information produced (the first 🔌 on the VSCode statusbar)

Connect and setup MoonLight

Before changing code, test if the current download of MoonLight is running fine. Follow the instructions in Connect MoonLight and Setup MoonLight

Technical info:

• MoonLight has a cache expiration of one year. However if you are developing or updating nightly builds cached UI code might be outdated.

  • First time connect to an ESP32-device is generally smoothly
  • If the UI has changed, reconnect to the same device might result in the UI not showing up. See the instructions 'UI not showing when installing new version of MoonLight' in Connect MoonLight

• A MoonLight device can be accessed via it's IP address or via http://ml-home.local. The latter uses MDNS.

ESP32Devices

IF you want to know which MoonLight (or WLED) devices run on your network, use ESP32Devices to discover the ESP32 nodes on your network

Prepare for development

nodejs is needed if changes on the frontend (UI) are made (interface folder). On each file change, ☑️ or ➡️ will rebuild the UI using nodejs.

• Windows: if nodejs is not on your system you will get this error:

  

  • download nodejs if it is not run in admin mode you will get this:

  

  • if this is the case, run an administrator command prompt and run the downloaded .msi file as follows:

  

  • after succesful install of nodejs run ☑️ or ➡️ again. It might be needed to rebuild node_modules and package-lock.json if you see this

  

  • Remove node_modules and package-lock.json - run as administrator if the OS complains!
  • Rebuild node_modules and package-lock.json by opening a VSCode shell using [>_] in the statusbar

    cd interface 
    npm install
    

  • If that give errors set execution policies as follows:

  

  • Press run ☑️ or ➡️ again it should now complete succesfully

  

• MacOS

  • Go to nodejs download
  • Get a prebuilt Node.js® for macOS running a ARM64 architecture (for modern Mx MacBooks)
  • Choose maxOS Installer (.pkg)
  • Next Next Finish Done
  • Press run ☑️ or ➡️ again it should now complete succesfully (if needed restart VSCode)
  • If still errors, Remove node_modules and package-lock.json, cd interface, npm install and repeat previous step

Ignore DragDropList error

This error will show up in the logging

node_modules/svelte-dnd-list/DragDropList.svelte (595:3): Error when using sourcemap for reporting an error: Can't resolve original location of error.

Just ignore it.

• Check serial output

  

• Go to development for further info on developing MoonBase / MoonLight functionality.

UI development server

To ease the frontend 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 ESP32 is required to test updated UI. Svaing an 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 web 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-5-9-3_webflash.bin
  

• optionally add erase-flash before write-flash
• use ./build/release/MoonLight_esp32-s3-devkitc-1-n16r8v_0-5-9-3.bin and address 0x10000 to flash only the MoonLight partition

Troubleshooting

• In general: first close and restart VSCode and run ☑️ or ➡️ again.
• python > 3.10: install python (3.11.13) in the VSCode shell (not in a normal os terminal)
• esptool.py not downloaded: deinstall platformIO IDE and install pioarduino IDE extensions (required for support of latest esp-idf 5.5)
• Run everything from within VSCode, close any alternative / external tools which (potentially) access esp32 devices. They can claim resources or send commands to the device which interfere with what we trying to accomplish here.
• Set WWWData.h right
  • Open platformIO new terminal (>_)
  • touch ./interface/src/app.html (or windows variant?) so the build process will be triggered to create a new WWWData.h
  • build the project (✔)
  • check in your github manager (gitkraken of github desktop) that a new WWWData.h is created
• If the ESP32 device AP is not showing up in your WiFi list it might be helpful to fully erase the ESP32 device before flashing (VSCode 👽, Erase flash)
• Sometimes the Serial log may show: [5817][W][WiFiGeneric.cpp:1408] setTxPower(): Neither AP or STA has been started. This is from setTxPower in APSettingsService. Delay has been added to prevent this.