ha_traccar集成新增WGS84坐标实体，解决高德坐标偏移问题

MagicStarTrace

兼容高德坐标系的 Traccar 服务器Home Assistant集成，支持实时设备跟踪、传感器监控和事件响应。

**注意**：本项目基于原版插件进行了改进，新增了 WGS84 坐标转换实体，特别适用于中国地区的地图服务。

**推荐环境**：建议配合 Docker 版本的 Traccar 使用，推荐镜像：`bg6rsh/traccar-amap:5.8`

## 功能特性

### 🚗 实时设备跟踪
- **GPS 定位跟踪**：实时更新设备位置信息
- **坐标系统支持**：支持 WGS84 和 GCJ02 坐标系统
- **智能坐标转换**：新增 WGS84 坐标实体，可直接用于家庭区域判断
- **位置准确性监控**：显示 GPS 定位精度
- **地址反向解析**：自动获取设备当前地址

### 📊 丰富的传感器支持
- **电池监控**：实时显示设备电池电量（百分比）
- **充电状态检测**：监控设备充电状态变化
- **运动检测**：检测设备是否在移动
- **网络状态**：显示设备在线/离线状态
- **速度监控**：实时显示设备移动速度（公里/小时）
- **海拔高度**：显示设备当前海拔（米）
- **行驶方向**：显示设备移动方向（度）
- **温度监控**：设备温度传感器（如果支持）
- **里程统计**：总行驶距离统计（公里）

### 🌍 地理围栏功能
- **围栏检测**：自动检测设备进入/离开地理围栏
- **多围栏支持**：支持多个地理围栏同时监控
- **围栏事件**：围栏进出事件触发

### ⚡ 实时事件系统
- **WebSocket 连接**：与 Traccar 服务器保持实时连接
- **即时更新**：设备状态变化立即推送到 Home Assistant
- **事件类型支持**：
  - 设备上线/离线
  - 开始/停止移动
  - 进入/离开地理围栏
  - 超速警告
  - 点火开关状态
  - 维护提醒
  - 报警事件

## 支持的实体类型

### 设备跟踪器 (Device Tracker)
每个 Traccar 设备会创建以下跟踪器实体：

| 实体ID | 名称 | 描述 |
|--------|------|------|
| `device_tracker.{设备名}_` | 标准设备跟踪器 | 显示设备在地图上的位置 |
| `device_tracker.{设备名}_wgs84` | WGS84坐标跟踪器 | **新增功能** - 提供转换后的精确坐标，可直接用于区域判断 |

**状态属性：**
- `latitude` / `longitude` - 设备坐标
- `gps_accuracy` - GPS 精度
- `address` - 当前地址
- `speed` - 移动速度
- `course` - 行驶方向
- `altitude` - 海拔高度
- `battery_level` - 电池电量
- `status` - 设备状态（在线/离线）
- `motion` - 运动状态
- `geofence` - 当前地理围栏

### 传感器 (Sensor)
每个设备会自动创建以下传感器：

| 实体ID | 名称 | 单位 | 设备类别 | 描述 |
|--------|------|------|----------|------|
| `sensor.{设备名}_battery` | 电池 | % | 电池 | 设备电池电量百分比 |
| `sensor.{设备名}_speed` | 速度 | km/h | 速度 | 设备移动速度 |
| `sensor.{设备名}_altitude` | 海拔 | m | 距离 | 设备当前海拔高度 |
| `sensor.{设备名}_course` | 方向 | ° | - | 设备行驶方向角度 |
| `sensor.{设备名}_address` | 地址 | - | - | 设备当前位置地址 |
| `sensor.{设备名}_geofence` | 地理围栏 | - | - | 当前所在地理围栏名称 |
| `sensor.{设备名}_temperature` | 温度 | °C | 温度 | 设备温度（如果支持） |
| `sensor.{设备名}_distance` | 距离 | km | 距离 | 总行驶距离 |

### 二进制传感器 (Binary Sensor)
每个设备会创建以下二进制传感器：

| 实体ID | 名称 | 设备类别 | 描述 |
|--------|------|----------|------|
| `binary_sensor.{设备名}_motion` | 运动 | 运动 | 设备是否在移动 |
| `binary_sensor.{设备名}_status` | 在线 | 连接性 | 设备在线状态 |
| `binary_sensor.{设备名}_charging` | 充电 | 电池充电 | 设备充电状态 |

## 安装方法

### 通过 HACS 安装（推荐）

1. 在 HACS 中添加自定义存储库：
   ```
   https://github.com/MagicStarTrace/ha_traccar
   ```

2. 搜索并安装 "HA Traccar"

3. 重启 Home Assistant

### 手动安装

1. 下载附件中的源码
2. 将 `ha_traccar` 文件夹复制到 `custom_components` 目录
3. 重启 Home Assistant

## 配置方法

### 通过 UI 配置（推荐）

1. 进入 **配置** → **集成**
2. 点击 **添加集成**
3. 搜索 **Traccar 服务器**
4. 输入连接信息：
   - **主机名**：Traccar 服务器地址
   - **端口**：Traccar 服务器端口（默认 8082）
   - **用户名**：Traccar 账户用户名
   - **密码**：Traccar 账户密码
   - **SSL**：是否使用 HTTPS 连接
   - **SSL 验证**：是否验证 SSL 证书

### 高级配置选项

在集成配置页面的 **选项** 中可以设置：

#### 精度过滤
- **最大精度**：过滤精度低于指定值的位置数据（米）
- **跳过精度过滤的属性**：属性不受精度过滤影响


## 坐标系统支持

本集成支持多种坐标系统，特别针对中国地区：

### WGS84 坐标系（国际标准）
- **用途**：国际通用坐标系统
- **精度**：全球范围内精确
- **应用**：国外地图服务、GPS 设备原始数据

### GCJ02 坐标系（中国标准）
- **用途**：中国境内地图服务
- **精度**：在中国境内经过加密偏移
- **应用**：高德地图、腾讯地图等

### 坐标转换功能（新增特性）
- **智能坐标转换**：自动检测并转换坐标系统
- **双坐标支持**：在设备跟踪器属性中同时提供两种坐标
- **WGS84 专用实体**：新增独立的 WGS84 坐标跟踪器实体
- **区域判断优化**：WGS84 实体可直接用于 Home Assistant 的区域（Zone）判断
- **高精度转换**：配合 `bg6rsh/traccar-amap:5.8` 镜像获得最佳转换效果


## 故障排除

### 常见问题

#### 1. 设备无法连接
- 检查 Traccar 服务器地址和端口
- 确认用户名和密码正确
- 检查网络连接和防火墙设置

#### 2. 位置更新不及时
- 检查设备上报间隔设置
- 确认 WebSocket 连接正常
- 查看 Traccar 服务器日志

#### 3. 充电状态延迟
- 充电状态依赖位置数据更新
- 建议调整设备上报间隔或使用事件触发

#### 4. 坐标偏移问题
- 确认使用正确的坐标系统
- 检查坐标转换设置
- 验证设备GPS精度

### 日志调试

在 `configuration.yaml` 中添加调试日志：

```yaml
logger:
  default: warning
  logs:
    custom_components.ha_traccar: debug
    pytraccar: debug
```

### 支持的 Traccar 版本
- **Traccar 服务器**：4.0 及以上版本
- **Traccar 客户端**：所有版本
- **推荐 Docker 镜像**：`bg6rsh/traccar-amap:5.8`（已测试兼容）
- **推荐理由**：该镜像针对中国地区进行了优化，提供更好的地图服务和坐标转换支持

#### Docker 部署示例
```bash
docker run -d \
  --name traccar \
  -p 8082:8082 \
  -p 5013:5013 \
  -v /opt/traccar/data:/opt/traccar/data \
  bg6rsh/traccar-amap:5.8
```

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个集成。

### 开发环境设置
1. Fork 此项目
2. 创建开发分支
3. 进行修改并测试
4. 提交 Pull Request


---



如果此集成对您有帮助，请考虑给项目一个star ！

hz153jht

楼主你好，我已经安装好该插件，traccar amap是5.8版本，但是安装好后在实体里好像没有看到自动增加的实体呢？

MagicStarTrace

hz153jht 发表于 2025-8-2 11:23
楼主你好，我已经安装好该插件，traccar amap是5.8版本，但是安装好后在实体里好像没有看到自动增加的实体 ...

看看日志，有没有报错

hz153jht

huyifanstar 发表于 2025-8-6 11:37
看看日志，有没有报错

是我理解错了，第一次接触traccar，我以为是HA中的跟踪器实体能反向同步到traccar里面去。结果后来发现是只有traccar里的设备能同步到HA这边来。

MagicStarTrace

hz153jht 发表于 2025-8-7 20:27
是我理解错了，第一次接触traccar，我以为是HA中的跟踪器实体能反向同步到traccar里面去。结果后来发现是 ...

traccar需要traccar cleint获取坐标的

可以接车机

hz153jht

huyifanstar 发表于 2025-8-8 09:49
traccar需要traccar cleint获取坐标的

可以接车机

嗯，在车机里安装了。前两天都是正常的，昨天下午好像没生效了，HA的集成里提示实体不可用，但是traccar服务器这边一切正常。  之前有在traccar里对设备进行过重命名，是这个原因吗？

book123

楼主您好，今天HAOS升级到2025.8.0后忽然不行了，实体显示虚的，不知道是不是个例。

MagicStarTrace

hz153jht 发表于 2025-8-8 12:10
嗯，在车机里安装了。前两天都是正常的，昨天下午好像没生效了，HA的集成里提示实体不可用，但是traccar ...

重命名过 建议重新配置下插件

重新获取设备

MagicStarTrace

book123 发表于 2025-8-9 19:04
楼主您好，今天HAOS升级到2025.8.0后忽然不行了，实体显示虚的，不知道是不是个例。 ...

用这么新的版本？ 版本太新 感觉bug多

我手头没有2025.8.0的环境，等后面我有空看看吧

fencanyan

全是不可用，



日志记录器: homeassistant.components.sensor
来源: helpers/entity_platform.py:676
集成: 传感器 (文档, 问题)
首次出现: 11:28:58 (3 次出现)
上次记录: 11:28:58

Error adding entity sensor.fei_altitude for domain sensor with platform ha_traccar
Error adding entity sensor.fei_speed for domain sensor with platform ha_traccar
Error adding entity sensor.fei_distance for domain sensor with platform ha_traccar
Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/helpers/entity_platform.py", line 676, in _async_add_entities
    await self._async_add_entity(
        entity, False, entity_registry, config_subentry_id
    )
  File "/usr/src/homeassistant/homeassistant/helpers/entity_platform.py", line 1002, in _async_add_entity
    await entity.add_to_platform_finish()
  File "/usr/src/homeassistant/homeassistant/helpers/entity.py", line 1379, in add_to_platform_finish
    await self.async_internal_added_to_hass()
  File "/usr/src/homeassistant/homeassistant/components/sensor/__init__.py", line 292, in async_internal_added_to_hass
    self._update_suggested_precision()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/src/homeassistant/homeassistant/components/sensor/__init__.py", line 855, in _update_suggested_precision
    registry.async_update_entity_options(
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        self.entity_id, DOMAIN, sensor_options or None
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/src/homeassistant/homeassistant/helpers/entity_registry.py", line 1484, in async_update_entity_options
    old = self.entities[entity_id]
          ~~~~~~~~~~~~~^^^^^^^^^^^
  File "/usr/local/lib/python3.13/collections/__init__.py", line 1139, in __getitem__
    raise KeyError(key)
KeyError: 'sensor.fei_altitude'