anycubic-lan 0.1.0__tar.gz

anycubic_lan-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

anycubic_lan-0.1.0/LICENSE

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

anycubic_lan-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: anycubic-lan
+Version: 0.1.0
+Summary: Async client for Anycubic 3D printers in LAN Mode (local MQTT, no cloud).
+Project-URL: Source, https://github.com/Nino6689/anycubic-lan
+Project-URL: Issues, https://github.com/Nino6689/anycubic-lan/issues
+Author: Nino Bondonno
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d-printer,anycubic,asyncio,home-assistant,mqtt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.10
+Requires-Dist: cryptography>=43
+Requires-Dist: paho-mqtt>=2.1
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# anycubic-lan
+
+Talk to an Anycubic 3D printer in **LAN Mode**, directly on your network: no
+Anycubic account, no cloud.
+
+A printer with LAN Mode switched on runs its own MQTT broker. This library
+performs the printer's handshake to get the broker credentials, connects,
+asks for state, parses the reports into typed objects, and sends the commands
+the printer accepts locally. It is fully async and has no cloud code and no
+bundled certificates or keys.
+
+Tested on a Kobra S1 (firmware 2.7.2.7). Reports from a Kobra X (firmware
+2.0.2.2) informed the parser.
+
+## Install
+
+```sh
+pip install anycubic-lan
+```
+
+Python 3.13 or later. Dependencies: `aiohttp`, `paho-mqtt`, `cryptography`.
+
+Switch LAN Mode on at the printer first: **Settings → Network → LAN Mode**.
+While LAN Mode is on the printer is not connected to the Anycubic cloud.
+
+## Usage
+
+```python
+import asyncio
+
+import aiohttp
+
+from anycubic_lan import AnycubicLanClient, AnycubicLanError, handshake
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        info = await handshake(session, "192.168.1.50")  # the printer's IP
+    print(info.model_name, info.device_id)
+
+    client = AnycubicLanClient(info)
+    client.add_state_listener(
+        lambda state: print(state.status, state.temperatures.nozzle, state.job)
+    )
+    # Fires on changes after connect(): False when lost, True when restored.
+    client.add_connection_listener(lambda up: print("restored" if up else "lost"))
+
+    await client.connect()  # subscribes and sends every query
+    try:
+        for _ in range(4):
+            await asyncio.sleep(15)
+            await client.query_all()  # the printer answers queries; poll them
+        await client.light_on()
+    except AnycubicLanError as err:
+        print("printer error:", err)
+    finally:
+        await client.disconnect()
+
+
+asyncio.run(main())
+```
+
+- `handshake()` raises `PrinterUnreachableError`, `LanModeDisabledError`,
+  `UnsupportedPrinterError`, `RequestRejectedError` or `InvalidResponseError`
+  (all subclasses of `AnycubicLanError`).
+- `client.state` is an immutable `PrinterState` merged from every report:
+  status, temperatures, fans, speed mode, firmware, the current job (progress,
+  layers, times, task id), ACE boxes and slots, lights, head position,
+  capability flags, camera URL and the last printer error code.
+- Commands: `pause()`, `resume()`, `stop()` (for the current job),
+  `light_on()`, `light_off()`, `set_light_brightness()`.
+- The broker credentials rotate when the printer restarts. They are held in
+  memory only; if the connection does not come back, run the handshake again.
+
+## Supported printers
+
+| Model | Model id | Status |
+|---|---|---|
+| Kobra S1 | 20025 | Tested (firmware 2.7.2.7, with ACE Pro) |
+| Kobra X | 20030 | Parser informed by user logs (firmware 2.0.2.2) |
+
+Other models that offer LAN Mode with the same handshake should work and are
+reported as "Anycubic printer (model <id>)". Older models (Kobra 2 and
+earlier) are detected and refused as unsupported.
+
+## Status
+
+Version 0.1.0, alpha. The specification in [`docs/`](docs/) comes first; the
+implementation follows it. Questions to the specification team and their
+answers are in [`docs/QUESTIONS.md`](docs/QUESTIONS.md). See
+[`docs/CLEAN-ROOM.md`](docs/CLEAN-ROOM.md) for how this library was written
+and by whom.
+
+## Development
+
+```sh
+pip install -e ".[test]" ruff mypy
+ruff check . && ruff format --check .
+mypy --strict src
+pytest
+```
+
+## Licence
+
+MIT.

anycubic_lan-0.1.0/README.md

@@ -0,0 +1,105 @@
+# anycubic-lan
+
+Talk to an Anycubic 3D printer in **LAN Mode**, directly on your network: no
+Anycubic account, no cloud.
+
+A printer with LAN Mode switched on runs its own MQTT broker. This library
+performs the printer's handshake to get the broker credentials, connects,
+asks for state, parses the reports into typed objects, and sends the commands
+the printer accepts locally. It is fully async and has no cloud code and no
+bundled certificates or keys.
+
+Tested on a Kobra S1 (firmware 2.7.2.7). Reports from a Kobra X (firmware
+2.0.2.2) informed the parser.
+
+## Install
+
+```sh
+pip install anycubic-lan
+```
+
+Python 3.13 or later. Dependencies: `aiohttp`, `paho-mqtt`, `cryptography`.
+
+Switch LAN Mode on at the printer first: **Settings → Network → LAN Mode**.
+While LAN Mode is on the printer is not connected to the Anycubic cloud.
+
+## Usage
+
+```python
+import asyncio
+
+import aiohttp
+
+from anycubic_lan import AnycubicLanClient, AnycubicLanError, handshake
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        info = await handshake(session, "192.168.1.50")  # the printer's IP
+    print(info.model_name, info.device_id)
+
+    client = AnycubicLanClient(info)
+    client.add_state_listener(
+        lambda state: print(state.status, state.temperatures.nozzle, state.job)
+    )
+    # Fires on changes after connect(): False when lost, True when restored.
+    client.add_connection_listener(lambda up: print("restored" if up else "lost"))
+
+    await client.connect()  # subscribes and sends every query
+    try:
+        for _ in range(4):
+            await asyncio.sleep(15)
+            await client.query_all()  # the printer answers queries; poll them
+        await client.light_on()
+    except AnycubicLanError as err:
+        print("printer error:", err)
+    finally:
+        await client.disconnect()
+
+
+asyncio.run(main())
+```
+
+- `handshake()` raises `PrinterUnreachableError`, `LanModeDisabledError`,
+  `UnsupportedPrinterError`, `RequestRejectedError` or `InvalidResponseError`
+  (all subclasses of `AnycubicLanError`).
+- `client.state` is an immutable `PrinterState` merged from every report:
+  status, temperatures, fans, speed mode, firmware, the current job (progress,
+  layers, times, task id), ACE boxes and slots, lights, head position,
+  capability flags, camera URL and the last printer error code.
+- Commands: `pause()`, `resume()`, `stop()` (for the current job),
+  `light_on()`, `light_off()`, `set_light_brightness()`.
+- The broker credentials rotate when the printer restarts. They are held in
+  memory only; if the connection does not come back, run the handshake again.
+
+## Supported printers
+
+| Model | Model id | Status |
+|---|---|---|
+| Kobra S1 | 20025 | Tested (firmware 2.7.2.7, with ACE Pro) |
+| Kobra X | 20030 | Parser informed by user logs (firmware 2.0.2.2) |
+
+Other models that offer LAN Mode with the same handshake should work and are
+reported as "Anycubic printer (model <id>)". Older models (Kobra 2 and
+earlier) are detected and refused as unsupported.
+
+## Status
+
+Version 0.1.0, alpha. The specification in [`docs/`](docs/) comes first; the
+implementation follows it. Questions to the specification team and their
+answers are in [`docs/QUESTIONS.md`](docs/QUESTIONS.md). See
+[`docs/CLEAN-ROOM.md`](docs/CLEAN-ROOM.md) for how this library was written
+and by whom.
+
+## Development
+
+```sh
+pip install -e ".[test]" ruff mypy
+ruff check . && ruff format --check .
+mypy --strict src
+pytest
+```
+
+## Licence
+
+MIT.

anycubic_lan-0.1.0/docs/CLEAN-ROOM.md

@@ -0,0 +1,61 @@
+# Clean-room record
+
+This library and the Home Assistant core integration built on it are written
+so that they contain **no code or expression** from two GPL-3.0 projects:
+
+- `WaresWichall/hass-anycubic_cloud` (the original Anycubic Cloud integration)
+- `Nino6689/hass-anycubic` and `Nino6689/anycubic-cloud-api` (its fork and
+  the fork's API library)
+
+The fork's maintainer (Nino Bondonno) has worked on those projects, so the
+work is split into two teams.
+
+## Roles
+
+| Role | Who | May read | Must not read |
+|---|---|---|---|
+| **Specification team** ("dirty") | Nino Bondonno, and Claude sessions on his machine that have read the GPL projects | Everything | — |
+| **Implementation team** ("clean") | A separate Claude cloud session per phase, with no access to Nino's machine | This repository's `docs/`, the `anycubic-lan` package, Python and dependency documentation, the Home Assistant developer docs and `home-assistant/core` | The three repositories above, and any other Anycubic Home Assistant integration (e.g. adamoutler, chrisfore) |
+
+Rules:
+
+1. The specification team writes **facts and requirements only** — protocol
+   behaviour, captured payloads, entity lists — in `docs/`. It never writes or
+   edits code in this repository or in the core integration.
+2. The implementation team writes **all code**, from `docs/` and public
+   documentation. When a fact is missing it asks in `docs/QUESTIONS.md`; it
+   does not look elsewhere.
+3. Feedback from hardware testing reaches the implementation team only as
+   functional bug reports (observed behaviour vs expected), never as code or
+   diffs.
+4. Before publication, the finished code is compared mechanically against the
+   GPL projects and the result recorded below.
+
+## Log
+
+| Date | Team | Session | Inputs given | Outputs | Did not read the excluded repos |
+|---|---|---|---|---|---|
+| 2026-09-26 | Specification | Claude (local, Nino's machine) | Captured payloads from Nino's Kobra S1; Kobra X logs from a user; the public `anycubic_ha_local` protocol description; notes from testing the fork | `PROTOCOL.md`, `INTEGRATION-SPEC.md`, this file, `LICENSE`, `README.md`, CI workflows | n/a — specification team |
+| 2026-09-26 | Implementation | Claude cloud session (routine) | `docs/CLEAN-ROOM.md`, `docs/PROTOCOL.md`, `docs/INTEGRATION-SPEC.md`, `docs/QUESTIONS.md`, `README.md`, `LICENSE`, CI workflows; general knowledge of the Python, aiohttp, paho-mqtt, cryptography and pytest APIs and the installed packages themselves (no web searches, no Anycubic code) | `src/anycubic_lan/` (v0.1.0), `tests/`, `pyproject.toml`, `.gitignore`, README sections, questions Q1–Q9 in `QUESTIONS.md` | Yes |
+| 2026-09-26 | Specification | Claude (local) | The v0.1.0 implementation (for acceptance only); the GPL projects (for the similarity check) | Answers to Q1–Q9 in `QUESTIONS.md`; `PROTOCOL.md` §6.7 corrected; similarity checks below | n/a — specification team |
+| 2026-09-26 | Implementation | Claude cloud session (routine, round 2) | `docs/QUESTIONS.md` (answers to Q1–Q9), `docs/PROTOCOL.md` (incl. corrected §6.7), `docs/INTEGRATION-SPEC.md`, `docs/CLEAN-ROOM.md`, `README.md`, the CI workflow, this branch's own code and tests; the installed Python, paho-mqtt, pytest, mypy and ruff (no web searches, no Anycubic code) | `src/anycubic_lan/` and `tests/` updated for Q1–Q4 and Q9, comments for Q5–Q8; "Applied in round 2" marks in `QUESTIONS.md`; README status line; this row. Merged the concurrent commits `ce0ee48` and `ca86d53` pushed to this branch during the session, keeping this session's Q1–Q4/Q9 code where both overlapped | Yes |
+
+| 2026-09-28 | Specification | Claude (local) | Nino's Kobra S1 in LAN Mode; the v0.1.0 branch's public API (black-box script, not committed) | Hardware report HW1–HW3 in `QUESTIONS.md`; corrections to `PROTOCOL.md` §2, §6.8, §6.9 and the Q5 answer | n/a — specification team |
+| 2026-09-28 | Implementation | Claude cloud session (routine, round 3) | `docs/QUESTIONS.md` (HW1–HW3), `docs/PROTOCOL.md` (corrected §2, §6.8, §6.9), this branch's code and tests (no web searches, no Anycubic code) | Fixes for HW1–HW3 in `reports.py`, `client.py` docstring and `README.md`; tests from the live captures; "Fixed" notes in `QUESTIONS.md`; this row | Yes |
+
+| 2026-09-28 | Specification | Claude (local) | The core branch run against the Kobra S1 in a throwaway Home Assistant; the library re-run after round 3 | HW1–HW2 confirmed fixed on hardware; HW4 reported; `PROTOCOL.md` §2 discovery fields added | n/a — specification team |
+| 2026-09-28 | Implementation | Claude cloud session (core integration, round 2) | `docs/QUESTIONS.md` (HW4), `docs/PROTOCOL.md` §2 and §6.1, this library's source at `3f8ac33` (`DiscoveryInfo.as_redacted_dict`, `parse_discovery`); core's own code and dev tooling for house style (no web searches, no Anycubic code) | Core branch `anycubic-integration` `68757a01` (diagnostics redact `fileUploadurl` by key, use the library's redacted discovery copy, scrub any string containing `gcode_upload?s=`) and `cfb7317c` (discovery fixture refreshed with the live fields and a string `modelId`, regression test, snapshot); "Fixed on core branch" note under HW4; this row | Yes |
+
+| 2026-09-28 | Specification | Claude (local) | Core branch `cfb7317` and library `5b8b406`, both run against the Kobra S1 | HW1, HW2 and HW4 confirmed fixed on hardware (HW3 settled by documentation); similarity rechecked | n/a — specification team |
+
+## Similarity checks
+
+| Date | Artefact | Compared against | Longest identical run (non-blank, non-comment lines) | Result |
+|---|---|---|---|---|
+| 2026-09-26 | `src/anycubic_lan/` @ `b7c0042` | `hass-anycubic` integration, `anycubic-cloud-api` library, `WaresWichall/hass-anycubic_cloud` | 6 — alphabetised stdlib imports (`hashlib, json, re, secrets, string, time`); next 4 — the standard `ssl` no-verification idiom | Clean: both are dictated by the language, not copied expression |
+| 2026-09-26 | `tests/` @ `b7c0042` | the same, plus `anycubic-cloud-api/tests` | 15 — the captured `info.project` payload | Expected: data captured from a printer, copied from `PROTOCOL.md` §6.2 |
+| 2026-09-26 | `src/anycubic_lan/` @ `b87f11e` (after round 2) | same three projects | 6 — the same stdlib import block; next 4 — the same `ssl` idiom | Clean; unchanged by round 2 |
+| 2026-09-28 | `src/anycubic_lan/` @ `5b8b406` (after hardware fixes) | same three projects | 6 — the same stdlib import block | Clean; unchanged by rounds 3–4 |
+| 2026-09-28 | core `homeassistant/components/anycubic/` @ `cfb7317` (after HW4) | same three projects | 5 — HA's sensor import block | Clean; unchanged by the HW4 fix |
+| 2026-09-28 | core `tests/components/anycubic/` @ `cfb7317` | the same, plus both GPL test suites | 2 | Clean |
+

anycubic_lan-0.1.0/docs/INTEGRATION-SPEC.md

@@ -0,0 +1,121 @@
+# Home Assistant core integration `anycubic` — functional specification
+
+What the core integration must do. How it is built is up to the implementer,
+following the Home Assistant developer documentation and house style. All
+wire behaviour comes from `anycubic-lan` (see `PROTOCOL.md`).
+
+## Identity
+
+| manifest field | value |
+|---|---|
+| `domain` | `anycubic` |
+| `name` | `Anycubic` |
+| `integration_type` | `device` |
+| `iot_class` | `local_push` |
+| `config_flow` | `true` |
+| `requirements` | `["anycubic-lan==<released version>"]` |
+| `codeowners` | `["@Nino6689"]` |
+| `dhcp` | `[{"macaddress": "A4E88D*"}, {"hostname": "anycubic*"}, {"hostname": "kobra*"}]` |
+| `quality_scale` | `bronze` in the first PR |
+
+## Library API the integration needs (the library must provide this)
+
+- An async **handshake**: given an `aiohttp.ClientSession` and a host, return
+  broker credentials plus printer identity (model id, model name, serial,
+  MAC, device id). Distinct exceptions for: unreachable, LAN Mode off,
+  unsupported printer, bad/rejected response.
+- An async **client**: connect with those credentials; register a callback
+  that receives parsed state updates; `query_all()`; `disconnect()`;
+  `is_connected`; a connection-lost / connection-restored signal.
+- A **state model**: one object per printer with typed fields for everything
+  in `PROTOCOL.md` §6 (temperatures, fans, state, speed mode, firmware,
+  job with progress/layers/times/task id, ACE boxes and slots, light,
+  position, last error code/message, capability flags, camera URL).
+- **Commands**: pause, resume, stop (using the current job's task id), light
+  on/off.
+
+## Config flow
+
+- **user** step: one field, `host`. Run the handshake.
+  - Errors: `cannot_connect` (unreachable), `not_in_lan_mode`,
+    `unsupported_printer`, `unknown`.
+  - `unique_id` = the printer's `deviceId` from the handshake.
+    Abort `already_configured` if it exists (and update the host).
+  - Entry title = model name (e.g. "Anycubic Kobra S1").
+  - `data_description` text for `host` explaining where to find the IP and
+    that LAN Mode must be switched on at the printer (Settings → Network →
+    LAN Mode).
+- **dhcp** step: from the manifest matchers. Probe the host's discovery
+  document; if it is an Anycubic printer in LAN Mode, set `unique_id` and
+  abort `already_configured` with the new host if known
+  (`discovery-update-info`); otherwise confirm with the user
+  (`discovery_confirm`). If LAN Mode is off, abort `not_in_lan_mode`.
+- **reconfigure** step: change the host; must be the same printer
+  (`unique_id` match) or abort `wrong_device`.
+- No credentials are stored (the printer rotates them) → reauthentication is
+  exempt.
+
+## Runtime
+
+- Setup: handshake + connect; on failure raise `ConfigEntryNotReady`. Store
+  the client and coordinator in `entry.runtime_data`.
+- Coordinator: push-based. Apply each state update as it arrives; send
+  `query_all()` on connect and every **15 seconds**.
+- Connection lost: entities become **unavailable once**, stay unavailable, log
+  a single warning; on return log a single info line and re-run the handshake
+  if needed. Never alternate between stale values and unavailable.
+- Unload: disconnect cleanly.
+- Diagnostics: the latest parsed state and the discovery document, with
+  `token`, credentials, serial and MAC redacted.
+
+## Device
+
+One device per entry: manufacturer `Anycubic`, model from the model id
+(`PROTOCOL.md` §9), name from the printer, `sw_version` = firmware,
+`serial_number` = `cn`, connection = MAC, `configuration_url` optional.
+
+## Entities — first PR: `sensor` only
+
+All with `has_entity_name`, translated names (`entity-translations`), icons
+via `icons.json`, unique id = `<deviceId>_<key>`.
+
+| key | what | device class / unit | state class | category / default |
+|---|---|---|---|---|
+| `status` | printer state: `idle`, `printing`, `paused`, `busy`, `unknown` | enum | — | — |
+| `nozzle_temperature` | current nozzle °C | temperature, °C | measurement | — |
+| `nozzle_target_temperature` | target nozzle °C | temperature, °C | measurement | — |
+| `bed_temperature` | current bed °C | temperature, °C | measurement | — |
+| `bed_target_temperature` | target bed °C | temperature, °C | measurement | — |
+| `chamber_temperature` | only created if the printer reports a non-zero chamber reading | temperature, °C | measurement | — |
+| `fan_speed` | part fan % | %, | measurement | disabled by default |
+| `auxiliary_fan_speed` | aux fan % | % | measurement | disabled by default |
+| `job_progress` | % | % | measurement | — |
+| `job_current_layer` | layer | — | measurement | — |
+| `job_total_layers` | layers | — | — | — |
+| `job_elapsed` | minutes | duration, min | — | — |
+| `job_remaining` | minutes | duration, min | — | — |
+| `job_end_time` | now + remaining | timestamp | — | — |
+| `job_name` | file name without path/extension | — | — | — |
+| `job_status` | enum from `print_status`: `printing`, `complete`, `cancelled`, `downloading`, `checking`, `preheating`, `slicing`, `levelling`; `idle` when no job | enum | — | — |
+| `speed_mode` | enum: `silent`, `standard`, `sport` (raw otherwise) | enum | — | — |
+| `last_error_code` | printer error code; `none` when 200 | — | — | diagnostic |
+
+Job sensors must read `idle`/unknown sensibly when there is no job — never
+`unavailable` while the printer is connected.
+
+## Later PRs (one each, after the first merges)
+
+1. `binary_sensor`: printing, paused, ACE drying, runout-refill.
+2. `button`: pause, resume, stop (available only when applicable).
+3. `light`: printer light (type 2), on/off + brightness.
+4. ACE sensors: per-slot material/colour/status, loaded slot, box temperature,
+   drying remaining.
+5. `number` + `select`: target temperatures, speed mode.
+6. `camera`: the FLV stream URL from `info.urls.rtspUrl` via ffmpeg.
+7. `update`: firmware version (read-only unless a local update path exists).
+
+## Non-goals
+
+Anycubic cloud accounts, file browsers, printing files, a custom panel or
+card, filament cost ledgers, custom actions. Those belong to the separate
+HACS integration.