Skip to content

Installation

MoonLight Web installer

Install Moonlight onto an ESP32 microcontroller using the MoonLight Web installer

Step 1: Get an ESP32 and a WS2812 LED-strip or LED-panel. See Hardware.

Step 2: Connect the ESP32 via USB

Step 3: Go to the MoonLight Web Installer. Select your ESP32-device, or if not listed, press others.

Browser support

The Web Installer works on Google Chrome or Microsoft Edge or similar browsers, not on Safari.

Step 4: Connect to the ESP32-device

Step 5: Select Install MoonLight

Screenshot 2025-06-07 at 20 54 31

Step 6: Optionally erase the ESP32-device

Erase

Erase if you have a new ESP32-device or want to start fresh. Do not erase if you want to update an existing MoonLight installation. Erase deletes all settings and requires to re-connect to MoonLight.

Step 7: Confirm and install

Step 8: Optionally Press Logs and Console

Screenshot 2025-06-07 at 20 57 54

Logging

You can see the serial logging of the ESP32-device. In case you see nothing you can press reset device, now you should see the logging.

Connect MoonLight

Step 1: Make a WiFi connection to the ESP32-device, it should present itself in the list of WiFi access points of your computer, phone or tablet.

Step 2: After connecting, MoonLight will show up in a web browser (all browsers supported). You will see this screen, select WiFi Station.

  • The device will show in 'Captive portal' mode. Alternatively you can close the captive portal and show it in a browser using http://4.3.2.1

UI not showing when installing new version of MoonLight

If you ran previous versions of MoonLight, the UI might not show up if it has been changed since then. In this case it is needed to reload the UI from the ESP32-device (use http://4.3.2.1)

  • Chrome: Command Shift R (Mac) or Ctrl Shift R or Control Reload (Windows)
  • Safari: Reload from Origin : Option Shift R

  • After this not all UI elements might be immediately visible. If you see 'MoonLight loading ...' in the browser, just wait a bit (☕️)

  • Sometimes it migh be needed to clear the browser cache:

Step 3: Enter your local WiFi network credentials and hostname:

Hostname

The hostname will be used to access your device. E.g. if the hostname is ML-home you can access it using http://ml-home.local

Step 4: Press Add Network and apply settings. After connecting to your normal WiFi network you will see this screen showing the new IP address of your MoonLight ESP32-device.

Step 5: When connected to your local WiFi network, enter the IP address of the new device. Alternatively enter the hostname.

Using hostname

  • Restart the device to make the hostname known to your network (go to system status, scroll down and press restart)
  • Enter the hostname in your browser e.g. http://ml-home.local

reload UI

See step 2 ⚠️ if UI is not showing up, use http://ml-home.local (replace ml-home with the hostname) or the IP address.

Setup MoonLight

Step 1: Add an effect

Step 2: Add a layout and set pin(s)

  • Add a layout Node by pressing the blue + button and select on off the 🚥 options (Panel 🚥 is a safe bet to start with). Scroll down to the Pin Control field and enter the pin number(s) you connected the strip or panel to.

Monitor

The Monitor should now show the effect

Step 3: Add a driver

  • Add a driver node by pressing the blue + button and select one of the ☸️ options.

Strip or panel

The LEDs on your strip or panel should now show the effect

Choose driver

FastLED driver is best to start with if you have a normal (ws2812) LED strip or panel. Choose the Physical driver if you have more then 4 LED strips or panels or non standard LEDS (e.g. RGBW lights, curtains...). Other drivers (Virtual, Hub,) not supported yet. In some cases restart the device to make layout changes effective is needed.

Step 4: Press save (💾). Saves your setup to the file system, so if a device is restarted, your settings are still there.

Next steps

  • You can now change effect or add effects, modifiers, layouts and drivers
  • Go to MoonLigh Overview
  • press the ? in MoonLight to go directly to the relevant page

Update MoonLight