Claude v2
This commit is contained in:
206
README.md
206
README.md
@@ -1 +1,205 @@
|
||||
# `team1k`
|
||||
# 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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user