Skip to content

MoonLight Installation

Install Moonlight onto an ESP32 using the MoonLight Web installer

  • Step 1: Get an ESP32 or ESP32-S3 (preferred, support large setups and Live Scripts). Boards we use are ESP32 or ESP32-S3, but most of the ESP32 and ESP32-S3 boards will work. Get a WS2812 LED-strip or a LED-panel (preferred to see 2D effects). Connect the strip or panel to the board on a suitable pin (e.g. Pin 2 or 16).

  • Step 2: Connect an ESP32(-S3) via USB

  • Step 3: Click this link to go to the web installer: ESP Web Installer for MoonLight v0.5.6. The Web Installer works on Google Chrome or Microsoft Edge or similar browsers. Safari does not support installing things on ESP devices. Driver software might be needed to have the webinstaller recognise the board. The installer detects the board automatically. If you try to install and no boards are detected, a screen will popup inviting you to install the driver. Press Connect. You should see the ESP32 board (if not sure disconnect and connect and see which serial port is used):

Screenshot 2025-06-07 at 20 54 17

  • Step 4: Connect to the board, then select Install MoonLight

Screenshot 2025-06-07 at 20 54 31

  • Step 5: Choose to erase the board first or not. Erase if you have a new board 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 WiFi.

Screenshot 2025-06-07 at 20 54 42

  • Step 6: Confirm and install

Screenshot 2025-06-07 at 20 54 51 Screenshot 2025-06-07 at 20 55 00 Screenshot 2025-06-07 at 20 57 30

  • Step 7: Optionally Press Logs and Console

Screenshot 2025-06-07 at 20 57 54

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

  • Step 8: Make a WiFi connection to the board, it should present itself in the list of WiFi access points.

Screenshot 2025-06-07 at 20 58 22

  • Step 9: After connecting, MoonLight will show up in a web browser (all browsers supported). A new install will take some time to show up (up to a minute or sometimes 2). On some browsers, e.g. Safari, MoonLight pops up showing Connection to device lost repeatedly (bug). In that case, close this browser window and open MoonLight in a brower using 192.168.4.1 as URL. You will see this screen, select WiFi Station.

Screenshot 2025-06-07 at 20 59 19

  • Step 10: Enter your local WiFi network credentials:

Screenshot 2025-06-07 at 20 59 34

  • Step 11: Press Add Network and apply settings. After connecting to your local WiFi network you will see this screen showing the new IP address of your MoonLight board. If you don't know the IP address of your board anymore you can go to step 3 and 4 and step 7 and check the IP address in the Serial logging. Advanced tip: Use ESP32Instances to discover the ESP32 nodes on your network (using nodeJS and html)

Screenshot 2025-06-07 at 20 59 55

  • Step 12: Go to your WiFi settings and connect to your local WiFi network and enter the IP address of your MoonLight board in a browser and go to MoonLight Editor. Add a layout Node by pressing the blue + button and select Panel 🚥. Scroll down to the Pin Control field and enter the pin number you connected the strip or panel to in Step 1. After setting the right pin the strip or panel should show lights.

Screenshot 2025-06-07 at 21 01 02

  • That's it. You can now change effect nodes, or add nodes. For audio add the AudioSync node. More how to's will be added. At the moment:

    • Check the help pages on this documentation site, especially the editor page
    • press the ? in MoonLight to go directly to the relevant page More how to's will be added. At the moment:
    • Live scripts: how to run a live script

  • Made using esp-web-tools

  • See also ESP-Web-Tools-Tutorial