Flockinator - a microscope for emergent behaviour

Build one panel node

Think of one node as one rescue signpost that can light up, make sound, and remember what it showed. Build one well, and you can repeat it to make a wall that helps teams practice rescue signals.

This guide builds a single working node. Read it end to end before you plug anything in.

What One Node Is

One node is a small controller board paired with one square light panel.

The controller handles the picture, sound cues, and local sensing. The panel is what people across the room see. Each node also has its own memory card, so it can work as part of a larger shared display later.

In the full system, many panels join to show a shared virtual world for practice quadcopter visualisation. The scored research results are host replay, not measured on the panel itself.

Parts You Need

One complete node uses the parts below. Use exactly these types. For sellers, cable lengths, and card size, check the repo docs.

Related system parts, not part of this one-node build:

• Controller hub: ESP32-S31 Korvo with display/touch, for web host and practice sim
• Handheld viewer: LilyGo T5 4.7in ESP32-S3

CAD finished models for printed parts are in cad/.

Tools

For software, use Python via uv only, plus PlatformIO for the node build. The Korvo hub uses pinned ESP-IDF 6.1.

For hand tools, wire, and bench setup, check the repo docs. Do not substitute a different supply voltage.

Assemble the Node

Work with power off and give yourself clear table space.

1. Prepare the printed parts. Find the diffuser, speaker carriers, and mounts for one node. Check the repo docs for which finished model in cad/ matches your panel.
2. Fit controller to panel. Place the Waveshare board at the back of the 160 x 160 mm panel in the orientation shown in the docs. Check the repo docs for connector seating and fastener positions.
3. Insert the microSD card. Use one card per node. Push it fully into the node slot until it clicks. Check the repo docs for formatting and file layout.
4. Fit the speaker carriers. Place the perimeter speakers in their printed carriers around the edge. Check the repo docs for routing so wires stay clear of the panel back.
5. Check the fit. The panel should sit flat, the diffuser should sit even, and nothing should press on the controller. Check the repo docs for clearance photos.

Leave power disconnected until the power check below is done.

Power Safety

This system is 5V only.

• Use the MEAN WELL LRS-350-5 5V supply for bench power.
• Wire polarity correctly before first power-on. Check the repo docs for the wiring diagram.
• Plan for full-white brightness as your ceiling. Measure at brightness ceiling and keep within the documented limits — check the repo docs for test points and limits.
• If anything smells hot, looks dim in patches, or resets when brightness rises, switch off and recheck wiring. Check the repo docs for safe re-test steps.

Flash Node Firmware

Flashing loads the node program onto the controller.

1. Install Python tooling via uv only. Check the repo docs for the exact setup sequence.
2. From the repo root, run the node build:

```

pio run --project-dir firmware/node-platform -e waveshare-s3

```

1. Connect the Waveshare board over USB and flash using the documented upload target. Check the repo docs for the upload and monitor commands.
2. Wait for a clean finish with no errors before unplugging.

Notes:

• Handheld builds use lilygo-s3. Check the repo docs if you are building that separately.
• Korvo hub builds use pinned ESP-IDF 6.1. Check the repo docs for that separate flow.

Provision Identity

Each device gets its own private identity so logs and later reviews can tell nodes apart.

1. Run the provision tool privately, one device at a time:

- tool path: tools/node-commissioner

1. Follow the prompts to create the per-device identity. Check the repo docs for where identities are stored and what to keep private.
2. Label the physical node to match its identity. Check the repo docs for the naming pattern.

Do not copy one node's identity to another node.

First-Light Test: READY

This confirms panel, controller, card, and power are working together.

1. Confirm wiring matches the 5V diagram. Check the repo docs for the final checklist.
2. Switch on the 5V supply.
3. Watch the 64x64 panel. A good first build shows READY.
4. Listen for speaker output if your test image enables sound. Check the repo docs for which test enables audio.
5. Switch off, then add the diffuser and recheck brightness. Measure at brightness ceiling again after any housing change.

If you do not see READY, leave power off and use the next section.

Common Failures

Fix one thing at a time. For exact photos and meter points, check the repo docs.

• Panel stays dark: recheck 5V wiring, seating, and firmware target — check the repo docs.
• READY never appears but board lights respond: recheck microSD seating and firmware flash logs — check the repo docs.
• Resets at high brightness: supply or wiring is at its limit, measure at brightness ceiling — check the repo docs.
• No sound or rattling sound: recheck speaker carriers and seating — check the repo docs.
• Wrong device name in logs: re-run identity provisioning privately with tools/node-commissioner — check the repo docs.

Scaling From 1 to 16

Once one node reliably shows READY, you can repeat the build to form a panel wall.

• Plan a regular grid of up to 16 identical nodes.
• Pitch candidates under review are 250 mm and 199.8 mm. Check the repo docs for which drawings, mounts, and diffuser spacing match each pitch.
• Split power into branches rather than daisy-chaining everything from one point. Check the repo docs for branch layout for the MEAN WELL LRS-350-5 5V supply.
• Provision identity separately for each new node with tools/node-commissioner.
• Re-run the READY test node by node, then as a group. Check the repo docs for group test order and brightness ceiling measurements.

Source in the repo

• firmware/node-platform — node firmware and waveshare-s3 build environment
• tools/node-commissioner — per-device private identity provisioning
• cad/ — finished models for Bambu PLA diffusers, carriers, and mounts