# team1k

Python control library and server for the TEAM1k X-ray detector.

Communicates directly with the detector FPGA via UDP, replacing the previous `k_test` C++ program. Uses EPICS PV Access (PVA) for command/status and ZMQ for bulk data transfer.

## Architecture

```
Client machine                          Detector machine
+--------------+                        +-------------------------------+
|              |   PVA (commands/status) |  team1k-server                |
|  Client      |<---------------------->|    Register I/O (UDP:42000)   |
|              |                        |    PVA server                 |
|              |   ZMQ (frame data)     |    PVA streamer thread        |
|              |<---------------------->|    Frame capture thread       |
|              |                        |    ZMQ data transfer thread   |
+--------------+                        |                               |
                                        |  Acquisition subprocess       |
                                        |    UDP data recv (UDP:41000)  |
                                        |    Frame assembly             |
                                        |    -> locking_shmring         |
                                        +-------------------------------+
```

## Installation

```bash
pip install .
```

For HDF5 support (optional):

```bash
pip install ".[hdf5]"
```

### Dependencies

- `locking_shmring` — shared memory ring buffer (must be installed separately)
- `p4p` — EPICS PV Access for Python
- `pyzmq` — ZeroMQ for bulk data transfer
- `numpy`, `pyserial`

## Running the server

```bash
team1k-server --detector-ip 10.0.0.32 --log-level INFO
```

All options:

```
--detector-ip     Detector IP address (default: 10.0.0.32)
--register-port   Detector register port (default: 42000)
--data-port       Detector data port (default: 41000)
--pv-prefix       PVA prefix (default: TEAM1K:)
--zmq-port        ZMQ data transfer port (default: 42005)
--config          Parameter file to apply on startup
--bellow-port     Bellow stage serial port (default: /dev/CameraBellowStage)
--log-level       DEBUG, INFO, WARNING, ERROR (default: INFO)
```

## Client usage

### Acquire frames

```python
from team1k import Client, ExposureModes

client = Client(data_host="detector-machine")

# Configure
client.set_exposure_mode(ExposureModes.GLOBAL_SHUTTER_CDS)
client.set_integration_time(6.0)  # ms

# One-shot: start DAQ, capture 100 frames, stop DAQ
frames = client.acquire_frames(100)
print(frames.shape)  # (100, 1024, 1024)
print(frames.dtype)  # uint16

client.close()
```

### Manual DAQ control

```python
client = Client(data_host="detector-machine")

client.start_daq()

# Grab frames from the running stream
batch1 = client.get_frames(50)
batch2 = client.get_frames(50)

client.stop_daq()
client.close()
```

### Live image monitoring

```python
client = Client()

def on_frame(image):
    print(f"Frame received: {image.shape}")

client.monitor_image(on_frame)

# ... later
client.stop_monitor("IMAGE")
client.close()
```

### Status

```python
client = Client()

print(client.get_status())
print(client.is_acquiring())
print(client.get_frame_rate())
print(client.get_exposure_mode())
print(client.get_integration_time())

client.close()
```

### Other commands

```python
client.set_trigger_mode(TriggerModes.EXTERNAL)
client.set_adc_clock_freq(60.0)       # MHz
client.set_adc_data_delay(0x1A7)
client.load_parameter_file("/path/to/params.txt")
client.set_test_mode(True)             # FPGA test pattern
client.reset_connection()

# Peripherals
client.insert_detector()
client.retract_detector()
client.power_on()
client.power_off()
```

## PV Access interface

All PVs are prefixed with `TEAM1K:` by default.

### Status PVs (read-only)

| PV | Type | Description |
|----|------|-------------|
| `STATUS` | string[] | Server status |
| `ACQUIRING` | bool | DAQ running |
| `FRAME_RATE` | float | Current frame rate (Hz) |
| `FRAME_COUNT` | int | Total frames acquired |
| `EXPOSURE_MODE` | int | Current exposure mode (0-3) |
| `TRIGGER_MODE` | int | Current trigger mode |
| `INTEGRATION_TIME` | float | Integration time (ms) |
| `CAPTURE:STATUS` | string | IDLE / CAPTURING / READY / ERROR |
| `CAPTURE:PROGRESS` | int | Frames captured so far |
| `CAPTURE:TOTAL` | int | Frames requested |
| `IMAGE` | NTNDArray | Live image stream |

### Command PVs (writable)

| PV | Type | Description |
|----|------|-------------|
| `CMD:EXPOSURE_MODE` | int | Set exposure mode |
| `CMD:TRIGGER_MODE` | int | Set trigger mode |
| `CMD:INTEGRATION_TIME` | float | Set integration time (ms) |
| `CMD:START_DAQ` | int | 1=start, 0=stop |
| `CMD:CAPTURE` | int | Capture N frames |
| `CMD:ADC_CLOCK_FREQ` | float | Set ADC clock (MHz) |
| `CMD:ADC_DATA_DELAY` | int | Set ADC data delay |
| `CMD:PARAMETER_FILE` | string | Apply parameter file |
| `CMD:RESET` | int | 1=reset connection |
| `CMD:TEST_MODE` | int | 1=enable FPGA test data |

## Package structure

```
src/team1k/
    detector/           # Direct UDP communication with detector FPGA
        udp_transport.py    # Low-level UDP socket
        registers.py        # Register read/write protocol
        data_port.py        # Data port + loopback registration
        chip_config.py      # Chip constants (1024x1024, packet layout)
        commands.py         # Detector commands (exposure, trigger, etc.)
        adc.py              # Si570 I2C clock programming
        parameter_file.py   # Parameter file parser
    acquisition/        # High-throughput data path
        receiver.py         # Acquisition subprocess (UDP -> shmring)
    filewriter/         # On-demand frame capture
        capture.py          # FrameCapture + ZMQ DataTransferServer
    pva/                # EPICS PV Access
        interface.py        # PVA server, command/status PVs
        streamer.py         # shmring -> NTNDArray live stream
    peripherals/        # Hardware peripherals
        bellow_stage.py     # Camera bellow stage (serial)
        power_supply.py     # Power supply control
    server.py           # Main server entry point
    Client.py           # PVA + ZMQ client library
```