PrintHive

Set up an MQTT status display

This guide connects a TLS-capable LED controller to Print Hive through Mosquitto. The display receives status only for the Printers that you assign to its pixels.

Check the requirements

You need these components:

  • A Mosquitto broker with the Dynamic Security plugin.
  • A public DNS hostname with a valid TLS certificate.
  • Outbound TCP access from Print Hive and the controller to port 8883.
  • A Dig-Next-2 controller that runs WLED and the Print Hive Usermod.
  • An organization admin account in Print Hive.

Standard WLED MQTT does not support the required verified TLS transport. Use the custom Print Hive Usermod. Do not expose the WLED HTTP interface to the public internet.

Prepare a self-hosted Print Hive deployment

If your service operator has configured MQTT displays, continue to Add and test the broker. The following service settings are for the operator of a self-hosted deployment.

Apply the repository database migrations, including 20260905120000_mqtt_status_displays.sql, before starting the API and display worker.

Set these environment variables on the API and display worker:

Use a direct PostgreSQL connection or a session pooler. Transaction pooling is not supported because the worker holds a session lock for each broker connection.

MQTT_DISPLAY_DATABASE_URL=postgresql://...
MQTT_DISPLAY_SECRET_KEY=<32-byte-base64-key>
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>

The service also accepts SUPABASE_DB_URL when MQTT_DISPLAY_DATABASE_URL is absent. Keep MQTT_DISPLAY_SECRET_KEY in the deployment secret store.

Print Hive blocks private, loopback, link-local, and metadata broker addresses by default. A lab deployment can set MQTT_DISPLAY_ALLOW_PRIVATE_BROKERS=true. Do not set this variable on a public multi-tenant deployment.

During development, start the display worker in a separate process:

bun --filter @hiv3d/api mqtt-displays:dev

After an API build, start the production worker with:

bun --filter @hiv3d/api mqtt-displays:start

Run one active publisher owner for each broker connection. Use the same process supervisor and restart policy as the API.

Build and configure the controller

From the Print Hive source repository, run:

tools/mqtt-displays/build-wled-firmware.sh

The script builds WLED 16.0.1 with the Print Hive and Multi-Relay Usermods. It writes /tmp/printhive-wled-16.0.1.bin and does not flash a controller. Save your WLED configuration before you install the firmware through the applicable WLED update procedure.

Check the LED type, color order, and pixel count in WLED. Keep Multi-Relay enabled for Dig-Next-2 output power. Set a WLED settings PIN and unlock it. From the same subnet, open /printhive-display on the controller. Let its clock synchronize before pairing.

The build and native decoder tests pass. Physical WS2805 output, power switching, and Wi-Fi recovery still require a controller test before production use.

Add and test the broker

  1. Open Settings, then open Integrations.
  2. In MQTT status displays, select Add broker.
  3. Enter the broker hostname, TLS port, and Dynamic Security admin credential.
  4. If the broker uses a private CA, paste the CA certificate.
  5. Select Save and test.

The connection must show online. Print Hive creates a separate publisher account. The display never receives this account.

Add and pair the display

  1. Select Add display.
  2. Enter a display name, select the broker, and enter the physical pixel count.
  3. Open the display and select Pairing.
  4. Select Generate pairing token.
  5. Open the Print Hive Usermod page on the controller.
  6. Paste the token and pairing service URL into the controller page.
  7. Wait for the setup checklist to show controller health and capabilities.

The token expires after ten minutes and works once. The QR code contains no MQTT password or Print Hive API key.

Map Printers to pixels

  1. Open Pixel mapping.
  2. Select the line, vertical, grid, serpentine, or custom layout.
  3. Select Identify on a pixel to find its physical position.
  4. Search for a Printer and assign it to the pixel.
  5. Enter an optional rack, row, or slot label.
  6. Leave an intentional blank pixel set to Blank pixel.
  7. Select Save draft.

Draft changes do not change the live display. Use Reverse orderor the swap control when the physical strip order differs from the editor.

Test and publish

  1. Open Test and publish.
  2. Select Walk pixels and Test colors.
  3. Confirm that the pixel direction is correct and every pixel lights.
  4. Select Record confirmation.
  5. Select Publish draft.
  6. Open Diagnostics and confirm that the configuration and Printer source are fresh.

Print Hive publishes a complete snapshot every ten seconds. Each snapshot expires after fifteen seconds. Bambu and base adapter source evidence expires after ninety seconds unless the source has a different configured cadence.

Understand the pixel patterns

  • Red and green, 500 ms: filament runout.
  • Red and green, 150 ms: active error.
  • Bright green, four flashes: recent completion.
  • Purple and off, 700 ms: explicit offline state.
  • Amber pulse: paused.
  • Blue: running.
  • White-blue: waiting.
  • White: idle.
  • Dim purple: unknown or stale source evidence.
  • Off: intentional blank pixel.

Stop the live feed

Open Settings and select Disable live feed. Print Hive stops status publication and clears the retained display images. The controller can still send health and run display tests. Its credential stays valid so you can enable the feed again.

Rotate or revoke a credential

Open Pairing and select Rotate credential. Download the JSON bundle before you dismiss it. Print Hive does not show the password again. The old credential remains valid for the displayed grace period.

Unlock the WLED settings PIN and open /printhive-display. Paste the downloaded JSON into Rotated credential bundleand select Import and reconnect. Check that controller health returns before the old credential expires.

To stop one credential, open Settings and select Revoke. Publication stops if the broker cannot confirm revocation.

If a checklist item stays incomplete, use the MQTT display troubleshooting guide.