Bambu Lab Printer Reverse-Engineering Knowledge Base

Living Document - This knowledge base is continuously extended and updated.

Last updated: 2026-03-22

Table of Contents

• Overview
• Printer Discovery
• MQTT Communication
• HTTPS Communication
• File Uploads
• Printer Commands
• Filament Management

Overview

Bambu Lab printers communicate with third-party applications using three primary protocols:

1. SSDP - For network discovery and printer detection
2. MQTT - For real-time communication with connected printers
3. HTTPS - For cloud communication, firmware updates, and cloud APIs

This knowledge base documents the protocol details, command structures, and data formats used by Bambu Lab devices. Note that HTTP communication uses HTTPS (secure).

Printer Discovery

SSDP (Simple Service Discovery Protocol)

Printers announce themselves on the local network using SSDP multicast messages from port 1900 to ports 1990 and 2021.

Discovery Example

NOTIFY * HTTP/1.1
HOST: 239.255.255.250:1900
Server: UPnP/1.0
Location: 192.168.2.80
NT: urn:bambulab-com:device:3dprinter:1
USN: <serial_number>
Cache-Control: max-age=1800
DevModel.bambu.com: C12
DevName.bambu.com: 3DP-01P-426
DevSignal.bambu.com: -38
DevConnect.bambu.com: lan
DevBind.bambu.com: free
Devseclink.bambu.com: secure
DevVersion.bambu.com: <firmware version>
DevCap.bambu.com: 1

Key Fields

MQTT Communication

Printers communicate via secure MQTT on port 8883.

Connection Parameters

• Host: Printer IP address
• Port: 8883
• Username: bblp
• Password: Access code
• Protocol: MQTT over TLS
• QoS: 0 (most requests), 1 (critical operations)
• Keepalive: 60 seconds

Certificate Setup

To communicate securely, you need the printer's CA certificate:

echo | openssl s_client -showcerts -connect :8883 2>/dev/null | \ awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/{print $0}' > mqtt_server.crt

Extract the second certificate (CA certificate)

awk 'BEGIN {c=0} /BEGIN CERTIFICATE/{c++} {if(c==2) print}' mqtt_server.crt > bbl_ca.crt ```

Connect and subscribe to the report topic:

mosquitto_sub --cafile bbl_ca.crt -v -L mqtt://bblp:<ACCESS_CODE>@<PRINTER_IP>:8883/device/<serial>/report --insecure

MQTT Topics

Report Topic (Receives Data)

device/{SERIAL}/report - Push updates (asynchronous)

Request Topic (Sends Commands)

device/{SERIAL}/request - Interactive requests (synchronous)

See Printer Commands for detailed command descriptions.

Message Structure

All messages are JSON formatted and must include a unique sequence_id to correlate responses.

Example Request:

{
  "system": {
    "sequence_id": "2003",
    "command": "ledctrl",
    "led_node": "chamber_light",
    "led_mode": "on"
  }
}

System Status Codes (in report payload)

1. Preparing / Initializing
2. Idle
3. Running
4. Heating
5. Printing
6. Paused
7. Completed
8. Error

HTTPS Communication

Bambu Lab APIs communicate over HTTPS through Cloudflare.

API Hosts

All Bambu APIs are hosted through Cloudflare at api.bambulab.com:

Slicer Resource Updates

• Base URL: https://api.bambulab.com
• Paths:
• /v1/iot-service/api/slicer/resource?slicer/plugins/cloud=<version> - Returns plugin resources
• /v1/iot-service/api/slicer/resource?slicer/printer/bbl=<version> - Returns printer resources

OrcaSlicer Custom Headers

Applications add these headers to requests:

X-BBL-Client-Name: OrcaSlicer
X-BBL-Client-Type: slicer
X-BBL-Client-Version: 01.10.01.50
X-BBL-Device-ID: <device-id>
X-BBL-Language: en-US
X-BBL-OS-Type: linux
X-BBL-OS-Version: <kernel-version>

File Uploads

Files (G-code/3MF) are uploaded directly to the printer using FTPS (FTP over TLS).

Connection Details

• Protocol: FTPS (Implicit TLS)
• Port: 990
• Username: bblp
• Password: Access code
• Encryption: TLS 1.2+ (Reuse of TLS session IDs is often required)

Upload Process

1. Connect to the printer on port 990 using Implicit SSL.
2. Authenticate with bblp and the access code.
3. Upload the .gcode.3mf file to the root directory /.
4. Note: The printer may reject uploads to subdirectories like /sdcard/.

cURL Example

curl --ftp-ssl --insecure \
     --user "bblp:<ACCESS_CODE>" \
     --upload-file "model.gcode.3mf" \
     "ftps://<PRINTER_IP>:990/"

Printer Commands

{
  "pushing": {
    "sequence_id": "0",
    "command": "pushall"
  }
}

{
  "system": {
    "sequence_id": "2003",
    "command": "ledctrl",
    "led_node": "chamber_light",
    "led_mode": "on",
    "led_on_time": 500,
    "led_off_time": 500,
    "loop_times": 1
  }
}

{
  "system": {
    "sequence_id": "2003",
    "command": "ledctrl",
    "led_node": "chamber_light2",
    "led_mode": "on",
    "led_on_time": 500,
    "led_off_time": 500,
    "loop_times": 1
  }
}

{
  "print": {
    "sequence_id": "0",
    "command": "project_file",
    "param": "Metadata/plate_1.gcode",
    // Always 0 for local prints
    "project_id": "0",
    // Always 0 for local prints
    "profile_id": "0",
    // Always 0 for local prints
    "task_id": "0",
    // Always 0 for local prints
    "subtask_id": "0",
    "subtask_name": "",
    "file": "filename.gcode.3mf",
    "url": "ftp://filename.gcode.3mf",
    "md5": "",
    "timelapse": false,
    "bed_type": "hot_plate",
    "bed_leveling": true,
    "auto_bed_leveling": 1,
    "flow_cali": false,
    "vibration_cali": true,
    "layer_inspect": true,
    // Example: [3] uses AMS slot 4
    "ams_mapping": [3],
    "ams_mapping2": "",
    "use_ams": true,
    "cfg": "0",
    "extrude_cali_flag": 2,
    "nozzle_offset_cali": 2,
    "reason": "success",
    "result": "success"
  }
}

{
  "print": {
    "sequence_id": "0",
    "command": "pause"
  }
}

{
  "print": {
    "sequence_id": "0",
    "command": "resume"
  }
}

{
  "print": {
    "sequence_id": "0",
    "command": "stop"
  }
}

{
  "info": {
    "command": "get_version",
    "sequence_id": "20001"
  }
}

{
  "print": {
    "sequence_id": "0",
    "command": "gcode_line",
    "param": "<GCODE>\n"
  }
}

AMS Mapping Configuration (ams_mapping)

Overview

The ams_mapping parameter is crucial for multi-color print jobs when using the AMS (Automatic Material System). It defines which AMS slot corresponds to each color in your print file. Structure { "print": { "ams_mapping": [ -1, -1, -1, 1, 0 ], // ... rest of print command } }

How AMS Mapping Works

The ams_mapping array uses a reverse indexing system where:

• Array positions represent color indices in your print file (starting from 0)
• Array values represent AMS slot numbers (0-3 for typical 4-slot AMS)
• -1 indicates unused color slots

Key Rules:

• Fixed array length: Always use 5 elements (supports up to 4 colors + padding)
• Right-to-left assignment: Color assignments fill from the end of the array
• Pad with -1: Fill unused positions at the beginning with -1

Important Notes

• AMS slot numbers are zero-indexed (0, 1, 2, 3)
• Color indices in your print file start from 0
• The printer will just pause and won't start if the mapping is not correct
• Ensure the specified AMS slots contain the correct filament types and colors
• Always set "use_ams": true when using AMS mapping
• Verify your AMS is properly loaded before sending the print job

Essential Report Fields

When subscribing to the device/{SERIAL}/report topic, the JSON payload contains comprehensive state info:

• ams: Details filament in each AMS slot (color, type, remaining %).
• lights_report: Current state of LEDs.
• vt_tray: Virtual tray status (for printers without AMS).

Filament Management

AMS Filament Reading

The printer broadcasts AMS status periodically in the /report topic:

{
  "ams": {
    "ams": [
      {
        "id": "0",
        "humidity": "2",
        "humidity_raw": "38",
        "temp": "25.4",
        "dry_time": 0,
        "info": "1001",
        "tray": [
          {
            "id": "0",
            "state": 3,
            "remain": -1,
            "k": 0.019999999552965164,
            "n": 1,
            "cali_idx": -1,
            "total_len": 330000,
            "tag_uid": "0000000000000000",
            "tray_id_name": "",
            "tray_info_idx": "GFL99",
            "tray_type": "PLA",
            "tray_sub_brands": "",
            "tray_color": "161616FF",
            "tray_weight": "0",
            "tray_diameter": "0.00",
            "tray_temp": "0",
            "tray_time": "0",
            "bed_temp_type": "0",
            "bed_temp": "0",
            "nozzle_temp_max": "240",
            "nozzle_temp_min": "190",
            "xcam_info": "000000000000000000000000",
            "tray_uuid": "00000000000000000000000000000000",
            "ctype": 0,
            "cols": [
              "161616FF"
            ]
          },
          {
            "id": "1",
            "state": 3,
            "remain": 21,
            "k": 0.019999999552965164,
            "n": 1,
            "cali_idx": -1,
            "total_len": 330000,
            "tag_uid": "8A160AB500000100",
            "tray_id_name": "A00-A0",
            "tray_info_idx": "GFA00",
            "tray_type": "PLA",
            "tray_sub_brands": "PLA Basic",
            "tray_color": "FF6A13FF",
            "tray_weight": "250",
            "tray_diameter": "1.75",
            "tray_temp": "55",
            "tray_time": "8",
            "bed_temp_type": "0",
            "bed_temp": "0",
            "nozzle_temp_max": "230",
            "nozzle_temp_min": "190",
            "xcam_info": "8813100EE803E8039A99193F",
            "tray_uuid": "73B6F9DA7BE24818940EB178AAF8550F",
            "ctype": 0,
            "cols": [
              "FF6A13FF"
            ]
          },
          {
            "id": "2",
            "state": 3,
            "remain": -1,
            "k": 0.019999999552965164,
            "n": 1,
            "cali_idx": -1,
            "total_len": 330000,
            "tag_uid": "0000000000000000",
            "tray_id_name": "",
            "tray_info_idx": "GFL99",
            "tray_type": "PLA",
            "tray_sub_brands": "",
            "tray_color": "BCBCBCFF",
            "tray_weight": "0",
            "tray_diameter": "0.00",
            "tray_temp": "0",
            "tray_time": "0",
            "bed_temp_type": "0",
            "bed_temp": "0",
            "nozzle_temp_max": "240",
            "nozzle_temp_min": "190",
            "xcam_info": "000000000000000000000000",
            "tray_uuid": "00000000000000000000000000000000",
            "ctype": 0,
            "cols": [
              "BCBCBCFF"
            ]
          },
          {
            "id": "3",
            "state": 3,
            "remain": -1,
            "k": 0.019999999552965164,
            "n": 1,
            "cali_idx": -1,
            "total_len": 330000,
            "tag_uid": "0000000000000000",
            "tray_id_name": "",
            "tray_info_idx": "Ped69f1a",
            "tray_type": "PLA",
            "tray_sub_brands": "",
            "tray_color": "FFFFFFFF",
            "tray_weight": "0",
            "tray_diameter": "0.00",
            "tray_temp": "0",
            "tray_time": "0",
            "bed_temp_type": "0",
            "bed_temp": "0",
            "nozzle_temp_max": "240",
            "nozzle_temp_min": "190",
            "xcam_info": "000000000000000000000000",
            "tray_uuid": "00000000000000000000000000000000",
            "ctype": 0,
            "cols": [
              "FFFFFFFF"
            ]
          }
        ]
      }
    ]
  }
}

Setting AMS Filaments

To set filament information manually (for third-party spools):

{
  "print": {
    "sequence_id": "0",
    "command": "ams_filament_setting",
    "ams_id": 0,
    "tray_id": 0,
    "tray_info_idx": "GFL99",
    "tray_color": "FF0000FF",
    "tray_type": "PLA",
    "tray_brand_id": "GFL"
  }
}

Common Profile IDs (tray_info_idx)

Important Notes

1. Color Format: Always 8 characters (RRGGBBAA), alpha is usually FF
2. RFID Override: Official Bambu spools will eventually overwrite manual settings with RFID data
3. k-value: Ejection/extrusion coefficient for each slot

This is a living document. If you discover additional protocols or commands, please contact me.

Note: This knowledge base is derived from reverse engineering and experimentation with Bambu Lab devices and third-party applications.