Metadata-Version: 2.4
Name: imprintx
Version: 1.0.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pyzmq>=22
License-File: LICENSE
Summary: Python SDK for ImprintX Sensors and TUI devices
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# ImprintX SDK (Python)

Python SDK for Imprint X and Imprint TUI. Imprint X support
provides event-stream acquisition and device control. Imprint TUI support
provides synchronized five-channel tactile image acquisition, raw IMU data,
device-state control, and data streaming.

The SDK distinguishes the devices as `sensor` and `tui` in module names and
the service's `--device` option. The Python classes remain `Sensor` and `TUI`.

Use `imprintx.tui`, `TUI`, `--device tui`, and `example/tui/` consistently.
Reinstall the SDK to use these names; legacy aliases are not available.
Dual-device recording uses the `tui` field in `hardware_sync.json` for device
information.

The SDK supports Python 3.8 and newer. The package includes resident Imprint TUI
button recording; model inference, GUI, and example programs are not included.
Python dependencies are NumPy/PyZMQ and the bundled Rust extension. Automatic TUI
recording also requires a system FFmpeg executable with a working `libx265` encoder
on PATH; startup checks this before enabling recording. Communication-only mode
and Imprint X do not require FFmpeg.

## What's New in 1.0.0

1. Imprint X events are stored in a fixed ring with a global event index and
   read through read-only `events(start, end)` and `slots(start, end)` snapshots,
   replacing batch polling. Service batches carry `start`/`end` indices, and
   gaps show overwritten events.
2. EVT20 decode errors and timestamp jumps are reported in `sensor.stats` and
   the service STATUS reply.
3. `imprintx-sdk --device tui` now defaults to resident button recording in
   `recordings/`; use `--no-record` for communication only or an external recording
   controller. The shared TUI client and recorder are included in the package.

## Installation

```bash
pip install imprintx
```

## Imprint X

Shared mode (the service owns the serial port):

```bash
imprintx-sdk --device sensor /dev/ttyACM0
```

Direct mode (the application owns the serial port; do not run the service for
the same device at the same time):

```python
from imprintx.sensor import Sensor

with Sensor("/dev/ttyACM0") as sensor:
    sensor.set_light(True)
    try:
        start = sensor.events_written
        sensor.start()
        end = sensor.wait_for_events(start, timeout_sec=1.0)
        if end == start:
            raise TimeoutError("No events received")

        events = sensor.events(start, end)
        print(events["x"], events["y"], events["polarity"], events["timestamp_us"])
    finally:
        try:
            if sensor.is_streaming:
                sensor.stop()
        finally:
            if not sensor.is_streaming:
                sensor.set_light(False)
```

Imprint X events include 320 x 320 coordinates, polarity, and a device timestamp
in microseconds, in serial arrival order. Starting stops previous output, waits
500 ms, clears old input, and enables capture. Valid events arriving before the
startup reply are preserved. One resident reader reads up to 8 KiB at a time;
serial failures raise errors without reconnecting. The event ring holds 200,000
events (`SENSOR_EVENT_CAPACITY`), and the completed-slot ring holds 1,000 slots
(`SENSOR_SLOT_CAPACITY`). Both use global indices and overwrite their oldest items.
`events(start, end)` and `slots(start, end)` return read-only NumPy snapshots
copied under the reader's lock. Events or TIME_HIGH advancing device milliseconds
publish the previous slot; stopping flushes the final nonempty slot.

Zero TIME_HIGH is valid. Regressing CD timestamps are dropped and counted in
`decode_errors` without losing word alignment. Resynchronization validates a
candidate sequence and preserves incomplete candidates across serial reads.
A TIME_HIGH decrease adopts raw device time without unwrapping rollover;
regressions in successfully decoded events count as `timestamp_jumps` and do not
split slots. `sync_lost_bytes` counts bytes skipped during resynchronization,
`protocol_words` counts valid auxiliary messages other than TIME_HIGH, and `command_reply_bytes`
and `total_raw_bytes` count removed command replies and serial input bytes.
Statistics are available through `sensor.stats` and the service STATUS reply.
Decode errors are counted without stopping capture; command failures still raise.
`events()` returns an empty array if its start was overwritten. `slots()` advances
to retained slots whose events remain readable. Unwritten ends are clipped to the
current count; callers must check returned lengths and global indices for gaps.

The Sensor examples use the same IPC subscriber: `stream.py` prints every event's
`x`, `y`, `polarity`, and `timestamp_us`. The GUI follows the reference raw view:
accumulate all events received between display refreshes on a 320 x 320 gray image,
draw ON white and OFF black, and let later events overwrite earlier polarities at
the same pixel. Each display snapshots and clears the image, flips it vertically,
and scales to 640 x 640 with nearest-neighbor interpolation and the same raw header.
The default display limit is 60 FPS; a refresh with no new events shows gray.
The example retains all raw events, without the reference tracking application's
nine calibrated hot-pixel exclusions or coordinate correction.

The window title reports two independent rates: `FPS (1 ms)` counts completed
device-time milliseconds per elapsed host second, normally around 1000 during
continuous acquisition; `Display FPS` measures display refreshes. `--display-fps`
adjusts only the display limit while event reception and time accounting continue.
Without advancing device time, window FPS falls to zero; no windows are fabricated
from host time. Event index gaps and device timestamp regressions raise explicit
GUI errors. The separate Sensor recording example has been removed.

Sensor services and examples use ZeroMQ `ipc://` endpoints. Examples launch and
clean up a private service by default. To share a service, explicitly pass matching
custom data/control IPC endpoints to the service and examples. Existing TCP
endpoints must be replaced with local IPC addresses. The event message remains
`[events, {session, start, end}, binary_events]` with the existing event dtype.
Images and time slots are not published; control replies and errors retain their
own topics.

The Sensor Python flow uses a hierarchical FSM. Common controls and errors belong
to the connected parent state. Idle waits for commands and checks serial errors
every 100 ms. Active acquisition waits on Rust event notifications for up to 5 ms,
without an additional fixed 5 ms message wait. Publication backpressure retains the
cursor and retries after a 5 ms control wait. STOP drains retained events before
returning to idle; batches include events in the slot still being filled.

The client dispatches subscription, control-reply, and event waits through one
state handler. Only reply waits queue events; a full queue raises an error.
`Client.receive(0)` performs a nonblocking read. GUI and stream share the
`Client.streaming()` lifecycle, registering STOP only after START succeeds.
The GUI switches between receiving and presenting at display deadlines, handling
window events at the display cadence. OpenCV uses one thread, as in the reference
application. Raw rendering, 1 ms time accounting, IPC message fields, and explicit
error handling retain their existing behavior.

Send/receive high-water marks are one batch, but do not bound all IPC buffering.
Each batch reads at most half the event ring; skipped events remain visible as
global index gaps. The GUI raises on gaps, and stream reports them on exit.
Finite buffering cannot preserve arbitrarily long subscriber pauses. Slow
subscribers still affect the shared service; printing throughput depends on the
terminal. A receive timeout returns `None`, and timed streaming ends on schedule.

## Imprint TUI

Shared mode (the service owns the serial port and defaults to resident button
recording):

```bash
imprintx-sdk --device tui /dev/ttyACM0
```

The first button press starts a segment; the service writes `RECORDING` only after
the first real complete frame has been written. The second press stops recording,
finalizes and saves the files, then restores `CONNECTED` and waits for the next
segment. Each segment creates a unique MP4 in `recordings/` under the current
working directory, with matching `_timestamps.json` and `_imu.json` sidecars;
existing files are never overwritten. Wait for `RECORDING` before pressing again.
Ctrl+C exits while armed; during recording it saves the complete frames already
received before closing the service. Wait for the next armed message after
`Saving recording...` before starting another segment.

For communication only, or when another program owns recording state:

```bash
imprintx-sdk --device tui --no-record /dev/ttyACM0
```

The current reference firmware (`ecf17ce`) has a button-state defect: its first
normal press reports recording end, and its toggle is not synchronized with host
state changes or a forced stop. Firmware must fix this to guarantee the first-press
start sequence above; the SDK preserves the state actually reported.
Image and IMU streams use their own enable commands.

Only one recording controller may own a device's recording state. TUI examples
use a communication-only service and share the packaged `imprintx.tui.client`
and `imprintx.tui.recording` implementation. The repository command
`example/tui/record.py --button` still saves one segment and exits; resident
recording keeps waiting for further segments. Imprint X behavior is unchanged.

### Direct Access

Direct mode (the application owns the serial port; do not run the service for
the same device at the same time):

```python
from imprintx.tui import TUI

with TUI("/dev/ttyACM0") as tui:
    print(f"Firmware: {tui.firmware_version}; device: {tui.sn}")
    tui.start()

    if not tui.wait_for_batch(timeout_sec=1.0):
        raise TimeoutError("No synchronized tactile batch received")

    batch = tui.poll()
    for frame in batch:
        print(
            f"channel={frame.channel} "
            f"timestamp={frame.timestamp_us}us "
            f"shape={frame.image.shape}"
        )
```

TUI IMU samples now follow the 24-byte firmware layout introduced in
`tacprint_dev` commit `b9bb433` (current firmware reference: `ecf17ce`). Each
little-endian `<QI6h` sample contains `unix_us`, `sensor_time`, and six raw axes.
The direct API, client NumPy views, binary messages, and recording JSON all retain
`unix_us`. It is UTC Unix microseconds recorded by firmware after reading the IMU;
`18446744073709551615` means no valid date anchor and is preserved unchanged.
A valid date anchor alone does not prove synchronization with the host. The low
24 bits of `sensor_time` still provide the BMI088 clock and recording sample rate.
Image and RTC calendars use fixed UTC+8; RTC synchronization and image timestamp
conversion use that offset regardless of the host timezone. Setting RTC may
change the common wall-clock timeline.

**Compatibility:** old firmware with 16-byte IMU samples is no longer supported.
Upgrade firmware and update SDK services and clients together. The SDK does not
guess the layout from payload length: 16-byte and 24-byte batches can have the
same length. The connection handshake requires firmware V1.5 or newer.
The old JSON IMU message fallback has been removed; `imu` messages always carry
binary samples.

Up to three consecutive dropped synchronized batches are tolerated. Receive
sequence gaps confirming more than three consecutive drops raise an error;
a complete batch resets the count. Channel timestamps must still agree within
5 ms; missing images are not filled or combined across acquisition cycles.
Receive counters cannot detect cycles the device never reports at all. The
existing two-second timeout without a complete batch remains in effect.

Each image is a 192 x 192 NumPy array. A batch is returned only after the
detected active tactile channels have been synchronized. Opening an Imprint TUI
fails unless firmware version 1.5 or newer and the device identity are both
validated.
Unsupported firmware, invalid version responses and an unwritten SN raise explicit
Chinese errors and abort the TUI connection. Timeouts report that the identity
could not be read, without assuming its contents. Imprint X `get_sn()` also rejects
an empty SN with a Chinese error. Internal provisioning can still write an SN to
an unprovisioned device.

## Examples

`pps, fsync = tui.get_io_sync_status()` reads DI `0x2F100300` and returns
the tuple `(pps, fsync)`. Each integer is `0` for invalid or `1` for valid.
It works while idle or streaming; the shared-service equivalent is
`client.control(Control.GET_IO_SYNC_STATUS)`, which returns a JSON array
`[pps, fsync]`. PPS and FSYNC validity are separate from the recording state
at `0x2F100200`. Unsupported firmware, malformed responses, and a one-second response
timeout raise explicit errors rather than returning `0`.

For usage examples, see the
[ImprintX SDK repository](https://github.com/Imprint-X/Imprintx-sdk).
TUI stream, GUI, snapshot, inference, and single-recording examples close their
subscriptions on exit without stopping a shared service. Examples that launch a
private service also close that service when they finish.

## Data Integrity

Imprint X commands validate their checksums and acknowledgements; Imprint X event
streams validate EVT20 types, coordinates, and timestamps. Imprint TUI streams
validate checksums, payload sizes, hardware timestamps, and synchronized channel
batches. Missing channels, timestamps, serial numbers, events, and frames are
never fabricated. Queue overflow, malformed batches, timestamp regressions, and
stream continuity failures beyond the three-batch allowance raise explicit errors.
A full TUI publication queue fails immediately instead of blocking service controls;
the SDK does not automatically
reconnect or silently retry control requests.

## License

Copyright (c) ImprintX. All rights reserved. This package is proprietary
software; use and distribution are subject to the included license terms.

## TUI firmware upgrade

Firmware image validation and USB OTG transfer are implemented in
`imprintx.tui.upgrade`. This feature additionally requires `pyserial>=3.5`;
install it separately or use the repository's example requirements.
Stop the SDK service and other programs using the target serial port first.
The device must have a matching preinstalled bootloader and support firmware
transfer. Use an App `.bin` supplied for your hardware by the maintainer.

```bash
python -m imprintx.tui.upgrade /path/to/app.bin --check
python -m imprintx.tui.upgrade /path/to/app.bin --port /dev/ttyACM0
```

The repository's `example/tui/upgrade.py` calls this same implementation.
Device identity and firmware build are checked after restart; failures are
reported without automatic retransmission. Real-device upgrades, USB
re-enumeration and power-loss recovery have not yet been validated.

