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), 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.

Credentials are saved to the device and survive reflashing.

Network module docs: NetworkModule · WifiStaModule · WifiApModule · EthernetModule

→ Network and WiFi test coverage

Option B — Run on PC¶

Step 1 — Build¶

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

Step 2 — Run¶

deploy/build/pc/projectMM

Step 3 — 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