Metadata-Version: 2.4
Name: muse-driver-framework
Version: 1.1.2
Summary: Shared pure-Python framework for AMX MUSE Script-as-Device drivers
Author: AMX MUSE driver project
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# muse-driver-framework

Shared pure-Python runtime framework for AMX MUSE Script-as-Device programs.

The package contains the transport-independent pieces shared by the Precis
Driver and Meter Validation programs:

- asynchronous TCP connection lifecycle and reconnect handling;
- descriptor control registry and control type inference;
- bounded, latest-only `MeterStream` frame delivery;
- bounded, latest-only `XYSeriesStream` delivery for complete `[x, y]` frames.

`XYSeriesStream` accepts a variable-length array of finite pairs, including an
empty array. Each frame is atomic and only the newest complete frame is kept,
so a slow chart cannot create a backlog or mix points from different frames.

It has no third-party runtime dependencies and supports the Python 3.10 runtime
used by current MUSE firmware.

## Runtime use in MUSE

Each Script-as-Device program declares the exact framework version in its own
`requirements.txt`:

```text
muse-driver-framework==1.1.2
```

The program imports the package, never a copied local `driver_framework.py`:

```python
from muse_driver_framework import AsyncTcpDeviceClient, AsyncTcpDeviceManager
```

MUSE must have internet access when it installs the requirements file. Keep
the version exact so a framework release cannot silently change an existing
driver.

## Local verification

Build and install the wheel into an isolated environment before testing a
driver. The driver directories should not contain a local framework copy.

To test unpublished source changes, run `python3 -m unittest discover -s tests -v`
here, or the parent project's `local-validation/test-source.sh`. The latter
uses `PYTHONPATH` for source testing only; MUSE still installs the pinned public
version, not these local edits. Tests and builds do not publish or deploy code.

Numeric commands and configuration timers reject nonfinite values before
clamping or scheduling. Realtime Meter/XY-series descriptors are read-only and
cannot declare both delivery types on one parameter. Driver entry points
should call `manager.stop()` from their normal stop/exit cleanup.

## Performance and ownership

The control registry compiles path, protocol-channel and feedback-route indexes
once at construction. Treat the descriptor and registered controls as a startup
snapshot; create a new registry after changing their mapping. Lookup results do
not expose mutable internal sets or path lists.

Continuous commands are also coalesced by device/key before crossing into the
TCP event loop, so a burst does not create one scheduled task per intermediate
value. Pending keys per device are bounded by `command_queue_size`; stopping
discards them. FIFO commands are not coalesced, and new continuous keys retain
their scheduling positions relative to FIFO requests.

Meter and XY-series caches own their accepted frames. `snapshot()` and
`take_frame()` capture a complete frame under the producer lock, then copy it
outside the lock; callers still receive independent mutable arrays. This reduces
producer contention without removing validation or changing the wire format.

`run(publish)` includes copying and synchronous/asynchronous publishing time in
the rate-limit period, rather than sleeping an extra full period after publishing.
Slow callbacks still reduce achieved throughput. Missed periods are not replayed,
and idle streams wait instead of spinning. These are limits, not a promise that
every configuration or MUSE host sustains the declared rate.

The parent project's `local-validation/benchmark-driver.py` measures source CPU
costs; `local-validation/stress-driver.py` tests 50 loopback TCP processors and
multiple complete telemetry streams with a mock SDK. Neither tests actual MUSE
SDK transport or physical devices. Unpublished source changes require a new
framework release and updated pinned driver requirements before deployment.
