# gps_mqtt

**Repository Path**: rugels/gps_mqtt

## Basic Information

- **Project Name**: gps_mqtt
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-19
- **Last Updated**: 2025-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GPS数据MQTT接口技术文档

## 1. 数据格式规范

### 1.1 JSON数据结构

GPS数据采用JSON格式传输，具体结构如下：

```json
{
  "utc_time": "084530.00",
  "latitude": 31.23045,
  "longitude": 121.47379,
  "satellites": 8,
  "altitude": 25.45,
  "true_north_heading": 45.5,
  "magnetic_north_heading": 46.2,
  "ground_speed_kn": 12.5,
  "ground_speed_kmh": 23.15
}
```

### 1.2 字段说明

| 字段名称               | 数据类型 | 单位      | 描述                     | 示例值      |
| ---------------------- | -------- | --------- | ------------------------ | ----------- |
| utc_time               | string   | -         | UTC时间戳，格式HHMMSS.ss | "084530.00" |
| latitude               | float    | 度        | 纬度坐标，北纬为正       | 31.23045    |
| longitude              | float    | 度        | 经度坐标，东经为正       | 121.47379   |
| satellites             | integer  | 个        | 可见卫星数量             | 8           |
| altitude               | float    | 米        | 海拔高度                 | 25.45       |
| true_north_heading     | float    | 度        | 真北方向航向角           | 45.5        |
| magnetic_north_heading | float    | 度        | 磁北方向航向角           | 46.2        |
| ground_speed_kn        | float    | 节        | 地面速度（节）           | 12.5        |
| ground_speed_kmh       | float    | 公里/小时 | 地面速度（公里/小时）    | 23.15       |

## 2. MQTT配置

### 2.1 连接参数

| 参数       | 值                  | 说明                                                         |
| ---------- | ------------------- | ------------------------------------------------------------ |
| Broker地址 | 由部署环境决定      | 生产环境：mqtt.prod.example.com<br>测试环境：mqtt.test.example.com |
| 端口       | 1883                | 默认MQTT端口                                                 |
| 主题       | `/device1/gps_data` | 设备GPS数据主题                                              |
| QoS等级    | 1                   | 至少交付一次                                                 |
| 保留消息   | false               | 不保留消息                                                   |

### 2.2 主题结构
```
/device{device_id}/gps_data
```
- `device_id`: 设备唯一标识符

## 3. 代码实现示例

### 3.1 Python发布示例

```python
import json
import paho.mqtt.client as mqtt
import time

class GPSDataPublisher:
    def __init__(self, broker_host, broker_port=1883):
        self.broker_host = broker_host
        self.broker_port = broker_port
        self.client = mqtt.Client()
        self.topic = "/device1/gps_data"
        
        # 设置回调函数
        self.client.on_connect = self.on_connect
        self.client.on_publish = self.on_publish
        
    def on_connect(self, client, userdata, flags, rc):
        if rc == 0:
            print("成功连接到MQTT broker")
        else:
            print(f"连接失败，错误代码: {rc}")
            
    def on_publish(self, client, userdata, mid):
        print(f"消息发布成功，消息ID: {mid}")
        
    def connect(self):
        try:
            self.client.connect(self.broker_host, self.broker_port, 60)
            self.client.loop_start()
            return True
        except Exception as e:
            print(f"连接异常: {e}")
            return False
            
    def publish_gps_data(self, gps_data):
        """
        发布GPS数据
        :param gps_data: 符合规范的GPS数据字典
        """
        try:
            payload = json.dumps(gps_data)
            result = self.client.publish(self.topic, payload, qos=1)
            
            if result.rc == mqtt.MQTT_ERR_SUCCESS:
                print(f"GPS数据发布成功")
                return True
            else:
                print(f"发布失败，错误代码: {result.rc}")
                return False
                
        except Exception as e:
            print(f"发布异常: {e}")
            return False
            
    def disconnect(self):
        self.client.loop_stop()
        self.client.disconnect()
        print("MQTT连接已断开")

# 使用示例
if __name__ == "__main__":
    publisher = GPSDataPublisher("broker.example.com")
    
    if publisher.connect():
        gps_data = {
            "utc_time": "084530.00",
            "latitude": 31.23045,
            "longitude": 121.47379,
            "satellites": 8,
            "altitude": 25.45,
            "true_north_heading": 45.5,
            "magnetic_north_heading": 46.2,
            "ground_speed_kn": 12.5,
            "ground_speed_kmh": 23.15
        }
        
        publisher.publish_gps_data(gps_data)
        time.sleep(1)
        publisher.disconnect()
```

## 4. 数据有效性

- 纬度范围：-90° 到 +90°
- 经度范围：-180° 到 +180°
- 卫星数量：≥ 4（有效定位）
- 时间格式必须符合UTC标准

## 5.测试环境

```bash
# 安装依赖
pip install paho-mqtt
```