PrintHive

Set up an MQTT status display

This guide pairs a Dig-Next-2 controller with Print Hive hosted MQTT. The display receives status only for the Printers that you assign to its pixels. Print Hive supplies the broker connection and creates a restricted credential for each display.

Check the requirements

You need these components:

  • Print Hive hosted MQTT enabled by your service operator.
  • A farm network that permits MQTT over TLS to mqtt.printhiv3d.com:443.
  • 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.

Download and install the firmware

  1. Open Settings. Under Connections, open Integrations.
  2. In MQTT status displays, expand Advanced: customer brokers & hosted endpoint and select Download Dig-Next-2 firmware.
  3. Save your current WLED configuration.
  4. Open http://<controller-address>/update from the controller's network. If you set a WLED settings PIN, unlock settings first.
  5. Upload the binary. The controller restarts when the upload completes.

If the controller has no working WLED install, flash it over USB with esptool:

esptool.py --chip esp32 write_flash 0x0 printhive-wled-16.0.1-dig-next-2-*.bin

If the hosted connection is unavailable, contact your service operator. Broker administrator credentials are not part of the hosted customer setup.

Developers can build the same firmware from the repository:

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.

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 pair the display

  1. Select Pair controller. The Displays workspace opens on its pair sheet.
  2. Enter a display name and physical pixel count. Keep PrintHive hosted MQTT selected as the broker, then select Add display.
  3. The display's Setup tab opens. Select Pairing.
  4. Select Generate pairing token.
  5. Open the Print Hive Usermod page on the controller.
  6. Paste the token into the controller page. The production pairing URL is already set.
  7. Wait for the display's Health tab 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 Settings, then Displays, and select the display strip on the rack elevation.
  2. Drag each pixel puck onto its Printer tile. Each drop saves the draft, and the tile shows a px badge for each binding.
  3. Select a puck, then use the identify badge on it to flash the physical pixel and find its position.
  4. Leave an intentional blank pixel unbound.
  5. If the strip is not a single line, set the physical layout under the display's Setup → Settings.

Draft changes do not change the live display. Use Reverse orderunder Setup → Settings → Physical layout when the physical strip order differs from the canvas.

Test and publish

  1. Open the display's Setup tab and select Test and publish.
  2. Select Run full setup test. Wait for red, green, blue, white, a walking white pixel, and the final off phase.
  3. Wait for the controller's successful test receipt. Confirm that the pixel direction is correct and every pixel lights.
  4. Select Record confirmation.
  5. Select Publish draft.
  6. Open the display's Health tab and confirm that the configuration and Printer source are fresh.
  7. Open Setup → Settings and select Enable live feed.

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 the display's Setup → 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 Setup → 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 Setup → Settings and select Revoke. Publication stops if the broker cannot confirm revocation.

Use your own broker

  1. Open Settings, then open Integrations.
  2. In MQTT status displays, expand Advanced: customer brokers & hosted endpoint, then 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.

Prepare a self-hosted Print Hive deployment

These settings are for the service operator. Hosted customers do not need to configure them. Deploy the API, separate display worker, and authenticated broker before enabling hosted admission.

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 worker-specific healthcheck and include the worker in release rollback. The hosted broker uses server-owned administrator credential files; never copy those credentials into a customer configuration bundle.

To change the colors and patterns each status renders, continue to the signal profile guides: set up your first status display, configure a custom palette, or the signal profile reference.

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