michaelwoods/onstar2mqtt

OnStar API 至 MQTT 转发服务镜像

镜像概述

该镜像提供一个轻量级服务，用于将OnStar API（通用汽车车联网服务）的车辆数据转发至MQTT broker，实现车辆状态、位置、诊断等数据的实时传输与集成。通过该服务，用户可将OnStar平台的车辆数据便捷地接入自定义系统，满足监控、分析或自动化需求。

核心功能与特性

• 实时数据转发：持续拉取OnStar API数据并推送至指定MQTT主题
• 多端点支持：兼容OnStar API的车辆状态、位置、燃油/电量、诊断故障码等核心数据端点
• 灵活配置：支持自定义MQTT连接参数（broker地址、端口、认证信息）及数据拉取间隔
• 安全连接：支持MQTT over TLS（mqtts）及OnStar API认证机制
• 轻量化设计：基于Alpine构建，镜像体积小，资源占用低

使用场景

• 车辆监控系统：集成至自定义监控面板，实时显示车辆位置、状态及告警信息
• 智能家居联动：根据车辆位置触发家居设备（如远程启动空调、开启车库门）
• 车队管理平台：集中收集多车辆数据，支持车队运营监控与效率分析
• 数据分析平台：将车辆历史数据存储至数据库，用于驾驶行为分析或车辆健康评估

使用方法与配置说明

前提条件

• 有效的OnStar开发者账号及API访问凭证（API Key、Client ID等）
• 可访问的MQTT broker（自建或第三方服务，如Mosquitto、EMQX、AWS IoT等）
• 目标车辆已激活OnStar服务并授予API访问权限

快速启动（Docker Run）

bash
docker run -d \
  --name onstar-mqtt-forwarder \
  -e ONSTAR_API_KEY="your_onstar_api_key" \
  -e ONSTAR_CLIENT_ID="your_client_id" \
  -e ONSTAR_VIN="your_vehicle_vin" \
  -e MQTT_BROKER="mqtt.example.com" \
  -e MQTT_PORT=8883 \
  -e MQTT_TOPIC="vehicles/onstar/vin_${VIN}" \
  -e MQTT_USER="mqtt_username" \
  -e MQTT_PASSWORD="mqtt_password" \
  -e MQTT_PROTOCOL="mqtts" \
  -e POLL_INTERVAL=30 \
  --restart unless-stopped \
  [镜像名称]

Docker Compose 配置示例

yaml
version: '3.8'
services:
  onstar-mqtt-forwarder:
    image: docker.xuanyuan.run/[镜像名称]
    container_name: onstar-mqtt-forwarder
    environment:
      # OnStar API 配置
      - ONSTAR_API_KEY=your_onstar_api_key
      - ONSTAR_CLIENT_ID=your_client_id
      - ONSTAR_CLIENT_SECRET=your_client_secret
      - ONSTAR_VIN=your_vehicle_vin
      - ONSTAR_REGION=north_america  # 可选，支持north_america/europe/asia
      # MQTT 配置
      - MQTT_BROKER=mqtt.example.com
      - MQTT_PORT=8883
      - MQTT_TOPIC=vehicles/onstar/${ONSTAR_VIN}
      - MQTT_USER=mqtt_username
      - MQTT_PASSWORD=mqtt_password
      - MQTT_PROTOCOL=mqtts  # 可选，支持mqtt/mqtts/ws/wss
      - MQTT_QOS=1  # 可选，消息服务质量（0/1/2），默认1
      # 服务配置
      - POLL_INTERVAL=30  # 数据拉取间隔（秒），默认60
      - LOG_LEVEL=info  # 可选，日志级别（debug/info/warn/error），默认info
    restart: unless-stopped

环境变量配置说明

数据格式说明

转发至MQTT的消息为JSON格式，示例如下：

json
{
  "vin": "1HGCM82633A123456",
  "timestamp": "2024-05-20T15:30:45Z",
  "vehicleStatus": {
    "ignition": "on",
    "speed": 65,
    "fuelLevel": 78,
    "range": 420,
    "tirePressure": {"frontLeft": 32, "frontRight": 33, "rearLeft": 31, "rearRight": 32}
  },
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "timestamp": "2024-05-20T15:30:40Z"
  },
  "diagnostics": {
    "dtcCount": 0,
    "lastUpdated": "2024-05-20T14:00:00Z"
  }
}

故障排除

• API连接失败：检查ONSTAR_API_KEY、CLIENT_ID及VIN是否正确，确认车辆已授予API访问权限
• MQTT连接超时：验证MQTT_BROKER地址及端口是否可达，检查防火墙规则是否允许容器出站连接
• 数据推送延迟：调整POLL_INTERVAL参数减小拉取间隔（最小值10秒），或检查网络延迟
• 日志查看：通过docker logs onstar-mqtt-forwarder查看详细日志，建议开启debug级别定位问题