MQTT Publishing¶

Bambuddy can publish events to an external MQTT broker, enabling integration with home automation platforms like Home Assistant, Node-RED, and other MQTT-based systems.

Configuration¶

Navigate to Settings → Network → MQTT Publishing to configure the connection.

Settings¶

Published Topics¶

All topics are prefixed with your configured topic prefix (default: bambuddy).

Status¶

Printer Events¶

Queue Events¶

Maintenance Events¶

Smart Plug Events¶

Archive Events¶

Payload Format¶

All payloads are JSON objects. Here's an example printer status payload:

{
  "printer_id": 1,
  "printer_name": "X1C-1",
  "printer_serial": "00M09C411500579",
  "timestamp": "2026-01-13T12:00:00.000000",
  "connected": true,
  "state": "PRINTING",
  "progress": 45.5,
  "remaining_time": 3600,
  "layer_num": 150,
  "total_layers": 300,
  "current_print": "benchy.3mf",
  "subtask_name": "Benchy",
  "temperatures": {
    "bed": 60.0,
    "bed_target": 60.0,
    "nozzle": 220.0,
    "nozzle_target": 220.0,
    "chamber": 35.0
  },
  "wifi_signal": -55,
  "chamber_light": true,
  "speed_level": 2,
  "cooling_fan_speed": 100,
  "big_fan1_speed": 50,
  "big_fan2_speed": 50,
  "awaiting_plate_clear": false
}

Plate Clear¶

awaiting_plate_clear is a Bambuddy-side flag, not printer telemetry: the printer itself only ever reports RUNNING, PAUSE, FAILED, FINISH and IDLE. It goes true when a print reaches a terminal state and stays true until someone confirms the build plate is free — the queue will not dispatch the next job in the meantime. See Print Queue for the gate itself.

Because the status topic only refreshes when the printer pushes telemetry — which stops entirely once Auto Off powers the printer down — every transition is also published on its own retained topic:

{
  "printer_id": 1,
  "printer_name": "X1C-1",
  "printer_serial": "00M09C411500579",
  "awaiting": true,
  "timestamp": "2026-01-13T12:00:00.000000"
}

Subscribe to bambuddy/printers/+/plate_clear and you get the current state of every printer the moment you connect, then one message per change. Acknowledge from your own automation with POST /api/v1/printers/{id}/clear-plate (see the API reference).

Home Assistant Integration¶

MQTT Discovery¶

Bambuddy does not currently support Home Assistant MQTT discovery. You'll need to configure sensors manually.

Example Sensor Configuration¶

Add to your configuration.yaml:

mqtt:
  sensor:
    - name: "X1C Print Progress"
      state_topic: "bambuddy/printers/00M09C411500579/status"
      value_template: "{{ value_json.progress }}"
      unit_of_measurement: "%"

    - name: "X1C State"
      state_topic: "bambuddy/printers/00M09C411500579/status"
      value_template: "{{ value_json.state }}"

    - name: "X1C Bed Temperature"
      state_topic: "bambuddy/printers/00M09C411500579/status"
      value_template: "{{ value_json.temperatures.bed }}"
      unit_of_measurement: "°C"
      device_class: temperature

Node-RED Example¶

Use an MQTT In node subscribed to bambuddy/# to receive all events, then route them based on topic:

[MQTT In] → [Switch (by topic)] → [Function/Dashboard]

TLS/SSL Configuration¶

Bambuddy supports TLS connections with self-signed certificates:

• Certificates are not verified (allows self-signed certs)
• Connection is still encrypted
• Suitable for home networks

For production environments, use properly signed certificates from your broker.

Troubleshooting¶

Connection Status¶

The connection status is shown in the Settings page:

• Green dot = Connected
• Red dot = Disconnected or error

Common Issues¶

Testing with Mosquitto¶

# Subscribe to all Bambuddy topics
mosquitto_sub -h your-broker -t "bambuddy/#" -v

# With authentication
mosquitto_sub -h your-broker -u username -P password -t "bambuddy/#" -v

# With TLS
mosquitto_sub -h your-broker -p 8883 --cafile ca.crt -t "bambuddy/#" -v