feat(python): add asyncio client interface

Author: yujia21

README.md

@@ -0,0 +1,253 @@
+# libbacnet
+
+A sans-IO BACnet/IP client library written in Rust with a Python asyncio interface.
+
+## Overview
+
+`libbacnet` implements the BACnet/IP client protocol as a pure state machine (the
+[sans-IO](https://sans-io.readthedocs.io/) pattern).  All protocol logic lives in
+a Rust `Stack` type that:
+
+- receives inputs (`Received`, `Tick`, `Send`),
+- returns outputs (`Transmit`, `Event`, `Deadline`),
+- never touches a socket, spawns a thread, or reads a clock.
+
+A thin Python asyncio layer (`BacnetProtocol` / `BacnetClient`) wires the stack
+to UDP I/O, drives the retry scheduler, and exposes `async def` methods for each
+supported service.
+
+### Supported services
+
+| Service | Direction |
+|---|---|
+| ReadProperty | confirmed request |
+| ReadPropertyMultiple | confirmed request |
+| WriteProperty | confirmed request |
+| Who-Is / I-Am | unconfirmed |
+| WhoIsRouterToNetwork / IAmRouterToNetwork | unconfirmed (NPDU) |
+
+Segmented responses (ComplexACK with `more-follows`) are transparently
+reassembled; large segmented requests are automatically fragmented.
+
+### Non-goals (v1)
+
+- MS/TP or other physical layers (BACnet/IP only)
+- Server / device role
+- COV subscriptions, alarms, trend logs
+- BBMD / foreign device registration
+- IPv6
+
+---
+
+## Build
+
+### Prerequisites
+
+- Rust 1.75+ (`rustup toolchain install stable`)
+- Python 3.12+
+- [`maturin`](https://maturin.rs) (`uv tool install maturin`)
+
+### Development build
+
+```bash
+# clone and enter the repo
+git clone https://github.com/example/libbacnet
+cd libbacnet
+
+# create a virtual environment and install dev dependencies
+uv sync
+
+# compile the Rust extension and install it into the venv (editable)
+maturin develop
+```
+
+### Release build (wheel)
+
+```bash
+maturin build --release
+uv pip install target/wheels/libbacnet-*.whl
+```
+
+---
+
+## Quick start
+
+```python
+import asyncio
+from libbacnet import BacnetClient, BacnetAddr, ObjectIdentifier, PropertyIdentifier
+
+async def main():
+    async with BacnetClient(local_addr=("0.0.0.0", 47808)) as client:
+        # Discover devices (3-second collection window)
+        devices = await client.who_is(wait=3.0)
+        print(f"Found {len(devices)} device(s)")
+
+        for ev in devices:
+            addr = BacnetAddr(ev.src.addr, ev.src.port)
+            obj = ObjectIdentifier(object_type=8, instance=ev.message.device_id.instance)
+
+            # Read the device object's description — returns a ReadPropertyResult
+            result = await client.read_property(
+                addr=addr,
+                obj_id=obj,
+                prop_id=PropertyIdentifier.DESCRIPTION,
+            )
+            print(f"  {addr} description: {result.value}")
+
+asyncio.run(main())
+```
+
+See [`examples/discover_read_write.py`](examples/discover_read_write.py) for a
+longer example that performs Who-Is discovery, reads the object list, reads and
+writes `present-value` on each object, and then reads all values with
+`read_property_multiple`.
+
+---
+
+## API reference
+
+### `BacnetClient`
+
+High-level asyncio client.  Most users should start here.
+
+```python
+async with BacnetClient(config=None, local_addr=("0.0.0.0", 47808)) as client:
+    # Confirmed services — return typed result objects
+    result   = await client.read_property(addr, obj_id, prop_id, array_index=None)
+    result   = await client.read_property_multiple(addr, request_list)
+    await client.write_property(addr, obj_id, prop_id, value, array_index=None, priority=None)
+
+    # Discovery — return lists of EventUnconfirmedReceived
+    devices  = await client.who_is(addr=None, low=None, high=None, wait=3.0)
+    routers  = await client.who_is_router_to_network(network=None, wait=3.0)
+```
+
+#### Return types
+
+| Method | Return type |
+|---|---|
+| `read_property` | `ReadPropertyResult` |
+| `read_property_multiple` | `ReadPropertyMultipleResult` |
+| `write_property` | `None` (raises on error) |
+| `who_is` | `list[EventUnconfirmedReceived]` |
+| `who_is_router_to_network` | `list[EventUnconfirmedReceived]` |
+
+**`ReadPropertyResult`** — fields: `object_id`, `property_id`, `array_index`, `value` (`PropertyValue`).
+
+**`ReadPropertyMultipleResult`** — field: `objects` (`list[ObjectResult]`).  Each
+`ObjectResult` has `object_id` and `properties` (`list[PropertyResult]`).  Each
+`PropertyResult` has either `value` (`PropertyValue`) or `error`
+(`BacnetPropertyError`).
+
+**`PropertyValue`** — one of: `PropertyValueNull`, `PropertyValueBoolean`,
+`PropertyValueUnsigned`, `PropertyValueSigned`, `PropertyValueReal`,
+`PropertyValueDouble`, `PropertyValueOctetString`, `PropertyValueCharacterString`,
+`PropertyValueBitString`, `PropertyValueEnumerated`, `PropertyValueDate`,
+`PropertyValueTime`, `PropertyValueObjectIdentifier`, `PropertyValueArray`,
+`PropertyValueAny`.
+
+### `BacnetProtocol`
+
+Low-level `asyncio.DatagramProtocol`.  Use this when you need direct access to
+the event stream or want to integrate the stack into an existing event loop.
+
+```python
+from libbacnet import BacnetProtocol
+
+protocol = BacnetProtocol(config=None, on_event=None)
+
+# Inject inputs manually (e.g. in tests)
+outputs = protocol.send_input(InputSend(service=svc, dest=addr))
+
+# Consume events from the async queue
+event = await protocol.events.get()
+```
+
+### `StackConfig`
+
+```python
+from libbacnet import StackConfig
+
+cfg = StackConfig(
+    apdu_timeout_secs=3.0,   # seconds before retransmit
+    apdu_retries=3,           # retransmit attempts before Timeout
+    max_apdu_length=1476,     # outgoing segmentation threshold (bytes)
+    max_segment_buffer=2_097_152,  # reassembly buffer limit (bytes)
+)
+```
+
+### Enumerations
+
+`PropertyIdentifier`, `ObjectType`, `ErrorClass`, and `ErrorCode` are Python
+`IntEnum` classes exported directly from `libbacnet`.  They support unknown
+values via a `_missing_` fallback that returns a dynamic `UNKNOWN_<value>`
+member, so code never raises on an unrecognised wire value.
+
+```python
+from libbacnet import PropertyIdentifier, ObjectType
+
+prop = PropertyIdentifier.PRESENT_VALUE   # 85
+obj  = ObjectType.ANALOG_INPUT            # 0
+
+# Pass enum members directly to client methods
+result = await client.read_property(addr, obj_id, prop_id=PropertyIdentifier.OBJECT_LIST)
+```
+
+### `ReadAccessSpec`
+
+Used to build `read_property_multiple` requests.
+
+```python
+from libbacnet import ReadAccessSpec, PropertyIdentifier
+
+spec = ReadAccessSpec(
+    object_id=obj_id,
+    properties=[
+        (PropertyIdentifier.PRESENT_VALUE, None),   # (prop_id, array_index)
+        (PropertyIdentifier.DESCRIPTION, None),
+    ],
+)
+result = await client.read_property_multiple(addr=dest, request_list=[spec])
+```
+
+### Exceptions
+
+| Exception | Raised when |
+|---|---|
+| `BacnetTimeoutError` | No response within the retry budget |
+| `BacnetError` | Server sent Error, Abort, or Reject PDU |
+| `InvokeIdExhaustedError` | All 256 invoke IDs for the destination are in use |
+
+---
+
+## Running tests
+
+```bash
+# Unit and integration tests (no real device required)
+uv run pytest -v
+
+# Rust unit tests (activate the venv first so PyO3 links against the correct Python)
+source .venv/bin/activate
+cargo test
+
+# Linting
+cargo clippy
+cargo fmt --check
+uv run ruff format python/ tests/
+uv run ruff check python/ tests/
+```
+
+---
+
+## Limitations and known constraints
+
+- **BACnet/IP only** — MS/TP and other data links are not supported.
+- **Client role only** — incoming confirmed requests from other devices are
+  silently ignored.
+- **IPv4 only** — `BacnetAddr` stores an IPv4 address; IPv6 BVLC is not
+  implemented.
+- **No BBMD** — the library sends `Original-Unicast-NPDU` (0x0A) and
+  `Original-Broadcast-NPDU` (0x0B) only.  Foreign device registration and
+  broadcast distribution are out of scope.
+- **Single-threaded** — `Stack` is not `Send + Sync`; use it from a single
+  asyncio event loop thread.