bambu-local 0.1.0__tar.gz

bambu_local-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,41 @@
+# 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/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bambu-local"
+version = "0.1.0"
+description = "Read a Bambu Lab printer's report, send it commands and put files on it, over the LAN with no cloud and no dependencies."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Konstantinos Georgiou" }]
+dependencies = []
+keywords = ["bambu", "bambu-lab", "3d-printing", "mqtt", "ftps", "lan"]
+classifiers = ["Programming Language :: Python :: 3", "Topic :: Printing"]
+
+[project.urls]
+Homepage = "https://github.com/drkostas/bambu.local"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+bambu_local = ["skill/SKILL.md"]

bambu_local-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bambu_local-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/bambu_local.egg-info/PKG-INFO

@@ -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/src/bambu_local.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/bambu_local/__init__.py
+src/bambu_local/printer.py
+src/bambu_local/storage.py
+src/bambu_local.egg-info/PKG-INFO
+src/bambu_local.egg-info/SOURCES.txt
+src/bambu_local.egg-info/dependency_links.txt
+src/bambu_local.egg-info/requires.txt
+src/bambu_local.egg-info/top_level.txt
+src/bambu_local/skill/SKILL.md
+tests/test_printer.py
+tests/test_storage.py

bambu_local-0.1.0/src/bambu_local.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bambu_local-0.1.0/src/bambu_local.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=8

bambu_local-0.1.0/src/bambu_local.egg-info/top_level.txt

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

bambu_local-0.1.0/tests/test_printer.py

@@ -0,0 +1,92 @@
+"""The hand-written MQTT, checked against the specification. No printer is needed."""
+import json
+import struct
+
+import bambu_local
+from bambu_local import printer as P
+
+
+class FakeSock:
+    def __init__(self, script: bytes):
+        self.data = script
+
+    def recv(self, n):
+        chunk, self.data = self.data[:n], self.data[n:]
+        return chunk                           # b"" for ever once spent, as a closed TLS socket does
+
+
+def publish(obj: dict) -> bytes:
+    body = struct.pack("!H", 5) + b"topic" + json.dumps(obj).encode()
+    return bytes([0x30]) + P._remaining_length(len(body)) + body
+
+
+def test_remaining_length_at_its_boundaries():
+    assert P._remaining_length(0) == b"\x00"
+    assert P._remaining_length(127) == b"\x7f"
+    assert P._remaining_length(128) == b"\x80\x01"
+    assert P._remaining_length(16383) == b"\xff\x7f"
+    assert P._remaining_length(16384) == b"\x80\x80\x01"
+    assert P._remaining_length(9654) == b"\xb6\x4b"
+
+
+def test_remaining_length_reads_back_what_it_writes():
+    for n in (0, 127, 128, 9654, 16384, 2097152):
+        assert P._read_remaining_length(FakeSock(P._remaining_length(n))) == n
+
+
+def test_string_carries_its_length():
+    assert P._string("MQTT") == b"\x00\x04MQTT"
+    assert P._string("") == b"\x00\x00"
+
+
+def test_connect_packet_shape():
+    packet = P._connect_packet("12345678")
+    assert packet[0] == 0x10
+    body = packet[2:]
+    assert packet[1] == len(body)
+    assert body[:6] == b"\x00\x04MQTT"
+    assert body[6] == 4                        # MQTT 3.1.1
+    assert body[7] == 0xC0                     # a username and a password follow
+    assert struct.unpack("!H", body[8:10])[0] == 60
+    assert body.endswith(P._string("bblp") + P._string("12345678"))
+
+
+def test_credentials_reads_the_first_pair(tmp_path):
+    conf = tmp_path / "BambuStudio.conf"
+    conf.write_text(json.dumps({"access_code": {"": "x", "SERIAL1": 12345678}}))
+    assert bambu_local.credentials(conf) == ("SERIAL1", "12345678")
+
+
+def test_credentials_finds_nothing_without_raising(tmp_path):
+    assert bambu_local.credentials(tmp_path / "absent.conf") is None
+    bad = tmp_path / "bad.conf"
+    bad.write_text("not json")
+    assert bambu_local.credentials(bad) is None
+    empty = tmp_path / "empty.conf"
+    empty.write_text("{}")
+    assert bambu_local.credentials(empty) is None
+
+
+def test_a_packet_cut_off_mid_body_returns_and_does_not_spin():
+    cut = bytes([0x90]) + P._remaining_length(50) + b"only ten b"
+    assert P._read_reports(FakeSock(cut), deadline=float("inf")) == {}
+
+
+def test_deltas_merge_and_the_read_stops_once_the_state_is_known():
+    script = publish({"print": {"bed_temper": 20}}) + publish({"print": {"gcode_state": "IDLE"}}) \
+        + publish({"print": {"bed_temper": 99}})
+    got = P._read_reports(FakeSock(script), deadline=float("inf"))
+    assert got == {"print": {"bed_temper": 20, "gcode_state": "IDLE"}}
+
+
+def test_a_printer_that_never_says_its_state_is_cut_off_at_the_deadline():
+    ticks = iter(range(1000))
+    got = P._read_reports(FakeSock(publish({"print": {"bed_temper": 20}}) * 200), deadline=5,
+                          clock=lambda: next(ticks))
+    assert got == {"print": {"bed_temper": 20}}
+
+
+def test_a_message_that_is_not_json_is_skipped():
+    body = struct.pack("!H", 1) + b"t" + b"not json"
+    script = bytes([0x30]) + P._remaining_length(len(body)) + body + publish({"print": {"gcode_state": "RUNNING"}})
+    assert P._read_reports(FakeSock(script), deadline=float("inf"))["print"]["gcode_state"] == "RUNNING"

bambu_local-0.1.0/tests/test_storage.py

@@ -0,0 +1,30 @@
+"""Reading the printer's file list. `test_live_round_trip` needs a printer and is skipped without one."""
+import os
+
+import pytest
+
+import bambu_local
+from bambu_local import storage as S
+
+
+def test_parse_list_takes_files_and_leaves_folders_out():
+    lines = ["-rwxr-xr-x 1 root root 1048576 Nov 01 10:00 a card.gcode.3mf",
+             "drwxr-xr-x 2 root root 4096 Nov 01 10:00 cache",
+             "total 8",
+             "-rw-r--r-- 1 root root 0 Jan 02 2026 empty.txt"]
+    assert S._parse_list(lines) == [{"name": "a card.gcode.3mf", "size": 1048576},
+                                    {"name": "empty.txt", "size": 0}]
+
+
+@pytest.mark.skipif("BAMBU_HOST" not in os.environ or "BAMBU_CODE" not in os.environ,
+                    reason="needs BAMBU_HOST and BAMBU_CODE")
+def test_live_round_trip(tmp_path):
+    host, code = os.environ["BAMBU_HOST"], os.environ["BAMBU_CODE"]
+    local = tmp_path / "bambu-local-test.txt"
+    local.write_bytes(b"bambu-local round trip\n")
+    assert bambu_local.upload(host, code, local) == {"name": local.name, "size": local.stat().st_size}
+    try:
+        assert local.name in [f["name"] for f in bambu_local.files(host, code)]
+    finally:
+        bambu_local.delete(host, code, f"/{local.name}")
+    assert local.name not in [f["name"] for f in bambu_local.files(host, code)]