hCRI.io Companion Bridge setup

ESP32 Bridge — Setup Guide

Last updated October 15, 2026 · Firmware source on GitHub ↗

01 What the bridge does

The Torch Bearer and the X-Rite ColorMunki Photo / Design are USB spectrometers with no Bluetooth. The bridge is a small LilyGO ESP32-S3 board that plugs into the instrument as a USB host, takes the measurement, and passes the spectrum to the hCRI Companion app over Bluetooth LE. Total cost is roughly the price of the board plus a cable adapter.

Supported instruments

Torch Bearer, ColorMunki Photo and ColorMunki Design (USB ID 0971:2007). The ColorMunki Display and ColorMunki Smile are different instruments and do not work. The firmware detects which instrument is plugged in automatically; the same file runs both.

Not supported

Boards that cannot act as a USB host will not work, including the LilyGO T-Echo (nRF52840) and plain ESP32 / ESP32-S2 boards. You need an ESP32-S3.

02 What to buy

Buy one of these two boards from LilyGO. Check the listing before you order, because LilyGO sells several variants.

BoardGet this variantNotes
LilyGO T-Display-S3 (standard)16 MB flash, with or without touch, not the AMOLED model Cheapest option. Needs external power (power bank) when used with a ColorMunki.
LilyGO T-Display-S3 Pro"Without Camera" version Built-in battery and charger. Shows battery level. Can run the instrument from its own battery with the right adapter.

Where to buy: the LilyGO store (lilygo.cc) is the manufacturer; search for "T-Display-S3". The Pro is at lilygo.cc/products/t-display-s3-pro, and LilyGO's official shops on AliExpress and Amazon also carry both. Stock changes, and the Pro is sometimes sold out.

Which one?

Choose the Pro if you want to run on a battery with no power bank; choose the standard S3 if you want the lowest cost and don't mind carrying a power bank.

You also need a phone with the hCRI Companion app (Android 7.0+ or iPhone with iOS 15.1+).

03 Cables and power

The board is the USB host, so the instrument plugs into it, not the other way around.

Standard T-Display-S3

  • A USB-C OTG splitter: a USB-C male plug on one end that provides a female USB-A (for the instrument's cable) and a female USB-C (for power) at the same time. Search for "USB-C OTG adapter with charging" or "OTG hub with PD passthrough".
  • A power bank plugged into the female USB-C of that adapter.
  • The instrument's own USB cable (USB-A on the Torch Bearer and ColorMunki).

T-Display-S3 Pro

  • Simplest: a plain USB-C male to USB-A female OTG adapter, with the instrument cable plugged into it and nothing else connected. The board's battery supplies 5 V to the instrument. While outside power is connected, the 5 V output is off and the battery charges instead.
  • For long sessions, use the same splitter and power bank as above.

ColorMunki power

The ColorMunki draws more current than the Torch Bearer. On the standard S3 always power it from a power bank, and use a good quality OTG adapter. A flat or weak supply shows up as repeated "communication" errors in the app.

A PC USB port is only needed to flash the firmware.

04 Installing the firmware

You only need a computer with a USB-C cable (a data cable, not a charge-only one) for this step. Firmware releases live on the prod-latest release page ↗.

Option A: the flasher program (recommended)

  1. Install PythonGet it from python.org if you don't have it.
  2. Download the programhcri_companion_esp32_bridge.py from the prod-latest release page.
  3. Plug the board into your computerUse the board's USB-C port. If the screen is blank and nothing has been flashed, it is already in the right mode.
  4. Run itWindows: py hcri_companion_esp32_bridge.py. Mac/Linux: python3 hcri_companion_esp32_bridge.py. It finds the port, identifies the board (S3 or S3 Pro), downloads the matching firmware, verifies its checksum and flashes it. If the board already has exactly that build it says so and leaves it alone; add --force to flash it anyway. To skip all questions: py hcri_companion_esp32_bridge.py --s3 --prod --yes (use --s3pro for the Pro).

Option B: flash the file by hand

  1. Download the right fileFrom the prod-latest release page: hcri-esp32-bridge-factory.bin for the standard S3. For the T-Display-S3 Pro use hcri-esp32-bridge-pro-factory.bin. If you are unsure, use Option A, which picks it for you.
  2. Put the board in download modeHold BOOT, tap RST, then release BOOT (or plug the cable in while holding BOOT). A new serial port appears on your computer. This is needed whenever the bridge firmware is already running, because it takes over the USB port as a host.
  3. Flash at address 0x0In Chrome or Edge, open espressif.github.io/esptool-js, click Connect, choose the board's port, set Flash Address to 0x0, choose the .bin file and click Program. Or with esptool: esptool.py --chip esp32s3 --port COM5 --baud 460800 write_flash 0x0 hcri-esp32-bridge-factory.bin (use your own port, such as /dev/ttyACM0 on Linux).
  4. RestartUnplug the board, or tap RST. The screen shows the idle bridge screen.

If the board misbehaves after flashing

Run esptool.py --chip esp32s3 erase_flash as a separate first command, then flash again.

05 Connecting the instrument

  1. Unplug the board from the computerThe bridge runs from a power bank or the Pro's battery, not from a PC.
  2. Attach the adapterPlug the OTG adapter into the board's USB-C port.
  3. Plug in the instrumentPut the instrument's USB-A plug into the adapter's female USB-A.
  4. Add powerStandard S3: plug the power bank into the adapter's female USB-C. Pro: optional.
  5. Wait for the screenUntil an instrument is plugged in the screen says HCRI BRIDGE with a red NO USB. Once it finds the instrument the header changes to TORCH BEARER or COLORMUNKI and it goes to its ready screen.

06 First connection

Open hCRI Companion and use the meter picker (the connect button on the Main tab). The bridge appears in the list. The bridge is listed as hCRI Bridge · Torch Bearer or hCRI Bridge · ColorMunki, because the latest firmware tells the app what is plugged in even before you connect. A bridge with nothing plugged in is left out of the list. Older firmware can't say, so it is listed as plain hCRI Bridge. Tap it to connect; once connected, the app reads which instrument is attached and shows its name, Torch Bearer or ColorMunki, in the header.

The bridge accepts one Bluetooth connection at a time and stops advertising while connected. If the app cannot see it, close other Bluetooth tools (nRF Connect, a second phone) and try again. Firmware from before October 14, 2026 advertises as "Torch Bearer" instead of "hCRI Bridge"; the app accepts both. Reflash to get the new name (see Updating the firmware), and update the app first.

07 Using a ColorMunki

  1. CalibrateTurn the instrument's dial to the calibration position (the white tile) and tap Calibrate in the app, or press the ColorMunki's button. This measures the sensor's dark reference, for normal and high gain (about 6 seconds).
  2. Turn to AmbientTurn the dial to ambient (the lamp icon) with the diffuser dome in place. Only ambient mode is used.
  3. Take a readingPoint the instrument at the light and tap the measure button. In dim light the bridge integrates longer and averages several integrations (10–15 s); tap the button again to cancel.

How often to recalibrate

The dark reference drifts within tens of minutes. The app can require a fresh calibration after a set time: Settings → ColorMunki → Calibration limit (hours). The default is 1 hour, and 0 turns the check off. After that time the button changes to Recalibrate.

Accuracy

The ColorMunki's spectrum is its own (the Argyll / X-Rite factory calibration), with no correction of ours. On six flashlights (2680–6880 K) it agreed with a Hopoocolor HPCS to within about 46 K in CCT. In normal light the ColorMunki is read in its high-resolution mode (3.3 nm bands, about 4 nm effective resolution), so narrow peaks agree much more closely than in the standard mode; in very dim light the firmware uses the steadier standard 10 nm spectrum, which smooths very peaky, low-CRI LEDs. The Torch Bearer is sent as it reports it (the same as the open-source tobes-ui software) and reads a few percent high in CCT next to an HPCS at higher CCT. Neither is traceable to a standard. In very dim light the ColorMunki is noisier, and lux is approximate unless you check it against a reference meter.

08 Using a Torch Bearer

Plug it in, connect from the app, and tap the measure button. The bridge sends the spectrum exactly as the Torch Bearer reports it (the same as the open-source tobes-ui software), with no correction added. See the manual for the full workflow.

09 Updating the firmware

Updates are not delivered over Bluetooth. To update, repeat Installing the firmware: put the board in download mode and flash the new file. Settings in the app are kept. The newest tested release is always prod-latest.

10 Troubleshooting

SymptomTry
App can't find the bridgeBridge powered and showing the ready screen? Close other Bluetooth apps; only one connection at a time. Check phone Bluetooth and location/nearby-devices permissions.
No port appears when flashingUse a data-capable USB-C cable. Enter download mode (BOOT + RST). On Windows, try a different USB port.
Screen says no instrumentRe-seat the instrument cable. Check the OTG adapter really has a female USB-A. Add a power bank.
ColorMunki "Calibrate first"Turn the dial to calibration, tap Calibrate. Recalibrate when the age limit passes.
"Calibration failed" or wrong dialDial must sit in the calibration position and the instrument must be still. Try again.
"Too bright" / "no data"Move the instrument back from the light or use the diffuser. Check the dial is in ambient.
Repeated communication errorsPower problem: use a power bank on the standard S3 and a better quality adapter.

Still stuck? Open an issue on GitHub.