Getting Started¶

This guide takes you from a blank device (or a fresh PC build) to a running projectMM instance with a live LED preview in the browser. No coding required.

What you need¶

Target	Requirements
ESP32	ESP32 classic (D0) or S3 (P4 soon), USB cable, a computer with a browser
PC	macOS / Linux / Windows, CMake ≥ 3.16, a C++17 compiler, Git

Option A — Flash an ESP32¶

Step 1 — Get the firmware¶

From a release (recommended): download the latest .bin from the GitHub Releases page.

From source: follow the deploy guide then come back here.

Step 2 — Flash¶

Use ESP Web Tools (Chrome/Edge, no install required) or PlatformIO:

python3 deploy/flashfs.py      # all test:true ESP32 devices
python3 deploy/flashfs.py --wifi  # also inject WiFi credentials

Step 3 — Connect to the device's access point¶

On first boot, projectMM creates a Wi-Fi access point:

SSID: MM-XXXX (last 4 characters of the device MAC address)
Password: (none — open AP)

Connect your phone or laptop to this network.

Step 4 — Open the UI¶

Navigate to http://4.3.2.1 in your browser. You should see the projectMM control panel.

Step 5 — (Optional) Connect to your home Wi-Fi¶

In the module list, find the WifiStaModule card. Enter your home Wi-Fi SSID and password and press Enter. The device will connect and its IP address will appear in the WifiStaModule status field. You can then connect your browser to that IP instead of the AP.

Once STA is connected, the AP (MM-XXXX) is automatically disabled within 10 seconds. If STA drops for more than 30 seconds, the AP re-opens as a recovery path. Credentials are saved to the device and survive reflashing.

Network module docs: NetworkModule · WifiStaModule · WifiApModule · EthernetModule · Network developer guide

→ Network and WiFi test coverage

Option B — Run on PC¶

Step 1 — Download or build¶

From a nightly release (easiest): download the latest archive from the GitHub nightly release and extract it.

Platform	File
macOS	`projectMM-pc-macos.tar.gz`
Windows	`projectMM-pc-windows.zip`

From source:

git clone https://github.com/ewowi/projectMM.git
cd projectMM
uv run deploy/build.py -target pc

The binary is placed at deploy/build/pc/macos/projectMM (macOS/Linux) or deploy/build/pc/windows/projectMM.exe (Windows).

Step 2 — First launch: security warning¶

Downloaded binaries are unsigned, so the OS will warn you on first run.

macOS: open System Settings, go to Privacy & Security, scroll to the bottom and click Allow Anyway next to the projectMM entry. Alternatively, run in Terminal:

xattr -d com.apple.quarantine projectMM-pc-macos

Windows: when SmartScreen blocks the exe, click More info then Run anyway.

Step 3 — Run¶

# macOS / Linux (extracted nightly)
./projectMM-pc-macos

# macOS / Linux (built from source)
deploy/build/pc/macos/projectMM

# Windows (extracted nightly)
projectMM-pc-windows.exe

Step 4 — Open the UI¶

Navigate to http://localhost (port 80) in your browser.

Step 6 — Add your first modules¶

A freshly booted device starts with an empty module list (or the network modules on ESP32). To see a live preview, add a standard pipeline:

Open the UI and click + (or use the REST API below).
Add a EffectsLayer (id: producer1, width: 16, height: 16).
Add a SineEffectModule (id: sine1, parent: producer1, input layer: producer1).
Add a DriverLayer (id: consumer1, input source: producer1).
Add a PreviewModule (id: preview1, parent: consumer1, input source: consumer1).

Or use the REST API (PC example):

curl -sX POST http://localhost/api/modules -H 'Content-Type: application/json' \
  -d '{"type":"EffectsLayer","id":"producer1","props":{"width":16,"height":16}}'

curl -sX POST http://localhost/api/modules -H 'Content-Type: application/json' \
  -d '{"type":"SineEffectModule","id":"sine1","parent_id":"producer1","inputs":{"layer":"producer1"}}'

curl -sX POST http://localhost/api/modules -H 'Content-Type: application/json' \
  -d '{"type":"DriverLayer","id":"consumer1","props":{"width":16,"height":16},"inputs":{"source":"producer1"}}'

curl -sX POST http://localhost/api/modules -H 'Content-Type: application/json' \
  -d '{"type":"PreviewModule","id":"preview1","parent_id":"consumer1","inputs":{"source":"consumer1"}}'

The configuration is saved automatically to state/modulemanager.json and survives restarts.

Verify live updates¶

Move the frequency slider on the SineEffectModule card — the WebGL preview should update immediately.
The WebSocket connection indicator (dot in the top bar) should be green.
The device name appears in the top bar (set it in the SystemStatusModule card).

Next steps¶

UI reference — all UI features explained
Modules overview — what each module does
API reference — REST + WebSocket reference for scripting and integration
Deploy guide — build from source, run tests, flash ESP32
FAQ — common questions about deployment, platforms, and external libraries