aiobambulab 0.0.1__tar.gz

aiobambulab-0.0.1/.gitignore

@@ -0,0 +1,122 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# OSX useful to ignore
+*.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# pyenv
+.python-version
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache
+
+# Visual Studio Code
+.vscode
+
+# IntelliJ Idea family of suites
+.idea
+*.iml
+
+## File-based project format:
+*.ipr
+*.iws
+
+## mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# PyBuilder
+target/
+
+# Cookiecutter
+output/
+python_boilerplate/
+
+# Node
+node_modules/
+
+# Deepcode AI
+.dccache

aiobambulab-0.0.1/LICENSE.md

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

aiobambulab-0.0.1/PKG-INFO

@@ -0,0 +1,336 @@
+Metadata-Version: 2.5
+Name: aiobambulab
+Version: 0.0.1
+Summary: Asynchronous Python client for Bambu Lab 3D printers on the local network
+Project-URL: Homepage, https://github.com/joostlek/python-bambulab
+Project-URL: Repository, https://github.com/joostlek/python-bambulab
+Project-URL: Documentation, https://github.com/joostlek/python-bambulab
+Project-URL: Bug Tracker, https://github.com/joostlek/python-bambulab/issues
+Project-URL: Changelog, https://github.com/joostlek/python-bambulab/releases
+Author-email: Joost Lekkerkerker <joostlek@outlook.com>
+Maintainer-email: Joost Lekkerkerker <joostlek@outlook.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: 3d printer,asyncio,bambu lab,bambulab,mqtt
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.13
+Requires-Dist: aiomqtt>=2.5.0
+Description-Content-Type: text/markdown
+
+# Python: Bambu Lab
+
+[![GitHub Release][releases-shield]][releases]
+[![Python Versions][python-versions-shield]][pypi]
+![Project Stage][project-stage-shield]
+![Project Maintenance][maintenance-shield]
+[![License][license-shield]](LICENSE.md)
+
+[![Build Status][build-shield]][build]
+[![Code Coverage][codecov-shield]][codecov]
+[![Code Smells][code-smells]][sonarcloud]
+
+Asynchronous Python client for Bambu Lab 3D printers on the local network.
+
+## About
+
+The client connects to the MQTT server that every Bambu Lab printer runs, and follows what the printer reports: the state of the print job, its progress, temperatures, and more. It does not use the Bambu Lab cloud.
+
+- Fully asynchronous, built on [aiomqtt](https://github.com/empicano/aiomqtt). No threads.
+- Push based: the printer tells the client what changed, and the client tells you.
+- Typed models and typed errors.
+- Verifies that it talks to your printer: it only accepts a certificate that Bambu Lab issued to the serial number you pass in.
+- Connects again by itself when the connection is lost.
+- Knows what the printer is doing in detail: the stage of the print job, fans, nozzle, errors, and the filament in each tray of an AMS.
+- Sends commands: pause, resume, or stop a print, set the speed profile, temperatures, and fans, switch the light, and more.
+- Gives you the camera: images for the printers that send images, and the address of the video stream for the printers that have one.
+- Finds the printers on your network.
+
+## Installation
+
+```bash
+pip install aiobambulab
+```
+
+## Usage
+
+### What you need
+
+- The IP address of the printer.
+- The serial number of the printer. It is not case sensitive.
+- The LAN access code of the printer.
+
+You find all three on the screen of the printer. The printer does not have to be in LAN only mode.
+
+### Finding printers
+
+A printer announces itself on the network every few seconds. `discover()` listens for that, so you do not have to look up the IP address and the serial number:
+
+```python
+from aiobambulab import discover
+
+for printer in await discover():
+    print(printer.serial, printer.host, printer.name)
+```
+
+It returns shortly after the last printer showed up, or after 15 seconds when there are none. The access code is not announced: that one you still read from the screen of the printer.
+
+Announcements do not cross routers, so this only finds printers on the same network.
+
+### Connecting
+
+```python
+import asyncio
+
+from aiobambulab import BambuLabClient
+
+
+async def main() -> None:
+    async with BambuLabClient("192.168.1.50", "01P00A000000001", "12345678") as client:
+        print(client.info.model_name, client.info.firmware_version)
+        print(client.state)
+
+        def on_change() -> None:
+            if not client.available:
+                print("The printer is gone")
+                return
+            print(client.state.print_state, client.state.progress)
+
+        remove_listener = client.add_listener(on_change)
+        await asyncio.sleep(3600)
+        remove_listener()
+
+
+asyncio.run(main())
+```
+
+`connect()`, which the context manager calls, returns once the client knows which printer it is and what its state is. From then on:
+
+- `client.info` is what the printer is: its model, firmware version, and hardware version.
+- `client.state` is what the printer is doing. A value is `None` when the printer does not report it. Temperatures are in whole degrees Celsius, like the printer shows them.
+- `client.available` is `False` while the connection is lost. The client keeps trying to connect again, and `client.state` keeps the last known state.
+- `client.error` is why the printer is not available, if that is known. The client keeps trying whatever the error is. An error like a rejected access code does not go away by itself, so act on it.
+- Listeners are called when the state, the info, or the availability changes.
+
+### State
+
+`client.state` is a `PrinterState`. Next to the print job and the temperatures, it holds:
+
+- `stage`: what the printer is doing right now, like leveling its bed, changing filament, or being paused because the filament ran out. See `PrintStage`.
+- `part_fan_speed`, `aux_fan_speed`, `chamber_fan_speed`, and `heatbreak_fan_speed`: the speed of each fan, as a percentage.
+- `print_error`: the code of what went wrong with the print job, like `0700_8006`.
+- `errors`: the problems the printer reports, each with the code that Bambu Lab calls an HMS code, and a severity.
+- `ams`: the AMS units, each with its humidity, its temperature, and its trays. A tray has the `Filament` that is in it, with its type, name, color, and what remains of it. `active` tells which tray the printer prints from.
+- `external_spool` and `external_spool_active`: the same for the spool that is not in an AMS.
+- `nozzle_diameter` and `nozzle_type`.
+- `timelapse_enabled` and `recording_enabled`: what the camera does during a print job.
+- `sd_card_present`.
+- `available_firmware_version`: the version the printer can update to, if there is one.
+
+The texts that go with the codes of errors are not part of this library. Bambu Lab publishes them.
+
+### Commands
+
+```python
+from aiobambulab import Fan, SpeedProfile
+
+await client.set_chamber_light(on=True)
+await client.pause_print()
+await client.resume_print()
+await client.stop_print()
+await client.set_speed_profile(SpeedProfile.SILENT)
+await client.set_nozzle_temperature(215)
+await client.set_bed_temperature(60)
+await client.set_fan_speed(Fan.PART_COOLING, 50)
+await client.set_timelapse(enabled=True)
+await client.set_recording(enabled=False)
+await client.skip_objects([206])
+await client.calibrate(bed_leveling=True)
+await client.home()
+await client.send_gcode("M400")
+await client.refresh()
+```
+
+Temperatures, fans, and homing are sent as G-code. Whether a printer accepts a G-code depends on its model and its firmware.
+
+A command raises `BambuLabConnectionError` when the printer is not connected. The printer does not confirm a command in a way to rely on: what it did shows in the state it reports afterwards.
+
+Newer firmware only accepts commands when the printer is in developer mode. `client.state.accepts_commands` tells whether it does. The light is the exception: the printer always accepts the command for it.
+
+### Camera
+
+Printers have one of two kinds of camera access, depending on the model.
+
+The A1 and P1 series, and the A2L, send images:
+
+```python
+if client.supports_camera_images:
+    image = await client.camera_image()  # A JPEG image
+```
+
+The first image takes a moment, because the connection to the camera only opens when you ask for an image. It stays open while you keep asking, so the next images come right away. It closes when you stop asking for 30 seconds, and on `disconnect()`.
+
+The other printers serve a video stream, when that is turned on on the printer:
+
+```python
+if (url := client.camera_stream_url) is not None:
+    ...  # An rtsps:// address for a video player. It holds the access code.
+```
+
+`client.state.camera_stream_enabled` is `None` for a printer without a video stream, and `False` when the stream is turned off on the printer.
+
+### Errors
+
+`connect()` raises one of these, all subclasses of `BambuLabError`:
+
+| Error                         | Meaning                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------- |
+| `BambuLabAuthenticationError` | The printer rejected the access code.                                     |
+| `BambuLabSerialMismatchError` | The printer at this address has another serial number.                    |
+| `BambuLabCertificateError`    | The device at this address has no certificate issued by Bambu Lab.        |
+| `BambuLabConnectionError`     | The printer could not be reached, or it did not report its state in time. |
+
+`BambuLabSerialMismatchError` is a `BambuLabCertificateError`, which is a `BambuLabConnectionError`. Catch the specific ones first.
+
+### TLS
+
+A printer serves a certificate that Bambu Lab issued to its serial number. By default, the client only trusts the certificate authorities of Bambu Lab, and checks the serial number in the certificate before it sends the access code.
+
+To decide this yourself, pass your own `ssl.SSLContext` as `ssl_context`.
+
+Creating the default context reads files from disk. The client does that in an executor. To create it yourself, for example to reuse it, call `create_ssl_context(serial)` in an executor.
+
+## What is not in this library
+
+- Anything that goes through the Bambu Lab cloud.
+- Starting a print job, and everything else that needs the files on the printer: uploading, the cover image of a print job, and downloading a timelapse.
+- Loading and unloading filament, and drying it in an AMS.
+- The second nozzle of a printer with two: temperatures are those of the nozzle in use.
+- What only a few models have, like a laser, a cutter, a door sensor, or an air filter.
+- Updating the firmware.
+
+## Changelog & Releases
+
+This repository keeps a change log using [GitHub's releases][releases]
+functionality. The format of the log is based on
+[Keep a Changelog][keepchangelog].
+
+Releases are based on [Semantic Versioning][semver], and use the format
+of `MAJOR.MINOR.PATCH`. In a nutshell, the version will be incremented
+based on the following:
+
+- `MAJOR`: Incompatible or major changes.
+- `MINOR`: Backwards-compatible new features and enhancements.
+- `PATCH`: Backwards-compatible bugfixes and package updates.
+
+## Contributing
+
+This is an active open-source project. We are always open to people who want to
+use the code or contribute to it.
+
+We've set up a separate document for our
+[contribution guidelines](.github/CONTRIBUTING.md).
+
+Thank you for being involved! :heart_eyes:
+
+## Setting up development environment
+
+This Python project is fully managed using the [uv][uv] dependency manager. But also relies on the use of NodeJS for certain checks during development.
+
+You need at least:
+
+- Python 3.13+
+- [uv][uv-install]
+- NodeJS 12+ (including NPM)
+
+To install all packages, including all development requirements:
+
+```bash
+npm install
+uv sync --all-groups
+```
+
+As this repository uses the [prek][prek] framework, all changes
+are linted and tested with each commit. You can run all checks and tests
+manually, using the following command:
+
+```bash
+uv run prek run --all-files
+```
+
+To run just the Python tests:
+
+```bash
+uv run pytest
+```
+
+The tests run the client against a fake printer: a small MQTT server over TLS, in `tests/fake_printer.py`. Nothing in the tests is mocked between the client and the network.
+
+## Credits
+
+The protocol of the printers is not documented by Bambu Lab. This library builds on what others found out and wrote down:
+
+- [OpenBambuAPI](https://github.com/Doridian/OpenBambuAPI), the community documentation of the protocol.
+- [ha-bambulab](https://github.com/greghesp/ha-bambulab), the custom integration for Home Assistant. The certificate authorities in `src/aiobambulab/certs/bambulab.pem` are the ones of Bambu Lab that this project collected.
+
+This library is not affiliated with or endorsed by Bambu Lab.
+
+## Authors & contributors
+
+The content is by [Joost Lekkerkerker][joostlek].
+
+For a full list of all authors and contributors,
+check [the contributor's page][contributors].
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Joost Lekkerkerker
+
+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.
+
+[build-shield]: https://github.com/joostlek/python-bambulab/actions/workflows/tests.yaml/badge.svg
+[build]: https://github.com/joostlek/python-bambulab/actions
+[code-smells]: https://sonarcloud.io/api/project_badges/measure?project=joostlek_python-bambulab&metric=code_smells
+[codecov-shield]: https://codecov.io/gh/joostlek/python-bambulab/branch/main/graph/badge.svg
+[codecov]: https://codecov.io/gh/joostlek/python-bambulab
+[contributors]: https://github.com/joostlek/python-bambulab/graphs/contributors
+[joostlek]: https://github.com/joostlek
+[keepchangelog]: http://keepachangelog.com/en/1.0.0/
+[license-shield]: https://img.shields.io/github/license/joostlek/python-bambulab.svg
+[maintenance-shield]: https://img.shields.io/maintenance/yes/2026.svg
+[uv-install]: https://docs.astral.sh/uv/getting-started/installation/
+[uv]: https://docs.astral.sh/uv/
+[prek]: https://prek.j178.dev/
+[project-stage-shield]: https://img.shields.io/badge/project%20stage-beta-yellow.svg
+[python-versions-shield]: https://img.shields.io/pypi/pyversions/aiobambulab
+[releases-shield]: https://img.shields.io/github/release/joostlek/python-bambulab.svg
+[releases]: https://github.com/joostlek/python-bambulab/releases
+[semver]: http://semver.org/spec/v2.0.0.html
+[sonarcloud]: https://sonarcloud.io/summary/new_code?id=joostlek_python-bambulab
+[pypi]: https://pypi.org/project/aiobambulab/