bambu-local 0.1.0__py3-none-any.whl

bambu_local/__init__.py

@@ -0,0 +1,6 @@
+"""Talk to a Bambu Lab printer over the LAN, with no cloud and no dependencies."""
+from .printer import MQTT_PORT, command, credentials, report
+from .storage import FTPS_PORT, delete, files, upload
+
+__version__ = "0.1.0"
+__all__ = ["FTPS_PORT", "MQTT_PORT", "command", "credentials", "delete", "files", "report", "upload"]

bambu_local/printer.py

@@ -0,0 +1,172 @@
+"""A printer's report and commands, over the MQTT broker it runs on port 8883.
+
+The printer answers a `pushall` request with its whole state, and that is the only interface that
+says what it is doing. Only the part of MQTT this needs is written here (connect, subscribe, publish
+once, read publishes), so nothing has to install on a machine that runs this unattended. It has QoS 0
+only, with no keepalive, reconnect or will, because a caller asks one question and goes away. If the
+printer is off, the connect fails, and that failure is the answer.
+
+The printer's certificate is its own and cannot be checked against a public authority, so TLS here
+protects the access code from a passive listener only. Use this on a network you trust.
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+import socket
+import ssl
+import struct
+import time
+
+#: where Bambu Studio keeps the serial to access-code pairs on macOS, and on Linux and Windows
+STUDIO_CONFS = (
+    pathlib.Path.home() / "Library/Application Support/BambuStudio/BambuStudio.conf",
+    pathlib.Path.home() / ".config/BambuStudio/BambuStudio.conf",
+    pathlib.Path.home() / "AppData/Roaming/BambuStudio/BambuStudio.conf",
+)
+MQTT_PORT = 8883
+CLIENT_ID = "bambu-local"
+USER = "bblp"
+
+
+def credentials(conf: str | pathlib.Path | None = None) -> tuple[str, str] | None:
+    """The first printer Bambu Studio is paired with, as (serial, access code), or None. Reading them
+    from there means a code changed on the printer is picked up by pairing again in the app."""
+    for path in ([pathlib.Path(conf)] if conf else STUDIO_CONFS):
+        try:
+            pairs = json.loads(path.read_text()).get("access_code") or {}
+        except (OSError, ValueError, AttributeError):
+            continue
+        for serial, code in pairs.items():
+            if serial and code:
+                return serial, str(code)
+    return None
+
+
+def _remaining_length(n: int) -> bytes:
+    """MQTT's variable-byte integer: seven bits a byte, and the high bit means another follows."""
+    out = b""
+    while True:
+        byte = n % 128
+        n //= 128
+        out += bytes([byte | (0x80 if n else 0)])
+        if not n:
+            return out
+
+
+def _read_remaining_length(sock) -> int:
+    multiplier, value = 1, 0
+    while True:
+        byte = sock.recv(1)
+        if not byte:
+            raise ConnectionError("broker closed while reading a length")
+        value += (byte[0] & 127) * multiplier
+        if not byte[0] & 0x80:
+            return value
+        multiplier *= 128
+        if multiplier > 128 ** 3:
+            raise ValueError("malformed remaining length")
+
+
+def _string(s: str) -> bytes:
+    raw = s.encode()
+    return struct.pack("!H", len(raw)) + raw
+
+
+def _connect_packet(code: str, client_id: str = CLIENT_ID) -> bytes:
+    """CONNECT at protocol level 4 (MQTT 3.1.1), with a username, a password and a 60 s keepalive."""
+    body = _string("MQTT") + bytes([4, 0xC0]) + struct.pack("!H", 60) \
+        + _string(client_id) + _string(USER) + _string(code)
+    return bytes([0x10]) + _remaining_length(len(body)) + body
+
+
+def _publish_packet(topic: str, message: dict) -> bytes:
+    body = _string(topic) + json.dumps(message).encode()
+    return bytes([0x30]) + _remaining_length(len(body)) + body
+
+
+def _connect(host: str, code: str, timeout: float, port: int = MQTT_PORT):
+    """Open a TLS socket and complete an MQTT CONNECT, or raise. The caller closes it."""
+    context = ssl.create_default_context()
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_NONE
+    raw = socket.create_connection((host, port), timeout=timeout)
+    sock = context.wrap_socket(raw, server_hostname=host)
+    try:
+        sock.settimeout(timeout)
+        sock.sendall(_connect_packet(code))
+        kind = sock.recv(1)
+        if not kind or kind[0] >> 4 != 2:
+            raise ConnectionError("no CONNACK from the printer")
+        connack = sock.recv(_read_remaining_length(sock))
+        if len(connack) >= 2 and connack[1] != 0:
+            raise PermissionError(f"printer refused the connection (code {connack[1]})")
+    except Exception:
+        sock.close()
+        raise
+    return sock
+
+
+def report(host: str, serial: str, code: str, *, timeout: float = 20.0) -> dict:
+    """Connect, ask for everything, and return the merged report, or {} if the printer says nothing.
+
+    The whole read is bounded by twice `timeout`, so a printer that keeps talking without giving its
+    state cannot hold the caller."""
+    with _connect(host, code, timeout) as sock:
+        sub = struct.pack("!H", 1) + _string(f"device/{serial}/report") + bytes([0])
+        sock.sendall(bytes([0x82]) + _remaining_length(len(sub)) + sub)
+        kind = sock.recv(1)
+        if kind and kind[0] >> 4 == 9:
+            sock.recv(_read_remaining_length(sock))
+        sock.sendall(_publish_packet(f"device/{serial}/request",
+                                     {"pushing": {"sequence_id": "1", "command": "pushall"}}))
+        return _read_reports(sock, deadline=time.monotonic() + 2 * timeout)
+
+
+def _read_reports(sock, deadline: float, clock=None) -> dict:
+    """Read MQTT packets and merge the report publishes one level deep (later ones are deltas), until
+    the printer has said what it is doing, it closes, a read times out, or `deadline` passes.
+
+    An empty read ends the loop: a closed TLS socket returns b"" for ever, so a loop that waits for a
+    byte count would spin at full CPU."""
+    clock = clock or time.monotonic
+    merged: dict = {}
+    while clock() < deadline:
+        try:
+            kind = sock.recv(1)
+        except (TimeoutError, socket.timeout):
+            break
+        if not kind:
+            break
+        try:
+            remaining = _read_remaining_length(sock)
+        except (ConnectionError, ValueError):
+            break
+        buf = b""
+        while len(buf) < remaining:
+            chunk = sock.recv(min(65536, remaining - len(buf)))
+            if not chunk:
+                return merged
+            buf += chunk
+        if kind[0] >> 4 != 3:                  # not a PUBLISH: its body is read, and skipped
+            continue
+        topic_len = struct.unpack("!H", buf[:2])[0]
+        try:
+            message = json.loads(buf[2 + topic_len:])
+        except ValueError:
+            continue
+        for key, value in message.items():
+            if isinstance(value, dict):
+                merged.setdefault(key, {}).update(value)
+            else:
+                merged[key] = value
+        if merged.get("print", {}).get("gcode_state") is not None:
+            break
+    return merged
+
+
+def command(host: str, serial: str, code: str, payload: dict, *, timeout: float = 15.0) -> None:
+    """Send one command and return. Nothing here confirms it worked: at QoS 0 the broker accepts the
+    publish whether or not the firmware acts on it, so read `report` afterwards and compare."""
+    with _connect(host, code, timeout) as sock:
+        sock.sendall(_publish_packet(f"device/{serial}/request", payload))

bambu_local/skill/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: bambu.local
+description: Use when reading a Bambu Lab printer's state, sending it a command, or putting a sliced file on its storage over the local network, with no cloud account. Python package `bambu-local`, imported as `bambu_local`. Also use when a connection to the printer fails with "No route to host" or is refused.
+---
+
+# Talking to a Bambu Lab printer on the LAN
+
+```python
+import bambu_local as bambu
+serial, code = bambu.credentials()     # from Bambu Studio's file, or pass your own
+state = bambu.report(host, serial, code)
+state["print"]["gcode_state"], state["print"].get("print_error"), state["print"].get("layer_num")
+```
+
+## Rules
+
+- Never print or log the access code.
+- `upload` starts nothing. Starting a print is the person's decision, so ask first.
+- `command` does not confirm anything. Read `report` afterwards and compare.
+- `delete` cannot be undone. Look at the name in `files` first.
+- A printer that is off fails to connect, and that is the answer. Do not read it as a failed print.
+
+## Reading a stop
+
+`gcode_state` FAILED with `print_error` names the cause. The number in hexadecimal is the code in Bambu's error list (`0x05FF803C` is written 05FF-803C). `layer_num` 0 means nothing was laid down.
+
+## When it does not connect
+
+- `[Errno 65] No route to host` while `ping` answers means macOS refused this program the local network. The setting is the person's, under Privacy & Security, Local Network.
+- `PermissionError` means the access code is wrong. The code changes when it is reset on the printer.
+- A timeout means the printer is off, asleep or on another network.

bambu_local/storage.py

@@ -0,0 +1,104 @@
+"""The printer's own storage, over implicit FTPS on port 990.
+
+A file put here starts nothing. The printer lists it on its screen and a person presses print, or a
+`project_file` command starts it. The login is the user `bblp` and the printer's access code. The data
+connection must reuse the control connection's TLS session or the printer refuses it, which plain
+`ftplib.FTP_TLS` does not do. The certificate cannot be checked, as with `bambu_local.printer`.
+"""
+from __future__ import annotations
+
+import ftplib
+import os
+import pathlib
+import socket
+import ssl
+
+from .printer import USER
+
+FTPS_PORT = 990
+
+
+class _ImplicitFTPS(ftplib.FTP_TLS):
+    """FTP_TLS that opens with TLS at once and reuses that session on each data connection."""
+
+    def connect(self, host="", port=FTPS_PORT, timeout=60.0, source_address=None):
+        self.host, self.port, self.timeout = host, port, timeout
+        raw = socket.create_connection((host, port), timeout)
+        self.sock = self.context.wrap_socket(raw, server_hostname=host)
+        self.af = self.sock.family
+        self.file = self.sock.makefile("r", encoding=self.encoding)
+        self.welcome = self.getresp()
+        return self.welcome
+
+    def ntransfercmd(self, cmd, rest=None):
+        conn, size = ftplib.FTP.ntransfercmd(self, cmd, rest)
+        if self._prot_p:
+            conn = self.context.wrap_socket(conn, server_hostname=self.host, session=self.sock.session)
+        return conn, size
+
+
+def _open(host: str, code: str, timeout: float, port: int = FTPS_PORT) -> _ImplicitFTPS:
+    context = ssl.create_default_context()
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_NONE
+    ftp = _ImplicitFTPS(context=context)
+    ftp.connect(host, port, timeout)
+    try:
+        ftp.login(USER, code, secure=False)
+        ftp.prot_p()
+    except Exception:
+        ftp.close()
+        raise
+    return ftp
+
+
+def _parse_list(lines: list[str]) -> list[dict]:
+    """Unix `LIST` lines -> [{"name", "size"}], folders left out."""
+    out = []
+    for line in lines:
+        parts = line.split(None, 8)
+        if len(parts) == 9 and parts[4].isdigit() and not line.startswith("d"):
+            out.append({"name": parts[8], "size": int(parts[4])})
+    return out
+
+
+def files(host: str, code: str, folder: str = "/", *, timeout: float = 60.0) -> list[dict]:
+    """The files in `folder` on the printer, as [{"name", "size"}]."""
+    ftp = _open(host, code, timeout)
+    try:
+        lines: list[str] = []
+        ftp.retrlines(f"LIST {folder}", lines.append)
+        return _parse_list(lines)
+    finally:
+        ftp.close()
+
+
+def upload(host: str, code: str, local: str | os.PathLike, remote: str | None = None, *,
+           timeout: float = 300.0) -> dict:
+    """Copy `local` to `remote` on the printer (its own name in the top folder by default), starting
+    nothing. Raises unless the printer then lists it at the same size. Returns {"name", "size"}."""
+    path = pathlib.Path(local)
+    remote = remote or f"/{path.name}"
+    size = path.stat().st_size
+    ftp = _open(host, code, timeout)
+    try:
+        with path.open("rb") as f:
+            ftp.storbinary(f"STOR {remote}", f)
+        folder, _, name = remote.rpartition("/")
+        lines: list[str] = []
+        ftp.retrlines(f"LIST {folder or '/'}", lines.append)
+    finally:
+        ftp.close()
+    for entry in _parse_list(lines):
+        if entry["name"] == name and entry["size"] == size:
+            return entry
+    raise OSError(f"{remote} is not on the printer at {size} bytes after the upload")
+
+
+def delete(host: str, code: str, remote: str, *, timeout: float = 60.0) -> None:
+    """Remove one file from the printer's storage. This cannot be undone."""
+    ftp = _open(host, code, timeout)
+    try:
+        ftp.delete(remote)
+    finally:
+        ftp.close()

bambu_local-0.1.0.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: bambu-local
+Version: 0.1.0
+Summary: Read a Bambu Lab printer's report, send it commands and put files on it, over the LAN with no cloud and no dependencies.
+Author: Konstantinos Georgiou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/drkostas/bambu.local
+Keywords: bambu,bambu-lab,3d-printing,mqtt,ftps,lan
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Printing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# bambu.local
+
+Talk to a Bambu Lab printer over your own network, with no cloud account and no dependencies.
+
+```bash
+pip install bambu-local
+```
+
+```python
+import bambu_local as bambu
+
+serial, code = bambu.credentials()          # the pair Bambu Studio saved, or pass your own
+state = bambu.report("192.0.2.10", serial, code)
+print(state["print"]["gcode_state"])        # IDLE, RUNNING, PAUSE, FINISH or FAILED
+
+bambu.upload("192.0.2.10", code, "card.gcode.3mf")   # shows on the printer's screen, starts nothing
+print(bambu.files("192.0.2.10", code))
+```
+
+The access code is on the printer's screen under its network settings.
+
+## What it does
+
+- `report(host, serial, code)` asks the printer for its whole state over MQTT on port 8883.
+- `command(host, serial, code, payload)` sends one command. It does not confirm the command worked, so read `report` afterwards and compare.
+- `upload`, `files` and `delete` use the printer's storage over implicit FTPS on port 990. `upload` checks that the printer lists the file at the same size.
+- `credentials(conf=None)` reads the first serial and access code from Bambu Studio's configuration file.
+
+## What it does not do
+
+It holds no session, so it has no keepalive and no reconnect. It speaks MQTT at QoS 0 only. It is not a general MQTT or FTP library.
+
+The printer's certificate cannot be checked against a public authority, so the connection protects the access code from a passive listener only. Use it on a network you trust.
+
+## On macOS
+
+macOS can refuse a program access to the local network with `[Errno 65] No route to host`, while other programs on the same Mac reach the printer. If `ping` answers and Python does not, look at Privacy & Security, Local Network in System Settings.
+
+## Tested with
+
+A Bambu Lab X2D. Other models use the same ports, but only this one has been tried.

bambu_local-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+bambu_local/__init__.py,sha256=0tndocdJ9lRZ-xcdzVQIu5QPuyl8Dky4rtGWbPucOhw,323
+bambu_local/printer.py,sha256=JU4hBobTucNvARGmcMqfLU42Gms8-uI7o19ZD7bVDDc,7029
+bambu_local/storage.py,sha256=Y3AfC-qepJJtQGkACX1ewNtMDU28MBiGUJZ25CCrxc0,3816
+bambu_local/skill/SKILL.md,sha256=nL91pFgDPV8-IUxqzT1y_5nBPIicLZM39h83lT9yLRA,1615
+bambu_local-0.1.0.dist-info/licenses/LICENSE,sha256=y2yT4XOJ5hjMzENqKJShtqLiwI-IE1PnWqMxbhhL5r8,1078
+bambu_local-0.1.0.dist-info/METADATA,sha256=Pu_Jx9MZU7GElwB9uUiUYVzwLij1P8wGm_pfdiQhf0o,2444
+bambu_local-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+bambu_local-0.1.0.dist-info/top_level.txt,sha256=5D9RJZstyl-CcgLhXIZoERjG3aAcUomhrEAUUJ0W3Hw,12
+bambu_local-0.1.0.dist-info/RECORD,,

bambu_local-0.1.0.dist-info/WHEEL

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

bambu_local-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konstantinos Georgiou
+
+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.

bambu_local-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bambu_local