# 接口与数据格式

## `IDigitizer`

| 成员 | 作用 | 前置条件 |
|---|---|---|
| `EnumerateDevicesAsync` | 枚举逻辑设备并读取物理 ID/型号 | 厂商运行库与驱动可用 |
| `OpenAsync` | 按 `DeviceInfo.LogicalId` 创建设备句柄 | 未打开或已关闭 |
| `ConfigureAsync` | 校验并写入 AD 参数 | 已打开、未采集 |
| `StartAcquisitionAsync` | 启动、软件触发并持续返回采样块 | 已打开且已配置 |
| `StopAsync` | 停止 AD 并释放 AD 资源 | 可重复调用 |
| `CloseAsync` | 先停止，再释放设备句柄 | 可重复调用 |

`Pcie8586Digitizer` 用于真卡；`SimulatedDigitizer` 用于无硬件开发和主项目数据链测试。

## 配置

```csharp
var config = new AcquisitionConfig(
    ChannelCount: 4,
    InputRange: InputRange.PlusMinus5V,
    ClockDivider: 100,
    Mode: AcquisitionMode.Continuous,
    FiniteSamplesPerChannel: 10_000);
```

此配置启用 CH0–CH3，量程 ±5 V，采样率 1 MS/s。

## `SampleBlock`

```text
Channels[channel][sample]  double，单位 V
SampleRateHz               每通道采样率
StartSampleIndex           此块首点在当前采集任务中的序号
Timestamp                  软件生成块时的本机时间
ChannelCount               通道数
SamplesPerChannel          每通道点数
```

原始 DMA word 必须先截断到通道数的整数倍，再解交错。不能把返回的 word 数当作每通道点数。

## 文件输出

`WaveformWriter` 输出：

- `.bin`：小端 `float32`，按采样点交错。
- `.json`：通道数、采样率、量程、每通道点数、布局、单位和时间。

Python 读取示例：

```python
data = np.fromfile(path, dtype="<f4").reshape(-1, channel_count).T
```

结果形状为 `[通道][采样点]`。

## 资源生命周期示例

完整可运行版本见 `examples/ConsoleIntegration/Program.cs`。生产代码的核心要求是：

```csharp
try
{
    await digitizer.OpenAsync(device, token);
    await digitizer.ConfigureAsync(config, token);
    await foreach (var block in digitizer.StartAcquisitionAsync(token))
    {
        await pipeline.WriteAsync(block, token);
    }
}
finally
{
    await digitizer.StopAsync();
    await digitizer.CloseAsync();
}
```