Archived
Compare commits
14
Commits
8e5b8f0095
..
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
fb97346806 | ||
|
|
36a505b0e5 | ||
|
|
6f2cf62a2c | ||
|
|
670fb8bc81 | ||
|
|
9e55c585f9 | ||
|
|
9b937c8840 | ||
|
|
d2e399afc2 | ||
|
|
c596db47bf | ||
|
|
e4851696eb | ||
|
|
b4fc6f799f | ||
|
|
5659408d8d | ||
|
|
9658db3bcc | ||
|
|
25088f660e | ||
|
|
042630b7df |
No files matched your search
@@ -1 +0,0 @@
|
||||
github: eigger
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
name: "🚗 Vehicle PID Contribution (English)"
|
||||
about: Share your vehicle's working OBD-II PID configuration.
|
||||
title: "[Vehicle] Manufacturer Model (Year)"
|
||||
labels: vehicle-config
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
### 1. Vehicle Information
|
||||
* **Manufacturer**:
|
||||
* **Model**:
|
||||
* **Year**:
|
||||
* **Engine/Fuel Type**: (e.g., Gasoline, Diesel, Hybrid, EV)
|
||||
|
||||
### 2. Connection Settings
|
||||
* **OBD-II Adapter Model**: (e.g., vLinker MC+, ELM327 v1.5)
|
||||
* **OBD Protocol / Init Commands (If any)**: (e.g., `ATSP6`, `ATSP0` or leave blank if standard)
|
||||
|
||||
### 3. Sensor List
|
||||
Please list the OBD PIDs you successfully configured.
|
||||
|
||||
| Sensor Name | Mode | PID | Formula (Decoding) | Unit | Description | Update Interval |
|
||||
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
|
||||
| *e.g., Engine Oil Temp* | *22* | *1008* | *a - 40* | *°C* | *Engine oil temperature* | *10s* |
|
||||
| | | | | | | |
|
||||
| | | | | | | |
|
||||
|
||||
*Note: In the formula, use `a`, `b`, `c`, `d`, etc., for response bytes.*
|
||||
|
||||
### 4. Raw YAML Draft (Optional)
|
||||
If you have already generated a YAML config draft in the app or wrote one yourself, paste it here:
|
||||
|
||||
```yaml
|
||||
# Paste your YAML snippet here if available
|
||||
```
|
||||
|
||||
### 5. Verification
|
||||
* [ ] I have successfully tested these PIDs in my car using the HassBle app.
|
||||
* Additional comments or screenshots:
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
name: "🚗 차량 PID 제보 (Korean)"
|
||||
about: 작동 확인된 차량의 OBD-II PID 설정을 공유해 주세요.
|
||||
title: "[Vehicle] 제조사 모델명 (연식)"
|
||||
labels: vehicle-config
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
### 1. 차량 정보
|
||||
* **제조사 (Manufacturer)**:
|
||||
* **모델명 (Model)**:
|
||||
* **연식 (Year)**:
|
||||
* **유종/엔진 형식**: (예: 가솔린, 디젤, 하이브리드, EV)
|
||||
|
||||
### 2. 연결 설정
|
||||
* **OBD-II 어댑터 모델**: (예: vLinker MC+, ELM327 v1.5)
|
||||
* **OBD 프로토콜 / 초기화 명령어**: (예: `ATSP6`, `ATSP0` 또는 표준 규격일 경우 생략 가능)
|
||||
|
||||
### 3. 센서 목록
|
||||
정상 작동 확인된 PID 목록을 작성해 주세요.
|
||||
|
||||
| 센서 이름 (영문 권장) | Mode | PID | 변환 수식 (Formula) | 단위 (Unit) | 설명 | 폴링 주기 |
|
||||
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
|
||||
| *예) engine_oil_temp* | *22* | *1008* | *a - 40* | *°C* | *엔진 오일 온도* | *10s* |
|
||||
| | | | | | | |
|
||||
| | | | | | | |
|
||||
|
||||
*참고: 수식에는 수신 바이트 순서대로 `a`, `b`, `c`, `d` 등을 변수로 사용합니다.*
|
||||
|
||||
### 4. YAML 초안 (선택 사항)
|
||||
앱에서 내보낸 YAML이나 직접 작성한 초안이 있다면 아래에 붙여넣어 주세요.
|
||||
|
||||
```yaml
|
||||
# 여기에 YAML 코드를 붙여넣어 주세요.
|
||||
```
|
||||
|
||||
### 5. 작동 확인 여부
|
||||
* [ ] HassBle 앱을 통해 실제 차량에서 값이 정상적으로 읽히는 것을 확인했습니다.
|
||||
* 추가 설명 및 작동 스크린샷:
|
||||
@@ -1,25 +0,0 @@
|
||||
## Description
|
||||
Please describe the vehicle template or configuration changes you are proposing.
|
||||
|
||||
- Added/Updated Vehicle: E.g., *Hyundai Avante CN7*
|
||||
- Source Type: OBD / BLE Advertisement / GATT
|
||||
- Main Features: E.g., *Added custom Mode 22 PIDs for Oil Temperature and Gear Status*
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
Before submitting this PR, please check the following:
|
||||
|
||||
- [ ] **Valid YAML Syntax**: The YAML formatting is correct and contains no parser errors.
|
||||
- [ ] **No Hex Literals for IDs**: Used decimal integers for numeric parameters like `manufacturer_id` (e.g., Apple is `76`, not `0x004C`).
|
||||
- [ ] **Unique Template IDs**: The new template ID is unique and doesn't conflict with existing ones in `templates.yaml`.
|
||||
- [ ] **Tested & Verified**: I have tested this configuration in the HassBle app and verified that the sensor data is decoded properly.
|
||||
|
||||
---
|
||||
|
||||
## YAML Code Snippet (Optional)
|
||||
If you've added a new template, you can highlight it below for a quick review:
|
||||
|
||||
```yaml
|
||||
# Put your added template block here
|
||||
```
|
||||
@@ -1,25 +0,0 @@
|
||||
## Description
|
||||
Please describe the vehicle template or configuration changes you are proposing.
|
||||
|
||||
- Added/Updated Vehicle: E.g., *Hyundai Avante CN7*
|
||||
- Source Type: OBD / BLE Advertisement / GATT
|
||||
- Main Features: E.g., *Added custom Mode 22 PIDs for Oil Temperature and Gear Status*
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
Before submitting this PR, please check the following:
|
||||
|
||||
- [ ] **Valid YAML Syntax**: The YAML formatting is correct and contains no parser errors.
|
||||
- [ ] **No Hex Literals for IDs**: Used decimal integers for numeric parameters like `manufacturer_id` (e.g., Apple is `76`, not `0x004C`).
|
||||
- [ ] **Unique Template IDs**: The new template ID is unique and doesn't conflict with existing ones in `templates.yaml`.
|
||||
- [ ] **Tested & Verified**: I have tested this configuration in the HassBle app and verified that the sensor data is decoded properly.
|
||||
|
||||
---
|
||||
|
||||
## YAML Code Snippet (Optional)
|
||||
If you've added a new template, you can highlight it below for a quick review:
|
||||
|
||||
```yaml
|
||||
# Put your added template block here
|
||||
```
|
||||
@@ -1,25 +0,0 @@
|
||||
## 변경 사항 설명 (Description)
|
||||
제안하시는 차량 템플릿 또는 설정 변경 사항을 설명해 주세요.
|
||||
|
||||
- 추가/업데이트된 차량: 예) *현대 아반떼 CN7*
|
||||
- 소스 타입: OBD / BLE Advertisement / GATT
|
||||
- 주요 기능: 예) *엔진 오일 온도 및 기어 단수 커스텀 Mode 22 PID 추가*
|
||||
|
||||
---
|
||||
|
||||
## 체크리스트 (Checklist)
|
||||
PR을 제출하기 전에 아래 사항들을 확인해 주세요.
|
||||
|
||||
- [ ] **올바른 YAML 문법**: YAML 포맷에 구문 오류가 없습니다.
|
||||
- [ ] **ID 필드에 16진수(Hex) 금지**: `manufacturer_id` 등의 숫자 파라미터에는 `0x...` hex 대신 10진수 정수를 사용했습니다. (예: Apple은 `0x004C` 대신 `76`)
|
||||
- [ ] **템플릿 ID 중복 확인**: 추가한 템플릿의 ID가 `templates.yaml` 내의 기존 ID와 중복되지 않습니다.
|
||||
- [ ] **작동 검증 완료**: HassBle 앱에서 실제로 이 설정을 구동하여 센서 데이터가 올바르게 디코딩되는지 확인했습니다.
|
||||
|
||||
---
|
||||
|
||||
## 추가된 YAML 코드 (선택 사항)
|
||||
새 템플릿이 추가된 경우 아래에 코드를 작성해 주시면 빠른 리뷰에 도움이 됩니다.
|
||||
|
||||
```yaml
|
||||
# 여기에 추가된 템플릿 블록을 붙여넣어 주세요.
|
||||
```
|
||||
@@ -0,0 +1,27 @@
|
||||
name: Validate YAML Configs
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
name: Validate YAML Schema
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout Repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.11'
|
||||
|
||||
- name: Install Dependencies
|
||||
run: pip install pyyaml
|
||||
|
||||
- name: Validate config.yaml and templates.yaml
|
||||
run: python scripts/validate.py
|
||||
@@ -1,89 +0,0 @@
|
||||
# HassBle 차량 설정 및 PID 기여 가이드
|
||||
|
||||
**[English Version → CONTRIBUTING.md](CONTRIBUTING.md)**
|
||||
|
||||
HassBle는 커뮤니티 기반의 오픈소스 프로젝트로, 사용자들이 직접 성공적으로 연동한 OBD-II PID 설정과 BLE 기기 설정을 공유하며 함께 발전해 나갑니다.
|
||||
|
||||
본인의 차량에 맞는 PID 설정을 구축하셨다면, 아래 방법 중 편한 방식을 선택해 다른 사용자들을 위해 공유해 주세요! 차량의 설정을 공유하면 동일한 차종을 소유한 다른 사용자들이 단 몇 초 만에 설정을 완료할 수 있습니다.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 기여 방법
|
||||
|
||||
GitHub 사용 방식이나 YAML 파일 편집에 익숙한 정도에 따라 아래 두 가지 방법 중 하나를 선택하실 수 있습니다:
|
||||
|
||||
### 방법 A: GitHub Issue로 제보하기 (가장 쉬운 방법)
|
||||
Git이나 YAML 형식 작성이 익숙하지 않으시다면, 아래 정보를 포함하여 이슈(Issue)로 제보해 주세요. 관리자가 확인 후 검증하여 대신 `templates.yaml`에 반영해 드립니다.
|
||||
1. **차량 정보**: 제조사, 모델명, 연식, 유종/엔진 형식 (예: *2022년식 현대 아이오닉 5 EV*, *2020년식 쉐보레 콜로라도 2.8L 디젤*).
|
||||
2. **OBD-II 어댑터**: 사용 중인 어댑터 모델 (예: *vLinker MC+*, *ELM327 v1.5*).
|
||||
3. **OBD 프로토콜 / 초기화 명령어 (선택)**: 예) CAN 11bit 500kbps의 경우 `ATSP6` 등.
|
||||
4. **센서 목록**: 각 센서마다 다음 정보를 적어주세요:
|
||||
* **센서 이름 및 설명** (예: 엔진오일 온도)
|
||||
* **Mode & PID** (예: Mode `22`, PID `1008`)
|
||||
* **변환 수식 (Formula)** (예: 수신 바이트 계산식 `a - 40`)
|
||||
* **측정 단위** (예: `°C`)
|
||||
* **폴링 주기** (예: `10s` 마다)
|
||||
|
||||
### 방법 B: Pull Request (PR)로 직접 등록하기 (개발자 권장)
|
||||
GitHub 사용이 익숙하시다면 이 저장소의 [templates.yaml](templates.yaml) 파일에 본인의 차량 템플릿 설정을 직접 추가하고 Pull Request를 보내주세요. (PR 생성 시 한국어 템플릿을 선택하거나, URL 뒤에 `?template=pull_request_template_ko.md`를 붙여 작성하실 수 있습니다.)
|
||||
|
||||
---
|
||||
|
||||
## 📝 `templates.yaml` 작성법 및 예시
|
||||
|
||||
`templates.yaml`에 차종별 설정을 추가할 때는 아래 예시와 같은 형식을 사용합니다.
|
||||
|
||||
각 설정 필드에 대한 상세한 설명과 스펙은 이 저장소의 **[README.ko.md](README.ko.md)** 파일에 매우 상세하게 설명되어 있으니 참고해 주세요.
|
||||
|
||||
### 차량 템플릿 작성 예시
|
||||
|
||||
```yaml
|
||||
- id: obd_hyundai_avante_cn7
|
||||
name: "Hyundai Elantra/Avante CN7 (Gasoline)"
|
||||
description: "아반떼 CN7 가솔린 모델을 위한 기본 주행 데이터 및 엔진/미션오일 온도 센서 세트"
|
||||
device:
|
||||
id: avante_cn7_obd
|
||||
name: "Avante CN7 OBD"
|
||||
source: obd
|
||||
obd:
|
||||
service_uuid: "18F0" # OBD-II 어댑터의 BLE 서비스 UUID (대개 FFF0 또는 18F0)
|
||||
tx_char_uuid: "2AF1" # 쓰기(Write) 캐릭터리스틱 UUID
|
||||
rx_char_uuid: "2AF0" # 알림(Notify) 캐릭터리스틱 UUID
|
||||
tx_delay: 50ms # 명령 간 전송 딜레이
|
||||
init_commands: ["ATSP6"] # OBD 초기화 명령 (ATSP6 또는 ATSP0 등)
|
||||
sensors:
|
||||
# 1. 내장 프리셋 사용 (앱에 내장된 공통 PID 정의 활용)
|
||||
- { key: rpm, preset: rpm, update_interval: 2s }
|
||||
- { key: speed, preset: speed, update_interval: 2s }
|
||||
- { key: coolant_temp, preset: coolant_temp, update_interval: 10s }
|
||||
|
||||
# 2. 제조사 전용 확장 PID 수동 정의 (프리셋이 없는 경우)
|
||||
- key: engine_oil_temp
|
||||
mode: "22" # UDS Mode 22 (확장 PID 읽기)
|
||||
pid: "1008" # 4자리 PID Hex 코드
|
||||
formula: "a - 40" # 'a'는 수신된 첫 번째 바이트. 섭씨 온도로 변환하는 수식
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
update_interval: 10s
|
||||
|
||||
- key: trans_oil_temp
|
||||
mode: "22"
|
||||
pid: "2201"
|
||||
formula: "a - 40"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
update_interval: 10s
|
||||
```
|
||||
|
||||
### 💡 디코딩 수식(Formula) 작성 팁:
|
||||
* **바이트 변수**: 응답 바이트 순서대로 `a`, `b`, `c`, `d` 등을 변수로 사용합니다.
|
||||
* **수학 연산**: `+`, `-`, `*`, `/` 및 괄호 `()`를 사용해 수식을 구성할 수 있습니다. (예: 2바이트 조합 고해상도 값은 `(a*256+b)*0.1` 형식으로 많이 사용됩니다.)
|
||||
|
||||
---
|
||||
|
||||
## 🤝 도움이 필요하신가요?
|
||||
다른 앱(Torque Pro, Car Scanner 등)을 통해 본인 차량의 PID와 수식은 알아냈으나, 이를 HassBle의 YAML 스키마 형식으로 변환하기 어려우시다면 주저하지 말고 Q&A Discussion이나 Issue에 질문을 올려주세요. 커뮤니티가 기꺼이 변환 작성을 도와드립니다!
|
||||
|
||||
소중한 기여를 통해 모두가 더 편하게 차량 상태를 통합할 수 있도록 도와주셔서 감사합니다! 🚗💨
|
||||
@@ -1,91 +0,0 @@
|
||||
# Contributing to HassBle Configurations
|
||||
|
||||
**[한국어 기여 가이드 → CONTRIBUTING.ko.md](CONTRIBUTING.ko.md)**
|
||||
|
||||
Welcome! HassBle is a community-driven project, and we love it when users share their working OBD-II PID configurations and BLE device configurations.
|
||||
|
||||
By contributing your vehicle's specific PIDs and configurations, you can help other owners of the same car set up their Home Assistant integration in seconds.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 How to Contribute
|
||||
|
||||
Depending on your comfort level with GitHub and YAML, you can choose one of the following methods:
|
||||
|
||||
### Option A: Open a GitHub Issue (Easiest)
|
||||
If you are not familiar with Git or YAML editing, simply open an issue with the following details:
|
||||
1. **Vehicle Info**: Manufacturer, Model, Year, and Engine/Fuel Type (e.g., *2022 Hyundai Ioniq 5 EV*, *2020 Chevrolet Colorado 2.8L Diesel*).
|
||||
2. **OBD-II Adapter**: The adapter you are using (e.g., *vLinker MC+*, *ELM327 v1.5*).
|
||||
3. **OBD Protocol / Init Commands (If any)**: E.g., `ATSP6` for ISO 15765-4 CAN (11bit/500kbps).
|
||||
4. **Sensor List**: For each sensor, please provide:
|
||||
* **Name/Description** (e.g., Engine Oil Temperature)
|
||||
* **Mode & PID** (e.g., Mode `22`, PID `1008`)
|
||||
* **Formula** (e.g., `a - 40` to decode bytes)
|
||||
* **Unit of Measurement** (e.g., `°C`)
|
||||
* **Polling Interval** (e.g., every `10s`)
|
||||
|
||||
We will verify your submission and manually add it to the global `templates.yaml` list!
|
||||
|
||||
### Option B: Submit a Pull Request (PR) (For Developers)
|
||||
If you are comfortable with Git, you can directly add your vehicle configuration to [templates.yaml](templates.yaml) and submit a Pull Request. (You can select the English template when creating the PR, or append `?template=pull_request_template_en.md` to the PR creation URL.)
|
||||
|
||||
---
|
||||
|
||||
## 📝 How to Format Your Template in `templates.yaml`
|
||||
|
||||
When adding a new vehicle template to `templates.yaml`, please follow the structure below.
|
||||
|
||||
For detailed information about the parameters, please refer to the [README.md](README.md) file in this repository.
|
||||
|
||||
### Template Schema Example
|
||||
|
||||
```yaml
|
||||
- id: obd_hyundai_avante_cn7
|
||||
name: "Hyundai Elantra/Avante CN7 (Gasoline)"
|
||||
description: "Standard driving metrics plus engine/transmission oil temperature sensors."
|
||||
device:
|
||||
id: avante_cn7_obd
|
||||
name: "Avante CN7 OBD"
|
||||
source: obd
|
||||
obd:
|
||||
service_uuid: "18F0" # Ble service UUID of your OBD-II adapter (typically FFF0 or 18F0)
|
||||
tx_char_uuid: "2AF1" # Write characteristic UUID
|
||||
rx_char_uuid: "2AF0" # Notify characteristic UUID
|
||||
tx_delay: 50ms # Delay between sending commands
|
||||
init_commands: ["ATSP6"] # OBD initialization commands (often ATSP6 or ATSP0)
|
||||
sensors:
|
||||
# 1. Standard Presets (Using pre-defined presets in the app)
|
||||
- { key: rpm, preset: rpm, update_interval: 2s }
|
||||
- { key: speed, preset: speed, update_interval: 2s }
|
||||
- { key: coolant_temp, preset: coolant_temp, update_interval: 10s }
|
||||
|
||||
# 2. Custom Manufacturer-Specific UDS PIDs (Without presets)
|
||||
- key: engine_oil_temp
|
||||
mode: "22" # UDS mode 22 (Extended PIDs)
|
||||
pid: "1008" # 4-digit PID for Mode 22
|
||||
formula: "a - 40" # 'a' is the first response byte. Decodes the OBD reply to Celsius.
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
update_interval: 10s
|
||||
|
||||
- key: trans_oil_temp
|
||||
mode: "22"
|
||||
pid: "2201"
|
||||
formula: "a - 40"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
update_interval: 10s
|
||||
```
|
||||
|
||||
### 💡 Tips for Writing Formulas:
|
||||
* **Byte Variables**: Use `a`, `b`, `c`, `d`, etc., to represent sequential bytes returned from the OBD-II response.
|
||||
* **Math Operations**: Standard operations like `+`, `-`, `*`, `/`, and parentheses `()` are fully supported. (e.g., `(a*256+b)*0.1` is a common formula for reading high-resolution values).
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Need Help?
|
||||
If you've managed to read some PIDs using other OBD apps (like Torque Pro or Car Scanner) but aren't sure how to translate the formulas and PIDs into HassBle's YAML schema, feel free to open a Q&A Discussion or an Issue. The community is happy to help you format the YAML configurations!
|
||||
|
||||
Thank you for contributing and helping make HassBle better for everyone! 🚗💨
|
||||
-778
@@ -1,778 +0,0 @@
|
||||
# HassBle Config
|
||||
|
||||
> 이 저장소는 [HassBle](https://github.com/eigger/hassble-android) Android 앱의 기기 설정 파일(`config.yaml`)을 저장합니다.
|
||||
|
||||
**[English Documentation → README.md](README.md) | [기여 가이드 → CONTRIBUTING.ko.md](CONTRIBUTING.ko.md)**
|
||||
|
||||
---
|
||||
|
||||
## 목차
|
||||
|
||||
1. [동작 원리](#동작-원리)
|
||||
2. [빠른 시작](#빠른-시작)
|
||||
3. [루트 구조](#루트-구조)
|
||||
4. [defaults — 발행 규칙](#defaults--발행-규칙)
|
||||
5. [기기 타입](#기기-타입)
|
||||
6. [source: advertisement — BLE 수동 스캔](#source-advertisement--ble-수동-스캔)
|
||||
- [match — 매칭 조건](#match--매칭-조건)
|
||||
- [instance_mode — 엔티티 전략](#instance_mode--엔티티-전략)
|
||||
7. [source: gatt_notify — GATT 연결](#source-gatt_notify--gatt-연결)
|
||||
8. [source: obd — ELM327 OBD 폴링](#source-obd--elm327-obd-폴링)
|
||||
9. [sensors — 센서 설정](#sensors--센서-설정)
|
||||
- [decode — 바이너리 디코딩](#decode--바이너리-디코딩)
|
||||
- [데이터 타입](#데이터-타입)
|
||||
10. [controls — HA 제어](#controls--ha-제어)
|
||||
11. [publish — 센서별 발행 필터](#publish--센서별-발행-필터)
|
||||
12. [OBD 프리셋 목록](#obd-프리셋-목록)
|
||||
13. [전체 예제](#전체-예제)
|
||||
14. [주의사항](#주의사항)
|
||||
15. [기여하기](#기여하기)
|
||||
|
||||
---
|
||||
|
||||
## 저장소 파일
|
||||
|
||||
| 파일 | 용도 |
|
||||
|------|------|
|
||||
| `config.yaml` | 게이트웨이 운영 설정 (실제로 동작하는 기기 목록) |
|
||||
| `templates.yaml` | 센서 탭 **템플릿 가져오기**용 기기 템플릿 |
|
||||
|
||||
앱은 선택한 브랜치의 리포 루트에서 두 파일을 고정 이름으로 불러옵니다 (`owner/repo` + 브랜치).
|
||||
|
||||
## 동작 원리
|
||||
|
||||
HassBle 앱은 이 저장소에서 `config.yaml`과 `templates.yaml`을 다운로드하고, 정의한 규칙에 따라 BLE 데이터를 디코딩한 뒤, [ws_bridge](https://github.com/eigger/hass-ws-bridge) 통합을 통해 Home Assistant에 자동으로 센서를 등록합니다. 코드 수정 없이 YAML만 편집하면 됩니다.
|
||||
|
||||
Raw URL (브랜치 `main`):
|
||||
|
||||
- 설정: `https://raw.githubusercontent.com/eigger/hassble-config/main/config.yaml`
|
||||
- 템플릿: `https://raw.githubusercontent.com/eigger/hassble-config/main/templates.yaml`
|
||||
|
||||
```
|
||||
Android Phone (BLE 스캔)
|
||||
│ raw bytes
|
||||
▼
|
||||
HassBle 앱 ──── config.yaml (이 저장소) ────▶ 디코딩 규칙
|
||||
│ 디코딩된 값
|
||||
▼
|
||||
HA WebSocket API ─────────────────────────────▶ ws_bridge
|
||||
│
|
||||
▼
|
||||
Home Assistant 엔티티 (sensor / switch / number / …)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
1. 이 저장소를 자신의 GitHub 계정으로 Fork 또는 복사합니다.
|
||||
2. `config.yaml`을 편집하여 BLE 기기를 정의합니다. 앱에서 빠르게 추가할 블록은 `templates.yaml`에 넣을 수 있습니다.
|
||||
3. HassBle 앱 → **Sensors 탭** → `your-username/hassble-config`와 브랜치 `main` 입력 (`config.yaml` + `templates.yaml` 자동 로드).
|
||||
4. **Gateway 탭**에서 HA URL과 토큰(또는 OAuth 로그인)을 입력하고 게이트웨이를 시작합니다.
|
||||
5. **Sensors 탭**에서 원하는 센서를 활성화하면 Home Assistant에 나타납니다.
|
||||
|
||||
> ⚠️ **HA 자격증명(URL / 토큰)을 이 파일에 절대 저장하지 마세요.**
|
||||
> 앱 설정에서만 입력하세요.
|
||||
|
||||
---
|
||||
|
||||
## 루트 구조
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
defaults:
|
||||
publish:
|
||||
on_change_only: true
|
||||
min_interval: 10s
|
||||
|
||||
devices:
|
||||
- id: ...
|
||||
```
|
||||
|
||||
| 필드 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `version` | int | `1` | 스키마 버전. 항상 `1`. |
|
||||
| `defaults.publish` | object | 아래 참조 | 모든 센서에 적용되는 기본 발행 필터. |
|
||||
| `devices` | list | `[]` | 기기 설정 목록. |
|
||||
|
||||
---
|
||||
|
||||
## defaults — 발행 규칙
|
||||
|
||||
센서 값을 HA에 얼마나 자주, 어떤 조건에서 전송할지를 제어합니다. 기기별 또는 센서별로 덮어쓸 수 있습니다.
|
||||
|
||||
```yaml
|
||||
defaults:
|
||||
publish:
|
||||
on_change_only: true # 값이 변할 때만 전송 (기본: true)
|
||||
min_interval: 10s # 전송 최소 간격 (기본: 10s)
|
||||
heartbeat: 5m # 변화 없어도 이 간격으로 강제 전송 (선택)
|
||||
deadband: 0.5 # 이 값 미만의 변화는 무시 (선택, 숫자 센서만)
|
||||
```
|
||||
|
||||
| 필드 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `on_change_only` | bool | `true` | 값이 변할 때만 전송. |
|
||||
| `min_interval` | duration | `10s` | 두 번의 전송 사이 최소 간격. 형식: `500ms`, `30s`, `5m`. |
|
||||
| `heartbeat` | duration | `null` | 변화 없어도 이 간격으로 강제 전송. |
|
||||
| `deadband` | float | `null` | 이 값 미만의 변화는 무시 (숫자 센서). |
|
||||
|
||||
---
|
||||
|
||||
## 기기 타입
|
||||
|
||||
`devices`의 각 항목에는 데이터 경로를 선택하는 `source` 필드가 필요합니다.
|
||||
|
||||
| `source` | 설명 |
|
||||
|----------|------|
|
||||
| `advertisement` | BLE 수동 스캔 — 연결 없이 브로드캐스트 패킷을 읽습니다. |
|
||||
| `gatt_notify` | GATT 능동 연결 — 기기에 연결하여 알림을 구독합니다. 쓰기 명령을 지원합니다. |
|
||||
| `obd` | BLE를 통한 ELM327 OBD 어댑터 — PID 명령을 폴링하고 ISO-TP 응답을 파싱합니다. |
|
||||
|
||||
**모든 기기 타입에 공통인 필드:**
|
||||
|
||||
```yaml
|
||||
- id: my_device # 고유 식별자 (소문자, 숫자, _)
|
||||
name: "My Device" # 표시 이름 (HA 기기명)
|
||||
source: advertisement # advertisement | gatt_notify | obd
|
||||
publish: # (선택) 이 기기의 모든 센서에 대한 발행 규칙 덮어쓰기
|
||||
on_change_only: true
|
||||
min_interval: 5s
|
||||
sensors: [...]
|
||||
controls: [...] # gatt_notify / obd만 사용 가능
|
||||
```
|
||||
|
||||
| 필드 | 타입 | 필수 | 설명 |
|
||||
|------|------|------|------|
|
||||
| `id` | string | ✅ | 고유 식별자. HA 엔티티 unique_id에 사용됩니다. 소문자, 숫자, `_` 사용. |
|
||||
| `name` | string | ✅ | HA 기기에 표시되는 이름. |
|
||||
| `source` | enum | ✅ | 데이터 소스 타입 (위 참조). |
|
||||
| `publish` | object | ❌ | 기기 수준의 발행 규칙 덮어쓰기. |
|
||||
| `sensors` | list | ❌ | 센서 정의 목록. |
|
||||
| `controls` | list | ❌ | 제어 정의 목록. |
|
||||
|
||||
---
|
||||
|
||||
## source: advertisement — BLE 수동 스캔
|
||||
|
||||
연결 없이 BLE 광고 패킷을 수신합니다. `match`를 사용하여 패킷을 필터링합니다.
|
||||
|
||||
```yaml
|
||||
- id: my_sensor
|
||||
name: "My BLE Sensor"
|
||||
source: advertisement
|
||||
instance_mode: mac # mac | shared (아래 참조)
|
||||
match:
|
||||
manufacturer_id: 76 # Apple = 76 (0x004C) — 반드시 10진수 사용
|
||||
manufacturer_min_length: 24
|
||||
manufacturer_hex_prefix: "0215"
|
||||
sensors:
|
||||
- key: temperature
|
||||
source_field: manufacturer_data # manufacturer_data | service_data | raw
|
||||
decode:
|
||||
offset: 18
|
||||
length: 2
|
||||
type: uint16
|
||||
endian: big
|
||||
scale: 0.002670288
|
||||
offset_value: -45
|
||||
```
|
||||
|
||||
### match — 매칭 조건
|
||||
|
||||
지정된 모든 조건이 동시에 만족되어야 합니다 (AND 논리). 지정하지 않은 필드는 무시됩니다.
|
||||
|
||||
| 필드 | 타입 | 설명 |
|
||||
|------|------|------|
|
||||
| `mac` | string | 고정 MAC 주소 필터. 형식: `"AA:BB:CC:DD:EE:FF"`. |
|
||||
| `service_data_uuid` | string | 16비트 또는 128비트 서비스 UUID 접미사. 예: `"F51C"`, `"181A"`. |
|
||||
| `manufacturer_id` | int | 제조사 company ID. **반드시 10진수 사용** (`0x...` 불가). 예: Apple=`76`. |
|
||||
| `manufacturer_hex_prefix` | string | 제조사 페이로드(hex 문자열)가 이 접두사로 시작해야 합니다. 예: iBeacon=`"0215"`. |
|
||||
| `manufacturer_min_length` | int | 제조사 페이로드의 최소 바이트 길이. |
|
||||
| `name_prefix` | string | BLE 기기 이름이 이 문자열로 시작해야 합니다. |
|
||||
|
||||
> **⚠️ Hex 리터럴 주의**
|
||||
> YAML 파서(`kaml`)는 `0x...` hex 값을 잘못 파싱할 수 있습니다. 항상 **10진수 정수**를 사용하세요.
|
||||
> `0x004C` → `76`, `0x035D` → `861`
|
||||
|
||||
### instance_mode — 엔티티 전략
|
||||
|
||||
같은 타입의 기기가 여러 개 감지될 때 HA 엔티티를 어떻게 생성할지를 결정합니다.
|
||||
|
||||
| 값 | 설명 |
|
||||
|----|------|
|
||||
| `mac` (기본) | 고유 MAC 주소마다 별도의 HA 엔티티 세트를 생성합니다. 엔티티 unique_id: `{device_id}_{MAC}_temperature` 등. 앱의 Sensors 탭에서 MAC을 바인딩하면 기기가 스캔되기 전에 엔티티를 미리 생성할 수 있습니다. |
|
||||
| `shared` | 모든 매칭 광고 기기가 하나의 HA 엔티티를 공유합니다. 마지막으로 수신된 패킷이 상태를 덮어씁니다. 주차 비콘, 클리커 등에 유용합니다. |
|
||||
|
||||
---
|
||||
|
||||
## source: gatt_notify — GATT 연결
|
||||
|
||||
특정 BLE 기기에 연결하여 GATT 캐릭터리스틱을 구독하고 알림을 수신합니다. 선택적으로 hex 명령을 역방향으로 전송할 수 있습니다.
|
||||
|
||||
```yaml
|
||||
- id: custom_meter
|
||||
name: "Custom BLE Meter"
|
||||
source: gatt_notify
|
||||
gatt:
|
||||
mac: "AA:BB:CC:DD:EE:FF" # 또는 앱 Sensors 탭에서 바인딩
|
||||
service_uuid: "ffe0"
|
||||
notify_char_uuid: "ffe1"
|
||||
write_char_uuid: "ffe2" # 선택 — controls 사용 시 필요
|
||||
auto_connect: true
|
||||
sensors:
|
||||
- key: power
|
||||
unit: "W"
|
||||
device_class: power
|
||||
state_class: measurement
|
||||
decode: { offset: 0, length: 2, type: uint16, endian: little }
|
||||
controls:
|
||||
- key: relay
|
||||
type: switch
|
||||
command: { on: "A10100", off: "A10000" }
|
||||
```
|
||||
|
||||
| 필드 | 타입 | 필수 | 설명 |
|
||||
|------|------|------|------|
|
||||
| `mac` | string | ❌ | 기기 MAC 주소. 앱 바인딩으로도 설정 가능. |
|
||||
| `service_uuid` | string | ✅ | GATT 서비스 UUID (16비트 또는 128비트). |
|
||||
| `notify_char_uuid` | string | ✅ | 알림을 구독할 캐릭터리스틱. |
|
||||
| `write_char_uuid` | string | ❌ | 명령을 전송할 캐릭터리스틱 (controls에 필요). |
|
||||
| `auto_connect` | bool | ❌ | 연결 끊김 시 자동 재연결. 기본 `true`. |
|
||||
|
||||
> YAML에 `mac`을 설정하지 않으면 앱의 **Sensors 탭**에서 기기 옆 "Connect / Bind"를 눌러 바인딩하세요.
|
||||
|
||||
---
|
||||
|
||||
## source: obd — ELM327 OBD 폴링
|
||||
|
||||
BLE ELM327 어댑터에 연결하여 OBD-II(및 GM mode 22) PID 명령을 전송하고 ISO-TP 응답을 파싱합니다. 내장 `preset`을 사용하거나 `mode`/`pid`/`formula`를 직접 정의할 수 있습니다.
|
||||
|
||||
```yaml
|
||||
- id: car_obd
|
||||
name: "Vehicle OBD"
|
||||
source: obd
|
||||
obd:
|
||||
# mac: "AA:BB:CC:DD:EE:FF" # 또는 앱에서 바인딩
|
||||
service_uuid: "18F0"
|
||||
tx_char_uuid: "2AF1"
|
||||
rx_char_uuid: "2AF0"
|
||||
tx_delay: 50ms
|
||||
init_commands:
|
||||
- "ATZ"
|
||||
- "ATE0"
|
||||
- "ATL0"
|
||||
- "ATS0"
|
||||
- "ATH0"
|
||||
- "ATSP6" # 프로토콜: ATSP0=자동, ATSP6=ISO 15765-4 CAN 500kbps
|
||||
sensors:
|
||||
# 프리셋 사용 (권장)
|
||||
- { key: rpm, preset: rpm, update_interval: 1s }
|
||||
- { key: speed, preset: speed, update_interval: 1s }
|
||||
# 직접 정의
|
||||
- key: custom_pid
|
||||
mode: "01"
|
||||
pid: "0C"
|
||||
formula: "(a*256+b)/4"
|
||||
unit: "rpm"
|
||||
state_class: measurement
|
||||
update_interval: 1s
|
||||
```
|
||||
|
||||
| 필드 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `mac` | string | — | 어댑터 MAC. 여기 또는 앱 바인딩으로 설정. |
|
||||
| `service_uuid` | string | `"FFF0"` | BLE GATT 서비스 UUID. |
|
||||
| `tx_char_uuid` | string | `"FFF2"` | 쓰기 캐릭터리스틱 (명령 전송). |
|
||||
| `rx_char_uuid` | string | `"FFF1"` | 알림 캐릭터리스틱 (응답 수신). |
|
||||
| `tx_delay` | duration | `50ms` | 연속 명령 사이 딜레이. |
|
||||
| `init_commands` | list | `[]` | 폴링 시작 전 연결마다 한 번 전송하는 초기 명령. |
|
||||
| `default_commands` | list | 자동 | `pre_commands`가 없는 센서를 폴링하기 직전에 보낼 명령. 보통 생략하면 됨 — 아래 "헤더 복원" 참고. |
|
||||
| `auto_connect` | bool | `true` | 연결 끊김 시 자동 재연결. |
|
||||
|
||||
**OBD 센서 전용 필드:**
|
||||
|
||||
| 필드 | 타입 | 설명 |
|
||||
|------|------|------|
|
||||
| `preset` | string | 내장 프리셋 사용 (아래 표 참조). |
|
||||
| `mode` | string | OBD 모드. `"01"`=표준, `"22"`=제조사 확장. 기본 `"01"`. |
|
||||
| `pid` | string | PID hex 코드. 예: `"0C"`, `"199A"`. |
|
||||
| `formula` | string | 수식. `a`~`t`가 응답의 0~19번째 바이트. 예: `"(a*256+b)/4"`. 응답이 짧아 식에 쓴 바이트가 없으면 그 주기는 발행하지 않음. |
|
||||
| `decode` | map | `formula` 대신 offset으로 값 추출. 20번째 이후 바이트를 읽어야 할 때 사용 (아래 참조). |
|
||||
| `update_interval` | duration | 이 PID를 폴링하는 간격. 기본 `60s`. |
|
||||
| `pre_commands` | list | 이 PID 전에 전송할 추가 명령 (예: GM 헤더 전환). |
|
||||
|
||||
### 긴 응답에서 값 꺼내기 (decode)
|
||||
|
||||
`formula`의 변수는 응답의 **앞 20바이트**(`a`~`t`)까지만 가리킵니다. 그보다 뒤에 있는 값은
|
||||
`decode`로 읽습니다. 필드 구성은 [decode 절](#decode--바이트-디코딩)과 같습니다.
|
||||
|
||||
```yaml
|
||||
# 현대 21 03 블록의 총주행거리 — byte 57~60, 32bit, /1000 = km
|
||||
- key: odometer
|
||||
mode: "21"
|
||||
pid: "03"
|
||||
pre_commands: ["ATSH7E0"]
|
||||
decode: { offset: 57, length: 4, type: uint32, endian: big, scale: 0.001 }
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: total_increasing
|
||||
```
|
||||
|
||||
`offset`은 mode/PID 에코를 제외한 데이터의 0-based 위치로, `formula`의 `a`가 `offset: 0`과
|
||||
같습니다. 응답이 짧아 `offset + length`가 범위를 벗어나면 그 주기에는 아무것도 발행하지
|
||||
않습니다 — 지원하지 않는 차에서 엉뚱한 값이 올라오지 않습니다.
|
||||
|
||||
한 센서에 `decode`와 `formula`를 모두 쓰면 `decode`가 우선합니다.
|
||||
|
||||
### 헤더 복원 (ATSH)
|
||||
|
||||
ELM327의 전송 헤더는 **한 번 바꾸면 계속 유지**됩니다. 그래서 `pre_commands: ["ATSH7C6"]` 같은
|
||||
센서 뒤에 `pre_commands`가 없는 표준 센서(rpm, speed 등)가 폴링되면, 그 요청까지 7C6으로 나가
|
||||
`NO DATA`가 됩니다.
|
||||
|
||||
앱이 이를 자동으로 처리합니다. **한 센서라도 `pre_commands`에 `ATSH`를 쓰면**, `pre_commands`가
|
||||
없는 센서 앞에 헤더 복원 명령을 자동으로 넣습니다. 복원할 헤더는 이 순서로 정해집니다:
|
||||
|
||||
1. `default_commands` — 명시했다면 이 값
|
||||
2. `init_commands`의 마지막 `ATSH…`
|
||||
3. `ATSH7DF` — ELM327의 11bit CAN 기본 헤더
|
||||
|
||||
`ATSH`를 쓰는 센서가 하나도 없으면 아무것도 보내지 않습니다. K-line(ISO 9141 / KWP)처럼 헤더
|
||||
형식이 다른 프로토콜에 `ATSH7DF`를 밀어넣지 않기 위한 것입니다.
|
||||
|
||||
즉 **보통은 `default_commands`를 생략**하면 되고, 복원 헤더를 직접 지정해야 할 때만 씁니다:
|
||||
|
||||
```yaml
|
||||
obd:
|
||||
init_commands: ["ATSP6"]
|
||||
default_commands: ["ATSH7E0"] # 브로드캐스트(7DF) 대신 엔진 ECU 직접 지정
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## sensors — 센서 설정
|
||||
|
||||
`sensors` 목록의 각 항목은 하나의 HA 엔티티를 정의합니다.
|
||||
|
||||
```yaml
|
||||
sensors:
|
||||
- key: temperature # 필수 — 기기 내 고유 키
|
||||
platform: sensor # sensor | binary_sensor | text_sensor
|
||||
device_class: temperature # HA device_class (선택)
|
||||
unit: "°C"
|
||||
state_class: measurement # measurement | total | total_increasing
|
||||
icon: "mdi:thermometer"
|
||||
entity_category: diagnostic # diagnostic | config (일반 센서는 생략)
|
||||
accuracy_decimals: 2
|
||||
source_field: manufacturer_data # advertisement만
|
||||
min_length: 24
|
||||
decode:
|
||||
offset: 18
|
||||
length: 2
|
||||
type: uint16
|
||||
endian: big
|
||||
scale: 0.002670288
|
||||
offset_value: -45
|
||||
publish: # 이 센서만의 발행 규칙 덮어쓰기
|
||||
deadband: 0.1
|
||||
min_interval: 30s
|
||||
```
|
||||
|
||||
| 필드 | 타입 | 필수 | 설명 |
|
||||
|------|------|------|------|
|
||||
| `key` | string | ✅ | 기기 내 고유 키. HA 엔티티 unique_id의 일부. |
|
||||
| `platform` | string | ❌ | HA 엔티티 플랫폼. 기본 `sensor`. |
|
||||
| `device_class` | string | ❌ | HA device class (temperature, humidity, battery, voltage, …). |
|
||||
| `unit` | string | ❌ | HA에 표시되는 단위. |
|
||||
| `state_class` | string | ❌ | HA 통계용 state class. |
|
||||
| `icon` | string | ❌ | MDI 아이콘. 예: `"mdi:thermometer"`. |
|
||||
| `entity_category` | string | ❌ | `diagnostic` 또는 `config`. 일반 센서는 생략. |
|
||||
| `accuracy_decimals` | int | ❌ | 디코딩된 값을 소수 N자리로 반올림. |
|
||||
| `source_field` | enum | ❌ | `manufacturer_data` / `service_data` / `raw`. 기본 `raw`. |
|
||||
| `min_length` | int | ❌ | 페이로드가 N바이트 미만이면 이 센서를 건너뜀. |
|
||||
| `decode` | object | ❌ | 바이너리 디코딩 규칙. 아래 참조. |
|
||||
| `publish` | object | ❌ | 이 센서만의 발행 규칙 덮어쓰기. |
|
||||
|
||||
### decode — 바이너리 디코딩
|
||||
|
||||
raw 바이트 배열에서 숫자 또는 문자열 값을 추출합니다.
|
||||
|
||||
**공식:** `최종값 = (raw_정수 * scale) + offset_value`
|
||||
|
||||
```yaml
|
||||
decode:
|
||||
offset: 18 # 바이트 오프셋 (0-based)
|
||||
length: 2 # 읽을 바이트 수
|
||||
type: uint16 # 데이터 타입 (아래 표 참조)
|
||||
endian: big # big | little
|
||||
bitmask: 0x0F # (선택) AND 비트마스크 적용 후 디코딩
|
||||
scale: 0.1 # (선택) 곱할 계수. 기본 1.0
|
||||
offset_value: -40 # (선택) 더할 오프셋. 기본 0.0
|
||||
map: # (선택) 정수값 → 문자열 매핑
|
||||
"0": "off"
|
||||
"1": "on"
|
||||
"2": "standby"
|
||||
```
|
||||
|
||||
| 필드 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `offset` | int | `0` | 시작 바이트 인덱스 (0부터). |
|
||||
| `length` | int | `1` | 읽을 바이트 수. |
|
||||
| `type` | enum | `uint8` | 바이트를 해석할 데이터 타입. |
|
||||
| `endian` | enum | `big` | 바이트 순서. `big`=MSB 먼저, `little`=LSB 먼저. |
|
||||
| `bitmask` | int | `null` | 스케일링 전 AND 비트마스크 적용. |
|
||||
| `scale` | float | `1.0` | raw 정수에 곱할 계수. |
|
||||
| `offset_value` | float | `0.0` | 스케일링 후 더하는 값: `(raw * scale) + offset_value`. |
|
||||
| `map` | object | `{}` | 정수 결과를 문자열로 매핑. 키는 따옴표로 감싼 문자열. |
|
||||
|
||||
### 데이터 타입
|
||||
|
||||
| 타입 | 바이트 | 설명 |
|
||||
|------|--------|------|
|
||||
| `uint8` | 1 | 부호 없는 8비트 정수 (0–255). |
|
||||
| `int8` | 1 | 부호 있는 8비트 정수 (-128–127). |
|
||||
| `uint16` | 2 | 부호 없는 16비트 정수 (0–65535). |
|
||||
| `int16` | 2 | 부호 있는 16비트 정수 (-32768–32767). |
|
||||
| `uint32` | 4 | 부호 없는 32비트 정수. |
|
||||
| `int32` | 4 | 부호 있는 32비트 정수. |
|
||||
| `float32` | 4 | IEEE 754 단정밀도 부동소수점. |
|
||||
| `timestamp` | 4 | 각 바이트를 월/일/시/분으로 해석. ISO 8601 문자열 반환. |
|
||||
| `string` | N | 바이트를 ASCII로 디코딩. `platform: text_sensor`와 함께 사용. |
|
||||
|
||||
---
|
||||
|
||||
## controls — HA 제어
|
||||
|
||||
HA에서 제어 시 BLE 쓰기 명령을 전송하는 HA 엔티티를 정의합니다. `gatt_notify`와 `obd` 소스에서만 사용 가능합니다.
|
||||
|
||||
```yaml
|
||||
controls:
|
||||
# Switch — on/off hex 명령
|
||||
- key: relay
|
||||
type: switch
|
||||
name: "Main Relay"
|
||||
icon: "mdi:electric-switch"
|
||||
entity_category: config
|
||||
command:
|
||||
on: "A10100"
|
||||
off: "A10000"
|
||||
|
||||
# Number — 값을 hex에 삽입
|
||||
- key: brightness
|
||||
type: number
|
||||
min: 0
|
||||
max: 100
|
||||
step: 1
|
||||
command:
|
||||
template: "B2{value:02X}FF"
|
||||
|
||||
# Select — 옵션별 hex 명령
|
||||
- key: mode
|
||||
type: select
|
||||
options: ["auto", "cool", "heat", "fan"]
|
||||
command:
|
||||
auto: "C000"
|
||||
cool: "C001"
|
||||
heat: "C002"
|
||||
fan: "C003"
|
||||
|
||||
# Button — 누르면 hex 전송
|
||||
- key: restart
|
||||
type: button
|
||||
command:
|
||||
press: "FFFE"
|
||||
```
|
||||
|
||||
| 필드 | 타입 | 필수 | 설명 |
|
||||
|------|------|------|------|
|
||||
| `key` | string | ✅ | 기기 내 고유 키. |
|
||||
| `type` | enum | ✅ | `switch` / `number` / `select` / `button`. |
|
||||
| `name` | string | ❌ | HA 표시 이름. 생략 시 key에서 자동 생성. |
|
||||
| `icon` | string | ❌ | MDI 아이콘. |
|
||||
| `entity_category` | string | ❌ | `config` 또는 `diagnostic`. |
|
||||
| `command` | object | ✅ | 명령 맵. type에 따라 키가 다릅니다 (위 예제 참조). |
|
||||
| `options` | list | select만 | `select` 타입 옵션 목록. |
|
||||
| `min` | float | number만 | `number` 타입 최솟값. |
|
||||
| `max` | float | number만 | `number` 타입 최댓값. |
|
||||
| `step` | float | ❌ | `number` 타입 단계. |
|
||||
|
||||
**command 템플릿 플레이스홀더:**
|
||||
|
||||
| 플레이스홀더 | 설명 |
|
||||
|-------------|------|
|
||||
| `{value}` | 정수 값 (10진수). |
|
||||
| `{value:02X}` | 값을 2자리 대문자 hex로 (0 패딩). |
|
||||
| `{value:04X}` | 4자리 대문자 hex. |
|
||||
|
||||
---
|
||||
|
||||
## publish — 센서별 발행 필터
|
||||
|
||||
특정 센서에 대해 전역 `defaults.publish`를 덮어씁니다. 느리게 변하는 센서(연료량)나 빠른 업데이트가 필요한 센서(RPM)에 유용합니다.
|
||||
|
||||
```yaml
|
||||
sensors:
|
||||
- key: fuel_level
|
||||
preset: fuel_level
|
||||
update_interval: 30s
|
||||
publish:
|
||||
on_change_only: true
|
||||
deadband: 0.5
|
||||
min_interval: 60s
|
||||
heartbeat: 30m
|
||||
```
|
||||
|
||||
**우선순위:** sensor `publish` > device `publish` > `defaults.publish`
|
||||
|
||||
---
|
||||
|
||||
## OBD 프리셋 목록
|
||||
|
||||
OBD 센서에서 `preset: <이름>`으로 내장 정의를 사용합니다. 프리셋 지정 후 개별 필드(`unit`, `accuracy_decimals` 등)를 덮어쓸 수 있습니다.
|
||||
|
||||
### 표준 OBD-II (mode 01)
|
||||
|
||||
| 프리셋 | PID | 공식 | 단위 | 설명 |
|
||||
|--------|-----|------|------|------|
|
||||
| `rpm` | `0C` | `(a*256+b)/4` | rpm | 엔진 RPM |
|
||||
| `speed` | `0D` | `a` | km/h | 차속 |
|
||||
| `engine_load` | `04` | `a/2.55` | % | 엔진 부하 |
|
||||
| `throttle` | `11` | `a/2.55` | % | 스로틀 개도 |
|
||||
| `coolant_temp` | `05` | `a-40` | °C | 냉각수 온도 |
|
||||
| `intake_air_temp` | `0F` | `a-40` | °C | 흡기 온도 |
|
||||
| `ambient_temp` | `46` | `a-40` | °C | 외기 온도 |
|
||||
| `battery_voltage` | `42` | `(a*256+b)/1000` | V | 배터리 전압 |
|
||||
| `run_time` | `1F` | `a*256+b` | s | 시동 후 경과 시간 |
|
||||
| `fuel_level` | `2F` | `a/2.55` | % | 연료량 |
|
||||
| `actual_torque` | `62` | `a-125` | % | 실제 토크 |
|
||||
| `odometer` | `A6` | `(a*16777216+b*65536+c*256+d)/10` | km | 주행 거리 |
|
||||
|
||||
### GM 확장 (mode 22)
|
||||
|
||||
| 프리셋 | PID | 공식 | 단위 | 설명 |
|
||||
|--------|-----|------|------|------|
|
||||
| `gm_current_gear` | `199A` | `a` | — | 현재 기어 |
|
||||
| `gm_prnd_status_alt` | `2889` | `a` | — | PRND 상태 |
|
||||
| `gm_oil_pressure` | `115C` | `(a*0.65)-17.5` | psi | 오일 압력 |
|
||||
| `gm_trans_temp` | `1940` | `a-40` | °C | 변속기 온도 |
|
||||
| `gm_fuel_level_liters` | `132A` | `(a*256+b)/64` | L | 연료량 (리터) |
|
||||
|
||||
---
|
||||
|
||||
## 전체 예제
|
||||
|
||||
### 예제 1 — Jaalee JHT (iBeacon 온도·습도)
|
||||
|
||||
```yaml
|
||||
# instance_mode: mac → 각 기기 MAC마다 별도 엔티티 생성
|
||||
- id: jaalee_jht
|
||||
name: "Jaalee JHT"
|
||||
source: advertisement
|
||||
instance_mode: mac
|
||||
match:
|
||||
manufacturer_id: 76 # Apple Inc. (반드시 10진수)
|
||||
manufacturer_min_length: 24
|
||||
manufacturer_hex_prefix: "0215" # iBeacon 타입 마커
|
||||
sensors:
|
||||
- key: temperature
|
||||
device_class: temperature
|
||||
unit: "°C"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
source_field: manufacturer_data
|
||||
decode: { offset: 18, length: 2, type: uint16, endian: big, scale: 0.002670288, offset_value: -45 }
|
||||
- key: humidity
|
||||
device_class: humidity
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
source_field: manufacturer_data
|
||||
decode: { offset: 20, length: 2, type: uint16, endian: big, scale: 0.001524504 }
|
||||
- key: battery
|
||||
device_class: battery
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
source_field: manufacturer_data
|
||||
decode: { offset: 23, length: 1, type: uint8 }
|
||||
```
|
||||
|
||||
### 예제 2 — 커스텀 서비스 데이터 센서
|
||||
|
||||
```yaml
|
||||
# 서비스 데이터에 센서 값이 포함된 커스텀 기기
|
||||
- id: my_env_sensor
|
||||
name: "Environment Sensor"
|
||||
source: advertisement
|
||||
instance_mode: shared
|
||||
match:
|
||||
service_data_uuid: "181A" # Environmental Sensing UUID
|
||||
sensors:
|
||||
- key: temperature
|
||||
device_class: temperature
|
||||
unit: "°C"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
source_field: service_data
|
||||
decode: { offset: 0, length: 2, type: int16, endian: little, scale: 0.01 }
|
||||
- key: humidity
|
||||
device_class: humidity
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
source_field: service_data
|
||||
decode: { offset: 2, length: 2, type: uint16, endian: little, scale: 0.01 }
|
||||
- key: battery
|
||||
device_class: battery
|
||||
unit: "%"
|
||||
source_field: service_data
|
||||
decode: { offset: 9, length: 1, type: uint8 }
|
||||
```
|
||||
|
||||
### 예제 3 — GATT 센서 + 스위치 제어
|
||||
|
||||
```yaml
|
||||
# GATT 기반 전력 모니터 + 릴레이 제어
|
||||
- id: power_monitor
|
||||
name: "Power Monitor"
|
||||
source: gatt_notify
|
||||
gatt:
|
||||
service_uuid: "ffe0"
|
||||
notify_char_uuid: "ffe1"
|
||||
write_char_uuid: "ffe2"
|
||||
sensors:
|
||||
- key: power
|
||||
device_class: power
|
||||
unit: "W"
|
||||
state_class: measurement
|
||||
decode: { offset: 0, length: 2, type: uint16, endian: little }
|
||||
- key: voltage
|
||||
device_class: voltage
|
||||
unit: "V"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
decode: { offset: 2, length: 2, type: uint16, endian: little, scale: 0.1 }
|
||||
- key: current
|
||||
device_class: current
|
||||
unit: "A"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
decode: { offset: 4, length: 2, type: uint16, endian: little, scale: 0.01 }
|
||||
controls:
|
||||
- key: relay
|
||||
type: switch
|
||||
name: "Relay"
|
||||
icon: "mdi:electric-switch"
|
||||
command: { on: "A10100", off: "A10000" }
|
||||
```
|
||||
|
||||
### 예제 4 — OBD 프리셋 + 커스텀 발행 규칙
|
||||
|
||||
```yaml
|
||||
# OBD 차량 센서 (프리셋 + 커스텀 발행 규칙)
|
||||
- id: car_obd
|
||||
name: "Vehicle"
|
||||
source: obd
|
||||
obd:
|
||||
service_uuid: "18F0"
|
||||
tx_char_uuid: "2AF1"
|
||||
rx_char_uuid: "2AF0"
|
||||
tx_delay: 50ms
|
||||
init_commands: ["ATZ", "ATE0", "ATL0", "ATS0", "ATH0", "ATSP6"]
|
||||
sensors:
|
||||
- { key: rpm, preset: rpm, update_interval: 1s }
|
||||
- { key: speed, preset: speed, update_interval: 1s }
|
||||
- { key: coolant_temp, preset: coolant_temp, update_interval: 10s }
|
||||
- key: fuel_level
|
||||
preset: fuel_level
|
||||
update_interval: 30s
|
||||
publish:
|
||||
deadband: 1.0 # 1% 미만 변화 무시
|
||||
min_interval: 60s
|
||||
heartbeat: 10m
|
||||
```
|
||||
|
||||
### 예제 5 — 값 매핑 (상태 코드)
|
||||
|
||||
```yaml
|
||||
# 상태 코드를 문자열로 매핑하는 예제
|
||||
- id: status_device
|
||||
name: "Status Device"
|
||||
source: advertisement
|
||||
instance_mode: shared
|
||||
match:
|
||||
manufacturer_id: 1234
|
||||
sensors:
|
||||
- key: mode
|
||||
platform: text_sensor
|
||||
source_field: manufacturer_data
|
||||
decode:
|
||||
offset: 5
|
||||
length: 1
|
||||
type: uint8
|
||||
map:
|
||||
"0": "idle"
|
||||
"1": "running"
|
||||
"2": "error"
|
||||
"3": "standby"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 주의사항
|
||||
|
||||
### ⚠️ manufacturer_id는 반드시 10진수로
|
||||
|
||||
YAML 파서(`kaml`)는 `0x004C`를 `0`으로 파싱하거나 오류를 낼 수 있습니다. 항상 hex를 10진수로 변환하세요:
|
||||
|
||||
```yaml
|
||||
# ❌ 잘못된 방법 — 파싱 오류 가능
|
||||
manufacturer_id: 0x004C
|
||||
|
||||
# ✅ 올바른 방법
|
||||
manufacturer_id: 76 # 0x004C = 76
|
||||
manufacturer_id: 861 # 0x035D = 861
|
||||
```
|
||||
|
||||
### match의 AND 논리
|
||||
|
||||
모든 `match` 조건은 AND로 결합됩니다. `service_data_uuid`와 `manufacturer_id`를 함께 지정하면 패킷이 **둘 다** 만족해야 합니다. 기기가 항상 특정 필드를 광고하지 않는다면 해당 조건을 제거하세요.
|
||||
|
||||
### instance_mode: mac — 조기 엔티티 생성을 위한 바인딩
|
||||
|
||||
`instance_mode: mac`이고 `match.mac`이 없으면 기기가 BLE 스캔에서 감지된 후에야 HA 엔티티가 나타납니다. 게이트웨이 연결 즉시 엔티티가 나타나도록 하려면 앱 **Sensors 탭** → "Connect / Bind"에서 MAC을 바인딩하세요.
|
||||
|
||||
### source_field 선택
|
||||
|
||||
광고 센서의 페이로드 소스 선택:
|
||||
- `manufacturer_data` — 제조사 ID 이후 데이터 (커스텀 센서에서 가장 일반적)
|
||||
- `service_data` — 서비스 데이터 AD 타입 데이터 (0x181A 등 표준 프로필에 일반적)
|
||||
- `raw` — 전체 스캔 레코드 바이트 (거의 사용 안 함)
|
||||
|
||||
### 시간 형식
|
||||
|
||||
시간은 밀리초(`ms`), 초(`s`), 분(`m`)을 지원합니다.
|
||||
|
||||
```yaml
|
||||
tx_delay: 50ms
|
||||
min_interval: 10s
|
||||
heartbeat: 5m
|
||||
update_interval: 1s
|
||||
```
|
||||
|
||||
### 설정은 캐시됨
|
||||
|
||||
앱은 마지막으로 성공적으로 불러온 설정을 캐시합니다. 시작 시 네트워크가 없으면 캐시를 사용합니다. 이 경우 앱 상단에 "캐시된 설정 사용 중"이 표시됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 기여하기
|
||||
|
||||
본인 차량의 OBD-II PID 설정을 공유해 주시면 다른 사용자들에게 큰 도움이 됩니다! 자세한 공유 및 기여 방법은 [기여 가이드(CONTRIBUTING.ko.md)](CONTRIBUTING.ko.md)를 참고해 주세요.
|
||||
|
||||
---
|
||||
|
||||
## 라이선스
|
||||
|
||||
MIT
|
||||
@@ -1,774 +1,40 @@
|
||||
# HassBle Config
|
||||
# HassBle Config — Toyota Proace City
|
||||
|
||||
> This repository stores the device configuration (`config.yaml`) for the [HassBle](https://github.com/eigger/hassble-android) Android app.
|
||||
Konfiguracja aplikacji [HassBle](https://gitea.trzcinski.pro/czcionka/hassble-android) okrojona do jednego
|
||||
pojazdu: Toyota Proace City (platforma PSA K9, 2019+) z adapterem Vgate iCar Pro ELM327 V2.3 (Bluetooth 4.0 / BLE).
|
||||
|
||||
**[한국어 문서 → README.ko.md](README.ko.md) | [Contributing Guide → CONTRIBUTING.md](CONTRIBUTING.md)**
|
||||
Fork [eigger/hassble-config](https://github.com/eigger/hassble-config). Pełna dokumentacja schematu YAML
|
||||
(`source: obd`, `sensors`, `publish`, presety OBD) jest w repozytorium upstream.
|
||||
|
||||
---
|
||||
## Pliki
|
||||
|
||||
## Table of Contents
|
||||
| Plik | Przeznaczenie |
|
||||
|------|---------------|
|
||||
| `config.yaml` | Konfiguracja bramki — jedno urządzenie `proace_city_obd` |
|
||||
| `templates.yaml` | Ten sam pojazd jako szablon do **Import template** w aplikacji |
|
||||
| `scripts/validate.py` | Walidator schematu (`pip install pyyaml && python scripts/validate.py`) |
|
||||
|
||||
1. [How It Works](#how-it-works)
|
||||
2. [Quick Start](#quick-start)
|
||||
3. [Root Structure](#root-structure)
|
||||
4. [defaults — Publish Rules](#defaults--publish-rules)
|
||||
5. [Device Types](#device-types)
|
||||
6. [source: advertisement — BLE Passive Scan](#source-advertisement--ble-passive-scan)
|
||||
- [match — Matching Conditions](#match--matching-conditions)
|
||||
- [instance_mode — Entity Strategy](#instance_mode--entity-strategy)
|
||||
7. [source: gatt_notify — Active GATT Connection](#source-gatt_notify--active-gatt-connection)
|
||||
8. [source: obd — ELM327 OBD Polling](#source-obd--elm327-obd-polling)
|
||||
9. [sensors — Sensor Config](#sensors--sensor-config)
|
||||
- [decode — Binary Decoding](#decode--binary-decoding)
|
||||
- [Data Types](#data-types)
|
||||
10. [controls — HA Controls](#controls--ha-controls)
|
||||
11. [publish — Per-Sensor Filter](#publish--per-sensor-filter)
|
||||
12. [OBD Preset List](#obd-preset-list)
|
||||
13. [Full Examples](#full-examples)
|
||||
14. [Tips & Gotchas](#tips--gotchas)
|
||||
15. [Contributing](#contributing)
|
||||
Aplikacja pobiera pliki z:
|
||||
|
||||
---
|
||||
- `https://gitea.trzcinski.pro/czcionka/hassble-config/raw/branch/main/config.yaml`
|
||||
- `https://gitea.trzcinski.pro/czcionka/hassble-config/raw/branch/main/templates.yaml`
|
||||
|
||||
## Repository files
|
||||
Zmodyfikowana aplikacja akceptuje konfigurację wyłącznie z `https://gitea.trzcinski.pro`.
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `config.yaml` | Active gateway configuration (devices the app runs) |
|
||||
| `templates.yaml` | Device templates for **Import template** in the Sensors tab |
|
||||
## Uruchomienie
|
||||
|
||||
The app loads both from the repo root on the selected branch (`owner/repo` + branch — file names are fixed).
|
||||
1. W Home Assistant zainstaluj integrację [ws_bridge](https://github.com/eigger/hass-ws-bridge).
|
||||
2. W aplikacji, zakładka **Sensors**: repozytorium `czcionka/hassble-config`, gałąź `main`.
|
||||
3. Zakładka **Gateway**: adres HA i token (lub logowanie OAuth), start bramki.
|
||||
4. Powiąż adapter OBD (MAC) w aplikacji i włącz czujniki, które ECU obsługuje.
|
||||
|
||||
## How It Works
|
||||
PID-y nieobsługiwane przez ECU odpowiadają `NO DATA` — wyłącz takie czujniki w aplikacji.
|
||||
Jeśli aplikacja zgłasza `OBD RX characteristic not found`, sprawdź układ GATT adaptera w nRF Connect
|
||||
i podmień UUID w `config.yaml` (alternatywy są w komentarzu).
|
||||
|
||||
The HassBle app downloads `config.yaml` and `templates.yaml` from this repository (fixed file names at repo root), decodes BLE data according to the rules you define, and automatically declares sensors in Home Assistant via the [ws_bridge](https://github.com/eigger/hass-ws-bridge) integration. No code changes are needed — just edit YAML and push.
|
||||
## Bezpieczeństwo
|
||||
|
||||
Raw URLs (branch `main`):
|
||||
|
||||
- Config: `https://raw.githubusercontent.com/eigger/hassble-config/main/config.yaml`
|
||||
- Templates: `https://raw.githubusercontent.com/eigger/hassble-config/main/templates.yaml`
|
||||
|
||||
```
|
||||
Android Phone (BLE Scan)
|
||||
│ raw bytes
|
||||
▼
|
||||
HassBle App ──── config.yaml (this repo) ────▶ decode rules
|
||||
│ decoded value
|
||||
▼
|
||||
HA WebSocket API ──────────────────────────────▶ ws_bridge
|
||||
│
|
||||
▼
|
||||
Home Assistant Entity (sensor / switch / number / …)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Fork or copy this repository to your GitHub account.
|
||||
2. Edit `config.yaml` to describe your BLE devices. Optionally add device blocks to `templates.yaml` for **Import template** in the app.
|
||||
3. In the HassBle app → **Sensors tab** → enter `your-username/hassble-config` and branch `main` (loads `config.yaml` + `templates.yaml` automatically).
|
||||
4. In the **Gateway tab**, enter your HA URL and token (or use OAuth login), then start the gateway.
|
||||
5. In the **Sensors tab**, enable the sensors you want and they will appear in Home Assistant.
|
||||
|
||||
> ⚠️ **Never put HA credentials (URL / Token) in this file.**
|
||||
> Enter them only in the app settings.
|
||||
|
||||
---
|
||||
|
||||
## Root Structure
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
defaults:
|
||||
publish:
|
||||
on_change_only: true
|
||||
min_interval: 10s
|
||||
|
||||
devices:
|
||||
- id: ...
|
||||
```
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `version` | int | `1` | Schema version. Always `1`. |
|
||||
| `defaults.publish` | object | see below | Default publish filter applied to all sensors. |
|
||||
| `devices` | list | `[]` | List of device configurations. |
|
||||
|
||||
---
|
||||
|
||||
## defaults — Publish Rules
|
||||
|
||||
Controls how often and under what conditions sensor values are sent to HA. Can be overridden per-device or per-sensor.
|
||||
|
||||
```yaml
|
||||
defaults:
|
||||
publish:
|
||||
on_change_only: true # Only send when value changes (default: true)
|
||||
min_interval: 10s # Minimum time between sends (default: 10s)
|
||||
heartbeat: 5m # Force a send at this interval even if unchanged (optional)
|
||||
deadband: 0.5 # Ignore changes smaller than this (optional, numeric sensors only)
|
||||
```
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `on_change_only` | bool | `true` | Only send when the value changes. |
|
||||
| `min_interval` | duration | `10s` | Minimum time between two sends. Formats: `500ms`, `30s`, `5m`. |
|
||||
| `heartbeat` | duration | `null` | Even if unchanged, force a send at this interval. |
|
||||
| `deadband` | float | `null` | Ignore changes smaller than this value (numeric sensors). |
|
||||
|
||||
---
|
||||
|
||||
## Device Types
|
||||
|
||||
Every entry in `devices` must have a `source` field that selects the data path.
|
||||
|
||||
| `source` | Description |
|
||||
|----------|-------------|
|
||||
| `advertisement` | Passive BLE scan — no connection, reads broadcast packets. |
|
||||
| `gatt_notify` | Active GATT connection — connects to the device and subscribes to notifications. Supports write commands. |
|
||||
| `obd` | ELM327 OBD adapter over BLE — polls PID commands and parses ISO-TP responses. |
|
||||
|
||||
**Common fields shared by all device types:**
|
||||
|
||||
```yaml
|
||||
- id: my_device # Unique identifier (lowercase letters, digits, _)
|
||||
name: "My Device" # Display name (HA device name)
|
||||
source: advertisement # advertisement | gatt_notify | obd
|
||||
publish: # (optional) Override publish rules for all sensors of this device
|
||||
on_change_only: true
|
||||
min_interval: 5s
|
||||
sensors: [...]
|
||||
controls: [...] # gatt_notify / obd only
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `id` | string | ✅ | Unique identifier. Used in HA entity unique_id. Use lowercase letters, digits, `_`. |
|
||||
| `name` | string | ✅ | Display name shown in HA device. |
|
||||
| `source` | enum | ✅ | Data source type (see above). |
|
||||
| `publish` | object | ❌ | Device-level publish rule override. |
|
||||
| `sensors` | list | ❌ | List of sensor definitions. |
|
||||
| `controls` | list | ❌ | List of control definitions. |
|
||||
|
||||
---
|
||||
|
||||
## source: advertisement — BLE Passive Scan
|
||||
|
||||
Listens for BLE advertisement packets without connecting. Use `match` to filter packets.
|
||||
|
||||
```yaml
|
||||
- id: my_sensor
|
||||
name: "My BLE Sensor"
|
||||
source: advertisement
|
||||
instance_mode: mac # mac | shared (see below)
|
||||
match:
|
||||
manufacturer_id: 76 # Apple = 76 (0x004C) — must use decimal
|
||||
manufacturer_min_length: 24
|
||||
manufacturer_hex_prefix: "0215"
|
||||
sensors:
|
||||
- key: temperature
|
||||
source_field: manufacturer_data # manufacturer_data | service_data | raw
|
||||
decode:
|
||||
offset: 18
|
||||
length: 2
|
||||
type: uint16
|
||||
endian: big
|
||||
scale: 0.002670288
|
||||
offset_value: -45
|
||||
```
|
||||
|
||||
### match — Matching Conditions
|
||||
|
||||
All specified conditions must be satisfied simultaneously (AND logic). Unspecified fields are ignored.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `mac` | string | Fixed MAC address filter. Format: `"AA:BB:CC:DD:EE:FF"`. |
|
||||
| `service_data_uuid` | string | 16-bit or 128-bit service UUID suffix. E.g. `"F51C"`, `"181A"`. |
|
||||
| `manufacturer_id` | int | Manufacturer company ID. **Must use decimal** (not `0x...`). E.g. Apple=`76`. |
|
||||
| `manufacturer_hex_prefix` | string | Manufacturer payload (hex string) must start with this prefix. E.g. iBeacon=`"0215"`. |
|
||||
| `manufacturer_min_length` | int | Minimum byte length of the manufacturer payload. |
|
||||
| `name_prefix` | string | BLE device name must start with this string. |
|
||||
|
||||
> **⚠️ Hex literals warning**
|
||||
> The YAML parser (`kaml`) may silently fail with `0x...` hex values. Always use **decimal integers**.
|
||||
> `0x004C` → `76`, `0x035D` → `861`
|
||||
|
||||
### instance_mode — Entity Strategy
|
||||
|
||||
Determines how HA entities are created when multiple devices of the same type are detected.
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `mac` (default) | Each unique MAC address creates its own set of HA entities. Entity unique_id: `{device_id}_{MAC}_temperature` etc. Bind a specific MAC in the app's Sensors tab to pre-declare entities before the device is seen. |
|
||||
| `shared` | All matching advertisers share a single HA entity. The last received packet overwrites the state. Useful for parking beacons, clickers, etc. |
|
||||
|
||||
---
|
||||
|
||||
## source: gatt_notify — Active GATT Connection
|
||||
|
||||
Connects to a specific BLE device, subscribes to a GATT characteristic, and receives notifications. Optionally sends hex commands back.
|
||||
|
||||
```yaml
|
||||
- id: custom_meter
|
||||
name: "Custom BLE Meter"
|
||||
source: gatt_notify
|
||||
gatt:
|
||||
mac: "AA:BB:CC:DD:EE:FF" # Or bind in the app's Sensors tab
|
||||
service_uuid: "ffe0"
|
||||
notify_char_uuid: "ffe1"
|
||||
write_char_uuid: "ffe2" # Optional — required for controls
|
||||
auto_connect: true
|
||||
sensors:
|
||||
- key: power
|
||||
unit: "W"
|
||||
device_class: power
|
||||
state_class: measurement
|
||||
decode: { offset: 0, length: 2, type: uint16, endian: little }
|
||||
controls:
|
||||
- key: relay
|
||||
type: switch
|
||||
command: { on: "A10100", off: "A10000" }
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `mac` | string | ❌ | Device MAC address. Can also be set via app bind. |
|
||||
| `service_uuid` | string | ✅ | GATT service UUID (16-bit or full 128-bit). |
|
||||
| `notify_char_uuid` | string | ✅ | Characteristic to subscribe for notifications. |
|
||||
| `write_char_uuid` | string | ❌ | Characteristic to write commands to (needed for controls). |
|
||||
| `auto_connect` | bool | ❌ | Automatically reconnect on disconnect. Default `true`. |
|
||||
|
||||
> If `mac` is not set in the YAML, bind the device in the app's **Sensors tab** (tap "Connect / Bind" next to the device).
|
||||
|
||||
---
|
||||
|
||||
## source: obd — ELM327 OBD Polling
|
||||
|
||||
Connects to an ELM327 BLE adapter, sends OBD-II (and GM mode 22) PID commands, and parses ISO-TP responses. Use built-in `preset`s or define custom `mode`/`pid`/`formula`.
|
||||
|
||||
```yaml
|
||||
- id: car_obd
|
||||
name: "Vehicle OBD"
|
||||
source: obd
|
||||
obd:
|
||||
# mac: "AA:BB:CC:DD:EE:FF" # Or bind in the app
|
||||
service_uuid: "18F0"
|
||||
tx_char_uuid: "2AF1"
|
||||
rx_char_uuid: "2AF0"
|
||||
tx_delay: 50ms
|
||||
init_commands:
|
||||
- "ATZ"
|
||||
- "ATE0"
|
||||
- "ATL0"
|
||||
- "ATS0"
|
||||
- "ATH0"
|
||||
- "ATSP6" # Protocol: ATSP0=auto, ATSP6=ISO 15765-4 CAN 500kbps
|
||||
sensors:
|
||||
# Using preset (recommended)
|
||||
- { key: rpm, preset: rpm, update_interval: 1s }
|
||||
- { key: speed, preset: speed, update_interval: 1s }
|
||||
# Custom definition
|
||||
- key: custom_pid
|
||||
mode: "01"
|
||||
pid: "0C"
|
||||
formula: "(a*256+b)/4"
|
||||
unit: "rpm"
|
||||
state_class: measurement
|
||||
update_interval: 1s
|
||||
```
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-|
|
||||
| `mac` | string | — | Adapter MAC. Set here or via app bind. |
|
||||
| `service_uuid` | string | `"FFF0"` | BLE GATT service UUID. |
|
||||
| `tx_char_uuid` | string | `"FFF2"` | Write characteristic (send commands). |
|
||||
| `rx_char_uuid` | string | `"FFF1"` | Notify characteristic (receive responses). |
|
||||
| `tx_delay` | duration | `50ms` | Delay between consecutive commands. |
|
||||
| `init_commands` | list | `[]` | Commands sent once on each connection before polling starts. |
|
||||
| `default_commands` | list | auto | Commands sent before polling any sensor that has no `pre_commands`. Usually omit it — see "Header restore" below. |
|
||||
| `auto_connect` | bool | `true` | Automatically reconnect on disconnect. |
|
||||
|
||||
**OBD sensor-specific fields:**
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `preset` | string | Use a built-in preset (see table below). |
|
||||
| `mode` | string | OBD mode. `"01"` = standard, `"22"` = manufacturer specific. Default `"01"`. |
|
||||
| `pid` | string | PID hex code (without mode prefix). E.g. `"0C"`, `"199A"`. |
|
||||
| `formula` | string | Math expression. Variables `a`–`t` are response bytes 0–19. E.g. `"(a*256+b)/4"`. If the response is too short to bind a byte used in the expression, nothing is published for that poll. |
|
||||
| `decode` | map | Extract the value by byte offset instead of `formula`. Use it to reach bytes past the 20th (see below). |
|
||||
| `update_interval` | duration | How often to poll this PID. Default `60s`. |
|
||||
| `pre_commands` | list | Extra AT/OBD commands to send before this PID (e.g., header switch for GM). |
|
||||
|
||||
### Reaching values in long responses (decode)
|
||||
|
||||
`formula` variables only address the **first 20 bytes** of a response (`a`–`t`). Anything
|
||||
further in is read with `decode`, which takes the same fields as the [decode section](#decode--byte-decoding).
|
||||
|
||||
```yaml
|
||||
# Odometer in the Hyundai 21 03 block — bytes 57-60, 32-bit, /1000 = km
|
||||
- key: odometer
|
||||
mode: "21"
|
||||
pid: "03"
|
||||
pre_commands: ["ATSH7E0"]
|
||||
decode: { offset: 57, length: 4, type: uint32, endian: big, scale: 0.001 }
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: total_increasing
|
||||
```
|
||||
|
||||
`offset` is 0-based into the data with the mode/PID echo removed, so `offset: 0` is the same
|
||||
byte as `a` in a formula. If the response is too short for `offset + length`, nothing is
|
||||
published for that poll, so an unsupported car never reports a bogus value.
|
||||
|
||||
`decode` wins if a sensor sets both `decode` and `formula`.
|
||||
|
||||
### Header restore (ATSH)
|
||||
|
||||
An ELM327 transmit header **stays in effect once set**. So a sensor with
|
||||
`pre_commands: ["ATSH7C6"]` leaves the header pointing at the cluster, and the next standard
|
||||
sensor (rpm, speed, …) that has no `pre_commands` gets sent there too — returning `NO DATA`.
|
||||
|
||||
The app handles this automatically. **If any sensor uses `ATSH` in `pre_commands`**, a restore
|
||||
command is inserted before every sensor that has no `pre_commands`. The header to restore is
|
||||
chosen in this order:
|
||||
|
||||
1. `default_commands`, if you set it
|
||||
2. the last `ATSH…` in `init_commands`
|
||||
3. `ATSH7DF` — the ELM327 default header for 11-bit CAN
|
||||
|
||||
If no sensor uses `ATSH`, nothing is sent. This avoids pushing `ATSH7DF` onto protocols with a
|
||||
different header format, such as K-line (ISO 9141 / KWP).
|
||||
|
||||
So you can normally **omit `default_commands`**; set it only to pin a specific restore header:
|
||||
|
||||
```yaml
|
||||
obd:
|
||||
init_commands: ["ATSP6"]
|
||||
default_commands: ["ATSH7E0"] # address the engine ECU instead of broadcasting to 7DF
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## sensors — Sensor Config
|
||||
|
||||
Each item in the `sensors` list defines one HA entity.
|
||||
|
||||
```yaml
|
||||
sensors:
|
||||
- key: temperature # Required — unique key within the device
|
||||
platform: sensor # sensor | binary_sensor | text_sensor
|
||||
device_class: temperature # HA device_class (optional)
|
||||
unit: "°C"
|
||||
state_class: measurement # measurement | total | total_increasing
|
||||
icon: "mdi:thermometer"
|
||||
entity_category: diagnostic # diagnostic | config (omit for normal sensor)
|
||||
accuracy_decimals: 2
|
||||
source_field: manufacturer_data # advertisement only
|
||||
min_length: 24
|
||||
decode:
|
||||
offset: 18
|
||||
length: 2
|
||||
type: uint16
|
||||
endian: big
|
||||
scale: 0.002670288
|
||||
offset_value: -45
|
||||
publish: # Override publish rule for this sensor only
|
||||
deadband: 0.1
|
||||
min_interval: 30s
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `key` | string | ✅ | Unique key within the device. Becomes part of HA entity unique_id. |
|
||||
| `platform` | string | ❌ | HA entity platform. Default `sensor`. |
|
||||
| `device_class` | string | ❌ | HA device class (temperature, humidity, battery, voltage, …). |
|
||||
| `unit` | string | ❌ | Unit of measurement shown in HA. |
|
||||
| `state_class` | string | ❌ | HA state class for statistics. |
|
||||
| `icon` | string | ❌ | MDI icon string, e.g. `"mdi:thermometer"`. |
|
||||
| `entity_category` | string | ❌ | `diagnostic` or `config`. Omit for normal sensor. |
|
||||
| `accuracy_decimals` | int | ❌ | Round the decoded value to N decimal places. |
|
||||
| `source_field` | enum | ❌ | `manufacturer_data` / `service_data` / `raw`. Default `raw`. |
|
||||
| `min_length` | int | ❌ | Skip this sensor if the payload is shorter than N bytes. |
|
||||
| `decode` | object | ❌ | Binary decoding rules. See below. |
|
||||
| `publish` | object | ❌ | Override publish rule for this sensor only. |
|
||||
|
||||
### decode — Binary Decoding
|
||||
|
||||
Extracts a numeric or string value from a raw byte array.
|
||||
|
||||
**Formula:** `final_value = (raw_integer * scale) + offset_value`
|
||||
|
||||
```yaml
|
||||
decode:
|
||||
offset: 18 # Byte offset (0-based)
|
||||
length: 2 # Number of bytes to read
|
||||
type: uint16 # Data type (see table below)
|
||||
endian: big # big | little
|
||||
bitmask: 0x0F # (optional) Apply AND bitmask before decoding
|
||||
scale: 0.1 # (optional) Multiply factor. Default 1.0
|
||||
offset_value: -40 # (optional) Add after scaling. Default 0.0
|
||||
map: # (optional) Map integer result to string
|
||||
"0": "off"
|
||||
"1": "on"
|
||||
"2": "standby"
|
||||
```
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-|
|
||||
| `offset` | int | `0` | Start byte index (0-based). |
|
||||
| `length` | int | `1` | Number of bytes to read. |
|
||||
| `type` | enum | `uint8` | Data type to interpret the bytes as. |
|
||||
| `endian` | enum | `big` | Byte order. `big` = MSB first, `little` = LSB first. |
|
||||
| `bitmask` | int | `null` | Apply AND bitmask to the raw integer before scaling. |
|
||||
| `scale` | float | `1.0` | Multiply the raw integer by this value. |
|
||||
| `offset_value` | float | `0.0` | Add this after scaling: `(raw * scale) + offset_value`. |
|
||||
| `map` | object | `{}` | Map integer result to a string. Keys must be quoted strings. |
|
||||
|
||||
### Data Types
|
||||
|
||||
| Type | Bytes | Description |
|
||||
|------|-------|-------------|
|
||||
| `uint8` | 1 | Unsigned 8-bit integer (0–255). |
|
||||
| `int8` | 1 | Signed 8-bit integer (-128–127). |
|
||||
| `uint16` | 2 | Unsigned 16-bit integer (0–65535). |
|
||||
| `int16` | 2 | Signed 16-bit integer (-32768–32767). |
|
||||
| `uint32` | 4 | Unsigned 32-bit integer. |
|
||||
| `int32` | 4 | Signed 32-bit integer. |
|
||||
| `float32` | 4 | IEEE 754 single-precision float. |
|
||||
| `timestamp` | 4 | Bytes interpreted as month/day/hour/minute (1 byte each). Returned as ISO 8601 string. |
|
||||
| `string` | N | Bytes decoded as ASCII. Use with `platform: text_sensor`. |
|
||||
|
||||
---
|
||||
|
||||
## controls — HA Controls
|
||||
|
||||
Define Home Assistant entities that send BLE write commands when triggered from HA. Only available for `gatt_notify` and `obd` sources.
|
||||
|
||||
```yaml
|
||||
controls:
|
||||
# Switch — on/off hex command
|
||||
- key: relay
|
||||
type: switch
|
||||
name: "Main Relay"
|
||||
icon: "mdi:electric-switch"
|
||||
entity_category: config
|
||||
command:
|
||||
on: "A10100"
|
||||
off: "A10000"
|
||||
|
||||
# Number — insert value into hex template
|
||||
- key: brightness
|
||||
type: number
|
||||
min: 0
|
||||
max: 100
|
||||
step: 1
|
||||
command:
|
||||
template: "B2{value:02X}FF"
|
||||
|
||||
# Select — per-option hex command
|
||||
- key: mode
|
||||
type: select
|
||||
options: ["auto", "cool", "heat", "fan"]
|
||||
command:
|
||||
auto: "C000"
|
||||
cool: "C001"
|
||||
heat: "C002"
|
||||
fan: "C003"
|
||||
|
||||
# Button — sends hex on press
|
||||
- key: restart
|
||||
type: button
|
||||
command:
|
||||
press: "FFFE"
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `key` | string | ✅ | Unique key within the device. |
|
||||
| `type` | enum | ✅ | `switch` / `number` / `select` / `button`. |
|
||||
| `name` | string | ❌ | Display name in HA. Auto-generated from key if omitted. |
|
||||
| `icon` | string | ❌ | MDI icon string. |
|
||||
| `entity_category` | string | ❌ | `config` or `diagnostic`. |
|
||||
| `command` | object | ✅ | Command map. Keys depend on type (see examples above). |
|
||||
| `options` | list | select only | Options list for `select` type. |
|
||||
| `min` | float | number only | Minimum value for `number` type. |
|
||||
| `max` | float | number only | Maximum value for `number` type. |
|
||||
| `step` | float | ❌ | Step size for `number` type. |
|
||||
|
||||
**command template placeholders:**
|
||||
|
||||
| Placeholder | Description |
|
||||
|-------------|-------------|
|
||||
| `{value}` | Integer value (decimal). |
|
||||
| `{value:02X}` | Value as 2-digit uppercase hex (zero-padded). |
|
||||
| `{value:04X}` | Value as 4-digit uppercase hex. |
|
||||
|
||||
---
|
||||
|
||||
## publish — Per-Sensor Filter
|
||||
|
||||
Override the global `defaults.publish` for a specific sensor. Useful for sensors that change slowly (fuel level) or need frequent updates (RPM).
|
||||
|
||||
```yaml
|
||||
sensors:
|
||||
- key: fuel_level
|
||||
preset: fuel_level
|
||||
update_interval: 30s
|
||||
publish:
|
||||
on_change_only: true
|
||||
deadband: 0.5
|
||||
min_interval: 60s
|
||||
heartbeat: 30m
|
||||
```
|
||||
|
||||
**Priority:** sensor `publish` > device `publish` > `defaults.publish`
|
||||
|
||||
---
|
||||
|
||||
## OBD Preset List
|
||||
|
||||
Use `preset: <name>` in OBD sensors to use these built-in definitions. You can override individual fields (`unit`, `accuracy_decimals`, etc.) after specifying the preset.
|
||||
|
||||
### Standard OBD-II (mode 01)
|
||||
|
||||
| Preset | PID | Formula | Unit | Description |
|
||||
|--------|-----|---------|------|-------------|
|
||||
| `rpm` | `0C` | `(a*256+b)/4` | rpm | Engine RPM |
|
||||
| `speed` | `0D` | `a` | km/h | Vehicle speed |
|
||||
| `engine_load` | `04` | `a/2.55` | % | Engine load |
|
||||
| `throttle` | `11` | `a/2.55` | % | Throttle position |
|
||||
| `coolant_temp` | `05` | `a-40` | °C | Coolant temperature |
|
||||
| `intake_air_temp` | `0F` | `a-40` | °C | Intake air temperature |
|
||||
| `ambient_temp` | `46` | `a-40` | °C | Ambient temperature |
|
||||
| `battery_voltage` | `42` | `(a*256+b)/1000` | V | Battery voltage |
|
||||
| `run_time` | `1F` | `a*256+b` | s | Engine run time |
|
||||
| `fuel_level` | `2F` | `a/2.55` | % | Fuel level |
|
||||
| `actual_torque` | `62` | `a-125` | % | Actual torque |
|
||||
| `odometer` | `A6` | `(a*16777216+b*65536+c*256+d)/10` | km | Odometer |
|
||||
|
||||
### GM Extensions (mode 22)
|
||||
|
||||
| Preset | PID | Formula | Unit | Description |
|
||||
|--------|-----|---------|------|-------------|
|
||||
| `gm_current_gear` | `199A` | `a` | — | Current gear |
|
||||
| `gm_prnd_status_alt` | `2889` | `a` | — | PRND status |
|
||||
| `gm_oil_pressure` | `115C` | `(a*0.65)-17.5` | psi | Oil pressure |
|
||||
| `gm_trans_temp` | `1940` | `a-40` | °C | Transmission temperature |
|
||||
| `gm_fuel_level_liters` | `132A` | `(a*256+b)/64` | L | Fuel level (liters) |
|
||||
|
||||
---
|
||||
|
||||
## Full Examples
|
||||
|
||||
### Example 1 — Jaalee JHT (iBeacon Temperature/Humidity)
|
||||
|
||||
```yaml
|
||||
- id: jaalee_jht
|
||||
name: "Jaalee JHT"
|
||||
source: advertisement
|
||||
instance_mode: mac
|
||||
match:
|
||||
manufacturer_id: 76 # Apple Inc. (must be decimal)
|
||||
manufacturer_min_length: 24
|
||||
manufacturer_hex_prefix: "0215" # iBeacon type marker
|
||||
sensors:
|
||||
- key: temperature
|
||||
device_class: temperature
|
||||
unit: "°C"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
source_field: manufacturer_data
|
||||
decode: { offset: 18, length: 2, type: uint16, endian: big, scale: 0.002670288, offset_value: -45 }
|
||||
- key: humidity
|
||||
device_class: humidity
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
source_field: manufacturer_data
|
||||
decode: { offset: 20, length: 2, type: uint16, endian: big, scale: 0.001524504 }
|
||||
- key: battery
|
||||
device_class: battery
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
source_field: manufacturer_data
|
||||
decode: { offset: 23, length: 1, type: uint8 }
|
||||
```
|
||||
|
||||
### Example 2 — Custom Service Data Sensor
|
||||
|
||||
```yaml
|
||||
- id: my_env_sensor
|
||||
name: "Environment Sensor"
|
||||
source: advertisement
|
||||
instance_mode: shared
|
||||
match:
|
||||
service_data_uuid: "181A" # Environmental Sensing UUID
|
||||
sensors:
|
||||
- key: temperature
|
||||
device_class: temperature
|
||||
unit: "°C"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
source_field: service_data
|
||||
decode: { offset: 0, length: 2, type: int16, endian: little, scale: 0.01 }
|
||||
- key: humidity
|
||||
device_class: humidity
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
source_field: service_data
|
||||
decode: { offset: 2, length: 2, type: uint16, endian: little, scale: 0.01 }
|
||||
- key: battery
|
||||
device_class: battery
|
||||
unit: "%"
|
||||
source_field: service_data
|
||||
decode: { offset: 9, length: 1, type: uint8 }
|
||||
```
|
||||
|
||||
### Example 3 — GATT Sensor with Switch Control
|
||||
|
||||
```yaml
|
||||
- id: power_monitor
|
||||
name: "Power Monitor"
|
||||
source: gatt_notify
|
||||
gatt:
|
||||
service_uuid: "ffe0"
|
||||
notify_char_uuid: "ffe1"
|
||||
write_char_uuid: "ffe2"
|
||||
sensors:
|
||||
- key: power
|
||||
device_class: power
|
||||
unit: "W"
|
||||
state_class: measurement
|
||||
decode: { offset: 0, length: 2, type: uint16, endian: little }
|
||||
- key: voltage
|
||||
device_class: voltage
|
||||
unit: "V"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
decode: { offset: 2, length: 2, type: uint16, endian: little, scale: 0.1 }
|
||||
- key: current
|
||||
device_class: current
|
||||
unit: "A"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
decode: { offset: 4, length: 2, type: uint16, endian: little, scale: 0.01 }
|
||||
controls:
|
||||
- key: relay
|
||||
type: switch
|
||||
name: "Relay"
|
||||
icon: "mdi:electric-switch"
|
||||
command: { on: "A10100", off: "A10000" }
|
||||
```
|
||||
|
||||
### Example 4 — OBD with Presets and Custom Publish
|
||||
|
||||
```yaml
|
||||
- id: car_obd
|
||||
name: "Vehicle"
|
||||
source: obd
|
||||
obd:
|
||||
service_uuid: "18F0"
|
||||
tx_char_uuid: "2AF1"
|
||||
rx_char_uuid: "2AF0"
|
||||
tx_delay: 50ms
|
||||
init_commands: ["ATZ", "ATE0", "ATL0", "ATS0", "ATH0", "ATSP6"]
|
||||
sensors:
|
||||
- { key: rpm, preset: rpm, update_interval: 1s }
|
||||
- { key: speed, preset: speed, update_interval: 1s }
|
||||
- { key: coolant_temp, preset: coolant_temp, update_interval: 10s }
|
||||
- key: fuel_level
|
||||
preset: fuel_level
|
||||
update_interval: 30s
|
||||
publish:
|
||||
deadband: 1.0
|
||||
min_interval: 60s
|
||||
heartbeat: 10m
|
||||
```
|
||||
|
||||
### Example 5 — Value Map (Status Codes)
|
||||
|
||||
```yaml
|
||||
- id: status_device
|
||||
name: "Status Device"
|
||||
source: advertisement
|
||||
instance_mode: shared
|
||||
match:
|
||||
manufacturer_id: 1234
|
||||
sensors:
|
||||
- key: mode
|
||||
platform: text_sensor
|
||||
source_field: manufacturer_data
|
||||
decode:
|
||||
offset: 5
|
||||
length: 1
|
||||
type: uint8
|
||||
map:
|
||||
"0": "idle"
|
||||
"1": "running"
|
||||
"2": "error"
|
||||
"3": "standby"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips & Gotchas
|
||||
|
||||
### ⚠️ Always use decimal for manufacturer_id
|
||||
|
||||
The YAML parser (`kaml`) may silently parse `0x004C` as `0` or cause a crash. Always convert hex to decimal:
|
||||
|
||||
```yaml
|
||||
# ❌ Wrong — may cause parse errors
|
||||
manufacturer_id: 0x004C
|
||||
|
||||
# ✅ Correct
|
||||
manufacturer_id: 76 # 0x004C = 76
|
||||
manufacturer_id: 861 # 0x035D = 861
|
||||
```
|
||||
|
||||
### AND logic in match
|
||||
|
||||
All `match` conditions are ANDed together. If you specify both `service_data_uuid` and `manufacturer_id`, the packet must satisfy **both**. Remove a condition if your device doesn't always advertise it.
|
||||
|
||||
### instance_mode: mac — Bind for early entity creation
|
||||
|
||||
With `instance_mode: mac` and no fixed `match.mac`, HA entities only appear after the device is detected by BLE scan. To make entities appear immediately on gateway connect, bind the MAC in the app's **Sensors tab** → "Connect / Bind".
|
||||
|
||||
### source_field selection
|
||||
|
||||
For advertisement sensors, choose the right payload source:
|
||||
- `manufacturer_data` — data after the manufacturer company ID (most common for custom sensors)
|
||||
- `service_data` — data in the service data AD type (common for standard profiles like 0x181A)
|
||||
- `raw` — full scan record bytes (rarely needed)
|
||||
|
||||
### Duration format
|
||||
|
||||
Durations support milliseconds (`ms`), seconds (`s`), and minutes (`m`).
|
||||
|
||||
```yaml
|
||||
tx_delay: 50ms
|
||||
min_interval: 10s
|
||||
heartbeat: 5m
|
||||
update_interval: 1s
|
||||
```
|
||||
|
||||
### Config is cached
|
||||
|
||||
The app caches the last successfully loaded config. If the network is unavailable on startup, it uses the cache. The app always shows "Using cached config" in the header when this happens.
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome your vehicle OBD-II PID configurations! Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on how to contribute.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
- Nie umieszczaj w tym repozytorium adresu ani tokenu Home Assistant.
|
||||
- Nie commituj adresu MAC adaptera — powiąż go w aplikacji.
|
||||
- Każda zmiana tego repozytorium trafia do telefonu przy następnym przeładowaniu konfiguracji.
|
||||
Chroń gałąź `main` (protected branch) i ogranicz prawa zapisu.
|
||||
+459
-141
@@ -1,8 +1,8 @@
|
||||
# HassBle Configuration File
|
||||
# HassBle configuration — Toyota Proace City (PSA K9 platform, 2019+)
|
||||
# Adapter: Vgate iCar Pro ELM327 V2.3, Bluetooth 4.0 (BLE) variant
|
||||
#
|
||||
# Host config.yaml and templates.yaml in a Git repository (e.g., GitHub).
|
||||
# In the HassBle app: enter owner/repo and branch (e.g. eigger/hassble-config, main).
|
||||
# The app loads config.yaml for the gateway and templates.yaml for Import template.
|
||||
# Served from https://gitea.trzcinski.pro/czcionka/hassble-config (branch main).
|
||||
# The app accepts config only from gitea.trzcinski.pro over HTTPS.
|
||||
#
|
||||
# Do NOT put any Home Assistant credentials (URL/Token) in this file. Enter them in the app.
|
||||
|
||||
@@ -14,155 +14,473 @@ defaults:
|
||||
min_interval: 10s
|
||||
|
||||
devices:
|
||||
# ──────────────────────────────────────────────────────────────
|
||||
# Path A: BLE Passive Scanning (Advertisements)
|
||||
# ──────────────────────────────────────────────────────────────
|
||||
# Jaalee JHT — instance_mode: mac → 스캔된 MAC마다 jaalee_jht_{MAC} 엔티티 자동 생성
|
||||
# Ref: https://github.com/eigger/espcomponents/tree/master/components/jaalee_jht
|
||||
# Temp/Humidity formula: https://sensor.jaalee.com/scan_api.html
|
||||
#- id: jaalee_jht
|
||||
# name: "Jaalee JHT"
|
||||
# source: advertisement
|
||||
# instance_mode: mac
|
||||
# match:
|
||||
# manufacturer_id: 76 # Apple Inc. (0x004C) — decimal 사용 필수 (hex 0x... 파싱 불안정)
|
||||
# manufacturer_min_length: 24
|
||||
# manufacturer_hex_prefix: "0215" # iBeacon 타입 마커 (0x02=subtype, 0x15=length 21)
|
||||
# sensors:
|
||||
# - key: temperature
|
||||
# device_class: temperature
|
||||
# unit: "°C"
|
||||
# state_class: measurement
|
||||
# accuracy_decimals: 2
|
||||
# source_field: manufacturer_data
|
||||
# decode: { offset: 18, length: 2, type: uint16, endian: big, scale: 0.002670288, offset_value: -45 }
|
||||
# - key: humidity
|
||||
# device_class: humidity
|
||||
# unit: "%"
|
||||
# state_class: measurement
|
||||
# accuracy_decimals: 2
|
||||
# source_field: manufacturer_data
|
||||
# decode: { offset: 20, length: 2, type: uint16, endian: big, scale: 0.001524504 }
|
||||
# - key: battery
|
||||
# device_class: battery
|
||||
# unit: "%"
|
||||
# state_class: measurement
|
||||
# source_field: manufacturer_data
|
||||
# decode: { offset: 23, length: 1, type: uint8 }
|
||||
|
||||
# Parking beacon — instance_mode: shared → MAC 무관, manufacturer 0x035D 광고가 하나의 엔티티 공유
|
||||
# payload 14바이트: [0]=04(응답타입), [1..6]=KeyMAC, [7..10]=월·일·시·분, [11]=층(256-raw), [12..13]=구역코드
|
||||
# 04xx: 주차위치 응답 비콘, 07xx: SmartKey 인증(22B 암호화), 02xx: 출입 이벤트(6B) — prefix "04" 로 응답만 매칭
|
||||
- id: parking_beacon
|
||||
name: "Parking Beacon"
|
||||
source: advertisement
|
||||
instance_mode: shared
|
||||
match:
|
||||
manufacturer_id: 861 # 0x035D
|
||||
manufacturer_hex_prefix: "04" # 응답 비콘만 매칭 (07=SmartKey 인증, 02=출입 이벤트 제외)
|
||||
sensors:
|
||||
- key: parking_time
|
||||
device_class: timestamp
|
||||
icon: mdi:clock-time-four-outline
|
||||
source_field: manufacturer_data
|
||||
length: 14
|
||||
decode: { offset: 7, length: 4, type: timestamp }
|
||||
- key: parking_floor
|
||||
icon: mdi:layers-outline
|
||||
source_field: manufacturer_data
|
||||
length: 14
|
||||
accuracy_decimals: 0
|
||||
decode: { offset: 11, length: 1, type: uint8, scale: -1, offset_value: 256 }
|
||||
- key: parking_location
|
||||
platform: text_sensor
|
||||
icon: mdi:map-marker-outline
|
||||
source_field: manufacturer_data
|
||||
length: 14
|
||||
decode: { offset: 12, length: 2, type: string }
|
||||
|
||||
# APT SmartKey 출입문 이벤트 — 고정 MAC으로 하드웨어 필터, 02xx 6바이트 패킷만 파싱
|
||||
# payload 6바이트: [0]=02(이벤트타입), [1..3]=05 00 55, [4]=상태, [5]=카운터
|
||||
# byte[4] 상태값: 0x41(65)=entering_start, 0x01(1)=entering, 0x40(64)=exiting, 0x00(0)=idle
|
||||
# 0x41→0x01 두 값 모두 "entering"으로 매핑 → on_change_only가 중간 전환 노이즈 제거
|
||||
- id: apt_key_door
|
||||
name: "APT Door Event"
|
||||
source: advertisement
|
||||
instance_mode: shared
|
||||
match:
|
||||
manufacturer_id: 861 # 0x035D
|
||||
manufacturer_hex_prefix: "02" # 출입 이벤트 타입만 (07xx=인증 22B, 04xx=주차응답 14B 제외)
|
||||
sensors:
|
||||
- key: door_status
|
||||
platform: text_sensor
|
||||
icon: mdi:door
|
||||
source_field: manufacturer_data
|
||||
length: 6
|
||||
publish:
|
||||
min_interval: 1s # 기본 10s 오버라이드 — 이벤트가 수 초 내 전환됨
|
||||
decode:
|
||||
offset: 4
|
||||
length: 1
|
||||
type: uint8
|
||||
map:
|
||||
"65": "entering" # 0x41 인증 시작
|
||||
"1": "entering" # 0x01 인증 완료 (entering과 동일 → 전환 노이즈 제거)
|
||||
"64": "exiting" # 0x40
|
||||
"0": "idle" # 0x00
|
||||
|
||||
# ──────────────────────────────────────────────────────────────
|
||||
# Path C: OBD (ELM327) over BLE
|
||||
# ──────────────────────────────────────────────────────────────
|
||||
- id: car_obd
|
||||
name: "Vehicle OBD"
|
||||
- id: proace_city_obd
|
||||
name: "Toyota Proace City"
|
||||
source: obd
|
||||
obd:
|
||||
# Bind the adapter MAC in the app (Sensors tab) instead of committing it here.
|
||||
# The adapter advertises as "IOS-Vlink" with service 0x18F0 (checked with nRF Connect).
|
||||
service_uuid: "18F0"
|
||||
tx_char_uuid: "2AF1"
|
||||
rx_char_uuid: "2AF0"
|
||||
tx_delay: 50ms
|
||||
init_commands:
|
||||
- "ATSP6"
|
||||
- "ATSP6" # ISO 15765-4 CAN 11-bit 500 kbps, confirmed by Car Scanner
|
||||
# PSA sensors below talk to the engine ECU at 6A8 (answers from 688);
|
||||
# standard PIDs need the functional header and automatic receive filter back.
|
||||
default_commands: ["ATSH7DF", "ATCRA"]
|
||||
sensors:
|
||||
#- { key: rpm, preset: rpm, update_interval: 1s }
|
||||
#- { key: speed, preset: speed, update_interval: 1s }
|
||||
#- { key: engine_load, preset: engine_load, update_interval: 1s }
|
||||
#- { key: throttle, preset: throttle, update_interval: 1s }
|
||||
#- { key: coolant_temp, preset: coolant_temp, update_interval: 10s }
|
||||
#- { key: intake_temp, preset: intake_air_temp, update_interval: 10s }
|
||||
#- { key: ambient_temp, preset: ambient_temp, update_interval: 30s }
|
||||
- { key: battery, preset: battery_voltage, update_interval: 10s }
|
||||
- { key: run_time, preset: run_time, update_interval: 5s }
|
||||
- { key: odometer, preset: odometer, update_interval: 30s }
|
||||
# Standard SAE J1979 mode 01 PIDs. A PID the ECU does not support answers NO DATA —
|
||||
# disable such sensors in the app.
|
||||
- { key: rpm, preset: rpm, update_interval: 2s }
|
||||
- { key: speed, preset: speed, update_interval: 2s }
|
||||
- { key: engine_load, preset: engine_load, update_interval: 5s }
|
||||
- { key: coolant_temp, preset: coolant_temp, update_interval: 30s }
|
||||
- { key: intake_temp, preset: intake_air_temp, update_interval: 30s }
|
||||
- { key: ambient_temp, preset: ambient_temp, update_interval: 60s }
|
||||
- { key: battery, preset: battery_voltage, update_interval: 10s }
|
||||
- { key: run_time, preset: run_time, update_interval: 10s }
|
||||
# The ECU does not answer 01 2F; see the psa_fuel_level_* candidates below.
|
||||
- key: fuel_level
|
||||
preset: fuel_level
|
||||
update_interval: 30s
|
||||
publish:
|
||||
deadband: 0.5
|
||||
min_interval: 60s
|
||||
# GM Extensions (mode 22)
|
||||
#- { key: gear, preset: gm_current_gear, update_interval: 1s }
|
||||
#- { key: prnd, preset: gm_prnd_status_alt, update_interval: 1s }
|
||||
#- { key: torque, preset: actual_torque, update_interval: 1s }
|
||||
#- { key: oil_pressure, preset: gm_oil_pressure, update_interval: 2s }
|
||||
#- { key: trans_temp, preset: gm_trans_temp, update_interval: 10s }
|
||||
# PID A6 is mandatory only on newer (Euro 6d) ECUs.
|
||||
- { key: odometer, preset: odometer, update_interval: 60s }
|
||||
- key: intake_map
|
||||
mode: "01"
|
||||
pid: "0B"
|
||||
formula: "a"
|
||||
unit: "kPa"
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 5s
|
||||
- key: barometric_pressure
|
||||
mode: "01"
|
||||
pid: "33"
|
||||
formula: "a"
|
||||
unit: "kPa"
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 120s
|
||||
# Diesel (1.5 BlueHDi) common-rail pressure; petrol engines answer NO DATA.
|
||||
- key: fuel_rail_pressure
|
||||
mode: "01"
|
||||
pid: "23"
|
||||
formula: "(a*256+b)*10"
|
||||
unit: "kPa"
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 5s
|
||||
- key: distance_since_dtc_clear
|
||||
mode: "01"
|
||||
pid: "31"
|
||||
formula: "a*256+b"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: total_increasing
|
||||
accuracy_decimals: 0
|
||||
update_interval: 300s
|
||||
- key: distance_with_mil_on
|
||||
mode: "01"
|
||||
pid: "21"
|
||||
formula: "a*256+b"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:engine-off
|
||||
update_interval: 300s
|
||||
# ── DPF / exhaust aftertreatment (SAE J1979 diesel PIDs) ──
|
||||
# Byte a is the PID's "supported" bitmask, so values start at byte b.
|
||||
# Car Scanner lists DPF data only from the PSA profile, so these may answer NO DATA;
|
||||
# the PSA section below reads the same values from the engine ECU directly.
|
||||
- key: dpf_inlet_temp
|
||||
mode: "01"
|
||||
pid: "7C"
|
||||
formula: "(b*256+c)/10-40"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:thermometer-chevron-up
|
||||
update_interval: 10s
|
||||
- key: dpf_outlet_temp
|
||||
mode: "01"
|
||||
pid: "7C"
|
||||
formula: "(d*256+e)/10-40"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:thermometer-chevron-down
|
||||
update_interval: 10s
|
||||
# Signed 16-bit: rising differential pressure means soot is building up.
|
||||
- key: dpf_differential_pressure
|
||||
mode: "01"
|
||||
pid: "7A"
|
||||
formula: "(b*256+c-floor(b/128)*65536)/100"
|
||||
unit: "kPa"
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
update_interval: 10s
|
||||
# 100 % means the ECU wants a regeneration.
|
||||
- key: dpf_regen_trigger
|
||||
mode: "01"
|
||||
pid: "8B"
|
||||
formula: "c*100/255"
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:air-filter
|
||||
update_interval: 30s
|
||||
- key: dpf_regen_required
|
||||
platform: binary_sensor
|
||||
mode: "01"
|
||||
pid: "8B"
|
||||
formula: "floor(c/255)"
|
||||
icon: mdi:air-filter
|
||||
update_interval: 30s
|
||||
- key: dpf_regen_active
|
||||
platform: binary_sensor
|
||||
mode: "01"
|
||||
pid: "8B"
|
||||
formula: "b%2"
|
||||
icon: mdi:fire
|
||||
update_interval: 10s
|
||||
- key: dpf_avg_distance_between_regens
|
||||
mode: "01"
|
||||
pid: "8B"
|
||||
formula: "f*256+g"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 300s
|
||||
- key: egt_bank1_sensor1
|
||||
mode: "01"
|
||||
pid: "78"
|
||||
formula: "(b*256+c)/10-40"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 10s
|
||||
- key: egt_bank1_sensor2
|
||||
mode: "01"
|
||||
pid: "78"
|
||||
formula: "(d*256+e)/10-40"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 10s
|
||||
|
||||
# ──────────────────────────────────────────────────────────────
|
||||
# Path B: GATT Notify & Write (Bi-directional Control)
|
||||
# ──────────────────────────────────────────────────────────────
|
||||
#- id: custom_meter
|
||||
# name: "Custom BLE Meter"
|
||||
# source: gatt_notify
|
||||
# gatt:
|
||||
# service_uuid: "ffe0"
|
||||
# notify_char_uuid: "ffe1"
|
||||
# write_char_uuid: "ffe2"
|
||||
# sensors:
|
||||
# - key: power
|
||||
# unit: "W"
|
||||
# device_class: power
|
||||
# state_class: measurement
|
||||
# decode: { offset: 0, length: 2, type: uint16, endian: little }
|
||||
# controls:
|
||||
# - key: relay
|
||||
# type: switch
|
||||
# command: { on: "A10100", off: "A10000" }
|
||||
# ── PSA engine ECU (Bosch MD1CS003, 1.5 BlueHDi), UDS mode 22 ──
|
||||
# DIDs and scaling from OBDb (github.com/OBDb/Citroen, header 6A8 → 688).
|
||||
# Names match what Car Scanner's "Citroen 1.5 BlueHDI" profile shows.
|
||||
# Byte a is the first byte after the "62 Dxxx" echo. OBDb marks some of these DIDs as
|
||||
# little-endian (blsb), but on this ECU that gave 425 % soot, so all values are read big-endian.
|
||||
- key: psa_dpf_soot_level
|
||||
mode: "22"
|
||||
pid: "D52F"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b)/10.24"
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:air-filter
|
||||
update_interval: 60s
|
||||
- key: psa_dpf_soot_load
|
||||
mode: "22"
|
||||
pid: "D54B"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b)/1024"
|
||||
unit: "g/L"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
icon: mdi:air-filter
|
||||
update_interval: 60s
|
||||
- key: psa_dpf_regen_status
|
||||
mode: "22"
|
||||
pid: "D521"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a"
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:fire
|
||||
update_interval: 15s
|
||||
- key: psa_dpf_distance_since_regen
|
||||
mode: "22"
|
||||
pid: "D519"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b)/16"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 120s
|
||||
- key: psa_dpf_avg_regen_interval
|
||||
mode: "22"
|
||||
pid: "D525"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b)/16"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 600s
|
||||
- key: psa_dpf_remaining_life
|
||||
mode: "22"
|
||||
pid: "D530"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b-floor(a/128)*65536)*16"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 3600s
|
||||
# Car Scanner shows this deviation in mbar.
|
||||
- key: psa_dpf_diff_pressure_deviation
|
||||
mode: "22"
|
||||
pid: "D518"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a*256+b-floor(a/128)*65536"
|
||||
unit: "mbar"
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 15s
|
||||
- key: psa_egt_before_catalyst
|
||||
mode: "22"
|
||||
pid: "D52E"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b-floor(a/128)*65536)/10-273.14"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 10s
|
||||
- key: psa_egt_after_catalyst
|
||||
mode: "22"
|
||||
pid: "D555"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b-floor(a/128)*65536)/10-273.14"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 10s
|
||||
- key: psa_adblue_range
|
||||
mode: "22"
|
||||
pid: "D513"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a*50"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:water
|
||||
update_interval: 600s
|
||||
- key: psa_adblue_volume
|
||||
mode: "22"
|
||||
pid: "D558"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a/10"
|
||||
unit: "L"
|
||||
device_class: volume_storage
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
icon: mdi:water
|
||||
update_interval: 600s
|
||||
- key: psa_adblue_temp
|
||||
mode: "22"
|
||||
pid: "D56D"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a-floor(a/128)*256"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 600s
|
||||
- key: psa_oil_temp
|
||||
mode: "22"
|
||||
pid: "D47D"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b-floor(a/128)*65536)/10-273.14"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:oil-temperature
|
||||
update_interval: 30s
|
||||
- key: psa_oil_pressure
|
||||
mode: "22"
|
||||
pid: "D429"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b)/1000"
|
||||
unit: "bar"
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
update_interval: 15s
|
||||
- key: psa_km_since_oil_change
|
||||
mode: "22"
|
||||
pid: "D43F"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a*256+b"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:oil
|
||||
update_interval: 3600s
|
||||
- key: psa_odometer
|
||||
mode: "22"
|
||||
pid: "D49C"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a*16777216+b*65536+c*256+d"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: total_increasing
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:counter
|
||||
update_interval: 300s
|
||||
- key: psa_fuel_rail_pressure
|
||||
mode: "22"
|
||||
pid: "D446"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b)/10"
|
||||
unit: "bar"
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 10s
|
||||
- key: psa_fuel_temp
|
||||
mode: "22"
|
||||
pid: "D42A"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b)/10-273.14"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 60s
|
||||
- key: psa_boost_air_temp
|
||||
mode: "22"
|
||||
pid: "D411"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b-floor(a/128)*65536)/10-273.14"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 30s
|
||||
- key: psa_engaged_gear
|
||||
mode: "22"
|
||||
pid: "D43D"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a"
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:car-shift-pattern
|
||||
update_interval: 5s
|
||||
- key: psa_water_in_diesel
|
||||
platform: binary_sensor
|
||||
mode: "22"
|
||||
pid: "D52C"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "signum(a)"
|
||||
icon: mdi:water-alert
|
||||
update_interval: 300s
|
||||
- key: psa_battery_voltage
|
||||
mode: "22"
|
||||
pid: "D78A"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*256+b)/128"
|
||||
unit: "V"
|
||||
device_class: voltage
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
update_interval: 30s
|
||||
- key: psa_battery_current
|
||||
mode: "22"
|
||||
pid: "D497"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "(a*16777216+b*65536+c*256+d-floor(a/128)*4294967296)/1024"
|
||||
unit: "A"
|
||||
device_class: current
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
update_interval: 30s
|
||||
# Raw BSI codes; meaning not documented in OBDb.
|
||||
- key: psa_battery_charge_state
|
||||
mode: "22"
|
||||
pid: "D742"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a"
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 600s
|
||||
- key: psa_battery_wear
|
||||
mode: "22"
|
||||
pid: "D741"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a"
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 3600s
|
||||
- key: psa_stop_start_restarts
|
||||
mode: "22"
|
||||
pid: "D71B"
|
||||
pre_commands: ["ATSH6A8", "ATCRA688"]
|
||||
formula: "a*16777216+b*65536+c*256+d"
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 3600s
|
||||
|
||||
# ── PSA fuel level candidates (engine ECU 7E0 → 7E8, OBDb) ──
|
||||
# OBDb lists three sources; keep whichever answers on this car and disable the rest.
|
||||
- key: psa_fuel_level_pct
|
||||
mode: "22"
|
||||
pid: "0227"
|
||||
pre_commands: ["ATSH7E0", "ATCRA"]
|
||||
formula: "a*100/255"
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:gas-station
|
||||
update_interval: 60s
|
||||
publish:
|
||||
deadband: 0.5
|
||||
min_interval: 60s
|
||||
- key: psa_fuel_level_l
|
||||
mode: "22"
|
||||
pid: "040F"
|
||||
pre_commands: ["ATSH7E0", "ATCRA"]
|
||||
formula: "(a*256+b-floor(a/128)*65536)*711/1250"
|
||||
unit: "L"
|
||||
device_class: volume_storage
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
icon: mdi:gas-station
|
||||
update_interval: 60s
|
||||
publish:
|
||||
deadband: 0.3
|
||||
min_interval: 60s
|
||||
- key: psa_fuel_level_21
|
||||
mode: "21"
|
||||
pid: "A8"
|
||||
pre_commands: ["ATSH7E0", "ATCRA"]
|
||||
formula: "(m*256+n)/256"
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:gas-station
|
||||
update_interval: 60s
|
||||
@@ -0,0 +1,680 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
HassBle YAML Configuration and Template Validator
|
||||
Validates config.yaml and templates.yaml against the HassBle Android schema and ConfigValidator rules.
|
||||
"""
|
||||
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from typing import Any, Dict, List, Optional, Set, Tuple
|
||||
import yaml
|
||||
|
||||
VALID_SOURCES = {"advertisement", "gatt_notify", "obd"}
|
||||
VALID_INSTANCE_MODES = {"mac", "shared"}
|
||||
VALID_SOURCE_FIELDS = {"service_data", "manufacturer_data", "raw"}
|
||||
VALID_PLATFORMS = {"sensor", "binary_sensor", "text_sensor", "event"}
|
||||
VALID_DATA_TYPES = {
|
||||
"int8", "uint8", "int16", "uint16", "int32", "uint32",
|
||||
"float32", "timestamp", "string"
|
||||
}
|
||||
VALID_ENDIANS = {"big", "little"}
|
||||
VALID_CONTROL_TYPES = {"switch", "number", "select", "button"}
|
||||
VALID_CONTROL_ACTIONS = {"advertise", "stop_advertise"}
|
||||
VALID_ADVERTISE_MODES = {"low_power", "balanced", "low_latency"}
|
||||
VALID_ADVERTISE_TX_POWERS = {"ultra_low", "low", "medium", "high"}
|
||||
VALID_ADVERTISE_COUNTER_MODES = {"reset", "persist"}
|
||||
VALID_STATE_CLASSES = {"measurement", "measurement_angle", "total", "total_increasing"}
|
||||
NUMERIC_DEVICE_CLASSES = {
|
||||
"battery", "carbon_dioxide", "carbon_monoxide", "current", "distance",
|
||||
"duration", "energy", "frequency", "gas", "humidity", "illuminance",
|
||||
"moisture", "monetary", "nitrogen_dioxide", "nitrogen_monoxide",
|
||||
"nitrous_oxide", "ozone", "pm1", "pm10", "pm25", "power", "power_factor",
|
||||
"precipitation", "precipitation_intensity", "pressure", "reactive_energy",
|
||||
"reactive_power", "signal_strength", "sound_pressure", "speed",
|
||||
"sulphur_dioxide", "temperature", "volatile_organic_compounds",
|
||||
"volatile_organic_compounds_parts", "voltage", "volume", "volume_flow_rate",
|
||||
"volume_storage", "water", "weight", "wind_speed",
|
||||
}
|
||||
|
||||
KNOWN_DEVICE_KEYS = {
|
||||
"id", "name", "source", "match", "instance_mode", "gatt", "obd",
|
||||
"advertise", "sensors", "controls", "publish"
|
||||
}
|
||||
KNOWN_MATCH_KEYS = {
|
||||
"mac", "service_data_uuid", "manufacturer_id", "manufacturer_hex_prefix",
|
||||
"manufacturer_min_length", "name_prefix"
|
||||
}
|
||||
KNOWN_GATT_KEYS = {
|
||||
"mac", "service_uuid", "notify_char_uuid", "write_char_uuid", "auto_connect"
|
||||
}
|
||||
KNOWN_OBD_KEYS = {
|
||||
"mac", "service_uuid", "tx_char_uuid", "rx_char_uuid", "tx_delay",
|
||||
"init_commands", "default_commands", "auto_connect"
|
||||
}
|
||||
KNOWN_ADVERTISE_KEYS = {
|
||||
"manufacturer_id", "payload", "counter_mode", "counter_start", "mode",
|
||||
"tx_power", "timeout", "repeat_interval", "payload_phases", "stop_on_response",
|
||||
"connectable", "scannable", "include_device_name", "local_name"
|
||||
}
|
||||
KNOWN_ADVERTISE_PHASE_KEYS = {
|
||||
"state", "duration", "payload"
|
||||
}
|
||||
KNOWN_SENSOR_KEYS = {
|
||||
"key", "name", "platform", "event_types", "device_class", "unit", "state_class", "icon",
|
||||
"entity_category", "accuracy_decimals", "source_field", "length",
|
||||
"min_length", "decode", "preset", "mode", "pid", "formula",
|
||||
"update_interval", "pre_commands", "publish"
|
||||
}
|
||||
KNOWN_DECODE_KEYS = {
|
||||
"offset", "length", "type", "endian", "bitmask", "scale",
|
||||
"offset_value", "map"
|
||||
}
|
||||
KNOWN_CONTROL_KEYS = {
|
||||
"key", "type", "name", "icon", "entity_category", "action", "command",
|
||||
"options", "min", "max", "step"
|
||||
}
|
||||
KNOWN_PUBLISH_KEYS = {
|
||||
"on_change_only", "min_interval", "heartbeat", "deadband"
|
||||
}
|
||||
|
||||
class ValidationResult:
|
||||
def __init__(self, filename: str):
|
||||
self.filename = filename
|
||||
self.errors: List[str] = []
|
||||
self.warnings: List[str] = []
|
||||
|
||||
def error(self, path: str, msg: str):
|
||||
self.errors.append(f"[{self.filename}] ERROR at '{path}': {msg}")
|
||||
|
||||
def warning(self, path: str, msg: str):
|
||||
self.warnings.append(f"[{self.filename}] WARNING at '{path}': {msg}")
|
||||
|
||||
@property
|
||||
def has_errors(self) -> bool:
|
||||
return len(self.errors) > 0
|
||||
|
||||
|
||||
def check_unknown_keys(data: Dict[str, Any], known_keys: Set[str], path: str, res: ValidationResult):
|
||||
if not isinstance(data, dict):
|
||||
return
|
||||
for k in data.keys():
|
||||
if k not in known_keys:
|
||||
res.error(f"{path}.{k}", f"Unknown property '{k}'. Allowed keys: {sorted(list(known_keys))}")
|
||||
|
||||
|
||||
def validate_publish(publish: Any, path: str, res: ValidationResult):
|
||||
if not isinstance(publish, dict):
|
||||
res.error(path, "publish must be an object (map)")
|
||||
return
|
||||
check_unknown_keys(publish, KNOWN_PUBLISH_KEYS, path, res)
|
||||
if "on_change_only" in publish and not isinstance(publish["on_change_only"], bool):
|
||||
res.error(f"{path}.on_change_only", "Must be a boolean (true/false)")
|
||||
for dur_field in ["min_interval", "heartbeat"]:
|
||||
if dur_field in publish:
|
||||
val = publish[dur_field]
|
||||
if not isinstance(val, str) or not re.match(r"^\d+(ms|s|m|h)$", str(val).strip()):
|
||||
res.error(f"{path}.{dur_field}", f"Invalid duration '{val}'. Example: 500ms, 10s, 5m")
|
||||
if "deadband" in publish and not isinstance(publish["deadband"], (int, float)):
|
||||
res.error(f"{path}.deadband", "deadband must be a number")
|
||||
|
||||
|
||||
def validate_decode(decode: Any, path: str, res: ValidationResult):
|
||||
if not isinstance(decode, dict):
|
||||
res.error(path, "decode must be an object")
|
||||
return
|
||||
check_unknown_keys(decode, KNOWN_DECODE_KEYS, path, res)
|
||||
|
||||
if "offset" in decode and not isinstance(decode["offset"], int):
|
||||
res.error(f"{path}.offset", "offset must be an integer")
|
||||
if "length" in decode and not isinstance(decode["length"], int):
|
||||
res.error(f"{path}.length", "length must be an integer")
|
||||
|
||||
dtype = str(decode.get("type", "uint8")).lower()
|
||||
if dtype not in VALID_DATA_TYPES:
|
||||
res.error(f"{path}.type", f"Invalid data type '{decode.get('type')}'. Must be one of {sorted(list(VALID_DATA_TYPES))}")
|
||||
|
||||
if "endian" in decode:
|
||||
endian = str(decode["endian"]).lower()
|
||||
if endian not in VALID_ENDIANS:
|
||||
res.error(f"{path}.endian", f"Invalid endian '{decode['endian']}'. Must be 'big' or 'little'")
|
||||
|
||||
if "scale" in decode and not isinstance(decode["scale"], (int, float)):
|
||||
res.error(f"{path}.scale", "scale must be a number")
|
||||
if "offset_value" in decode and not isinstance(decode["offset_value"], (int, float)):
|
||||
res.error(f"{path}.offset_value", "offset_value must be a number")
|
||||
if "map" in decode:
|
||||
if not isinstance(decode["map"], dict):
|
||||
res.error(f"{path}.map", "map must be a dictionary (key: value)")
|
||||
|
||||
|
||||
def validate_sensor(sensor: Any, device_source: str, path: str, res: ValidationResult,
|
||||
inherited_publish: Optional[Dict[str, Any]] = None):
|
||||
if not isinstance(sensor, dict):
|
||||
res.error(path, "Sensor must be an object")
|
||||
return
|
||||
check_unknown_keys(sensor, KNOWN_SENSOR_KEYS, path, res)
|
||||
|
||||
key = sensor.get("key")
|
||||
if not key or not isinstance(key, str):
|
||||
res.error(f"{path}.key", "Missing or invalid sensor 'key'")
|
||||
return
|
||||
|
||||
platform = sensor.get("platform", "sensor")
|
||||
if platform not in VALID_PLATFORMS:
|
||||
res.error(f"{path}.platform", f"Invalid platform '{platform}'. Must be one of {sorted(list(VALID_PLATFORMS))}")
|
||||
|
||||
is_text = platform == "text_sensor"
|
||||
is_event = platform == "event"
|
||||
unit = sensor.get("unit")
|
||||
state_class = sensor.get("state_class")
|
||||
if isinstance(state_class, str) and state_class.lower() == "none":
|
||||
state_class = None
|
||||
device_class = sensor.get("device_class")
|
||||
accuracy_decimals = sensor.get("accuracy_decimals")
|
||||
|
||||
if is_event:
|
||||
event_types = sensor.get("event_types")
|
||||
if not isinstance(event_types, list) or not event_types:
|
||||
res.error(f"{path}.event_types",
|
||||
"platform=event requires a non-empty 'event_types' list — HA rejects the declaration without it")
|
||||
event_types = []
|
||||
decode_map = (sensor.get("decode") or {}).get("map")
|
||||
if isinstance(decode_map, dict):
|
||||
undeclared = sorted({str(v) for v in decode_map.values()} - {str(t) for t in event_types})
|
||||
if undeclared:
|
||||
res.warning(f"{path}.event_types",
|
||||
f"decode.map value(s) {undeclared} missing from event_types — HA drops those events")
|
||||
elif sensor.get("decode") is not None:
|
||||
res.warning(f"{path}.decode",
|
||||
"platform=event without decode.map — the raw decoded value becomes the event_type and will be dropped")
|
||||
if unit is not None or state_class is not None or accuracy_decimals is not None:
|
||||
res.warning(f"{path}.unit", "unit/state_class/accuracy_decimals are ignored for event")
|
||||
if device_class in NUMERIC_DEVICE_CLASSES:
|
||||
res.warning(f"{path}.device_class",
|
||||
f"device_class='{device_class}' is numeric but platform is event — HA event supports doorbell/button/motion")
|
||||
publish = sensor.get("publish", inherited_publish) or {}
|
||||
heartbeat = publish.get("heartbeat") if isinstance(publish, dict) else None
|
||||
on_change_only = publish.get("on_change_only", True) if isinstance(publish, dict) else True
|
||||
if on_change_only and not (isinstance(heartbeat, str) and _DURATION_RE.match(heartbeat.strip())):
|
||||
res.warning(f"{path}.publish",
|
||||
"on_change_only suppresses repeats of the same event_type — "
|
||||
"set publish.heartbeat (or on_change_only: false) to fire on every occurrence")
|
||||
elif is_text:
|
||||
if unit is not None:
|
||||
res.warning(f"{path}.unit", f"unit='{unit}' is ignored for text_sensor")
|
||||
if state_class is not None:
|
||||
res.warning(f"{path}.state_class", f"state_class='{state_class}' is ignored for text_sensor")
|
||||
if accuracy_decimals is not None:
|
||||
res.warning(f"{path}.accuracy_decimals", "accuracy_decimals is ignored for text_sensor")
|
||||
if device_class in NUMERIC_DEVICE_CLASSES:
|
||||
res.warning(f"{path}.device_class", f"device_class='{device_class}' expects numeric value but platform is text_sensor")
|
||||
else:
|
||||
if state_class is not None and state_class not in VALID_STATE_CLASSES:
|
||||
res.error(f"{path}.state_class", f"Invalid state_class '{state_class}'. Must be one of {sorted(list(VALID_STATE_CLASSES))}")
|
||||
if unit is not None and state_class is None:
|
||||
res.warning(f"{path}.state_class", f"unit='{unit}' set but state_class is missing")
|
||||
if state_class is not None and unit is None:
|
||||
res.warning(f"{path}.unit", f"state_class='{state_class}' set but unit is missing")
|
||||
if device_class == "timestamp" and accuracy_decimals is not None:
|
||||
res.warning(f"{path}.accuracy_decimals", "accuracy_decimals is meaningless for timestamp")
|
||||
|
||||
if "source_field" in sensor:
|
||||
sf = str(sensor["source_field"]).lower()
|
||||
if sf not in VALID_SOURCE_FIELDS:
|
||||
res.error(f"{path}.source_field", f"Invalid source_field '{sensor['source_field']}'. Must be one of {sorted(list(VALID_SOURCE_FIELDS))}")
|
||||
|
||||
decode = sensor.get("decode")
|
||||
if decode:
|
||||
validate_decode(decode, f"{path}.decode", res)
|
||||
d_offset = decode.get("offset", 0)
|
||||
d_len = decode.get("length", 1)
|
||||
required = d_offset + d_len
|
||||
min_len = sensor.get("min_length")
|
||||
exact_len = sensor.get("length")
|
||||
if min_len is not None and required > min_len:
|
||||
res.error(f"{path}.decode", f"decode(offset={d_offset} + length={d_len}={required}) exceeds min_length={min_len}")
|
||||
if exact_len is not None and required > exact_len:
|
||||
res.error(f"{path}.decode", f"decode(offset={d_offset} + length={d_len}={required}) exceeds length={exact_len}")
|
||||
|
||||
if device_source == "obd":
|
||||
if sensor.get("pid") is None and sensor.get("preset") is None:
|
||||
res.error(f"{path}", "OBD sensor requires 'pid' or 'preset'")
|
||||
elif device_source in {"advertisement", "gatt_notify"}:
|
||||
if decode is None and platform != "binary_sensor":
|
||||
res.warning(f"{path}.decode", "No decode config — sensor will never produce a value")
|
||||
|
||||
if "publish" in sensor:
|
||||
validate_publish(sensor["publish"], f"{path}.publish", res)
|
||||
|
||||
|
||||
_PAYLOAD_TOKEN_RE = re.compile(r"\{(counter|state)(?::[^}]+)?\}")
|
||||
_DURATION_RE = re.compile(r"^\d+(ms|s|m|h)$")
|
||||
|
||||
|
||||
def _payload_has_state_token(payload: str) -> bool:
|
||||
return any(m.group(1) == "state" for m in _PAYLOAD_TOKEN_RE.finditer(payload))
|
||||
|
||||
|
||||
def validate_advertise_payload(payload: str) -> Optional[str]:
|
||||
def subst(m: re.Match) -> str:
|
||||
token = m.group(0)
|
||||
if ":02X" in token or ":02x" in token:
|
||||
return "00"
|
||||
return "0"
|
||||
|
||||
clean = _PAYLOAD_TOKEN_RE.sub(subst, payload)
|
||||
if not re.match(r"^[0-9A-Fa-f]*$", clean):
|
||||
return f"payload contains invalid hex characters: '{payload}'"
|
||||
if len(clean) % 2 != 0:
|
||||
return f"payload length ({len(clean)}) must be even"
|
||||
byte_len = len(clean) // 2
|
||||
if byte_len > 24:
|
||||
return f"payload size ({byte_len} bytes) exceeds 24 bytes legacy advertisement limit"
|
||||
return None
|
||||
|
||||
|
||||
def _payload_byte_len(payload: str) -> Optional[int]:
|
||||
def subst(m: re.Match) -> str:
|
||||
token = m.group(0)
|
||||
if ":02X" in token or ":02x" in token:
|
||||
return "00"
|
||||
return "0"
|
||||
|
||||
clean = _PAYLOAD_TOKEN_RE.sub(subst, payload)
|
||||
if not re.match(r"^[0-9A-Fa-f]*$", clean) or len(clean) % 2 != 0:
|
||||
return None
|
||||
return len(clean) // 2
|
||||
|
||||
|
||||
def _legacy_adv_size(payload_bytes: int, local_name: str) -> int:
|
||||
return 3 + 4 + payload_bytes + 2 + len(local_name.encode("utf-8"))
|
||||
|
||||
|
||||
def validate_advertise(adv: Any, device: dict, path: str, res: ValidationResult):
|
||||
if not isinstance(adv, dict):
|
||||
res.error(path, "advertise must be an object")
|
||||
return
|
||||
check_unknown_keys(adv, KNOWN_ADVERTISE_KEYS, path, res)
|
||||
|
||||
if device.get("source") != "advertisement":
|
||||
res.error(path, "'advertise' is only supported for source: advertisement")
|
||||
|
||||
if "manufacturer_id" not in adv:
|
||||
res.error(f"{path}.manufacturer_id", "Missing required 'manufacturer_id'")
|
||||
elif not isinstance(adv["manufacturer_id"], int):
|
||||
res.error(f"{path}.manufacturer_id", f"manufacturer_id must be a decimal integer (got '{adv['manufacturer_id']}')")
|
||||
|
||||
if "payload" not in adv:
|
||||
res.error(f"{path}.payload", "Missing required 'payload'")
|
||||
elif not isinstance(adv["payload"], str):
|
||||
res.error(f"{path}.payload", "payload must be a string")
|
||||
else:
|
||||
err = validate_advertise_payload(adv["payload"])
|
||||
if err:
|
||||
res.error(f"{path}.payload", err)
|
||||
|
||||
if "counter_mode" in adv:
|
||||
cm = str(adv["counter_mode"]).lower()
|
||||
if cm not in VALID_ADVERTISE_COUNTER_MODES:
|
||||
res.error(f"{path}.counter_mode", f"Invalid counter_mode '{adv['counter_mode']}'. Must be one of {sorted(list(VALID_ADVERTISE_COUNTER_MODES))}")
|
||||
|
||||
if "counter_start" in adv:
|
||||
cs = adv["counter_start"]
|
||||
if not isinstance(cs, int) or cs < 0 or cs > 255:
|
||||
res.error(f"{path}.counter_start", f"counter_start must be between 0 and 255 (got '{cs}')")
|
||||
|
||||
if "mode" in adv:
|
||||
m = str(adv["mode"]).lower()
|
||||
if m not in VALID_ADVERTISE_MODES:
|
||||
res.error(f"{path}.mode", f"Invalid mode '{adv['mode']}'. Must be one of {sorted(list(VALID_ADVERTISE_MODES))}")
|
||||
|
||||
if "tx_power" in adv:
|
||||
tp = str(adv["tx_power"]).lower()
|
||||
if tp not in VALID_ADVERTISE_TX_POWERS:
|
||||
res.error(f"{path}.tx_power", f"Invalid tx_power '{adv['tx_power']}'. Must be one of {sorted(list(VALID_ADVERTISE_TX_POWERS))}")
|
||||
|
||||
for dur_field in ["timeout", "repeat_interval"]:
|
||||
if dur_field in adv:
|
||||
val = adv[dur_field]
|
||||
if val is not None and (not isinstance(val, str) or not _DURATION_RE.match(str(val).strip())):
|
||||
res.error(f"{path}.{dur_field}", f"Invalid duration '{val}'. Example: 500ms, 15s, 1m")
|
||||
|
||||
phases = adv.get("payload_phases", [])
|
||||
if phases:
|
||||
if not isinstance(phases, list):
|
||||
res.error(f"{path}.payload_phases", "payload_phases must be a list")
|
||||
else:
|
||||
if adv.get("repeat_interval"):
|
||||
res.warning(f"{path}.repeat_interval", "repeat_interval is ignored when payload_phases is set — counter stays fixed across phases")
|
||||
for i, phase in enumerate(phases):
|
||||
ppath = f"{path}.payload_phases[{i}]"
|
||||
if not isinstance(phase, dict):
|
||||
res.error(ppath, "payload_phases item must be an object")
|
||||
continue
|
||||
check_unknown_keys(phase, KNOWN_ADVERTISE_PHASE_KEYS, ppath, res)
|
||||
duration = phase.get("duration")
|
||||
if not isinstance(duration, str) or not _DURATION_RE.match(duration.strip()):
|
||||
res.error(f"{ppath}.duration", f"Invalid duration '{duration}'. Example: 200ms, 3s")
|
||||
state = phase.get("state")
|
||||
if state is not None and (not isinstance(state, int) or state < 0 or state > 255):
|
||||
res.error(f"{ppath}.state", f"state must be between 0 and 255 (got '{state}')")
|
||||
template = phase["payload"] if isinstance(phase.get("payload"), str) and phase["payload"].strip() else adv.get("payload", "")
|
||||
if isinstance(template, str):
|
||||
if _payload_has_state_token(template) and state is None:
|
||||
res.error(f"{ppath}.state", "payload_phases item has a {state} token but no state value")
|
||||
err = validate_advertise_payload(template)
|
||||
if err:
|
||||
res.error(ppath, err)
|
||||
|
||||
payload = adv.get("payload")
|
||||
if isinstance(payload, str) and _payload_has_state_token(payload) and not phases:
|
||||
res.error(f"{path}.payload", "payload contains {state} but advertise.payload_phases is empty")
|
||||
|
||||
for bool_field in ["stop_on_response", "connectable", "scannable", "include_device_name"]:
|
||||
if bool_field in adv and not isinstance(adv[bool_field], bool):
|
||||
res.error(f"{path}.{bool_field}", f"{bool_field} must be a boolean (true/false)")
|
||||
|
||||
if adv.get("include_device_name") is True and not (isinstance(adv.get("local_name"), str) and adv["local_name"].strip()):
|
||||
res.warning(f"{path}.include_device_name", "include_device_name: true includes device name in advertising data, which may exceed the 31-byte legacy BLE limit")
|
||||
|
||||
local_name = adv.get("local_name")
|
||||
if local_name is not None:
|
||||
if not isinstance(local_name, str):
|
||||
res.error(f"{path}.local_name", "local_name must be a string")
|
||||
else:
|
||||
name = local_name.strip()
|
||||
if not name:
|
||||
res.warning(f"{path}.local_name", "local_name is empty after trim — ignored")
|
||||
else:
|
||||
name_bytes = len(name.encode("utf-8"))
|
||||
if name_bytes > 248:
|
||||
res.error(f"{path}.local_name", f"local_name UTF-8 size ({name_bytes} bytes) exceeds Bluetooth name limit (248)")
|
||||
templates = [adv.get("payload", "")]
|
||||
if isinstance(phases, list) and phases:
|
||||
templates = []
|
||||
for phase in phases:
|
||||
if not isinstance(phase, dict):
|
||||
continue
|
||||
override = phase.get("payload")
|
||||
if isinstance(override, str) and override.strip():
|
||||
templates.append(override)
|
||||
else:
|
||||
templates.append(adv.get("payload", ""))
|
||||
for i, template in enumerate(templates):
|
||||
if not isinstance(template, str):
|
||||
continue
|
||||
blen = _payload_byte_len(template)
|
||||
if blen is None:
|
||||
continue
|
||||
total = _legacy_adv_size(blen, name)
|
||||
if total > 31:
|
||||
loc = f"{path}.local_name" if not phases else f"{path}.payload_phases[{i}]"
|
||||
res.error(loc, f"local_name '{name}' plus payload would be {total} bytes, exceeding the 31-byte legacy BLE limit")
|
||||
res.warning(f"{path}.local_name", "local_name resets the phone Bluetooth name after advertising (and again on next app start if the process was killed)")
|
||||
|
||||
if device.get("instance_mode") == "mac" and not device.get("match", {}).get("mac"):
|
||||
res.warning(path, "advertise with instance_mode: mac creates one button per discovered MAC — use instance_mode: shared")
|
||||
|
||||
controls = device.get("controls", [])
|
||||
if isinstance(controls, list) and not any(isinstance(c, dict) and c.get("action") == "advertise" for c in controls):
|
||||
res.warning(path, "'advertise' block has no control with action: advertise — it can only be triggered from the app")
|
||||
|
||||
|
||||
def validate_control(control: Any, device_source: str, gatt: Optional[dict], obd: Optional[dict], path: str, res: ValidationResult):
|
||||
if not isinstance(control, dict):
|
||||
res.error(path, "Control must be an object")
|
||||
return
|
||||
check_unknown_keys(control, KNOWN_CONTROL_KEYS, path, res)
|
||||
|
||||
key = control.get("key")
|
||||
if not key or not isinstance(key, str):
|
||||
res.error(f"{path}.key", "Missing or invalid control 'key'")
|
||||
return
|
||||
|
||||
ctype_str = str(control.get("type", ""))
|
||||
if ctype_str not in VALID_CONTROL_TYPES:
|
||||
res.error(f"{path}.type", f"Invalid control type '{ctype_str}'. Must be one of {sorted(list(VALID_CONTROL_TYPES))}")
|
||||
return
|
||||
|
||||
action = control.get("action")
|
||||
if action is not None:
|
||||
if action not in VALID_CONTROL_ACTIONS:
|
||||
res.error(f"{path}.action", f"Invalid action '{action}'. Must be one of {sorted(list(VALID_CONTROL_ACTIONS))}")
|
||||
# When action is specified, command is optional
|
||||
if "command" not in control:
|
||||
return
|
||||
|
||||
if device_source == "gatt_notify":
|
||||
if not gatt or not gatt.get("write_char_uuid"):
|
||||
res.error(f"{path}", "Control requires write_char_uuid in gatt config")
|
||||
elif device_source == "obd":
|
||||
if not obd or not obd.get("tx_char_uuid"):
|
||||
res.error(f"{path}", "Control requires tx_char_uuid in obd config")
|
||||
|
||||
if "command" not in control:
|
||||
res.error(f"{path}", "Control requires 'command' or 'action'")
|
||||
return
|
||||
|
||||
cmd_raw = control.get("command", {})
|
||||
if not isinstance(cmd_raw, dict):
|
||||
res.error(f"{path}.command", "command must be a map of {state: hex_string}")
|
||||
return
|
||||
|
||||
# Normalize YAML boolean keys (e.g. on -> True, off -> False in YAML 1.1)
|
||||
cmd = {}
|
||||
for k, v in cmd_raw.items():
|
||||
if k is True:
|
||||
cmd["on"] = v
|
||||
elif k is False:
|
||||
cmd["off"] = v
|
||||
else:
|
||||
cmd[str(k)] = v
|
||||
|
||||
if ctype_str == "switch":
|
||||
for k in ["on", "off"]:
|
||||
if k not in cmd:
|
||||
res.error(f"{path}.command", f"Switch control missing command key '{k}'")
|
||||
elif ctype_str == "button":
|
||||
if "press" not in cmd:
|
||||
res.error(f"{path}.command", "Button control missing command key 'press'")
|
||||
elif ctype_str == "number":
|
||||
if "template" not in cmd:
|
||||
res.error(f"{path}.command", "Number control missing command key 'template'")
|
||||
elif ctype_str == "select":
|
||||
options = control.get("options", [])
|
||||
if not isinstance(options, list) or not options:
|
||||
res.error(f"{path}.options", "Select control requires a non-empty 'options' list")
|
||||
else:
|
||||
for opt in options:
|
||||
if opt not in cmd:
|
||||
res.error(f"{path}.command", f"Select control missing command key for option '{opt}'")
|
||||
|
||||
|
||||
def validate_device(device: Any, path: str, res: ValidationResult,
|
||||
defaults_publish: Optional[Dict[str, Any]] = None):
|
||||
if not isinstance(device, dict):
|
||||
res.error(path, "Device must be an object")
|
||||
return
|
||||
check_unknown_keys(device, KNOWN_DEVICE_KEYS, path, res)
|
||||
|
||||
dev_id = device.get("id")
|
||||
if not dev_id or not isinstance(dev_id, str):
|
||||
res.error(f"{path}.id", "Device missing required 'id'")
|
||||
dev_name = device.get("name")
|
||||
if not dev_name or not isinstance(dev_name, str):
|
||||
res.error(f"{path}.name", "Device missing required 'name'")
|
||||
|
||||
source = str(device.get("source", ""))
|
||||
if source not in VALID_SOURCES:
|
||||
res.error(f"{path}.source", f"Invalid source '{source}'. Must be one of {sorted(list(VALID_SOURCES))}")
|
||||
return
|
||||
|
||||
instance_mode = device.get("instance_mode", "mac")
|
||||
if instance_mode not in VALID_INSTANCE_MODES:
|
||||
res.error(f"{path}.instance_mode", f"Invalid instance_mode '{instance_mode}'. Must be one of {sorted(list(VALID_INSTANCE_MODES))}")
|
||||
|
||||
match = device.get("match")
|
||||
if match:
|
||||
if not isinstance(match, dict):
|
||||
res.error(f"{path}.match", "match must be an object")
|
||||
else:
|
||||
check_unknown_keys(match, KNOWN_MATCH_KEYS, f"{path}.match", res)
|
||||
if "manufacturer_id" in match:
|
||||
m_id = match["manufacturer_id"]
|
||||
if not isinstance(m_id, int):
|
||||
res.error(f"{path}.match.manufacturer_id", f"manufacturer_id must be a decimal integer (got '{m_id}')")
|
||||
|
||||
gatt = device.get("gatt")
|
||||
if gatt:
|
||||
if not isinstance(gatt, dict):
|
||||
res.error(f"{path}.gatt", "gatt must be an object")
|
||||
else:
|
||||
check_unknown_keys(gatt, KNOWN_GATT_KEYS, f"{path}.gatt", res)
|
||||
if source == "gatt_notify":
|
||||
if not gatt.get("service_uuid"):
|
||||
res.error(f"{path}.gatt.service_uuid", "Missing required 'service_uuid'")
|
||||
if not gatt.get("notify_char_uuid"):
|
||||
res.error(f"{path}.gatt.notify_char_uuid", "Missing required 'notify_char_uuid'")
|
||||
|
||||
obd = device.get("obd")
|
||||
if obd:
|
||||
if not isinstance(obd, dict):
|
||||
res.error(f"{path}.obd", "obd must be an object")
|
||||
else:
|
||||
check_unknown_keys(obd, KNOWN_OBD_KEYS, f"{path}.obd", res)
|
||||
|
||||
if "advertise" in device:
|
||||
validate_advertise(device["advertise"], device, f"{path}.advertise", res)
|
||||
|
||||
sensors = device.get("sensors", [])
|
||||
if not isinstance(sensors, list):
|
||||
res.error(f"{path}.sensors", "sensors must be a list")
|
||||
else:
|
||||
for idx, s in enumerate(sensors):
|
||||
validate_sensor(s, source, f"{path}.sensors[{idx}]", res,
|
||||
device.get("publish", defaults_publish))
|
||||
|
||||
controls = device.get("controls", [])
|
||||
if not isinstance(controls, list):
|
||||
res.error(f"{path}.controls", "controls must be a list")
|
||||
else:
|
||||
for idx, c in enumerate(controls):
|
||||
validate_control(c, source, gatt, obd, f"{path}.controls[{idx}]", res)
|
||||
|
||||
if "publish" in device:
|
||||
validate_publish(device["publish"], f"{path}.publish", res)
|
||||
|
||||
|
||||
def validate_config_file(filepath: str) -> ValidationResult:
|
||||
res = ValidationResult(os.path.basename(filepath))
|
||||
if not os.path.exists(filepath):
|
||||
res.error("", f"File '{filepath}' does not exist")
|
||||
return res
|
||||
|
||||
try:
|
||||
with open(filepath, "r", encoding="utf-8") as f:
|
||||
data = yaml.safe_load(f)
|
||||
except Exception as e:
|
||||
res.error("", f"YAML syntax error: {e}")
|
||||
return res
|
||||
|
||||
if not isinstance(data, dict):
|
||||
res.error("", "Root must be a YAML mapping")
|
||||
return res
|
||||
|
||||
version = data.get("version")
|
||||
if version != 1:
|
||||
res.warning("version", f"Schema version is {version}, expected 1")
|
||||
|
||||
defaults_publish: Optional[Dict[str, Any]] = None
|
||||
if "defaults" in data:
|
||||
defaults = data["defaults"]
|
||||
if not isinstance(defaults, dict):
|
||||
res.error("defaults", "defaults must be an object")
|
||||
elif "publish" in defaults:
|
||||
validate_publish(defaults["publish"], "defaults.publish", res)
|
||||
if isinstance(defaults["publish"], dict):
|
||||
defaults_publish = defaults["publish"]
|
||||
|
||||
devices = data.get("devices", [])
|
||||
if not isinstance(devices, list):
|
||||
res.error("devices", "devices must be a list")
|
||||
else:
|
||||
for idx, dev in enumerate(devices):
|
||||
validate_device(dev, f"devices[{idx}]", res, defaults_publish)
|
||||
|
||||
return res
|
||||
|
||||
|
||||
def validate_templates_file(filepath: str) -> ValidationResult:
|
||||
res = ValidationResult(os.path.basename(filepath))
|
||||
if not os.path.exists(filepath):
|
||||
res.error("", f"File '{filepath}' does not exist")
|
||||
return res
|
||||
|
||||
try:
|
||||
with open(filepath, "r", encoding="utf-8") as f:
|
||||
data = yaml.safe_load(f)
|
||||
except Exception as e:
|
||||
res.error("", f"YAML syntax error: {e}")
|
||||
return res
|
||||
|
||||
if not isinstance(data, dict):
|
||||
res.error("", "Root must be a YAML mapping")
|
||||
return res
|
||||
|
||||
templates = data.get("templates")
|
||||
if not isinstance(templates, list):
|
||||
res.error("templates", "templates must be a list")
|
||||
return res
|
||||
|
||||
for idx, t in enumerate(templates):
|
||||
path = f"templates[{idx}]"
|
||||
if not isinstance(t, dict):
|
||||
res.error(path, "Template item must be an object")
|
||||
continue
|
||||
for key in ["id", "name"]:
|
||||
if not t.get(key) or not isinstance(t[key], str):
|
||||
res.error(f"{path}.{key}", f"Missing or invalid template '{key}'")
|
||||
|
||||
device = t.get("device")
|
||||
if not device:
|
||||
res.error(f"{path}.device", "Missing 'device' configuration in template")
|
||||
else:
|
||||
validate_device(device, f"{path}.device", res)
|
||||
|
||||
return res
|
||||
|
||||
|
||||
def main():
|
||||
repo_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
config_file = os.path.join(repo_root, "config.yaml")
|
||||
templates_file = os.path.join(repo_root, "templates.yaml")
|
||||
|
||||
results = [
|
||||
validate_config_file(config_file),
|
||||
validate_templates_file(templates_file),
|
||||
]
|
||||
|
||||
total_errors = 0
|
||||
total_warnings = 0
|
||||
|
||||
for r in results:
|
||||
for w in r.warnings:
|
||||
print(f"⚠️ {w}")
|
||||
total_warnings += 1
|
||||
for e in r.errors:
|
||||
print(f"❌ {e}")
|
||||
total_errors += 1
|
||||
|
||||
if total_errors == 0:
|
||||
print(f"✅ All YAML configurations valid ({total_warnings} warnings, 0 errors).")
|
||||
sys.exit(0)
|
||||
else:
|
||||
print(f"\n💥 Validation failed with {total_errors} errors and {total_warnings} warnings.")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
+526
-388
@@ -2,391 +2,529 @@
|
||||
# Loaded from repo root as templates.yaml (same branch as config.yaml)
|
||||
|
||||
templates:
|
||||
- id: jaalee_jht
|
||||
name: "Jaalee JHT"
|
||||
description: "Temperature / humidity / battery (iBeacon, Apple manufacturer 76)"
|
||||
device:
|
||||
id: jaalee_jht
|
||||
name: "Jaalee JHT"
|
||||
source: advertisement
|
||||
instance_mode: mac
|
||||
match:
|
||||
manufacturer_id: 76
|
||||
manufacturer_min_length: 24
|
||||
manufacturer_hex_prefix: "0215"
|
||||
sensors:
|
||||
- key: temperature
|
||||
device_class: temperature
|
||||
unit: "°C"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
source_field: manufacturer_data
|
||||
decode: { offset: 18, length: 2, type: uint16, endian: big, scale: 0.002670288, offset_value: -45 }
|
||||
- key: humidity
|
||||
device_class: humidity
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
source_field: manufacturer_data
|
||||
decode: { offset: 20, length: 2, type: uint16, endian: big, scale: 0.001524504 }
|
||||
- key: battery
|
||||
device_class: battery
|
||||
unit: "%"
|
||||
state_class: measurement
|
||||
source_field: manufacturer_data
|
||||
decode: { offset: 23, length: 1, type: uint8 }
|
||||
|
||||
- id: parking_beacon
|
||||
name: "Parking Beacon"
|
||||
description: "Shared parking beacon (manufacturer 861 / 0x035D)"
|
||||
device:
|
||||
id: parking_beacon
|
||||
name: "Parking Beacon"
|
||||
source: advertisement
|
||||
instance_mode: shared
|
||||
match:
|
||||
manufacturer_id: 861
|
||||
sensors:
|
||||
- key: parking_time
|
||||
device_class: timestamp
|
||||
icon: mdi:clock-time-four-outline
|
||||
source_field: manufacturer_data
|
||||
length: 14
|
||||
decode: { offset: 7, length: 4, type: timestamp }
|
||||
- key: parking_floor
|
||||
icon: mdi:layers-outline
|
||||
source_field: manufacturer_data
|
||||
length: 14
|
||||
accuracy_decimals: 0
|
||||
decode: { offset: 11, length: 1, type: uint8, scale: -1, offset_value: 256 }
|
||||
- key: parking_location
|
||||
platform: text_sensor
|
||||
icon: mdi:map-marker-outline
|
||||
source_field: manufacturer_data
|
||||
length: 14
|
||||
decode: { offset: 12, length: 2, type: string }
|
||||
|
||||
- id: obd_standard
|
||||
name: "OBD-II (standard PIDs)"
|
||||
description: "RPM, speed, coolant, fuel — bind ELM327 adapter in app"
|
||||
device:
|
||||
id: obd_vehicle
|
||||
name: "OBD Vehicle"
|
||||
source: obd
|
||||
obd:
|
||||
service_uuid: "FFF0"
|
||||
tx_char_uuid: "FFF2"
|
||||
rx_char_uuid: "FFF1"
|
||||
tx_delay: 50ms
|
||||
init_commands: []
|
||||
sensors:
|
||||
- { key: rpm, preset: rpm, update_interval: 1s }
|
||||
- { key: speed, preset: speed, update_interval: 1s }
|
||||
- { key: coolant_temp, preset: coolant_temp, update_interval: 10s }
|
||||
- { key: fuel_level, preset: fuel_level, update_interval: 60s }
|
||||
|
||||
- id: obd_gm_extended
|
||||
name: "OBD-II + GM extensions"
|
||||
description: "Standard PIDs plus GM mode-22 sensors (ATSP6 init)"
|
||||
device:
|
||||
id: car_obd
|
||||
name: "Vehicle OBD"
|
||||
source: obd
|
||||
obd:
|
||||
service_uuid: "18F0"
|
||||
tx_char_uuid: "2AF1"
|
||||
rx_char_uuid: "2AF0"
|
||||
tx_delay: 50ms
|
||||
init_commands: ["ATSP6"]
|
||||
sensors:
|
||||
- { key: rpm, preset: rpm, update_interval: 1s }
|
||||
- { key: speed, preset: speed, update_interval: 1s }
|
||||
- { key: coolant_temp, preset: coolant_temp, update_interval: 10s }
|
||||
- key: fuel_level
|
||||
preset: fuel_level
|
||||
update_interval: 60s
|
||||
publish: { deadband: 0.5, min_interval: 60s }
|
||||
- { key: gear, preset: gm_current_gear, update_interval: 2s }
|
||||
- { key: prnd, preset: gm_prnd_status_alt, update_interval: 2s }
|
||||
- { key: oil_pressure, preset: gm_oil_pressure, update_interval: 5s }
|
||||
- { key: trans_temp, preset: gm_trans_temp, update_interval: 10s }
|
||||
|
||||
- id: obd_hyundai_kia
|
||||
name: "OBD-II + 현대/기아 계기판"
|
||||
description: "RPM, 속도, 총 주행거리, 연료잔량(L), 계기판 전압 — 계기판 7C6 / 22B002"
|
||||
device:
|
||||
id: car_obd_hk
|
||||
name: "Hyundai/Kia OBD"
|
||||
source: obd
|
||||
obd:
|
||||
service_uuid: "18F0"
|
||||
tx_char_uuid: "2AF1"
|
||||
rx_char_uuid: "2AF0"
|
||||
tx_delay: 50ms
|
||||
init_commands: ["ATSP6"]
|
||||
# default_commands 생략 — 아래 ATSH7C6 센서가 있으므로 앱이 ATSH7DF로 자동 복원
|
||||
sensors:
|
||||
- { key: rpm, preset: rpm, update_interval: 1s }
|
||||
- { key: speed, preset: speed, update_interval: 1s }
|
||||
# 계기판(CLU) UDS. 요청 7C6 → 응답 7CE. 한 응답에 주행거리·연료·전압이 함께 온다.
|
||||
# 응답: 62 B0 02 [a][b][c][d][e][f][g][h][i][j][k][l]…
|
||||
# (a = 62B002 에코 바로 다음 바이트)
|
||||
# e → 연료잔량 e*0.5 L
|
||||
# f → 계기판 전압 f/12.8 = f*0.078125 V
|
||||
# g:h:i → 총 주행거리 24bit km
|
||||
# j:k:l → 위와 같은 주행거리의 mile 값 (북미 사양 계기판)
|
||||
# 출처: OBDb(obdb.community)에서 현대·기아 11개 차종이 동일한 바이트 배치로 확인.
|
||||
# awesomeit Torque 플러그인(35개 차종)·Elantra CN7 PID 목록과도 일치.
|
||||
# 2013년식 이후에서 널리 동작하며, 미지원 차는 NO DATA를 반환한다.
|
||||
#
|
||||
# 예외: 엑센트(RB)는 계기판이 이 DID를 열지 않는다. 2013/2015/2019 실차 캡처에서
|
||||
# unsupported로 확인됐고 (2018년식만 예외), 요청하면 7F 22 22를 돌려준다.
|
||||
# 엑센트는 아래 obd_hyundai_accent_rb_diesel 템플릿을 쓸 것.
|
||||
- key: odometer
|
||||
mode: "22"
|
||||
pid: "B002"
|
||||
pre_commands: ["ATSH7C6"]
|
||||
formula: "g*65536+h*256+i"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: total_increasing
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:counter
|
||||
update_interval: 60s
|
||||
- key: fuel_level
|
||||
mode: "22"
|
||||
pid: "B002"
|
||||
pre_commands: ["ATSH7C6"]
|
||||
formula: "e*0.5"
|
||||
unit: "L"
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
icon: mdi:gas-station
|
||||
update_interval: 60s
|
||||
publish: { deadband: 0.5, min_interval: 60s }
|
||||
- key: cluster_voltage
|
||||
mode: "22"
|
||||
pid: "B002"
|
||||
pre_commands: ["ATSH7C6"]
|
||||
formula: "f*0.078125"
|
||||
unit: "V"
|
||||
device_class: voltage
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
entity_category: diagnostic
|
||||
update_interval: 120s
|
||||
|
||||
- id: obd_hyundai_accent_rb_diesel
|
||||
name: "OBD-II 엑센트(RB) 디젤"
|
||||
description: "RPM, 속도, 연료 %, 흡기온도, 대기압 + 총주행거리 프로브 — 엑센트 RB 1.6 TCI-U2"
|
||||
device:
|
||||
id: car_obd_accent
|
||||
name: "Accent RB Diesel"
|
||||
source: obd
|
||||
obd:
|
||||
service_uuid: "18F0"
|
||||
tx_char_uuid: "2AF1"
|
||||
rx_char_uuid: "2AF0"
|
||||
tx_delay: 50ms
|
||||
init_commands: ["ATSP6"]
|
||||
# 아래 ATSH7E0 센서가 있으므로 표준 센서 앞에 ATSH7DF가 자동 삽입된다
|
||||
sensors:
|
||||
- { key: rpm, preset: rpm, update_interval: 1s }
|
||||
- { key: speed, preset: speed, update_interval: 1s }
|
||||
# 연료량은 이 차에서 읽을 방법이 없다. 표준 01 2F는 실차에서 NO DATA를
|
||||
# 돌려주고(OBDb 캡처는 북미 가솔린 기준이라 디젤에는 맞지 않았다),
|
||||
# 계기판 22B002도 7F 22 22로 거부한다.
|
||||
# awesomeit 엑센트RB 2013 D 1.6 TCI-U2 프로필에서 확인된 값들
|
||||
- key: intake_temp
|
||||
mode: "21"
|
||||
pid: "01"
|
||||
pre_commands: ["ATSH7E0"]
|
||||
formula: "k*0.980392-50"
|
||||
unit: "°C"
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
update_interval: 20s
|
||||
- key: barometric_pressure
|
||||
mode: "21"
|
||||
pid: "01"
|
||||
pre_commands: ["ATSH7E0"]
|
||||
formula: "j*1.372549"
|
||||
unit: "kPa"
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
update_interval: 60s
|
||||
# ── 총주행거리 (엔진 ECU의 DPF 블록에 같이 실려 온다) ──────────────
|
||||
# 엑센트 RB는 계기판(7C6 / 22B002)이 주행거리를 직접 내주지 않는다 —
|
||||
# 요청하면 7F 22 22. 그래서 대안으로 엔진 ECU의 21 03 블록을 쓴다
|
||||
# (OBDb 메이커 공용 HYUNDAI_ODO_V2):
|
||||
# byte 49~52 마지막 DPF 재생 시점의 주행거리 /1000 km
|
||||
# byte 53~56 재생 이후 달린 거리 /1000 km
|
||||
# byte 57~60 총주행거리 /1000 km ← 목표
|
||||
# 셋은 서로 다른 필드다. awesomeit이 "DPF 주행거리"로 부르는 건 byte 53(재생 후 거리).
|
||||
#
|
||||
# 응답이 byte 57까지 도착하지 않으면 decode가 null을 돌려주고 아무것도
|
||||
# 발행되지 않는다 — 미지원 차에서 엉뚱한 값이 올라오지 않는다.
|
||||
#
|
||||
# 보정: 2026-07-30 실측에서 이 ECU 카운터가 계기판(195958 km)보다
|
||||
# 0.7331% 높게(197394.5 km) 나왔다. 처음엔 상수(offset_value)로 보정했으나
|
||||
# 신차(카운터=0)에서 dash=-1436.5km 가 나오는 게 되어 성립할 수 없다.
|
||||
# 배율(scale) 보정은 원점을 지나므로(카운터=0 → dash=0) 물리적으로 맞다 —
|
||||
# 이 카운터는 계기판과 별개 환산계수로 바퀴속도 펄스를 거리로 누적하는
|
||||
# 서비스용 값이라, 오차가 주행거리에 비례해 벌어지는 게 정상이다.
|
||||
# 세 필드가 odometer = at_regen + since_regen 항등식을 만족하려면
|
||||
# 셋 다 같은 배율을 써야 한다 (상수 보정과 달리 since_regen도 예외 없음).
|
||||
#
|
||||
# 측정이 한 점뿐이라 배율만 가정했고 절편은 0으로 뒀다. 100km 이상
|
||||
# 주행 후 재확인해 두 점으로 완전한 affine 식(scale·offset_value 둘 다)을
|
||||
# 풀 것 — 아래 odometer_flow_control 이 계기판 값을 직접 준다면 이 보정
|
||||
# 자체가 필요 없어지므로 그쪽을 먼저 확인한다.
|
||||
# 오도미터는 분 단위로 갱신될 필요가 없고, 63바이트 멀티프레임이라 짧은
|
||||
# PID보다 무겁다 — 주기를 늘리는 게 배터리에 가장 크게 도움되는 지점이다.
|
||||
- key: odometer
|
||||
mode: "21"
|
||||
pid: "03"
|
||||
pre_commands: ["ATSH7E0"]
|
||||
decode: { offset: 57, length: 4, type: uint32, endian: big, scale: 0.000992723 }
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: total_increasing
|
||||
accuracy_decimals: 1
|
||||
icon: mdi:counter
|
||||
update_interval: 300s
|
||||
# 검산용: 재생시점 주행거리 + 재생후 거리 = 총주행거리.
|
||||
# 셋 다 같은 카운터를 공유하므로 같은 배율을 적용해야 항등식이 유지된다.
|
||||
- key: odometer_at_last_dpf_regen
|
||||
mode: "21"
|
||||
pid: "03"
|
||||
pre_commands: ["ATSH7E0"]
|
||||
decode: { offset: 49, length: 4, type: uint32, endian: big, scale: 0.000992723 }
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: total_increasing
|
||||
accuracy_decimals: 1
|
||||
entity_category: diagnostic
|
||||
update_interval: 300s
|
||||
- key: distance_since_dpf_regen
|
||||
mode: "21"
|
||||
pid: "03"
|
||||
pre_commands: ["ATSH7E0"]
|
||||
decode: { offset: 53, length: 4, type: uint32, endian: big, scale: 0.000992723 }
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
entity_category: diagnostic
|
||||
update_interval: 300s
|
||||
|
||||
# ── 계기판 오도미터 재시도: 확장 진단 세션 ─────────────────────────
|
||||
# 위 odometer 는 어디까지나 대체 경로(추정 보정)다. 진짜 계기판 값을
|
||||
# 직접 받을 가능성이 아직 남아 있다 — 7F 22 22 의 NRC 22(conditionsNotCorrect)는
|
||||
# UDS 표준상 "그 DID는 존재하는데 지금 조건에서 거부"라는 뜻이다.
|
||||
# DID 자체가 없다는 NRC 11(serviceNotSupported)·31(requestOutOfRange)이 아니었다.
|
||||
#
|
||||
# meatpiHQ/wican-fw#478 에서 같은 헤더(7C6)·같은 PID(22B002)로 실제 성공한
|
||||
# 사례 둘을 확인했다: 아이오닉 28kWh(WiCAN, pid_init "ATSH7C6;ATFCSH7C6")와
|
||||
# 아이오닉5(canair, 세션 명령 없이 바로 조회). 둘 다 확장 세션(10 03) 없이
|
||||
# 됐고, 공통점은 흐름제어(ATFCSH) 설정뿐이었다. 그래서 세션 대신 흐름제어를
|
||||
# 먼저 시도한다 — 실제 성공 사례에 더 가깝다.
|
||||
#
|
||||
# 오도미터 위치도 세대별로 다르다: 아이오닉5·OBDb ICE 11개 차종은 byte
|
||||
# 6~8(g,h,i)인데, 구형 아이오닉 28kWh는 byte 9~11(j,k,l)이었다
|
||||
# (WiCAN이 ISO-TP PCI 바이트를 페이로드에 섞어 넣는 별도 버그가 있어,
|
||||
# 그 이슈에서 공개한 보정표로 실제 위치를 역산한 값). 응답은 왔는데
|
||||
# 195958과 안 맞으면 formula 를 "j*65536+k*256+l" 로 바꿔서 재시도할 것.
|
||||
#
|
||||
# pre_commands 자체의 응답(흐름제어 설정 OK/에러)은 로그에 안 남지만
|
||||
# (해당 응답을 기다리는 센서가 없어 기록 경로를 안 탄다), 뒤따르는
|
||||
# 22B002 응답은 그대로 남는다.
|
||||
# raw=62B002… → 성공. 계기판 값이 보정 없이 직접 나온다
|
||||
# negative response 그대로 → 흐름제어도 소용없음. 세션(10 03)으로 한 번 더
|
||||
# 시도해볼 수는 있으나, 위 두 성공 사례 모두 세션 없이 됐다는 점에서
|
||||
# 이 차는 DID 자체가 없을 가능성이 이전보다 높아졌다.
|
||||
- key: odometer_flow_control
|
||||
mode: "22"
|
||||
pid: "B002"
|
||||
pre_commands: ["ATSH7C6", "ATFCSH7C6", "ATFCSD300000", "ATFCSM1"]
|
||||
formula: "g*65536+h*256+i"
|
||||
unit: "km"
|
||||
device_class: distance
|
||||
state_class: total_increasing
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 300s
|
||||
|
||||
# 계기판(22B002)·표준(01A6)·변속기(21A0) 오프셋 0~15 스캔은 195958km와
|
||||
# 일치하는 값을 찾지 못해 제거했다. 계기판은 애초에 22B002 자체를
|
||||
# 7F 22 22로 거부하므로 다른 DID를 더 뒤져볼 이유가 약하고, 표준 01A6은
|
||||
# mode 01 지원 목록에 없어 예상대로였다. 위 offset_value 보정을 계속 쓴다.
|
||||
|
||||
# ── 변속기(TCU) 21 A0 @ 7E1 — 응답이 4바이트뿐이다 ────────────────
|
||||
# 실측: 요청 116건, 응답 115건이 전부 61A0FFFF0000.
|
||||
# 에코(61 A0)를 뺀 데이터는 FF FF 00 00 — 4바이트가 전부다.
|
||||
#
|
||||
# 잘린 멀티프레임이 아니라 완결된 응답이다. 응답 지연 중앙값이 92ms 로,
|
||||
# 단일프레임 010C(79ms)·멀티프레임 2101(41바이트, 76ms)과 같은 수준이다.
|
||||
# First Frame 만 오고 CF 가 끊긴 것이라면 ELM327 이 CF 를 기다리다
|
||||
# 내부 타임아웃을 먹어야 하므로 지연이 훨씬 커진다. 그런 흔적이 없다.
|
||||
# 흐름제어(ATFCSH) 문제도 아니다 — 같은 세션에서 7E0 멀티프레임은 정상이다.
|
||||
#
|
||||
# 따라서 awesomeit 프로필의 byte 13(미션오일온도)·20(기어위치)·21(기어단수)은
|
||||
# 이 응답으로는 절대 닿지 않는다. 프로필이 다른 사양 기준이거나,
|
||||
# 이 TCU 가 특정 조건에서만 전체 블록을 준다는 뜻이다.
|
||||
#
|
||||
# 아래는 실제로 오는 4바이트를 그대로 노출하는 프로브다.
|
||||
# 주차(P)·엔진공회전 상태에서만 로그를 떴으므로, 주행 중이나 기어를 바꿀 때
|
||||
# 값이 달라지는지 봐야 한다. 값이 움직이면 그 바이트가 기어 정보이고,
|
||||
# FF FF 00 00 이 계속 고정이면 이 차 TCU 는 이 블록을 안 채우는 것이다.
|
||||
- key: tcu_byte0
|
||||
mode: "21"
|
||||
pid: "A0"
|
||||
pre_commands: ["ATSH7E1"]
|
||||
decode: { offset: 0, length: 1, type: uint8 }
|
||||
entity_category: diagnostic
|
||||
update_interval: 2s
|
||||
- key: tcu_byte1
|
||||
mode: "21"
|
||||
pid: "A0"
|
||||
pre_commands: ["ATSH7E1"]
|
||||
decode: { offset: 1, length: 1, type: uint8 }
|
||||
entity_category: diagnostic
|
||||
update_interval: 2s
|
||||
- key: tcu_byte2
|
||||
mode: "21"
|
||||
pid: "A0"
|
||||
pre_commands: ["ATSH7E1"]
|
||||
decode: { offset: 2, length: 1, type: uint8 }
|
||||
entity_category: diagnostic
|
||||
update_interval: 2s
|
||||
- key: tcu_byte3
|
||||
mode: "21"
|
||||
pid: "A0"
|
||||
pre_commands: ["ATSH7E1"]
|
||||
decode: { offset: 3, length: 1, type: uint8 }
|
||||
entity_category: diagnostic
|
||||
update_interval: 2s
|
||||
|
||||
- id: gatt_meter_relay
|
||||
name: "GATT power meter + relay"
|
||||
description: "Notify characteristic + switch control example"
|
||||
device:
|
||||
id: custom_meter
|
||||
name: "Custom BLE Meter"
|
||||
source: gatt_notify
|
||||
gatt:
|
||||
service_uuid: "ffe0"
|
||||
notify_char_uuid: "ffe1"
|
||||
write_char_uuid: "ffe2"
|
||||
sensors:
|
||||
- key: power
|
||||
unit: "W"
|
||||
device_class: power
|
||||
state_class: measurement
|
||||
decode: { offset: 0, length: 2, type: uint16, endian: little }
|
||||
controls:
|
||||
- key: relay
|
||||
type: switch
|
||||
command: { on: "A10100", off: "A10000" }
|
||||
- id: toyota_proace_city
|
||||
name: Toyota Proace City (Vgate iCar Pro BLE)
|
||||
description: Standard OBD-II, DPF and PSA engine ECU data for the Proace City 1.5 BlueHDi — bind the adapter in the app
|
||||
device:
|
||||
id: proace_city_obd
|
||||
name: Toyota Proace City
|
||||
source: obd
|
||||
obd:
|
||||
service_uuid: 18F0
|
||||
tx_char_uuid: 2AF1
|
||||
rx_char_uuid: 2AF0
|
||||
tx_delay: 50ms
|
||||
init_commands:
|
||||
- ATSP6
|
||||
default_commands:
|
||||
- ATSH7DF
|
||||
- ATCRA
|
||||
sensors:
|
||||
- key: rpm
|
||||
preset: rpm
|
||||
update_interval: 2s
|
||||
- key: speed
|
||||
preset: speed
|
||||
update_interval: 2s
|
||||
- key: engine_load
|
||||
preset: engine_load
|
||||
update_interval: 5s
|
||||
- key: coolant_temp
|
||||
preset: coolant_temp
|
||||
update_interval: 30s
|
||||
- key: intake_temp
|
||||
preset: intake_air_temp
|
||||
update_interval: 30s
|
||||
- key: ambient_temp
|
||||
preset: ambient_temp
|
||||
update_interval: 60s
|
||||
- key: battery
|
||||
preset: battery_voltage
|
||||
update_interval: 10s
|
||||
- key: run_time
|
||||
preset: run_time
|
||||
update_interval: 10s
|
||||
- key: fuel_level
|
||||
preset: fuel_level
|
||||
update_interval: 30s
|
||||
publish:
|
||||
deadband: 0.5
|
||||
min_interval: 60s
|
||||
- key: odometer
|
||||
preset: odometer
|
||||
update_interval: 60s
|
||||
- key: intake_map
|
||||
mode: '01'
|
||||
pid: 0B
|
||||
formula: a
|
||||
unit: kPa
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 5s
|
||||
- key: barometric_pressure
|
||||
mode: '01'
|
||||
pid: '33'
|
||||
formula: a
|
||||
unit: kPa
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 120s
|
||||
- key: fuel_rail_pressure
|
||||
mode: '01'
|
||||
pid: '23'
|
||||
formula: (a*256+b)*10
|
||||
unit: kPa
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 5s
|
||||
- key: distance_since_dtc_clear
|
||||
mode: '01'
|
||||
pid: '31'
|
||||
formula: a*256+b
|
||||
unit: km
|
||||
device_class: distance
|
||||
state_class: total_increasing
|
||||
accuracy_decimals: 0
|
||||
update_interval: 300s
|
||||
- key: distance_with_mil_on
|
||||
mode: '01'
|
||||
pid: '21'
|
||||
formula: a*256+b
|
||||
unit: km
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:engine-off
|
||||
update_interval: 300s
|
||||
- key: dpf_inlet_temp
|
||||
mode: '01'
|
||||
pid: 7C
|
||||
formula: (b*256+c)/10-40
|
||||
unit: °C
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:thermometer-chevron-up
|
||||
update_interval: 10s
|
||||
- key: dpf_outlet_temp
|
||||
mode: '01'
|
||||
pid: 7C
|
||||
formula: (d*256+e)/10-40
|
||||
unit: °C
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:thermometer-chevron-down
|
||||
update_interval: 10s
|
||||
- key: dpf_differential_pressure
|
||||
mode: '01'
|
||||
pid: 7A
|
||||
formula: (b*256+c-floor(b/128)*65536)/100
|
||||
unit: kPa
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
update_interval: 10s
|
||||
- key: dpf_regen_trigger
|
||||
mode: '01'
|
||||
pid: 8B
|
||||
formula: c*100/255
|
||||
unit: '%'
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:air-filter
|
||||
update_interval: 30s
|
||||
- key: dpf_regen_required
|
||||
platform: binary_sensor
|
||||
mode: '01'
|
||||
pid: 8B
|
||||
formula: floor(c/255)
|
||||
icon: mdi:air-filter
|
||||
update_interval: 30s
|
||||
- key: dpf_regen_active
|
||||
platform: binary_sensor
|
||||
mode: '01'
|
||||
pid: 8B
|
||||
formula: b%2
|
||||
icon: mdi:fire
|
||||
update_interval: 10s
|
||||
- key: dpf_avg_distance_between_regens
|
||||
mode: '01'
|
||||
pid: 8B
|
||||
formula: f*256+g
|
||||
unit: km
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 300s
|
||||
- key: egt_bank1_sensor1
|
||||
mode: '01'
|
||||
pid: '78'
|
||||
formula: (b*256+c)/10-40
|
||||
unit: °C
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 10s
|
||||
- key: egt_bank1_sensor2
|
||||
mode: '01'
|
||||
pid: '78'
|
||||
formula: (d*256+e)/10-40
|
||||
unit: °C
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 10s
|
||||
- key: psa_dpf_soot_level
|
||||
mode: '22'
|
||||
pid: D52F
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b)/10.24
|
||||
unit: '%'
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:air-filter
|
||||
update_interval: 60s
|
||||
- key: psa_dpf_soot_load
|
||||
mode: '22'
|
||||
pid: D54B
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b)/1024
|
||||
unit: g/L
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
icon: mdi:air-filter
|
||||
update_interval: 60s
|
||||
- key: psa_dpf_regen_status
|
||||
mode: '22'
|
||||
pid: D521
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:fire
|
||||
update_interval: 15s
|
||||
- key: psa_dpf_distance_since_regen
|
||||
mode: '22'
|
||||
pid: D519
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b)/16
|
||||
unit: km
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 120s
|
||||
- key: psa_dpf_avg_regen_interval
|
||||
mode: '22'
|
||||
pid: D525
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b)/16
|
||||
unit: km
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 600s
|
||||
- key: psa_dpf_remaining_life
|
||||
mode: '22'
|
||||
pid: D530
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b-floor(a/128)*65536)*16
|
||||
unit: km
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 3600s
|
||||
- key: psa_dpf_diff_pressure_deviation
|
||||
mode: '22'
|
||||
pid: D518
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a*256+b-floor(a/128)*65536
|
||||
unit: mbar
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 15s
|
||||
- key: psa_egt_before_catalyst
|
||||
mode: '22'
|
||||
pid: D52E
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b-floor(a/128)*65536)/10-273.14
|
||||
unit: °C
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 10s
|
||||
- key: psa_egt_after_catalyst
|
||||
mode: '22'
|
||||
pid: D555
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b-floor(a/128)*65536)/10-273.14
|
||||
unit: °C
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 10s
|
||||
- key: psa_adblue_range
|
||||
mode: '22'
|
||||
pid: D513
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a*50
|
||||
unit: km
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:water
|
||||
update_interval: 600s
|
||||
- key: psa_adblue_volume
|
||||
mode: '22'
|
||||
pid: D558
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a/10
|
||||
unit: L
|
||||
device_class: volume_storage
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
icon: mdi:water
|
||||
update_interval: 600s
|
||||
- key: psa_adblue_temp
|
||||
mode: '22'
|
||||
pid: D56D
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a-floor(a/128)*256
|
||||
unit: °C
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 600s
|
||||
- key: psa_oil_temp
|
||||
mode: '22'
|
||||
pid: D47D
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b-floor(a/128)*65536)/10-273.14
|
||||
unit: °C
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:oil-temperature
|
||||
update_interval: 30s
|
||||
- key: psa_oil_pressure
|
||||
mode: '22'
|
||||
pid: D429
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b)/1000
|
||||
unit: bar
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
update_interval: 15s
|
||||
- key: psa_km_since_oil_change
|
||||
mode: '22'
|
||||
pid: D43F
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a*256+b
|
||||
unit: km
|
||||
device_class: distance
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:oil
|
||||
update_interval: 3600s
|
||||
- key: psa_odometer
|
||||
mode: '22'
|
||||
pid: D49C
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a*16777216+b*65536+c*256+d
|
||||
unit: km
|
||||
device_class: distance
|
||||
state_class: total_increasing
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:counter
|
||||
update_interval: 300s
|
||||
- key: psa_fuel_rail_pressure
|
||||
mode: '22'
|
||||
pid: D446
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b)/10
|
||||
unit: bar
|
||||
device_class: pressure
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 10s
|
||||
- key: psa_fuel_temp
|
||||
mode: '22'
|
||||
pid: D42A
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b)/10-273.14
|
||||
unit: °C
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 60s
|
||||
- key: psa_boost_air_temp
|
||||
mode: '22'
|
||||
pid: D411
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b-floor(a/128)*65536)/10-273.14
|
||||
unit: °C
|
||||
device_class: temperature
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
update_interval: 30s
|
||||
- key: psa_engaged_gear
|
||||
mode: '22'
|
||||
pid: D43D
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:car-shift-pattern
|
||||
update_interval: 5s
|
||||
- key: psa_water_in_diesel
|
||||
platform: binary_sensor
|
||||
mode: '22'
|
||||
pid: D52C
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: signum(a)
|
||||
icon: mdi:water-alert
|
||||
update_interval: 300s
|
||||
- key: psa_battery_voltage
|
||||
mode: '22'
|
||||
pid: D78A
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*256+b)/128
|
||||
unit: V
|
||||
device_class: voltage
|
||||
state_class: measurement
|
||||
accuracy_decimals: 2
|
||||
update_interval: 30s
|
||||
- key: psa_battery_current
|
||||
mode: '22'
|
||||
pid: D497
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: (a*16777216+b*65536+c*256+d-floor(a/128)*4294967296)/1024
|
||||
unit: A
|
||||
device_class: current
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
update_interval: 30s
|
||||
- key: psa_battery_charge_state
|
||||
mode: '22'
|
||||
pid: D742
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 600s
|
||||
- key: psa_battery_wear
|
||||
mode: '22'
|
||||
pid: D741
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 3600s
|
||||
- key: psa_stop_start_restarts
|
||||
mode: '22'
|
||||
pid: D71B
|
||||
pre_commands:
|
||||
- ATSH6A8
|
||||
- ATCRA688
|
||||
formula: a*16777216+b*65536+c*256+d
|
||||
accuracy_decimals: 0
|
||||
entity_category: diagnostic
|
||||
update_interval: 3600s
|
||||
- key: psa_fuel_level_pct
|
||||
mode: '22'
|
||||
pid: '0227'
|
||||
pre_commands:
|
||||
- ATSH7E0
|
||||
- ATCRA
|
||||
formula: a*100/255
|
||||
unit: '%'
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:gas-station
|
||||
update_interval: 60s
|
||||
publish:
|
||||
deadband: 0.5
|
||||
min_interval: 60s
|
||||
- key: psa_fuel_level_l
|
||||
mode: '22'
|
||||
pid: 040F
|
||||
pre_commands:
|
||||
- ATSH7E0
|
||||
- ATCRA
|
||||
formula: (a*256+b-floor(a/128)*65536)*711/1250
|
||||
unit: L
|
||||
device_class: volume_storage
|
||||
state_class: measurement
|
||||
accuracy_decimals: 1
|
||||
icon: mdi:gas-station
|
||||
update_interval: 60s
|
||||
publish:
|
||||
deadband: 0.3
|
||||
min_interval: 60s
|
||||
- key: psa_fuel_level_21
|
||||
mode: '21'
|
||||
pid: A8
|
||||
pre_commands:
|
||||
- ATSH7E0
|
||||
- ATCRA
|
||||
formula: (m*256+n)/256
|
||||
unit: '%'
|
||||
state_class: measurement
|
||||
accuracy_decimals: 0
|
||||
icon: mdi:gas-station
|
||||
update_interval: 60s
|
||||
Reference in new issue
Block a user