LightSwarm LED Systems

A LightSwarm rig drives lighting through one of two hardware systems. They differ in one thing — where the processing lives — and everything else (wiring, addressing, whether the LED can be cut to length) follows from that one difference.

The whole difference in one picture — where the processor sits:

The two systems side by side:

Every box that can appear on a LightSwarm rig, photographed from the actual kit. Two families — dumb drivers (the board does the thinking) and smart MOD-U-LED (the LED does) — plus the gateway and passive parts.

Dumb driver

MLS16

16-channel driver. Switches 16 passive LED loads; address set by Add-Hi/Add-Lo dials.

16 ch · LS bus · 38400 baud (bench)

Dumb driver

MLS40J

40-channel driver — the bigger MLS. Three of these run the Chalk Hill model (120 ch).

40 ch · LS bus · 115200 baud (Chalk Hill)

Smart driver

MOD-U-LED Interface

Drives the addressable smart-LED chain and sits on the bus as a control head. Internal fuse.

LS bus · drives daisy chain

Smart LED

MOD-U-LED Module

An LED with its own processor + stored address (yours are 989–992). Daisy-chains IN→OUT.

self-addressed · e.g. 989–992

Gateway

USB LS Bus Interface

Bridges a PC's USB to the LightSwarm serial bus. This is the port you open from the test panel.

USB → LS bus · RXD/TXD/PWR

Passive load

COB LED Strip

The "dumb" light — yellow-cover COB strip, no electronics. Cut to length, wired to an MLS output.

12V · cuttable · red=COM+ / black=ch

Passive wiring

Breakout Terminal

Fans an MLS board's IDC ribbon out to numbered screw terminals (COM+ / channels).

ribbon → screw terminals

Power

12V PSU

Feeds 12V to the boards (via +IN/GND) and the LED loads. Size it to the channel count.

12V DC · e.g. Mean Well 60W

The "dumb LED" system uses LED COB strips, identifiable by their yellow covers. The LEDs are passive; all the intelligence sits upstream in the driver board.

The MOD-U-LED system uses LEDs with an onboard processor, driven by the MOD-U-LED Interface. Because every LED is addressable in its own right, they can be daisy-chained on a single run.

Once you've identified a dumb-LED rig, this is what's actually driving each light. Because the intelligence is in the board, a light is identified by which board and which output it is wired to. Each MLS 16 board owns 16 contiguous addresses.

In code terms: addr = (mlsUnit − 1) × 16 + output. So output 0 on board 1 is addr 0; output 0 on board 2 is addr 16; and so on. The address map is the single source of truth for which physical light a given addr drives.

Two questions this raises

Two different rigs, both on the LightSwarm LS bus. Rig A is the bench demonstrator — one small dumb board plus the smart modules, side by side. Rig B is the Chalk Hill production setup — the same dumb-LED family scaled up to three 40-channel panels. Diagrams colour-coded by what each wire carries.

Rig A — Bench Demo

the real board · tap a number to find it in the list

1 2 3 4 5 6 7

1. 112V PSU ×2 — Mean Well + adapter. Power for everything.
2. 2USB LS Bus Interface — the only "brain link": PC USB → LightSwarm bus.
3. 3MOD-U-LED Interface — runs the smart side.
4. 4Smart modules 989–992 — MOD-U-LEDs, daisy-chained IN→OUT.
5. 5COB strips ×4 — the dumb LEDs (passive, cut to length).
6. 6Breakout terminal — ribbon fans MLS16's 16 outputs to screw terminals.
7. 7MLS16 — the dumb driver. All switching happens here.

Rig B — Chalk Hill FINAL

3× MLS40J panels · from the Chalk Hill control-points sheet

1 2 3 4 5 6

1. 1PANEL 1 — MLS40J — 40-channel dumb driver. Note the Add-Hi / Add-Lo dials set its address.
2. 2PANEL 2 — MLS40J — second 40-channel board.
3. 3PANEL 3 — MLS40J — third board → 120 channels total.
4. 4MOD-U-LED Interface — sits on the bus as the control head here.
5. 5USB LS Bus Interface — PC → bus, running at 115200 baud.
6. 6Power + bus wiring — red/black = 12V; white = the daisy-chained LS bus.

Worked example — how the system works, using Rig B

Chalk Hill is the clearest case to learn the whole system on: one control bus, three boards, 120 lights, all driven from a PC. Here's how an address becomes a lit light.

1. The address map

Each board's Add-Hi/Add-Lo dials set a base address; its 40 channels count up from there. Stagger the bases by 40 and the three panels tile a clean 0–119 with no overlap:

address = panel base + channel. So "Panel 2, channel 5" = 40 + 5 = 45. (Bases of 0/40/80 are an assumed convention — the real base is whatever each board's Add-Hi/Add-Lo dials are set to. Read the dials to know it, or light a test address and watch which unit responds.)

1b. The real port map — what each output drives

From the Chalk Hill control-points sheet. PORT is the output's label (1-based) — so Port 6 = channel 5. Panels 1–2 drive the apartment stack (floor-letter, e.g. 22-G = floor 22, unit G); Panel 3 finishes the apartments then the amenities & public areas.

1c. What the channels actually light (by area)

From the building control-points sheet — the ~78 channels group into three kinds of thing:

2. Follow one command

1. You send {lightsOn:[45]} at level 255 (one button click in the panel).
2. The controller frames it as a LightSwarm packet and puts it on the bus at 115200 baud.
3. Every panel sees the message — the bus is shared. Each asks "is 45 in my range?" P1 (0–39) no, P3 (80–119) no, P2 (40–79) yes.
4. Panel 2 switches its Port 6 output (unit 22-G) — connecting 12V to that strip.
5. Light on. Send addr 45, level 0 to turn it off; the board holds the last state until told otherwise.

3. Test it from this page

1. In the Test Panel, set Rig under test = Chalk Hill — baud jumps to 115200 and it generates 120 buttons (0–119).
2. Connect (Server to the Linux box, or Direct USB if the interface is on this machine).
3. Click button 45 → Panel 2's 6th light comes on. Or hit Test all (sweep) to walk every channel and confirm all 120.

There are three layers between your code and the lights: your client, the controller server (lightswarm-socket-server), and the serial link to the hardware. You talk to the server over WebSockets; the server talks to the boards over USB serial.

Bring it up

1. Plug in the USB LS Bus Interface and find its serial port — macOS ls /dev/tty.usbserial-*, Windows a COMx.
2. Set config.json — serialPort to that port and baudRate to match the rig (bench = 38400, Chalk Hill = 115200).
3. Install & run — yarn install then node index.js. The server listens on port 9090.
4. Verify — curl http://localhost:9090/health reports server + serial status.
5. Drive lights — connect a Socket.IO client, emit connect_device, then allOn or a lights command.

WebSocket API

The server emits back connectionStatus, commandStatus and error. REST: GET /health, GET /config.

Addresses & the wire protocol

The numbers in lightsOn:[…] are global light addresses — board base + output (MLS16 → (unit−1)×16 + output; MLS40J → base + channel). 65535 (0xFFFF) is the broadcast / all-lights address.

# each command is a SLIP-framed packet (lightswarm.js):
[ addrHi, addrLo, command, ...data, checksum ]
  command  = 0x23   # MDP_FADE (35) — set level / fade
  data     = [level, 1, 1]   # level 0–255 (on≈190, off=0)
  checksum = addrHi ^ addrLo ^ command ^ ...data   # XOR of all bytes

config.json (key fields)

{
  "server":     { "port": 9090, "cors": { "origin": "*" } },
  "lightswarm": { "serialPort": "/dev/tty.usbserial-DA00VYIC",
                  "baudRate": 115200 },
  "lightLevels":{ "on": 190, "dimmed": 10 },
  "inactivity": { "timeout": 900000, "resetAction": "allOn" }
}

A live tool to connect to a rig and exercise every channel. Pick a model (or type the LED count), generate a button per address, then click to toggle individual lights or run a full sweep. Two ways to drive it — no IP needed for either:

Practical reminders when working with the dumb-LED system on a physical model.