bambutools

Classes:

Name	Description
AMSControlCommand	AMS Control Commands enum
AMSDryingStage	Represents the operational stages of the AMS2 drying cycle.
AMSModel	AMS model enum
AMSSeries	AMS Series enum
AMSUserSetting	AMS User Settings enum
ActiveTool	The currently active extruder index.
ExtruderInfoState	Consolidated logical states for extruder sensor status.
ExtruderStatus	Operational states for physical extruders.
NozzleDiameter	Nozzle Diameter enum
NozzleType	Nozzle Type enum
PlateType	Used by BambuPrinter.print_3mf_file to specify which plate should be used when
PrintOption	Print Option enum
PrinterModel	Printer model enum
PrinterSeries	Printer Series enum
ServiceState	This enum is used by bambu-printer-manager to track the underlying state
TrayState	Operational status of the filament tray.

Functions:

Name	Description
decodeError	Decodes a raw print_error integer into a full HMS dictionary.
decodeHMS	Decodes the raw HMS list from telemetry into a structured list of dictionaries.
getAMSModelBySerial	Returns the hardware model based on the serial number prefix.
getAMSSeriesByModel	Returns the AMS series enum based on the provided model.
getModelBySerial
getPrinterModelBySerial	Returns the Printer model enum based on the provided serial #.
getPrinterSeriesByModel	Returns the Printer series enum based on the provided model.
getSeriesByModel
parseAMSInfo	Parses decimal bit-packed AMS info for status and feature reconciliation.
parseAMSStatus	Maps the ams_status code to human-readable descriptions.
parseExtruderInfo	Decodes the extruder 'info' bit-packed status using unique ExtruderInfoState names.
parseExtruderStatus	Decodes the operational extruder state using the exhaustive Enum map.
parseFan	Deprecated
parseRFIDStatus	Can be used to parse ams_rfid_status
parseStage	Maps stg_cur numeric codes to human-readable print stages.
scaleFanSpeed	Scales proprietary 0-15 fan speed values to a 0-100 percentage.
sortFileTreeAlphabetically	Sorts a dict of file/directory nodes hierarchically.
unpackTemperature	Unpacks a 32-bit packed temperature integer into a tuple of (Actual, Target).

AMSControlCommand

Bases: Enum

AMS Control Commands enum

AMSDryingStage

Bases: IntEnum

Represents the operational stages of the AMS2 drying cycle. Resolved from heater, vent, and fan bitmasks.

AMSModel

Bases: Enum

AMS model enum

AMSSeries

Bases: Enum

AMS Series enum

AMSUserSetting

Bases: Enum

AMS User Settings enum

ActiveTool

Bases: IntEnum

The currently active extruder index.

• SINGLE_EXTRUDER (-1): Standard single-toolhead architecture (X1/P1/A1).
• RIGHT_EXTRUDER (0): The primary/right toolhead in H2D (Dual Extruder) systems.
• LEFT_EXTRUDER (1): The secondary/left toolhead in H2D (Dual Extruder) systems.
• NOT_ACTIVE (15): The multi-extruder system is in a transitional state.

ExtruderInfoState

Bases: IntEnum

Consolidated logical states for extruder sensor status. Values represent unique state IDs to prevent bitmask collisions.

ExtruderStatus

Bases: IntEnum

Operational states for physical extruders. Values are mapped directly from the Bambu Studio source code (BBL_EXTRUDER_STATE).

NozzleDiameter

Bases: Enum

Nozzle Diameter enum

NozzleType

Bases: Enum

Nozzle Type enum

PlateType

Bases: Enum

Used by BambuPrinter.print_3mf_file to specify which plate should be used when starting a print job.

PrintOption

Bases: Enum

Print Option enum

PrinterModel

Bases: Enum

Printer model enum

PrinterSeries

Bases: Enum

Printer Series enum

ServiceState

Bases: Enum

This enum is used by bambu-printer-manager to track the underlying state of the mqtt connection to the printer.

TrayState

Bases: IntEnum

Operational status of the filament tray.

decodeError staticmethod

Python

decodeError(error: int) -> dict

Decodes a raw print_error integer into a full HMS dictionary.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def decodeError(error: int) -> dict:
    """
    Decodes a raw print_error integer into a full HMS dictionary.
    """
    if error == 0:
        return {}

    raw_hex = f"{error:08X}".upper()
    wiki_slug = "-".join(raw_hex[i : i + 4] for i in range(0, 8, 4))
    res = {
        "code": f"HMS_{wiki_slug}",
        "msg": "Unknown HMS Error",
        "module": "System",
        "severity": "Error",
        "is_critical": False,
        "type": "device_error",
        "url": f"https://e.bambulab.com/?e={raw_hex}",
    }

    real_module = (error >> 24) & 0xFF
    module_map = {
        0x03: "Mainboard",
        0x05: "AMS",
        0x12: "AMS",
        0x07: "Toolhead",
        0x0B: "Webcam",
        0x10: "HMS",
    }
    res["module"] = module_map.get(real_module, "System")

    msg_list = HMS_STATUS.get("data", {}).get("device_error", {}).get("en", [])
    modules = ["03", "05", "07", "0B", "0C", "10", "12"]
    if raw_hex[:2] in modules:
        modules.remove(raw_hex[:2])
    modules.insert(0, raw_hex[:2])

    for module in modules:
        current_hex = f"{module}{raw_hex[2:]}"
        for entry in msg_list:
            if entry.get("ecode", "").upper() == current_hex.upper():
                res["msg"] = entry.get("intro", res["msg"])
                break
        if res["msg"] != "Unknown HMS Error":
            break

    mask = (error >> 16) & 0xFF
    if mask in (0x00, 0x01):
        res["severity"] = "Fatal" if mask == 0x00 else "Error"
        res["is_critical"] = True
    elif mask == 0x02:
        res["severity"] = "Warning"
        res["is_critical"] = False
    else:
        res["severity"] = "Info"
        res["is_critical"] = False

    return res

decodeHMS staticmethod

Python

decodeHMS(hms_list: list) -> list[dict]

Decodes the raw HMS list from telemetry into a structured list of dictionaries.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def decodeHMS(hms_list: list) -> list[dict]:
    """
    Decodes the raw HMS list from telemetry into a structured list of dictionaries.
    """
    decoded_errors = []
    for item in hms_list:
        if isinstance(item, dict) and isinstance(item.get("code"), str):
            decoded_errors.append(item)
            continue
        try:
            attr = int(item.get("attr", 0))
            code = int(item.get("code", 0))
        except (AttributeError, ValueError, TypeError):
            continue
        if attr == 0:
            continue

        ecode = f"{attr:08X}{code:08X}"
        wiki_slug = "-".join(ecode[i : i + 4] for i in range(0, 16, 4))
        res = {
            "code": f"HMS_{wiki_slug}",
            "msg": "Unknown HMS Error",
            "module": "System",
            "severity": "Error",
            "is_critical": False,
            "type": "device_hms",
            "url": f"https://e.bambulab.com/?e={ecode}",
        }

        mid = (attr >> 24) & 0xFF
        mask = (attr >> 16) & 0xFF
        module_map = {
            0x03: "Mainboard",
            0x05: "AMS",
            0x12: "AMS",
            0x07: "Toolhead",
            0x0B: "Webcam",
            0x10: "HMS",
        }
        res["module"] = module_map.get(mid, "System")

        msg_list = HMS_STATUS.get("data", {}).get("device_hms", {}).get("en", [])
        for entry in msg_list:
            if entry.get("ecode", "").upper() == ecode:
                res["msg"] = entry.get("intro", res["msg"])
                break

        if mask in (0x00, 0x01):
            res["severity"], res["is_critical"] = (
                ("Fatal" if mask == 0x00 else "Error"),
                True,
            )
        elif mask == 0x02:
            res["severity"] = "Warning"
        else:
            res["severity"] = "Info"
        decoded_errors.append(res)
    return decoded_errors

getAMSModelBySerial staticmethod

Python

getAMSModelBySerial(serial: str) -> AMSModel

Returns the hardware model based on the serial number prefix.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def getAMSModelBySerial(serial: str) -> AMSModel:
    """
    Returns the hardware model based on the serial number prefix.
    """
    prefix = serial[:3].upper()
    if prefix == "19C":
        return AMSModel.AMS_2_PRO
    if prefix == "19F":
        return AMSModel.AMS_HT
    if prefix == "006":
        return AMSModel.AMS_1
    if prefix == "03C":
        return AMSModel.AMS_LITE
    return AMSModel.UNKNOWN

getAMSSeriesByModel staticmethod

Python

getAMSSeriesByModel(model: AMSModel) -> AMSSeries

Returns the AMS series enum based on the provided model.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def getAMSSeriesByModel(model: AMSModel) -> AMSSeries:
    """
    Returns the AMS series enum based on the provided model.
    """
    if model in (AMSModel.AMS_1, AMSModel.AMS_LITE):
        return AMSSeries.GEN_1
    if model in (AMSModel.AMS_HT, AMSModel.AMS_2_PRO):
        return AMSSeries.GEN_2
    return AMSSeries.UNKNOWN

getModelBySerial deprecated staticmethod

Python

getModelBySerial(serial: str) -> PrinterModel

Deprecated

This method is deprecated (v1.0.0). Use getPrinterModelBySerial.

Source code in src/bpm/bambutools.py

Python

@staticmethod
@deprecated("This method is deprecated (v1.0.0). Use `getPrinterModelBySerial`.")
def getModelBySerial(serial: str) -> PrinterModel:
    return getPrinterModelBySerial(serial)

getPrinterModelBySerial staticmethod

Python

getPrinterModelBySerial(serial: str) -> PrinterModel

Returns the Printer model enum based on the provided serial #.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def getPrinterModelBySerial(serial: str) -> PrinterModel:
    """
    Returns the Printer model enum based on the provided serial #.
    """
    mapping = {
        "00M": PrinterModel.X1C,
        "00W": PrinterModel.X1,
        "03W": PrinterModel.X1E,
        "01S": PrinterModel.P1P,
        "01P": PrinterModel.P1S,
        "030": PrinterModel.A1_MINI,
        "039": PrinterModel.A1,
        "22E": PrinterModel.P2S,
        "093": PrinterModel.H2S,
        "094": PrinterModel.H2D,
    }
    prefix = serial[:3]
    return mapping.get(prefix, PrinterModel.UNKNOWN)

getPrinterSeriesByModel staticmethod

Python

getPrinterSeriesByModel(model: PrinterModel) -> PrinterSeries

Returns the Printer series enum based on the provided model.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def getPrinterSeriesByModel(model: PrinterModel) -> PrinterSeries:
    """
    Returns the Printer series enum based on the provided model.
    """
    try:
        return PrinterSeries[model.name[:2]]
    except (KeyError, AttributeError):
        return PrinterSeries.UNKNOWN

getSeriesByModel deprecated staticmethod

Python

getSeriesByModel(model: PrinterModel) -> PrinterSeries

Deprecated

This method is deprecated (v1.0.0). Use getPrinterSeriesByModel.

Source code in src/bpm/bambutools.py

Python

@staticmethod
@deprecated("This method is deprecated (v1.0.0). Use `getPrinterSeriesByModel`.")
def getSeriesByModel(model: PrinterModel) -> PrinterSeries:
    return getPrinterSeriesByModel(model)

parseAMSInfo staticmethod

Python

parseAMSInfo(info_int: int) -> dict

Parses decimal bit-packed AMS info for status and feature reconciliation.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def parseAMSInfo(info_int: int) -> dict:
    """
    Parses decimal bit-packed AMS info for status and feature reconciliation.
    """
    return {
        "is_powered": bool(info_int & 1),
        "is_online": bool(info_int & 2),
        "rfid_ready": bool(info_int & 4),
        "hub_sensor_triggered": bool(info_int & 8),
        "circ_fan_on": bool(info_int & 16),
        "h2d_toolhead_index": (info_int >> 5) & 0x1,
        "exhaust_fan_on": bool(info_int & 64),
        "humidity_sensor_ok": bool((info_int & 128) or (info_int & 131072)),
        "heater_on": bool(info_int & 256),
        "motor_running": bool(info_int & 512),
        "is_rotating": bool(info_int & 1024),
        "venting_active": bool(info_int & 2048),
        "high_power_mode": bool(info_int & 8192),
        "hardware_fault": bool((info_int & 4096) or (info_int & 16384)),
    }

parseAMSStatus staticmethod

Python

parseAMSStatus(status_int: int) -> str

Maps the ams_status code to human-readable descriptions.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def parseAMSStatus(status_int: int) -> str:
    """
    Maps the ams_status code to human-readable descriptions.
    """
    main_status = (status_int >> 8) & 0xFF
    status_map = {
        0x00: "Idle",
        0x01: "Filament Changing",
        0x02: "RFID Identifying",
        0x03: "Assist/Engaged",
        0x04: "Calibration",
        0x10: "Self Check",
        0x20: "Debug",
        0xFF: "Unknown",
    }
    return status_map.get(main_status, "Idle")

parseExtruderInfo staticmethod

Python

parseExtruderInfo(info_int: int) -> ExtruderInfoState

Decodes the extruder 'info' bit-packed status using unique ExtruderInfoState names.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def parseExtruderInfo(info_int: int) -> ExtruderInfoState:
    """
    Decodes the extruder 'info' bit-packed status using unique ExtruderInfoState names.
    """
    if not (info_int & 0x08):
        return ExtruderInfoState.NO_NOZZLE
    if info_int & 0x02:
        return ExtruderInfoState.LOADED
    if info_int & 0x04:
        return ExtruderInfoState.BUFFER_LOADED
    return ExtruderInfoState.EMPTY

parseExtruderStatus staticmethod

Python

parseExtruderStatus(stat_int: int) -> ExtruderStatus

Decodes the operational extruder state using the exhaustive Enum map.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def parseExtruderStatus(stat_int: int) -> ExtruderStatus:
    """
    Decodes the operational extruder state using the exhaustive Enum map.
    """
    working_bits = (stat_int >> 8) & 0x03
    if working_bits in (0x02, 0x03):
        return ExtruderStatus.ACTIVE
    if stat_int & 0x01:
        return ExtruderStatus.HEATING
    return ExtruderStatus.IDLE

parseFan deprecated staticmethod

Python

parseFan(fan: int) -> int

Deprecated

This property is deprecated (v1.0.0). Use scaleFanSpeed.

Deprecated

This property is deprecated (v1.0.0). Use scaleFanSpeed.

Source code in src/bpm/bambutools.py

Python

@staticmethod
@deprecated("This property is deprecated (v1.0.0). Use `scaleFanSpeed`.")
def parseFan(fan: int) -> int:
    """
    !!! danger "Deprecated"
    This property is deprecated (v1.0.0). Use `scaleFanSpeed`.
    """
    fan_map = {
        1: 10,
        2: 20,
        3: 30,
        4: 30,
        5: 40,
        6: 40,
        7: 50,
        8: 50,
        9: 60,
        10: 70,
        11: 70,
        12: 80,
        13: 90,
        14: 90,
        15: 100,
    }
    return fan_map.get(int(fan), 0)

parseRFIDStatus staticmethod

Python

parseRFIDStatus(status)

Can be used to parse ams_rfid_status

Source code in src/bpm/bambutools.py

Python

@staticmethod
def parseRFIDStatus(status):
    """
    Can be used to parse `ams_rfid_status`
    """
    rfid_map = {
        0: "RFID Idle",
        1: "RFID Reading",
        2: "GCode Translating",
        3: "GCode Running",
        4: "RFID Assistant",
        5: "Switch Filament",
        6: "Has Filament",
    }
    return rfid_map.get(status, "Unknown")

parseStage staticmethod

Python

parseStage(stage_int: int) -> str

Maps stg_cur numeric codes to human-readable print stages.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def parseStage(stage_int: int) -> str:
    """
    Maps stg_cur numeric codes to human-readable print stages.
    """
    stage_map = {
        -1: "",
        0: "",
        1: "Auto bed leveling",
        2: "Heatbed preheating",
        3: "Sweeping XY mech mode",
        4: "Changing filament",
        5: "M400 pause",
        6: "Filament runout pause",
        7: "Heating hotend",
        8: "Calibrating extrusion",
        9: "Scanning bed surface",
        10: "Inspecting first layer",
        11: "Identifying build plate",
        12: "Calibrating Micro Lidar",
        13: "Homing toolhead",
        14: "Cleaning nozzle tip",
        15: "Temp check",
        16: "Paused by user",
        17: "Front cover falling",
        18: "Lidar calibration (alt)",
        19: "Calibrating flow",
        20: "Nozzle temp malfunction",
        21: "Bed temp malfunction",
        22: "Filament unloading",
        23: "Skip step pause",
        24: "Filament loading",
        25: "Motor noise calibration",
        26: "AMS lost pause",
        27: "Fan speed pause",
        28: "Chamber control error",
        29: "Cooling chamber",
        30: "Custom Gcode pause",
        31: "Motor noise showoff",
        32: "Nozzle cover pause",
        33: "Cutter error pause",
        34: "First layer error pause",
        35: "Nozzle clog pause",
        37: "Chamber control",
        38: "Chamber pre-heat (Legacy)",
        39: "Nozzle Offset Calibration",
        49: "Heating chamber",
        70: "Leading filament",
        71: "Reached toolhead",
        72: "Grabbing filament",
        73: "Purging",
        74: "Unloading",
        75: "Returning to AMS",
        76: "Cutting",
        77: "Tool switching",
        100: "Printing",
        255: "Completed",
    }
    return stage_map.get(stage_int, f"Stage [{stage_int}]")

scaleFanSpeed staticmethod

Python

scaleFanSpeed(raw_val: Any) -> int

Scales proprietary 0-15 fan speed values to a 0-100 percentage.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def scaleFanSpeed(raw_val: Any) -> int:
    """
    Scales proprietary 0-15 fan speed values to a 0-100 percentage.
    """
    try:
        val = int(raw_val)
        return min(max(round((val / 15.0) * 100), 0), 100)
    except Exception:
        return 0

sortFileTreeAlphabetically staticmethod

Python

sortFileTreeAlphabetically(source) -> dict

Sorts a dict of file/directory nodes hierarchically.

Source code in src/bpm/bambutools.py

Python

@staticmethod
def sortFileTreeAlphabetically(source) -> dict:
    """
    Sorts a dict of file/directory nodes hierarchically.
    """

    def sort_node_list(node_list):
        for item in node_list:
            if item.get("id", "").endswith("/") and "children" in item:
                item["children"] = sort_node_list(item["children"])
        return sorted(
            node_list,
            key=lambda i: (not i.get("id", "").endswith("/"), i.get("name", "").lower()),
        )

    source["children"] = sort_node_list(source["children"])
    return source

unpackTemperature staticmethod

Python

unpackTemperature(raw_temp: int) -> tuple[float, float]

Unpacks a 32-bit packed temperature integer into a tuple of (Actual, Target).

Source code in src/bpm/bambutools.py

Python

@staticmethod
def unpackTemperature(raw_temp: int) -> tuple[float, float]:
    """
    Unpacks a 32-bit packed temperature integer into a tuple of (Actual, Target).
    """
    return float(raw_temp & 0xFFFF), float((raw_temp >> 16) & 0xFFFF)