Skip to content

Add node mutex #103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ewowi merged 4 commits into from
Jan 12, 2026
Merged

Add node mutex #103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b9cea1b
Add node mutex around onUpdate, onSizeChanged, onLayout and loop
ewowi Jan 11, 2026
35e87d3
nodeMutex per node
ewowi Jan 12, 2026
336af74
Monitor without _accessMutex lock 💫, throttled slider updates
ewowi Jan 12, 2026
9db9dc5
Final changes
ewowi Jan 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 28 additions & 9 deletions docs/develop/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,15 @@ MoonLight uses a multi-core, multi-task architecture on ESP32 to achieve smooth
|------|------|----------|------------|-----------|---------|
| **WiFi/BT** | 0 (PRO_CPU) | 23 | System | Event-driven | System networking stack |
| **lwIP TCP/IP** | 0 (PRO_CPU) | 18 | System | Event-driven | TCP/IP protocol processing |
| **ESP32SvelteKit** | 0 (PRO_CPU) | 2 | System | 10ms | HTTP/WebSocket UI framework |
| **ESP32SvelteKit** | 1 (APP_CPU) | 2 | System | 20ms | HTTP/WebSocket UI framework |
| **Driver Task** | 1 (APP_CPU) | 3 | 3-4KB | ~60 fps | Output data to LEDs via DMA/I2S/LCD/PARLIO |
| **Effect Task** | 0 (PRO_CPU) | 3 | 3-4KB | ~60 fps | Calculate LED colors and effects |

Effect Task (Core 0, Priority 3)

- **Function**: Pure computation - calculates pixel colors based on effect algorithms
- **Operations**: Reads/writes to `channels` array, performs mathematical calculations
- **Tolerant to preemption**: WiFi interruptions are acceptable as this is non-timing-critical
- **Tolerant to preemption**: WiFi interruptions are acceptable as this is non-timing-critical and we have a double buffer
- **Why Core 0**: Can coexist with WiFi; uses idle CPU cycles when WiFi is not transmitting

Driver Task (Core 1, Priority 3)
Expand All @@ -32,7 +32,7 @@ ESP32SvelteKit Task (Core 1, Priority 2)

- **Function**: HTTP server and WebSocket handler for UI
- **Operations**: Processes REST API calls, WebSocket messages, JSON serialization
- **Runs every**: 10ms
- **Runs every**: 20ms
- **Why Core 1, Priority 2**: Lower priority than system Tasks

## Task Interaction Flow
Expand Down Expand Up @@ -69,6 +69,29 @@ sequenceDiagram
DriverTask->>LEDs: Pixel data
```

HTTPP task

* no assigned core (OS decides), prio 5
* processes WebUI / Websockets
* calls ModuleState read() and update() functions
* MoonLight Modules: runs Modules::compareRecursive and Modules::checkReOrderSwap which calls postUpdate which presents a semaphore-guarded updatedItem (updateProcessedSem, updateReadySem)
* Page refresh: runs onLayout pass 1 for the monitor

SvelteKit task

* Module::loop() runs in the SvelteKit task and calls getUpdate() to retrieve the updatedItem in a synchronized way, getUpdate() calls processUpdatedItem()
* processUpdatedItem() calls Module::onUpdate(), which is a virtual function which is overridden by Modules to implement custom functionality
* NodeManager::onUpdate() propagates onUpdate() to Node Controls (together with Node::updateControl()), guarded by nodeMutex

Driver Task

* PhysicalLayer::loopDrivers(): if requestMap call mapLayout(). mapLayout() calls onLayout(), guarded by nodeMutex
* PhysicalLayer::loopDrivers(): Node::onSizeChanged() and Node::loop() guarded by nodeMutex

Effect Task

* PhysicalLayer::loop() calls VirtualLayer::Loop(): Node::onSizeChanged() and Node::loop(), guarded by nodeMutex

## Core Assignments

Why This Configuration is Optimal
Expand Down Expand Up @@ -278,16 +301,14 @@ For big setups, 16K LEDs typically, Task watchdog got triggered crashes occur mo
void effectOrDriverTask(void* pvParameters) {
// 🌙
esp_task_wdt_add(NULL);

setup();

while (true) {

loop();

esp_task_wdt_reset();
loop();
vTaskDelay(1);
}

Comment on lines 306 to +311
Copy link

@coderabbitai coderabbitai bot Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Code example doesn't match the description.

The code shows esp_task_wdt_reset() being called before loop(), but the AI summary states it was moved to occur "after loop() execution." If the intent is to reset the watchdog after the loop completes, the code should be:

📝 Suggested fix if watchdog reset should be after loop 
   while (true) {
-    esp_task_wdt_reset();
     loop();
+    esp_task_wdt_reset();
     vTaskDelay(1);
   }

Otherwise, update the surrounding documentation to clarify the current behavior.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
while (true) {
loop();
esp_task_wdt_reset();
loop();
vTaskDelay(1);
}
while (true) {
loop();
esp_task_wdt_reset();
vTaskDelay(1);
}
🤖 Prompt for AI Agents 
In @docs/develop/architecture.md around lines 306 - 311, The code sample calls
esp_task_wdt_reset() before loop(), but the documentation text says the watchdog
reset occurs after loop() — fix by making code and prose consistent: either move
the esp_task_wdt_reset() call to after loop() (update the while(true) body
around loop(), esp_task_wdt_reset(), then vTaskDelay(1)) if you want the reset
to happen post-loop, or update the surrounding documentation to state that
esp_task_wdt_reset() is called before loop() and describe the implications;
refer to the loop(), esp_task_wdt_reset(), vTaskDelay(), and the while(true)
loop in the example when applying the change.

// Cleanup (never reached in this case, but good practice)
esp_task_wdt_delete(NULL);
}
Expand All @@ -309,8 +330,6 @@ inline void addYield(uint8_t frequency) {
vTaskDelay(1);
}
}


```

* esp_task_wdt ( #include "esp_task_wdt.h" ) make sure the tasks are in the watchdog system and in the task loop it is reset and vTaskDelay(1) makes sure there is a yield each time
Expand Down
107 changes: 66 additions & 41 deletions docs/gettingstarted/installer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,39 @@
# MoonLight Installer

Install <a href="https://github.com/MoonModules/MoonLight" target="_blank">MoonModules/MoonLight</a> on an ESP32 microcontroller. You need a compatible browser like Chrome, or Edge, not supported on Safari.
Install <a href="https://github.com/MoonModules/MoonLight" target="_blank">MoonModules/MoonLight</a> on an ESP32 microcontroller.
You need a Web Serial–compatible browser such as **Chrome** or **Edge**. **Safari is not supported.**

For devices which have already MoonLight installed, go to [Update](#update-moonlight)
For devices that already have MoonLight installed, go to [Update](#update-moonlight).

<a href="https://www.youtube.com/watch?v=7DQOEWa-Kwg">
<img width="380" src="https://img.youtube.com/vi/7DQOEWa-Kwg/maxresdefault.jpg" alt="Watch MoonLight Demo">
</a>

**[▶️ Watch the install tutorial](https://www.youtube.com/watch?v=7DQOEWa-Kwg)** (v0.6.0) or follow the instructions below
**[▶️ Watch the install tutorial](https://www.youtube.com/watch?v=7DQOEWa-Kwg)** (v0.6.0), or follow the instructions below.

## Prepare an ESP32 device
## Prepare an ESP32 device

See [Hardware](../hardware)
Recommended device to get started with: [QuinLED-dig2go](https://quinled.info/quinled-dig2go/)

Recommended device to get started: [QuinLED-dig2go](https://quinled.info/quinled-dig2go/)
![Dig2Go](https://shop.allnetchina.cn/cdn/shop/products/Led_4.jpg?v=1680836018&width=1600){: style="width:250px"}

![Dig2Go](https://shop.allnetchina.cn/cdn/shop/products/Led_4.jpg?v=1680836018&width=1600){: style="width:250px"}
See [Hardware](../hardware) for other options.

Connect the device via a USB cable (which supports data transfer) to your PC.
Connect the device to your PC using a USB cable that **supports data transfer**.

## Flash the firmware

<script type="module" src="https://unpkg.com/esp-web-tools@10/dist/web/install-button.js?module"></script>

Select your ESP32-device from the table below, press the corresponding **Connect** button and follow the steps. Your device should show up in this list. Press the **Erase** checkbox when installing MoonLight for the first time. After succesful install, go to Logs & Console, press **Restart** and close the installer.
Select your ESP32 device from the table below, press the corresponding **Connect** button, and follow the steps.
Your device should appear in the list.

When installing MoonLight for the **first time**, enable the **Erase** checkbox.
After a successful install, go to **Logs & Console**, press **Reset Device**, and close the installer.

!!! info "Bootloader mode"
If install doesn't work: some boards have to be placed in bootloader mode the first time: press and hold the `Boot` button on the ESP32, press the `Reset` button on the ESP32 and then release the `Boot` button.
If installation does not work, some boards must be placed into bootloader mode the first time:
press and hold the `Boot` button on the ESP32, press the `Reset` button, then release the `Boot` button.

| Name | Image* | Flash | Shop & Board presets |
|------|--------|-------|----------------------|
Expand All @@ -37,7 +43,7 @@ Select your ESP32-device from the table below, press the corresponding **Connect
| esp32-s3-n16r8v | ![esp32-s3-n16r8v](../firmware/installer/images/esp32-s3-n8r8v.jpg){: style="width:100px"} | <esp-web-install-button manifest="https://moonmodules.org/MoonLight/firmware/installer/manifest_esp32-s3-n16r8v.json"></esp-web-install-button> | [Ali*](https://s.click.aliexpress.com/e/_DBAtJ2H){:target="_blank"} |
| esp32-s3-atoms3r | ![esp32-s3-atoms3r](../firmware/installer/images/esp32-s3-atoms3r.jpg){: style="width:100px"} | <esp-web-install-button manifest="https://moonmodules.org/MoonLight/firmware/installer/manifest_esp32-s3-atoms3r.json"></esp-web-install-button> | [M5Stack store](https://shop.m5stack.com/products/atoms3r-dev-kit){:target="_blank"} |
| esp32-s3-zero-n4r2 | ![esp32-s3-zero-n4r2](../firmware/installer/images/esp32-s3-zero-n4r2.jpg){: style="width:100px"} | <esp-web-install-button manifest="https://moonmodules.org/MoonLight/firmware/installer/manifest_esp32-s3-zero-n4r2.json"></esp-web-install-button> | [Ali*](https://s.click.aliexpress.com/e/_EukjHX8){:target="_blank"} |
| esp32-p4-nano | ![esp32-p4-nano](../firmware/installer/images/esp32-p4-nano.jpg){: style="width:100px"} | install [esp32-c6-firmware-update](https://esp32-c6-firmware-update.github.io) first <br><esp-web-install-button manifest="https://moonmodules.org/MoonLight/firmware/installer/manifest_esp32-p4-nano.json"></esp-web-install-button> | [Waveshare](https://www.waveshare.com/esp32-p4-nano.htm){:target="_blank"} <br>[ESP32-P4 shield](https://shop.myhome-control.de/en/ABC-WLED-ESP32-P4-shield/HW10027):<br>![ESP32-P4 shield](https://shop.myhome-control.de/thumbnail/ed/a1/f1/1762031307/WLED_ESP32_P4_Shield_04_1920x1354.jpg?ts=1762031316){: style="width:100px"} |
| esp32-p4-nano | ![esp32-p4-nano](../firmware/installer/images/esp32-p4-nano.jpg){: style="width:100px"} | Install [esp32-c6-firmware-update](https://esp32-c6-firmware-update.github.io) first<br><esp-web-install-button manifest="https://moonmodules.org/MoonLight/firmware/installer/manifest_esp32-p4-nano.json"></esp-web-install-button> | [Waveshare](https://www.waveshare.com/esp32-p4-nano.htm){:target="_blank"}<br>[ESP32-P4 shield](https://shop.myhome-control.de/en/ABC-WLED-ESP32-P4-shield/HW10027):<br>![ESP32-P4 shield](https://shop.myhome-control.de/thumbnail/ed/a1/f1/1762031307/WLED_ESP32_P4_Shield_04_1920x1354.jpg?ts=1762031316){: style="width:100px"} |
| esp32-d0-wrover | ![esp32-d0-wrover](../firmware/installer/images/esp32-d0-wrover.jpg){: style="width:100px"} | <esp-web-install-button manifest="https://moonmodules.org/MoonLight/firmware/installer/manifest_esp32-d0-wrover.json"></esp-web-install-button> | [Ali*](https://a.aliexpress.com/_EzhPi6g){:target="_blank"} |
| esp32-p4-olimex | ![esp32-p4-olimex](../firmware/installer/images/esp32-p4-olimex.jpg){: style="width:100px"} | <esp-web-install-button manifest="https://moonmodules.org/MoonLight/firmware/installer/manifest_esp32-p4-olimex.json"></esp-web-install-button> | [Olimex](https://www.olimex.com/Products/IoT/ESP32-P4/ESP32-P4-DevKit/open-source-hardware){:target="_blank"} |
| esp32-c3 | ![esp32-c3](../firmware/installer/images/esp32-c3.jpg){: style="width:100px"} | <esp-web-install-button manifest="https://moonmodules.org/MoonLight/firmware/installer/manifest_esp32-c3.json"></esp-web-install-button> | [Ali*](https://s.click.aliexpress.com/e/_EIl7NKw){:target="_blank"} |
Expand All @@ -54,95 +60,114 @@ Install steps in pictures:

## Setup MoonLight

A new MoonLight device will show itself as a WiFi Access Point (AP) in the WiFi settings of your PC, tablet or smartphone. The name starts with ML- and 4 characters.
A new MoonLight device will appear as a WiFi Access Point (AP) in the WiFi settings of your PC, tablet, or smartphone.
The name starts with `ML-` followed by four characters.

<img width="200" src="https://github.com/user-attachments/assets/9a146e3c-1a53-4906-ad2a-d70215efcf4b" />

Select ML-xxxx, MoonLight will start in a browser:
Select `ML-xxxx`. MoonLight will open in your browser:

<img width="350" src="../../media/moonlight/ML-Start.png"/>

Follow the steps:
Follow the steps below.

### WiFi connection

Add a [WiFi](../../network/sta) connection
Add a [WiFi](../../network/sta) connection.

<img width="350" src="../../media/network/MB-WiFi2.png"/>

Enter a hostname, add your WiFi by adding the (+) button, enter SSID and password and press Apply Settings.
Enter a hostname, add your WiFi network using the (+) button, enter the SSID and password, and press **Apply Settings**.

Restart the device by pressing the boot button or simple unplug and plug the usb cable.
Restart the device by pressing the boot button, or simply unplug and reconnect the USB cable.

Go back to your home WiFi open a browser and enter hostname.local to open MoonLight via the new WiFi connection.
Reconnect to your home WiFi, open a browser, and go to `hostname.local` to access MoonLight via the new WiFi connection.

### IO Board Presets

Select your board in [Module IO](../../moonbase/inputoutput), if you have one of the premade boards supported (see above table), select this. If not sure, leave it as is.
Select your board in [Module IO](../../moonbase/inputoutput).
If you have one of the supported premade boards (see table above), select it.
If you are unsure, leave the default settings.

<img width="320" height="441" src="../../media/moonbase/inputoutput.png" />

Make sure the defined LED pin(s) are the same as the physical connections on the ESP32 board.
Ensure the configured LED pin(s) match the physical connections on your ESP32 board.

### Drivers

The drivers module contains [Layouts](../../moonlight/layouts) and [Drivers](../../moonlight/drivers).
The Drivers module contains [Layouts](../../moonlight/layouts) and [Drivers](../../moonlight/drivers).

Layouts define how your LEDs are arranged. Add a layout first, Press (+)
Layouts define how your LEDs are arranged.
First, add a layout by pressing (+).

<img width="320" src="../../media/moonlight/layouts/PanelLayout.png"/>

For LED strips, choose Single Column, for Panels choose Panel(s) or other layouts. Layouts are recognized by 🚥. Enter the size of your LEDs
For LED strips, choose **Single Column**.
For panels, choose **Panel(s)** or another suitable layout.
Layouts are indicated by 🚥. Enter the size of your LED setup.

Next add a LED driver by pressing the (+) button and select the Physical LED driver or FastLED driver. Drivers are recognized by ☸️
Next, add an LED driver by pressing (+) and selecting either the **Physical LED driver** or **FastLED driver**.
Drivers are indicated by ☸️.

<img width="350" src="https://github.com/user-attachments/assets/e7fab24f-3803-4aa5-8638-459cca8a9caf" />

### Effect

The Effects module contains [Effects](../../moonlight/effects) and [Modifiers](../../moonlight/modifiers). Start by adding one effect, press (+)
The Effects module contains [Effects](../../moonlight/effects) and [Modifiers](../../moonlight/modifiers).

Start by adding an effect using the (+) button.

<img width="350" src="https://github.com/user-attachments/assets/2c8a8b75-c429-4038-a5af-adc82b11c9de" />

The effect should be visible on the Monitor in MoonLight and on your LEDs
The effect should now be visible in the MoonLight monitor and on your LEDs.

<img width="320" src="../../media/moonlight/effects/LissajousShot.png"/>

### Save and next steps

Press save (💾). Saves your setup to the file system, so if a device is restarted, your settings are still there.
Press **Save** (💾).
This stores your configuration on the device, so your settings persist after a reboot.

If anything not working as expected, log an issue on GitHUB or contact us on Discord, Reddit or YouTube. See also [Installer troubleshooting](../../develop/installation/#moonlight-installer) and [USB-to-serial chip drivers](../../develop/installation/#usb-to-serial-chip-drivers)
If something does not work as expected, log an issue on GitHub or contact us via [Discord](https://discord.gg/TC8NSUSCdV), [Reddit](https://reddit.com/r/moonmodules) or [YouTube](https://www.youtube.com/@MoonModulesLighting).
See also [Installer troubleshooting](../../develop/installation/#moonlight-installer) and [USB-to-serial chip drivers](../../develop/installation/#usb-to-serial-chip-drivers).

!!! info "Next steps"
* You can now change effect or add effects, modifiers, layouts and drivers
* Go to [MoonLight Overview](../../moonlight/overview) to learn more
* press the (?) in MoonLight to go directly to the relevant page
* You can now change or add effects, modifiers, layouts, and drivers
* Visit the [MoonLight Overview](../../moonlight/overview) to learn more
* Press (?) in MoonLight to jump directly to the relevant documentation page

## Update MoonLight

MoonLight releases new versions regularly. As it is a new and growing platform it is recommended to update as soon as new releases are published. They can be installed via above procedure (without erase) or via one of the following procedures:
MoonLight releases new versions regularly.
As this is a new and growing platform, it is recommended to update as soon as new releases are published.

Updates can be installed using the installer above (without erasing), or via one of the methods below.

### System update

The preferred way to update MoonLight is directly in MoonLight via [System update](../../system/update). MoonLight notifies when new versions are available.
The preferred way to update MoonLight is directly within MoonLight via [System update](../../system/update).
MoonLight will notify you when new versions are available.

<img width="350" src="https://github.com/user-attachments/assets/523ea32f-88f8-4994-8d23-9541dce67ba1" />

Currently not supported on smaller devices like the ESP32-D0 and ESP32-C3. Use the MoonLight Installer in this case.
This method is currently not supported on smaller devices such as the ESP32-D0 and ESP32-C3.
Use the MoonLight Installer instead for these devices.

### ESPConnect

Use ESPConnect to install unreleased firmware e.g. provided via [discord](https://discord.gg/MTn9mVUG5n) or GitHub issues. Published [releases](https://github.com/MoonModules/MoonLight/releases) can also be installed via this way.
Use ESPConnect to install unreleased firmware (for example, versions shared via [Discord](https://discord.gg/TC8NSUSCdV) or [GitHub issues](https://github.com/MoonModules/MoonLight/issues)).
Published [releases](https://github.com/MoonModules/MoonLight/releases) can also be installed this way.

Launch [ESPConnect](https://thelastoutpostworkshop.github.io/microcontroller_devkit/espconnect)
Launch [ESPConnect](https://thelastoutpostworkshop.github.io/microcontroller_devkit/espconnect).

<img width="400" src="https://github.com/user-attachments/assets/3b702b3e-62cc-4330-83f6-d473067df449" />

Click Connect and choose your device. Select Flash Tools, go to Flash Firmware, open a firmware.bin file from your file system, select Flash Offset App0 and Flash.

### Visual Studio code
Click **Connect** and select your device.
Choose **Flash Tools**, go to **Flash Firmware**, open a `firmware.bin` file from your file system, select **Flash Offset App0**, and click **Flash**.

### Visual Studio Code

For developers. Upload directly from VSCode, see [Develop / Installation](../../develop/installation)
For developers: upload firmware directly from VS Code.
See [Develop / Installation](../../develop/installation).

*: This page contains affiliate links
\*: This page contains affiliate links
2 changes: 1 addition & 1 deletion docs/moonlight/effects.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ These effects have first been created in MoonLight:
| Praxis | ![Praxis](https://github.com/user-attachments/assets/f9271d1c-bcd1-4a79-bc1a-cac951758195) | <img width="320" alt="Praxis" src="https://github.com/user-attachments/assets/536ab4c8-5c90-4b76-9f80-2aaed4170901" />| |
| Wave | ![Wave](https://github.com/user-attachments/assets/a699f3a6-c981-4159-a96e-85d43c9a853c) | <img width="320" alt="Wave" src="https://github.com/user-attachments/assets/2e8408e8-4610-45dd-af36-8560fe5ec024" /> | Type: Saw, Triangle, Sinus, Square, Sin3, Noise |
| Fixed Rectangle | <img width="120" alt="Rectangle" src="https://github.com/user-attachments/assets/474bd313-d961-4a95-8e44-015539a0ba7f" /> | <img width="320" alt="RectangleC" src="https://github.com/user-attachments/assets/e9c1fca4-d7a2-42f4-9d23-643371b3c615" /> | To test a layout |
| Star Sky | ![lines](../../media/moonlight/effects/starsky.gif) | ![lines](../../media/moonlight/effects/starskycontrols.png) | tip: add the rotate modifier |
| Star Sky | ![lines](../../media/moonlight/effects/StarSky.gif) | ![lines](../../media/moonlight/effects/StarSkyControls.png) | tip: add the rotate modifier |

### MoonModules effects

Expand Down
Loading