client-py/CHANGELOG.md

# Changelog

## 1.1.0 — 2026-04-23

### Added

- `connect()` now validates and auto-adjusts the requested
  `LoRaConfig` against the device's advertised caps (`GET_INFO`):
  - `tx_power_dbm` is silently clamped into
    `[tx_power_min_dbm, tx_power_max_dbm]`. A clamp is logged at
    INFO. This keeps `dl.connect(config=my_config)` "just work" on
    boards with lower PA ceilings (e.g. SX1276 @ 20 dBm vs SX1262
    @ 22 dBm) without any per-board bookkeeping by the caller.
  - `freq_hz` outside the device's range, `sf` not in
    `supported_sf_bitmap`, or `bw` not in `supported_bw_bitmap` now
    raise :class:`ConfigNotSupported` *before* `SET_CONFIG` hits
    the wire. Silent shifts here would cross regulatory boundaries
    or change airtime/sensitivity without the caller noticing.
  - `Dongle.config` is now populated from `SetConfigResult.current`
    — the modulation the device actually stored, post-clamp — so
    callers can inspect what landed.
- New `ConfigNotSupported` exception (subclass of `DongloraError`),
  exported at the package root.

## 1.0.1 — 2026-04-22

### Fixed

- `discovery.find_port` / `wait_for_device` now match the WCH CH340K
  USB-UART bridge (`1a86:7522`) in `BRIDGE_VID_PIDS`. The Elecrow
  ThinkNode-M2 board ships with a CH340K bridge; the previous set
  covered CP2102, CH9102, standard CH340, and FTDI but missed this
  specific revision, so `discovery` returned `None` on that board.

## 1.0.0 — 2026-04-22

The 1.0 Python client, mirroring the Rust client 1.0 API and the
DongLoRa Protocol v2 wire format.

### Breaking

- **DongLoRa Protocol v2 wire format** (wire-incompatible with 0.x
  firmware and clients). All message types, tag correlation, and
  framing now follow `PROTOCOL.md` v1.0.
- **Module split.** Monolithic `protocol.py` / `client.py` are replaced
  with: `dongle.py` (high-level async `Dongle`), `session.py` (reader
  task, tag routing, keepalive), `frame.py` (streaming `FrameDecoder`
  + `encode_frame`), `commands.py` / `events.py` / `errors.py` /
  `modulation.py` / `info.py` / `crc.py`, matching the
  `donglora-protocol` Rust crate module-for-module.
- **Async API throughout.** Serial I/O via `asyncio-serial`; mux
  connections via `asyncio` streams. The blocking client surface is
  gone.
- **New error hierarchy.** `DongloraError` base with `Timeout`,
  `TransportClosed`, `ReaderExited`, `BadFrame`, and `ErrClient...`
  variants mirroring the Rust client's `ClientError`.

### Added

- Tag-aware dispatch with concurrent in-flight commands. The
  `TagAllocator` hands out 16-bit device tags; `Session` routes each
  response back to the originating coroutine.
- Auto-recovery from `ERR(ENOTCONFIGURED)`. The `Dongle` caches the
  last `SET_CONFIG` and silently re-applies it on timeout, retrying
  once.
- 500 ms background keepalive task per `PROTOCOL.md §3.4`.
- Sticky mux reconnect: once a mux connection succeeds, all future
  `connect()` calls in the same process only try the mux (waiting
  for it to reappear if needed). `try_connect()` raises immediately
  so callers can retry with backoff. Prevents clients from stealing
  the serial port during mux restarts.

### Test suite

- New tests: `test_dongle`, `test_session`, `test_frame`, `test_events`,
  `test_modulation`, `test_crc`, `test_ergonomics`.
- Removed: `test_client`, `test_protocol` (superseded).

## 0.2.0 — 2026-04-08

### Features

- **Module split matching Rust structure** — split monolithic `__init__.py` into
  `protocol.py`, `codec.py`, `discovery.py`, `transport.py`, `connect.py`, and
  `client.py`. All symbols re-exported from top-level for backwards compatibility.
- **Ping-on-connect validation** — all connect functions automatically ping the
  device and reject non-DongLoRa devices within 200 ms (matches Rust v0.2.0).
- **`try_connect(timeout)`** — non-blocking alternative to `connect()`. Returns
  an error immediately if no device is found.
- **`connect_default()`** — convenience wrapper with default timeout.
- **`connect_mux_auto(timeout)`** — mux-only connection, never falls back to USB
  serial. Equivalent of Rust client's "sticky mux" behaviour.
- **`default_socket_path()`** — resolve the preferred mux socket path.
- **`validate(ser)`** — public function for manual device validation.
- **Payload size validation** — `encode_command("Transmit", ...)` rejects
  payloads exceeding 256 bytes.
- **`Bandwidth` and `ErrorCode` enums** — `IntEnum` types matching the Rust
  definitions.
- **`RadioConfig` TypedDict** — typed dict for radio configuration.
- **New constants** — `MAX_PAYLOAD`, `RADIO_CONFIG_SIZE`, `CMD_TAG_*`,
  `RESP_TAG_*`, `ERROR_*` tag/error constants.
- **`py.typed` marker** — PEP 561 support for type checkers.
- **Comprehensive test suite** — 46 tests ported from the Rust client covering
  protocol roundtrips, COBS framing, client send/recv, firmware wire
  compatibility.
- **GitHub Actions CI** — ruff lint + format, pytest on Python 3.10–3.13, PyPI
  publish on tag.
- **Strict ruff linting** — E, W, F, I, UP, B, C4, ARG, SIM, RUF rules.

### Breaking changes

- **Package renamed back to `donglora`** — the short-lived `donglora-python`
  name is reverted. Import as `import donglora` (was always the intended API).
- **`connect()` no longer falls through from mux to USB serial** — if a mux
  socket file exists, the function commits to the mux or raises an error
  (matches Rust v0.2.1). This prevents port-stealing race conditions.
- **Sticky mux global removed** — the module-level `_mux_mode` variable and
  `_reconnect_mux()` are gone. Use `connect_mux_auto()` for mux-only mode.
- **`DEFAULT_CONFIG` now includes `cad: 1`** — previously relied on
  `encode_config()` defaulting it.

### Fixes

- Fixed broken dependency paths that prevented `uv sync` from resolving.
- Replaced `print()` calls with `logging` in discovery module.

## 0.1.0 — 2026-04-06

Initial release.