> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elata.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# 协议要求

> 在编写设备适配器之前，收集所需的协议、BLE 和元数据细节。

请在实现开始之前完成这项工作。

一份清晰的协议清单可以避免大多数集成延误，也能避免常见的失败情况：适配器只在某一次测试会话或某一个固件版本上能用。

## 必需的交付信息

为你计划支持的每个设备和固件版本收集以下信息。

| 方面 | 需要记录的内容 |
| - | - |
| 发现 | 设备名称模式、服务 UUID、过滤条件 |
| GATT 布局 | 特征值、方向、通知/读/写行为 |
| 数据包格式 | 分帧、字节序、包头、计数器、校验和 |
| EEG 数据 | 通道名称、通道数、采样率、单位、缩放 |
| 时序 | 设备时间戳、本地时间戳、序列行为 |
| 会话控制 | 开始或停止数据流所需的命令 |
| 故障模式 | 断开行为、低电量行为、固件问题 |

## BLE 清单模板

以下为最低要求的信息格式：

```md theme={null}
## Device
- Model:
- Firmware:
- Transport: Web Bluetooth / bridge / native helper

## Discovery
- Device name prefix:
- Primary service UUIDs:
- Required optional services:

## Characteristics
- UUID:
  - purpose:
  - read / write / notify:
  - notes:

## EEG payload
- channel names:
- channel count:
- sample rate:
- units and scaling:
- timestamp source:

## Session control
- how streaming starts:
- how streaming stops:
- reconnect notes:
```

## 应尽早回答的数据包问题

| 问题 | 原因 |
| - | - |
| 数据包如何开始和结束？ | 解码器需要确定的分帧规则。 |
| 是否有包计数器或序列字段？ | 有助于检测丢包、乱序和损坏。 |
| 是否有校验和或 CRC？ | 有助于安全地拒绝坏包。 |
| 样本如何打包？ | 解码器需要准确的字节布局和字节序。 |
| 一个数据包中是否可能包含多个时间步？ | 这会影响行批处理和时间戳处理。 |
| 不同固件版本之间有哪些变化？ | 你需要可预测的版本判断和测试覆盖。 |

## 元数据规则

你的适配器绝不应猜测基本信息。

| 元数据 | 规则 |
| - | - |
| 通道名称 | 使用有文档说明的稳定顺序 |
| 通道数 | 与输出的 EEG 行严格一致 |
| 采样率 | 使用当前模式下的真实输出速率 |
| 单位 | 说明数值是原始值、缩放值还是转换后的值 |
| 时钟来源 | 明确说明为 `device` 或 `local` |

<Warning>
  在这些元数据验证之前，不要调优模型或下游应用逻辑。大多数可靠性问题都从这里开始。
</Warning>

## 浏览器和平台问题

本指南聚焦于设备集成，但平台限制仍然重要。

在规划浏览器 BLE 上线之前，请确认：

| 问题 | 需要确认 |
| - | - |
| 设备能否通过 Web Bluetooth 工作？ | 此流程仅支持 Chromium 内核浏览器 |
| 是否需要安全上下文？ | `https://` 或 `localhost` |
| 是否需要原生辅助程序？ | 如果需要，请使用独立包或桥接路径 |
| Safari 或 iOS 是否重要？ | 这些平台不提供浏览器 Web Bluetooth |

当前的平台要求见[兼容性](/cn/sdk/operations/compatibility)。

## 就绪的标准

当你可以不靠猜测地回答以下所有问题时，就可以开始实现了：

1. 你采用哪种传输路径
2. 浏览器如何发现设备
3. 会话如何开始和停止
4. 数据包字节如何变成 EEG 行
5. 时间戳和通道元数据应如何输出
6. 不同固件、浏览器或平台有哪些注意事项

## 相关文档

* [集成路径](./integration-paths)
* [传输协议](./transport-contract)
* [兼容性](/cn/sdk/operations/compatibility)
* [故障排查](/cn/sdk/operations/troubleshooting)

## 下一步

<CardGroup cols={2}>
  <Card title="构建适配器" icon="arrow-right" href="./adapter-implementation">
    基于协议清单实现干净的设备层。
  </Card>

  <Card title="验证可靠性" icon="arrow-right" href="./testing-and-validation">
    把协议假设转化为可重复的测试。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.