pocketsized/bambupushnotifier repository overview

⁠bambu-ntfy

Full details on the Website⁠

A self-hosted push-notification bridge for Bambu Lab printers. It watches a printer's local MQTT status feed and sends a notification through your own or public ntfy⁠ server whenever:

• the print state changes (idle → preparing → slicing → running → paused → finished → failed)
• the printer reports a print error code (and when it clears)
• an HMS (Health Management System) warning/error is raised or cleared
• the connection to the printer is lost or restored
• Supports monitoring multiple printers from a single container.

⁠Why this exists

Bambu Handy does not work when the printer is in LAN Only / Developer Mode is enabled. Bambu Lab printers also run a local MQTT broker over TLS with a rich status feed but nothing to turn it into a notification unless you're watching the screen. Bambu-ntfy stays connected to that feed, diffs each status report against the last known state, and pushes a notification for anything worth knowing, entirely over your own network.

Bambu printer(s)  --MQTT/TLS, bblp + access code-->  bambu-ntfy  --HTTP POST-->  your ntfy server

⁠Quick start

1. Enable LAN mode on the printer

Settings → Network → LAN Only Mode (or Developer Mode on some firmware). This reveals the 8-digit access code used as the MQTT password, and the printer's serial number. You'll also need the printer's IP address.

2. Run the container

docker run -d \
  --name bambu-ntfy \
  -e NTFY_URL=https://ntfy.example.com \
  -e NTFY_TOPIC=bambu-printer \
  -e PRINTER_IP=192.168.1.50 \
  -e PRINTER_SERIAL=00M00A000000000 \
  -e PRINTER_ACCESS_CODE=12345678 \
  -e PRINTER_NAME="Bambu X1C" \
  pocketsized/bambupushnotifier

No ports need to be published as the container only makes outbound connections to the printer and to ntfy.

3. Subscribe with a ntfy client

ntfy subscribe https://ntfy.example.com/bambu-printer

⁠docker-compose

services:
  bambu-ntfy:
    image: pocketsized/bambupushnotifier
    container_name: bambu-ntfy
    restart: unless-stopped
    environment:
      # --- ntfy (shared across all printers) ---
      NTFY_URL: "https://ntfy.example.com"
      NTFY_TOPIC: "bambu-printer"
      NTFY_TOKEN: ""          # or use NTFY_USERNAME / NTFY_PASSWORD
      # NTFY_USERNAME: ""
      # NTFY_PASSWORD: ""

      # --- Single printer ---
      # PRINTER_IP: "192.168.1.50"
      # PRINTER_SERIAL: "00M00A000000000"
      # PRINTER_ACCESS_CODE: "12345678"
      # PRINTER_NAME: "Bambu Printer"
      # PRINTER_PORT: "8883"

      # --- Multiple printers (numbered format) ---
      PRINTER_1_IP: "192.168.1.50"
      PRINTER_1_SERIAL: "00M00A000000000"
      PRINTER_1_ACCESS_CODE: "12345678"
      PRINTER_1_NAME: "X1C Upstairs"

      PRINTER_2_IP: "192.168.1.51"
      PRINTER_2_SERIAL: "00M00B000000000"
      PRINTER_2_ACCESS_CODE: "87654321"
      PRINTER_2_NAME: "P1S Garage"

      # Add PRINTER_3_*, PRINTER_4_* ... PRINTER_9_* as needed

      LOG_LEVEL: "INFO"

Both the single-printer and numbered variables can be set at the same time. They all run side by side, each on its own thread.

⁠Environment variables

At least one printer (single or numbered) and NTFY_URL/NTFY_TOPIC are required. Failure to set required variables will cause the container to exit at startup.

⁠Notification events

HMS codes are decoded into a severity (fatal/serious/common/info) and, for a handful of common conditions (AMS communication errors, filament runout, nozzle/heatbed temperature abnormalities, nozzle clogs, toolhead communication errors), a friendly description. Unrecognized codes still notify with their raw code (look them up at wiki.bambulab.com/en/hms⁠).

⁠Image details

• Built on python:3.13-alpine3.24.
• Runs as a non-root user.
• Only two runtime dependencies: paho-mqtt and requests.
• No exposed ports as the container only makes outbound MQTT and HTTPS connections.

⁠Limitations

• Container has to be on the local network as this does not use Bambu's cloud API, it uses the MQTT stream. It won't work remotely unless you set up your own VPN or port access to your LAN.
• The known-HMS-code table only covers a handful of common conditions; everything else still notifies, just without a friendly description.
• Built against the general Bambu Lab MQTT report schema. Field availability can vary slightly by printer/firmware.

⁠Links

• Website: Website⁠
• ntfy: ntfy.sh⁠