Metadata-Version: 2.4
Name: redhorse-hil
Version: 0.1.0
Summary: Python API for the FPGA SPI register emulator
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Dynamic: license-file

# RedHorse01T9k Python API

Use this package to configure a RedHorse01T9k SPI peripheral emulator from Python. It can verify the USB connection, emulate register-based SPI devices, and capture SPI transactions.

## Install

RedHorse HIL supports Python 3.9 and newer. The package is installed as
`redhorse-hil` and imported in Python as `hil`.

```bash
python -m pip install redhorse-hil
```

For local development:

```bash
python -m pip install -e .
```

## 1. Verify the board connection

Connect the board by USB, find its serial port, and keep the control-link baud rate at `115200`.

```python
from hil import HIL

PORT = "COM7"  # Example for Windows
BAUD = 115200

with HIL(PORT, BAUD) as dev:
    dev.ping()
    print("PING OK")
    print(f"status = 0x{dev.get_status().raw:04X}")
```

## 2. Emulate an SPI register device

Define the command format and starting register values, then load them onto the board. The external SPI controller can then read and write the registers directly.

```python
from hil import HIL, RegisterDevice

registers = RegisterDevice(
    mode=0,
    default_miso=0x00,
    read_mask=0x80,
    read_value=0x80,
    write_mask=0x80,
    write_value=0x00,
    address_mask=0x3F,
    address_shift=0,
    auto_increment_mask=0x40,
    auto_increment_value=0x40,
)

registers[0x05] = 0x11
registers[0x06] = 0x22
registers.load([0xAA, 0xBB, 0xCC, 0xDD], start=0x20)

with HIL("COM7", 115200) as dev:
    dev.ping()
    dev.clear_errors()
    dev.spi.emulate_registers(registers)
```

This configuration interprets bit 7 as read/write, bit 6 as auto-increment, and bits 5:0 as the register address. For example, `0x85` reads register `0x05`; `0xE0` starts a burst read at `0x20`.

## 3. Capture SPI transactions

Configure a capture, start it, then retrieve the retained records after the capture finishes or is stopped.

```python
with HIL("COM7", 115200) as dev:
    dev.ping()
    dev.spi.capture_clear()
    dev.spi.capture_configure(
        triggers=[(0xFF, 0x60)],
        transaction_limit=10,
        record_limit=512,
    )
    dev.spi.capture_start()

    # Run SPI traffic from the external controller here.

    status = dev.spi.capture_status()
    if status.armed:
        dev.spi.capture_stop()

    records = dev.spi.capture_records()
    for record in records:
        print(
            record.type_name,
            f"t={record.timestamp.microseconds:.3f} us",
            f"MOSI=0x{record.mosi:02X}",
            f"MISO=0x{record.miso:02X}",
        )
```

A trigger is a `(mask, value)` pair that checks the first MOSI byte in a transaction. `transaction_limit`, `byte_limit`, and `record_limit` can stop a capture automatically.

## License

This project is released under the [MIT License](LICENSE).
