Metadata-Version: 2.4
Name: ikalogic-at1000
Version: 0.6.0
Summary: Python SDK for Ikalogic AT1000 devices
Keywords: at1000,ikalogic,test-sequencer,automated-testing,hardware,instrumentation,sdk,api
Author: Corentin AZAIS, Vladislav KOSINOV
Author-email: Corentin AZAIS <c.azais@ikalogic.com>, Vladislav KOSINOV <v.kosinov@ikalogic.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: websockets>=13.0
Requires-Dist: zeroconf>=0.148.0
Requires-Python: >=3.10
Project-URL: Homepage, https://ikalogic.com/test-sequencers/at1000/intro/
Project-URL: Documentation, https://ikalogic.com/kb/at1000-api/at1000_home/
Description-Content-Type: text/markdown

# ikalogic-at1000

Official Python SDK for the Ikalogic AT1000 Series Test Sequencers.

This package provides a high-level API to control and automate the Ikalogic [AT1000](https://ikalogic.com/test-sequencers/at1000/intro/), a test sequencer designed for functional testing of electronic devices, PCBs, and complex systems. It ships both a synchronous client (`ikalogic_at1000`) and an asynchronous client (`ikalogic_at1000.aio`).

## Key Features

- **32 Programmable I/Os:** Handle analog and digital signals within a ±25V range.
- **8 Dry Contact Relays:** Control external circuits, with one relay equipped for high-precision current measurement.
- **Programmable Power Supply:** Delivers 0 to 24V at up to 2A with precise current monitoring.
- **Dual USB 3.0 Ports:** Feature power cycling (on/off control) and current measurement for testing USB devices.
- **Communication Interfaces:** Includes Ethernet, RS232, RS485, CAN, SPI, I2C, and UART.
- **Human-Machine Interface (HMI):** Onboard screen, rotary knob, and speaker for standalone operation and feedback.

## Installation

```bash
pip install ikalogic-at1000
```

Or, with [uv](https://docs.astral.sh/uv/):

```bash
uv add ikalogic-at1000
```

Requires Python 3.10 or newer.

## Quick Start

Discover devices on the local network, then open one to take control:

```python
from ikalogic_at1000 import AT1000

# Discover AT1000 devices over mDNS (returns host strings)
for host in AT1000.find_devices():
    print(host)

# Open a device by host string (hostname or IP). open() acquires exclusive
# access; if another opener takes over, this client's mutating calls raise
# AccessRevokedError until it opens again.
device = AT1000.open("at1000.local")
print(device.info.model, device.info.serial_number)

device.reset()
device.close()
```

Pass `readonly=True` to observe a device without taking control (no session is opened and no calls are gated).

### Standalone vs remote

Inside an AT1000 project container the device resolves its own address without mDNS. Use `AT1000.is_standalone()` to branch:

```python
from ikalogic_at1000 import AT1000

if AT1000.is_standalone():
    device_address = AT1000.find_local_device()
else:
    devices = AT1000.find_devices()
    device_address = devices[0] if devices else None

if not device_address:
    raise SystemExit("No devices found")

device = AT1000.open(device_address)
```

## Asynchronous Usage

The same API is available as coroutines under `ikalogic_at1000.aio`:

```python
import asyncio

from ikalogic_at1000.aio import AT1000


async def main():
    device = await AT1000.open("at1000.local")
    print(device.info.model, device.info.serial_number)

    await device.reset()
    await device.aclose()


asyncio.run(main())
```

## HMI prompts

Display a single-choice prompt on the device and wait for the operator:

```python
from ikalogic_at1000 import AT1000, PromptChoice, PromptRequest

device = AT1000.open("at1000.local")
try:
    result = device.hmi.prompt(
        PromptRequest(
            text="Test failed.\nChoose the next action.",
            choices=[
                PromptChoice(label="Retry", color="#1769AA"),
                "Skip",
                PromptChoice(label="Cancel", color="#B3261E"),
            ],
            default_index=2,
            timeout_ms=60_000,
        )
    )
    print(result.status, result.selection.label, result.selection.index)
finally:
    device.close()
```

The knob moves between choices without wrapping. Press it to select the highlighted choice. A choice is a `PromptChoice` or a bare string, which is shorthand for `PromptChoice(label=...)`. Choices are identified by position, so two of them may carry the same label. `default_index` sets the initial highlight, not an automatic selection on timeout. It defaults to 0, the first choice.

Choice colors use `#RRGGBB`. The default background is `#1769AA`, with black or white text chosen for contrast. Selecting the choice named "Cancel" returns a selection like any other choice.

`prompt()` returns a `PromptState` with status `selected`, `cancelled`, or `timed_out`. Cancellation and timeout are ordinary results. `selection` is always present: the confirmed choice when the status is `selected`, and the last highlighted choice when it is `cancelled` or `timed_out`. `PromptState.id` identifies the prompt itself, not a choice.

`prompt()` waits on the `hmi.prompt` event instead of polling. It opens the event stream when the application has not already done so, closing only a stream it opened itself. Each event re-arms a window of `timeout_ms`, and an expired window costs a single read of the prompt.

Prompts require an owning session. Only one prompt can be active. Screen changes, HMI reset, raw knob reads, and another prompt creation conflict while it is pending. Audio remains available. The previous screen returns when the prompt ends, unless another screen or owner replaced it.

The default deadline is 60 seconds. `timeout_ms` accepts integers from 1,000 to 1,800,000 milliseconds. The device enforces the deadline even if the client stops listening. The deadline only guards against an abandoned prompt, so the first turn of the knob stops it: once the operator is answering, only a selection, a cancellation, or a lost session ends the prompt. If the wait fails, the helper attempts to cancel the prompt and preserves the original exception. It does not retry or recreate prompts.

`PromptRequest` validates 1 to 32 choices and a `default_index` below the number of choices. Text is limited to 256 UTF-8 bytes and each label to 64 UTF-8 bytes. Text and labels cannot be blank. Control characters are rejected, except line feeds in the prompt text. The device checks display glyph support.

The same models and methods are exported by `ikalogic_at1000.aio`. Use `await device.hmi.prompt(request)` with its async client. Task cancellation attempts to cancel the device prompt before re-raising `CancelledError`.

Run the [colored-choice example](examples/hmi_prompt.py) with either client:

```bash
uv run examples/hmi_prompt.py at1000.local
uv run examples/hmi_prompt.py at1000.local --async
```

## Real-time Events

Subscribe to live device state changes over a WebSocket. Connect, then register callbacks per event type (or `"*"` for all events):

```python
from ikalogic_at1000 import AT1000

device = AT1000.open("at1000.local", readonly=True)
device.events.connect()


def on_gpio(event):
    print(event.type, event.data)


unsubscribe = device.events.subscribe("gpio.state", on_gpio)

# later
unsubscribe()
device.close()
```

## Documentation

Full API documentation is available at <https://ikalogic.com/kb/at1000-api/at1000_home/>.

## License

This package is distributed under the MIT License.
