# 数据推送

## 推送设置

目前我们支持 HTTP 和 MQTT 协议推送定位结果数据。可在 WEB 控制台 http://localhost:8880 中的「推送设置」版块设置推送目标。

<Frame caption="">
![ape.webp](https://api.apifox.com/api/v1/projects/8175002/resources/658367/image-preview)
</Frame>

### 格式
- Raw：二进制小端模式
- Json：JSON

### 压缩
对推送的数据进行压缩处理。
- None：不压缩
- Zstd：用 Zstd 压缩
- Lz4：用 Lz4 压缩
- Gzip：用 Gzip 压缩

### 间隔
推送时间间隔。

### URI

推送地址用标准 URI 表示。示例如下：
- `http://192.168.1.100:8080?key=xxx`
- `https://192.168.1.100:8443?bearer_token=xxx`
- `mqtt://username:password@192.168.1.100:1883?client_id=client123&topic=/ape/123`
- `mqtts://username:password@192.168.1.100:1883?client_id=client123&topic=/ape/123`

以 `http://192.168.1.100:8080?key=xxx` 和 `mqtt://192.168.1.100:1883?client_id=client123&topic=/ape/123` 为例：
|消息类型|HTTP URL|MQTT Topic|
|---|---|---|
|定位结果|POST http://192.168.1.100:8080/positions?key=xxx|/ape/123/positions|
|用户数据|POST http://192.168.1.100:8080/userdata?key=xxx|/ape/123/userdata|
|基站更新时间|POST http://192.168.1.100:8080/locator-timestamps?key=xxx|/ape/123/locator-timestamps|

## 数据格式
### 定位结果
```rust
pub struct LocatedResult {
    /// 标签 MAC
    /// - 这里是十进制。如：`186916976721921`。转为 16 进制就是：`AA0000000001`。
    pub mac: u64,
    /// 地图 ID
    pub map: u32,
    pub x: f32,
    pub y: f32,
    pub z: f32,
    /// 定位的时间戳（毫秒）
    pub ts: i64,
    /// 定位基站的 MAC
    /// - 这里是十进制。如：`204509162766337`。转为 16 进制就是：`BA0000000001`。
    pub locator: u64,
}
```
#### 示例
```json
[
  {
    "mac": 186916976721921,
    "map": 1,
    "x": 12.34,
    "y": 45.67,
    "z": 2.8,
    "ts": 1785623491000,
    "locator": 204509162766337
  },
  {
    "mac": 186916976721922,
    "map": 1,
    "x": 15.72,
    "y": 42.19,
    "z": 2.8,
    "ts": 1785623493500,
    "locator": 204509162766337
  },
  {
    "mac": 186916976721923,
    "map": 1,
    "x": 8.11,
    "y": 33.45,
    "z": 3.0,
    "ts": 1785623496120,
    "locator": 204509162766337
  }
]
```
### 用户数据
```rust
pub struct UserData {
    pub mac: u64,
    pub ts: i64,
    pub kind: u8,
    pub data: [u8; 11],
}
```
### 基站更新时间
```rust
pub struct LocatorTimestamp {
    pub mac: u64,
    pub ts: i64,
}
```