tekhsi_rs 0.1.1

# tekhsi_rs

High-performance client for Tektronix HSI enabled oscilloscopes, with native Rust, Python, and Node.js bindings.

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/Rust-2024-orange.svg)](https://www.rust-lang.org/)
[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D6.14.2-green.svg)](https://nodejs.org/)

## Overview

`tekhsi_rs` connects to Tektronix HSI-compatible oscilloscopes, validates waveform headers, and decodes analog/digital/IQ data into typed waveforms with strict validation. It prioritizes correctness, performance, and reliability over the Python reference implementation.

### Key Features

- **High-throughput** — Parallel download and decode loops and minimal allocations
- **Strict validation** — Rejects invalid/unsupported waveform data with explicit errors
- **Streaming** — Async iterator-based acquisition with broadcast channels
- **Multi-language** — Native Rust, Python, and Node.js bindings
- **FFT support** — Calibrated FFT helpers for frequency analysis

## Language Bindings

| Language | Package | Status |
|----------|---------|--------|
| Rust | `tekhsi_rs` | Core implementation |
| Python | `pytekhsi` | Async + sync APIs |
| Node.js | `tekhsi_js` | TypedArray + async iter |

## Quick Start

### Rust

```rust
use tekhsi_rs::{SubscribeOptions, TekHsiClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = TekHsiClient::connect("scope:5000").await?;
    let symbols = client.list_available_symbols().await?;
    let mut rx = client.subscribe(symbols, SubscribeOptions::default())?;

    while let Ok(acquisition) = rx.recv().await {
        for channel in acquisition.data.iter() {
            println!("{:?}", channel);
        }
    }

    client.disconnect().await?;
    Ok(())
}
```

### Python

```python
import asyncio
import pytekhsi

async def main():
    client = await pytekhsi.TekHsiClient.connect("scope:5000")
    symbols = await client.list_available_symbols()
    receiver = client.subscribe(symbols)

    async for acquisition in receiver:
        for channel in acquisition:
            print(channel)

    await client.disconnect()

asyncio.run(main())
```

### Node.js

```typescript
import { TekHsiClient } from 'tekhsi_js'

const client = await TekHsiClient.connect('scope:5000')
const symbols = await client.listAvailableSymbols()
const receiver = await client.subscribe(symbols)

for await (const acquisition of receiver) {
    for (const channel of acquisition.iter()) {
        console.log(channel)
    }
}

await client.disconnect()
```

## Installation

### Rust

```bash
cargo add tekhsi_rs
# or for FFT support:
cargo add tekhsi_rs --features fft
```

### Python

```bash
pip install tekhsi-rs
# or build from source:
cd bindings/python && pip install .
```

### Node.js

```bash
npm install tekhsi-js
# or build from source:
cd bindings/node && npm install
```

## Benchmark

```bash
# Rust benchmark
cargo run --release --example benchmark -- 127.0.0.1:5000

# Python benchmark
cd bindings/python/examples && python benchmark.py

# Node.js benchmark
cd bindings/node && npm run bench
```

## Demo Applications

**scopeapp (Rust)** — egui/eframe-based oscilloscope viewer
  ```bash
  cargo run -p scopeapp -- 127.0.0.1:5000
  ```

**pyscopeapp (Python)** — PyQt6/pyqtgraph-based viewer
  ```bash
  cd bindings/python/examples/pyscopeapp && python main.py
  ```

## Testing

Integration tests depend on the Python test server in `tests/server/`.

```bash
# Build and run test server
cd tests/server && ./run-server.sh

# Run tests (requires --features client-id-header for test server)
cargo test --features client-id-header

# Clean test server artifacts
cd tests/server && ./clean.sh
```

## License

GPL-3.0 — See [LICENSE](LICENSE) for details.

## Related

- [What is HSI](https://www.tek.com/en/video/product-demo/what-is-hsi) - Introduction to Tektronix HSI
- [Tektronix TekHSI](https://github.com/tektronix/TekHSI) — Tektornix HSI python implementation