How to set up flag LEDs with SimHub

A flag panel is a small LED matrix beside your screen that lights up when the game shows a flag, so you notice a yellow even when the screen is busy. SimHub does most of the work. These are the steps from a bare LED matrix to flags that show up when the game throws them.

What you need

SimHub on your PC. It's free.
An LED matrix or strip. WS2812B LEDs are the usual choice, and 8×8 matrices are cheap and common.
A board to drive it. An Arduino Pro Micro, Nano or Uno works. SimHub uploads its own firmware to it, so you don't write any code.
A USB cable, three wires, and a resistor of a few hundred ohms for the data line.

Wiring

A WS2812B matrix has three input pads: 5V, ground and data in (DIN). Wire 5V and ground to the board, and the data line through the resistor to the data pin you'll pick in SimHub. Use the input pads. There's a matching set on the other end marked DOUT for chaining another matrix, and nothing lights if you wire to those by mistake.

Getting it into SimHub

Plug the board in with the LEDs connected.
In SimHub, open the Arduino section and its setup tool for building the firmware.
Pick your board, then add an RGB matrix or LED strip with the right number of LEDs and the data pin you wired to.
Upload the firmware to the board.
Once it's back, the device shows up in SimHub. Open its LED profile and use the test option to light everything once.

SimHub moves its menus around between versions, so the names may not match exactly. The steps stay the same: build the firmware, upload it, then set up what it shows.

Flags first, everything else after

In the LED profile you stack up things to show: flags, your gear, RPM, whatever you like. Items higher up the list draw on top of the ones below. Put flags at the top. That way the panel shows your gear most of the time, and the moment a flag comes out, the flag covers it.

Which flags your game sends

Not every sim reports every flag. SimHub's property list shows what your game is sending right now, and the flags are in there as properties like Flag_Yellow and Flag_Blue. The only real test is a session:

Join a practice or test session.
Watch the property list in SimHub while you drive.
See which ones turn on, and when.

Blue flags only show up with faster traffic around you, so don't worry if you can't trigger one alone.

Brightness and USB power

Each WS2812B LED can draw about 60 mA at full white. Sixty-four of them is close to 4 A, and a normal USB port gives you 500 mA. A green flag at low brightness is fine. A full white or yellow flag at full brightness pulls more than the port can give, and the board browns out and freezes on whatever it was showing.

You can keep the brightness low and cap it in the firmware so it can't go over what the port can give, or power the LEDs from a separate 5V supply with its ground tied to the board's ground. For a small panel next to your screen, low brightness is plenty, and it's easier on your eyes at night.

Your own effects

Past the built-in flags, SimHub can run JavaScript to draw anything you like on the matrix: a pit limiter warning, arrows for a car alongside, a low fuel icon. If you'd rather draw those than write them, the free Matrix Effect Builder lets you paint the frames, test them against pretend game data and copy the code into SimHub.

When it doesn't work

Nothing lights: check you're on the DIN pads, the data pin matches what you picked in SimHub, and ground is connected.
Wrong colours: the colour order setting is off. WS2812B is usually GRB.
Upside down or mirrored: change the rotation in the matrix settings. If every other row is backwards, turn on the serpentine (zig-zag) option.
Freezes on a bright flag: that's power. See the section above.
Flag never shows: check the property list. Your game may not send that flag.

If you'd rather skip the soldering, the Flag Dash is an 8×8 flag and gear panel that comes built, tested and capped to run off one USB port, with a SimHub profile ready to import.