Skip to content

Installation

The development environment consists of

  • VSCode

    • Platformio IDE
    • nodejs
    • git
    • python

  • Github manager

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

Summary

  • Fork the MoonLight repo and download
  • Install VSCode with the platformIO IDE extension
  • Open MoonLight in VSCode.
  • Build or upload to an ESP32 device.

Fork and Download

Step 1: Create a fork

* Login to your own github account
* Fork: go to [MoonModules/MoonLight](https://github.com/MoonModules/MoonLight/) and press Fork, uncheck 'Copy the main branch only' and press Create Fork. You will be moved to your fork of MoonLight

Step 2: 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 https://github.com//MoonLight.git and paste in the URL field of GitKraken
    • Press clone the repo

    • The main branch will be checked out per default. Latest development will be done in branches from main, merged back into main when done.

Install and setup VSCode

Step 1: Download Visual Studio Code

Step 2: Install PlatformIO IDE

  • 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 3: * Open the downloaded MoonLight repository

Build and upload

Step 1: Build

  • Press ☑️ in the bottom statusbar

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

Step 2: 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 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)

Step 3: Connect to MoonLight

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

  • If you are developing or updating existing MoonLight installations MoonLight might be outdated or not show up correctly in the browser or not even appear. Two reasons

    • Sometimes the latest front-end code is not generated yet (WWWData.h). This is how to set it right:

      • Open platformIO new terminal (>_)
      • touch ./interface/src/app.html so the build process will be triggered to create a new WWWData.h
      • build the project (✔) - if nodejs is not installed (yet) you will get errors. See troubleshooting
      • check in your github manager (gitkraken of github desktop) that a new WWWData.h is created

    • An old version is cached in the browser. See UI not showing when installing new version of MoonLight how to solve that.

  • 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

Troubleshooting

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

Git install

  • 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

Python and LZMA

MacOS: Python and LZMA

In some cases LZMA support must be installed

Screenshot 2025-09-29 at 13 58 07

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

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

Install nodejs

nodejs is needed if changes on the front-end (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:

    Screenshot 2025-09-25 212255

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

    Screenshot 2025-09-25 212842

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

    Screenshot 2025-09-25 220442 Screenshot 2025-09-25 214052

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

    Screenshot 2025-09-25 214700

    • 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:

    Screenshot 2025-09-25 215039

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

    Screenshot 2025-09-25 220023

  • 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.

Other troubles

  • 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.
  • 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.