circuitpython-bambulabs 1.0.0__py3-none-any.whl

bambulabs.py

@@ -0,0 +1,306 @@
+# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
+# SPDX-FileCopyrightText: Copyright (c) 2026 Paul Cutler
+#
+# SPDX-License-Identifier: MIT
+"""
+`bambulabs`
+================================================================================
+
+A library to interface with a Bambu Labs 3D printer and query status.
+
+
+* Author(s): Paul Cutler
+
+Implementation Notes
+--------------------
+
+**Hardware:**
+
+Requires a Bambu Labs 3D printer and Bambu Labs Makerworld account.
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://circuitpython.org/downloads
+"""
+
+import json
+import os
+import time
+
+import adafruit_connection_manager
+import adafruit_minimqtt.adafruit_minimqtt as MQTT
+import wifi
+
+__version__ = "1.0.0"
+__repo__ = "https://github.com/prcutler/CircuitPython_bambulabs.git"
+
+# BAMBU MQTT settings - Bambu Cloud
+BAMBU_BROKER = os.getenv("BAMBU_BROKER")
+ACCESS_TOKEN = os.getenv("BAMBU_ACCESS_TOKEN")
+USER_ID = os.getenv("USER_ID")
+BAMBU_IP = os.getenv("BAMBU_IP")
+
+
+class PrinterStatus:
+    """Wraps the raw JSON dict returned by a ``pushall`` response and exposes
+    each printer field as a named, readable property.
+
+    All values come from the snapshot captured at the time ``pushall`` was
+    called.  Use :attr:`raw` to access the complete original dict.
+
+    :param data: The raw JSON dict received from the printer's report topic.
+    """
+
+    def __init__(self, data):
+        self._data = data
+        self._print = data.get("print", {})
+        self._info = data.get("info", {})
+        self._system = data.get("system", {})
+        self._upgrade = data.get("upgrade", {})
+
+    @property
+    def raw(self):
+        """The complete raw JSON dict from the printer."""
+        return self._data
+
+    # ---- Print state -------------------------------------------------------
+
+    @property
+    def gcode_state(self):
+        """Printer gcode state string (e.g. ``RUNNING``, ``PAUSE``, ``FINISH``)."""
+        return self._print.get("gcode_state")
+
+    @property
+    def print_percentage(self):
+        """Current print completion percentage (0–100)."""
+        return self._print.get("mc_percent")
+
+    @property
+    def remaining_time(self):
+        """Estimated remaining print time in minutes."""
+        return self._print.get("mc_remaining_time")
+
+    @property
+    def current_layer(self):
+        """Current layer number being printed."""
+        return self._print.get("layer_num")
+
+    @property
+    def total_layers(self):
+        """Total number of layers in the print job."""
+        return self._print.get("total_layer_num")
+
+    @property
+    def gcode_file(self):
+        """Filename of the currently active gcode file."""
+        return self._print.get("gcode_file")
+
+    @property
+    def subtask_name(self):
+        """Current print subtask / job name."""
+        return self._print.get("subtask_name")
+
+    @property
+    def print_speed(self):
+        """Print speed level (0=silent, 1=standard, 2=sport, 3=ludicrous)."""
+        return self._print.get("spd_lvl")
+
+    @property
+    def print_error_code(self):
+        """Current print error code, or ``0`` if none."""
+        return self._print.get("print_error")
+
+    # ---- Temperatures ------------------------------------------------------
+
+    @property
+    def nozzle_temperature(self):
+        """Current nozzle temperature in degrees Celsius."""
+        return self._print.get("nozzle_temper")
+
+    @property
+    def nozzle_temperature_target(self):
+        """Target nozzle temperature in degrees Celsius."""
+        return self._print.get("nozzle_target_temper")
+
+    @property
+    def bed_temperature(self):
+        """Current bed temperature in degrees Celsius."""
+        return self._print.get("bed_temper")
+
+    @property
+    def bed_temperature_target(self):
+        """Target bed temperature in degrees Celsius."""
+        return self._print.get("bed_target_temper")
+
+    @property
+    def chamber_temperature(self):
+        """Current chamber temperature in degrees Celsius."""
+        return self._print.get("chamber_temper")
+
+    # ---- Fan speeds --------------------------------------------------------
+
+    @property
+    def part_fan_speed(self):
+        """Part cooling fan speed (0–255)."""
+        return self._print.get("cooling_fan_speed")
+
+    @property
+    def aux_fan_speed(self):
+        """Auxiliary fan speed (0–255)."""
+        return self._print.get("big_fan1_speed")
+
+    @property
+    def chamber_fan_speed(self):
+        """Chamber fan speed (0–255)."""
+        return self._print.get("big_fan2_speed")
+
+    # ---- Nozzle ------------------------------------------------------------
+
+    @property
+    def nozzle_type(self):
+        """Installed nozzle type string (e.g. ``"brass"``)."""
+        return self._print.get("nozzle_type")
+
+    @property
+    def nozzle_diameter(self):
+        """Installed nozzle diameter in mm."""
+        return self._print.get("nozzle_diameter")
+
+    # ---- Filament / AMS ----------------------------------------------------
+
+    @property
+    def ams_status(self):
+        """AMS filament / tray status dict, or ``None`` if no AMS present."""
+        return self._print.get("ams")
+
+    @property
+    def vt_tray(self):
+        """External spool (virtual tray) properties dict."""
+        return self._print.get("vt_tray")
+
+    # ---- System ------------------------------------------------------------
+
+    @property
+    def wifi_signal(self):
+        """WiFi signal strength string (e.g. ``"-45dBm"``)."""
+        return self._print.get("wifi_signal")
+
+    @property
+    def light_state(self):
+        """Chamber light state list from the system ``lights_report`` field."""
+        return self._system.get("lights_report")
+
+    # ---- Firmware ----------------------------------------------------------
+
+    @property
+    def firmware_version(self):
+        """Current OTA firmware version string, or ``None`` if not present."""
+        modules = self._info.get("module", [])
+        for module in modules:
+            if isinstance(module, dict) and module.get("name") == "ota":
+                return module.get("sw_ver")
+        return None
+
+
+class BambuPrinter:
+    """Connect to a Bambu Labs printer over MQTT and query its status.
+
+    :param mqtt_client: A configured ``adafruit_minimqtt.MQTT`` instance.
+    :param serial_number: The printer's serial number, used to build MQTT topics.
+    :param response_timeout: Seconds to wait for a printer response (default 10).
+    """
+
+    def __init__(self, serial_number, response_timeout=10):
+        pool = adafruit_connection_manager.get_radio_socketpool(wifi.radio)
+        ssl_context = adafruit_connection_manager.get_radio_ssl_context(wifi.radio)
+
+        # Set up MQTT client
+        mqtt_client = MQTT.MQTT(
+            broker=BAMBU_BROKER,
+            port=8883,
+            username=USER_ID,
+            password=ACCESS_TOKEN,
+            socket_pool=pool,
+            ssl_context=ssl_context,
+            is_ssl=True,
+        )
+        self._mqtt = mqtt_client
+        self._serial = serial_number
+        self._response_timeout = response_timeout
+        self._report_topic = f"device/{serial_number}/report"
+        self._request_topic = f"device/{serial_number}/request"
+        self._last_response = None
+
+        self._mqtt.on_connect = self._on_connect
+        self._mqtt.on_message = self._on_message
+
+    # ---- Internal ----------------------------------------------------------
+
+    def _on_connect(self, client, _userdata, _flags, _rc):
+        client.subscribe(self._report_topic)
+
+    def _on_message(self, _client, _topic, message):
+        try:
+            data = json.loads(message)
+        except Exception:
+            return
+        self._last_response = data
+
+    def _send_and_wait(self, payload):
+        """Publish *payload* and block until the printer responds or timeout.
+
+        :returns: The raw JSON response dict, or ``None`` on timeout.
+        """
+        self._last_response = None
+        self._mqtt.publish(self._request_topic, json.dumps(payload))
+        deadline = time.monotonic() + self._response_timeout
+        while self._last_response is None and time.monotonic() < deadline:
+            self._mqtt.loop()
+            time.sleep(0.05)
+        return self._last_response
+
+    # ---- Connection --------------------------------------------------------
+
+    def connect(self):
+        """Establish the MQTT connection to the printer."""
+        print(f"Connecting to Bambu printer at {BAMBU_IP}...")
+        self._mqtt.connect()
+
+    def loop(self):
+        """Process pending MQTT messages. Call regularly in your main loop."""
+        self._mqtt.loop()
+
+    def loop_forever(self):
+        """Block and loop indefinitely, processing MQTT messages."""
+        self._mqtt.loop_forever()
+
+    def is_connected(self):
+        """Return ``True`` if the MQTT client is currently connected."""
+        return self._mqtt.is_connected()
+
+    # ---- Queries -----------------------------------------------------------
+
+    def pushall(self):
+        """Request a full state snapshot from the printer.
+
+        :returns: A :class:`PrinterStatus` instance, or ``None`` on timeout.
+        """
+        response = self._send_and_wait({"pushing": {"command": "pushall"}})
+        if response is not None:
+            return PrinterStatus(response)
+        return None
+
+    def get_version(self):
+        """Request hardware and firmware version information.
+
+        :returns: The raw JSON response dict, or ``None`` on timeout.
+        """
+        return self._send_and_wait({"info": {"sequence_id": "0", "command": "get_version"}})
+
+    def get_firmware_history(self):
+        """Request the firmware version history.
+
+        :returns: The raw JSON response dict, or ``None`` on timeout.
+        """
+        return self._send_and_wait({"upgrade": {"sequence_id": "0", "command": "get_history"}})

circuitpython_bambulabs-1.0.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: circuitpython-bambulabs
+Version: 1.0.0
+Summary: A library to interface with a Bambu Labs 3D printer and query status and information
+Author-email: Paul Cutler <paul@paulcutler.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/prcutler/CircuitPython_bambulabs
+Keywords: adafruit,blinka,circuitpython,micropython,bambulabs,mqtt,circuitpython,bambulabs
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: Adafruit-Blinka
+Requires-Dist: Adafruit_CircuitPython_MiniMQTT
+Provides-Extra: optional
+Dynamic: license-file
+
+Introduction
+============
+
+
+.. image:: https://readthedocs.org/projects/circuitpython-bambulabs/badge/?version=latest
+    :target: https://circuitpython-bambulabs.readthedocs.io/
+    :alt: Documentation Status
+
+
+
+.. image:: https://img.shields.io/discord/327254708534116352.svg
+    :target: https://adafru.it/discord
+    :alt: Discord
+
+
+.. image:: https://github.com/prcutler/CircuitPython_bambulabs/workflows/Build%20CI/badge.svg
+    :target: https://github.com/prcutler/CircuitPython_bambulabs/actions
+    :alt: Build Status
+
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+    :target: https://github.com/astral-sh/ruff
+    :alt: Code Style: Ruff
+
+A library to interface with a Bambu Labs 3D printer and query status and information
+
+
+Dependencies
+=============
+This driver depends on:
+
+* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+* `Adafruit_CircuitPython_MiniMQTT <https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT/>`_
+
+Please ensure all dependencies are available on the CircuitPython filesystem.
+This is easily achieved by downloading
+`the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_
+or individual libraries can be installed using
+`circup <https://github.com/adafruit/circup>`_.
+
+Installing from PyPI
+=====================
+.. note:: This library is not available on PyPI yet. Install documentation is included
+   as a standard element. Stay tuned for PyPI availability!
+
+
+On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
+PyPI <https://pypi.org/project/circuitpython-bambulabs/>`_.
+To install for current user:
+
+.. code-block:: shell
+
+    pip3 install circuitpython-bambulabs
+
+To install system-wide (this may be required in some cases):
+
+.. code-block:: shell
+
+    sudo pip3 install circuitpython-bambulabs
+
+To install in a virtual environment in your current project:
+
+.. code-block:: shell
+
+    mkdir project-name && cd project-name
+    python3 -m venv .venv
+    source .env/bin/activate
+    pip3 install circuitpython-bambulabs
+
+Installing to a Connected CircuitPython Device with Circup
+==========================================================
+
+Make sure that you have ``circup`` installed in your Python environment.
+Install it with the following command if necessary:
+
+.. code-block:: shell
+
+    pip3 install circup
+
+With ``circup`` installed and your CircuitPython device connected use the
+following command to install:
+
+.. code-block:: shell
+
+    circup install bambulabs
+
+Or the following command to update an existing version:
+
+.. code-block:: shell
+
+    circup update
+
+Obtaining Your Printer Credentials and Save in settings.toml
+============================================================
+
+#. Login to `MakerWorld <https://makerworld.com/>`_.
+#. Open the dev-tools (F12 in most browsers) and select
+   ``Application > Cookies > https://makerworld.com``.
+#. Copy the ``token`` string and save it as ``BAMBU_ACCESS_TOKEN`` in ``settings.toml``.
+#. Access `https://makerworld.com/api/v1/design-user-service/my/preference
+   <https://makerworld.com/api/v1/design-user-service/my/preference>`_ and copy
+   ``uid`` as ``USER_ID``.
+#. Access `https://makerworld.com/api/v1/iot-service/api/user/bind
+   <https://makerworld.com/api/v1/iot-service/api/user/bind>`_ and copy
+   ``dev_id`` as ``DEVICE_ID``.
+#. On your printer, go to Settings and obtain the IP address and copy it as
+   ``BAMBU_IP``.
+
+
+You will need a ``settings.toml`` file with the following to connect via MQTT:
+
+* CIRCUITPY_WIFI_SSID = "your_wifi_ssid"
+* CIRCUITPY_WIFI_PASSWORD = "your_wifi_password"
+* BAMBU_BROKER = os.getenv("BAMBU_BROKER")
+* ACCESS_TOKEN = os.getenv("BAMBU_ACCESS_TOKEN")
+* USER_ID = os.getenv("USER_ID")
+* DEVICE_ID = "your_printer_serial_number"
+* BAMBU_IP = "your_printer_IP_address"
+
+Misc. information
+=================
+
+This library queries your Bambu Labs 3D printer via the Bambu Cloud using MQTT 5.0.
+Local mode is not supported due to it using MQTT 3.1.1. Issuing commands to your
+Bambu printer is out of scope for this library.
+
+Usage Example
+=============
+
+.. code-block:: python
+
+    import json
+    import os
+
+    import wifi
+
+    import bambulabs as bl
+
+    # You will need a settings.toml file with the following to connect via MQTT:
+    # bambu_broker = os.getenv("BAMBU_BROKER")
+    # access_token = os.getenv("BAMBU_ACCESS_TOKEN")
+    # user_id = os.getenv("USER_ID")
+    # DEVICE_ID = "your_printer_serial_number"
+
+    # Set up networking
+    print("Connecting to AP...")
+    wifi.radio.connect(os.getenv("CIRCUITPY_WIFI_SSID"), os.getenv("CIRCUITPY_WIFI_PASSWORD"))
+    print(f"Connected to {os.getenv('CIRCUITPY_WIFI_SSID')}")
+    print(f"My IP address: {wifi.radio.ipv4_address}")
+
+    device_id = os.getenv("DEVICE_ID")
+
+    printer = bl.BambuPrinter(bl.BambuPrinter.__init__, device_id)
+    printer.connect()
+
+    status = printer.pushall()
+
+    if status is None:
+        print("Timed out waiting for pushall response.")
+    else:
+        # Print out each individual status
+        print("--- Printer Status ---")
+        print(f"State:             {status.gcode_state}")
+        print(f"File:              {status.gcode_file}")
+        print(f"Job:               {status.subtask_name}")
+        print(f"Progress:          {status.print_percentage}%")
+        print(f"Remaining:         {status.remaining_time} min")
+        print(f"Layer:             {status.current_layer} / {status.total_layers}")
+        print(f"Print speed:       {status.print_speed}")
+        print(f"Print error:       {status.print_error_code}")
+        print(f"Nozzle temp:       {status.nozzle_temperature} / {status.nozzle_temperature_target} C")
+        print(f"Bed temp:          {status.bed_temperature} / {status.bed_temperature_target} C")
+        print(f"Chamber temp:      {status.chamber_temperature} C")
+        print(f"Part fan:          {status.part_fan_speed}")
+        print(f"Aux fan:           {status.aux_fan_speed}")
+        print(f"Chamber fan:       {status.chamber_fan_speed}")
+        print(f"Nozzle type:       {status.nozzle_type}")
+        print(f"Nozzle diameter:   {status.nozzle_diameter} mm")
+        print(f"WiFi signal:       {status.wifi_signal}")
+        print(f"Light state:       {status.light_state}")
+        print(f"Firmware version:  {status.firmware_version}")
+        print()
+        # Print the entire JSON response
+        print("--- Raw JSON ---")
+        print(json.dumps(status.raw))
+
+
+Documentation
+=============
+API documentation for this library can be found on `Read the Docs <https://circuitpython-bambulabs.readthedocs.io/>`_.
+
+For information on building library documentation, please check out
+`this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.
+
+Contributing
+============
+
+Contributions are welcome! Please read our `Code of Conduct
+<https://github.com/prcutler/CircuitPython_bambulabs/blob/HEAD/CODE_OF_CONDUCT.md>`_
+before contributing to help this project stay welcoming.
+
+This library was created with the assistance of Claude.  (I know, I know...)

circuitpython_bambulabs-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+bambulabs.py,sha256=g0kfTNGWUyHECH-tOj9TGPm1OwgKwHYQ0yhU_uDmle8,9928
+circuitpython_bambulabs-1.0.0.dist-info/licenses/LICENSE,sha256=Maocfq0E-T2QKRxYKgtMbI4CSXO7GocYugv1-V3NJ7E,1078
+circuitpython_bambulabs-1.0.0.dist-info/METADATA,sha256=JC09RhXCQCMoRhj526FrM-_v5alZNYR0s5aJXKhxDWc,8017
+circuitpython_bambulabs-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+circuitpython_bambulabs-1.0.0.dist-info/top_level.txt,sha256=xZ8f7rtBtbUvYUfd7CMbLvyPgntgnNLcTUz4kQRRDQs,10
+circuitpython_bambulabs-1.0.0.dist-info/RECORD,,

circuitpython_bambulabs-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

circuitpython_bambulabs-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Paul Cutler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

circuitpython_bambulabs-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bambulabs