LED Matrix Companion v4 Satellite (ESP8266)

ESP8266-based LED matrix “satellite” for Bitfocus Companion v4.

This firmware connects to Companion’s Satellite API, subscribes to key text, and renders it on a 32×8 LED matrix (4× MAX7219 8×8 modules in a row).

Buy the units here: https://www.aliexpress.com/item/1005006038630745.html

• ✅ Supports TEXT from Companion (base64 decoded)
• ✅ Centers short text, scrolls long text
• ✅ COLOR parsing from Companion (COLOR="#RRGGBB" or R,G,B)
• ✅ Background Modes (bgmode):
  • none – ignore COLOR, no invert, no bars
  • invert – invert full display when any channel ≥ 128
  • bars – left & right 2-column bars ON when any channel ≥ 128
  • pgmpvw – left bars = PGM (red ≥ 128), right bars = PVW (green ≥ 128)
  • pvwpgm – left bars = PVW (green ≥ 128), right bars = PGM (red ≥ 128)
• ✅ Brightness control via Companion BRIGHTNESS (0–100 → 0–15 LED intensity)
• ✅ WiFiManager config portal (for WiFi + Companion IP/port + bgmode)
• ✅ Companion IP/port + background mode stored in EEPROM
• ✅ Boot counter to force config mode with repeated resets
• ✅ Designed for cheap LED matrix clocks based on ESP8266 from AliExpress

---

Display Behaviour

Static text

• Text ≤ 5 characters → centered
• Text width ≤ 32 px → centered

Scrolling text

• Text wider than 32 columns → smooth right-to-left scroll
• Scroll restarts only when text changes (no flashing)

Rendering

• Zero flicker on updates
• Full UTF-8 via decoded base64 TEXT
• Automatic polarity switching via Companion color
• “Waiting…” shown until Companion responds

---

Hardware

https://www.aliexpress.com/item/1005006038630745.html

Arduino IDE Setup

Before uploading the firmware, you need to install the ESP8266 board support in Arduino IDE:

1. Start Arduino and open the Preferences window
2. Enter https://arduino.esp8266.com/stable/package_esp8266com_index.json into the File > Preferences > Additional Boards Manager URLs field of the Arduino IDE. You can add multiple URLs, separating them with commas.
3. Open Boards Manager from Tools > Board menu and install esp8266 platform (and don't forget to select your ESP8266 board from Tools > Board menu after installation).

Required Libraries

Install the following libraries via Sketch > Include Library > Manage Libraries:

1. WiFiManager by tzapu
2. MD_Parola by MajicDesigns
3. MD_MAX72XX by MajicDesigns

After installing these libraries, you should be able to compile and upload the firmware.

Connecting to Wi-Fi / Companion

The device boots and attempts Wi-Fi and Companion automatically.

WiFiManager Powered

• Built-in captive portal for:
• • Wi-Fi SSID & Password
• • Companion IP
• • Companion Port
• • Boot Counter info
• Stores Companion info in EEPROM
• • Automatically reconnects to both Wi-Fi and Companion

Automatic Boot-Recovery

• During boot, device displays CONFIG? for 5 seconds
• If you reset the device during this window → next boot forces config mode
• Boot counter stored in EEPROM ensures this works reliably
• You will NOT go into config mode just because Companion is offline (device keeps retrying forever)

Entering Config Portal

On boot if you see CONFIG? and you reset while it is scrolling, you will enter WiFi Manager config mode and display CFG! on the LED Matrix.

• Connect to LED-MATRIX-XXXXXXXXXXX (with the mac address at the end)
• It should take you to 192.168.4.1 (if not, go there)
• Setup the Companion IP, Companion Port, set the mode you want, and set Boot to 0
• Modes Are:
• • none – ignore COLOR, no invert, no bars
• • invert – invert the whole display when any color channel ≥ 128
• • bars – left and right 2-column bars ON when any color channel ≥ 128
• • pgmpvw – left = PGM (red ≥ 128), right = PVW (green ≥ 128)
• • pvwpgm – left = PVW (green ≥ 128), right = PGM (red ≥ 128)
• Save
• Hit BACK in your browser to get to the main menu (may be more than once)
• Setup Wifi
• Save and exit

Connect to the Wi-Fi network:

SSID: LEDMatrix- Password: (blank)

Browse to: http://192.168.4.1

Configure:

• Wi-Fi SSID & password
• Companion IP
• Companion Satellite Port (default 16622) Settings save to EEPROM.

Companion Setup

In Companion v4:

• It should automatically show up as Satellite Surface
• Assign the button offset in Surfaces

The device appears as:

PRODUCT_NAME = LED Matrix KEYS_TOTAL = 1 TEXT = true COLORS = true

You can now push text via:

Buttons which means it can be driven by: Variables & Custom Actions!

Display Behaviour

• Text ≤5 chars → centred static
• Long text → smooth scroll from right to left
• Updates do not flicker
• BRIGHTNESS 0–100 maps to matrix intensity 0–15
• “Waiting…” appears until Companion connects