From 2dfb54ee0d1950c6a4b2632244a6f5c0307e49fc Mon Sep 17 00:00:00 2001 From: eigger Date: Wed, 24 Jun 2026 22:00:12 +0900 Subject: [PATCH 1/6] Change min_length to length in config.yaml --- config.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/config.yaml b/config.yaml index ce696a7..f3fb0ee 100644 --- a/config.yaml +++ b/config.yaml @@ -62,19 +62,19 @@ devices: device_class: timestamp icon: mdi:clock-time-four-outline source_field: manufacturer_data - min_length: 14 + length: 14 decode: { offset: 7, length: 4, type: timestamp } - key: parking_floor icon: mdi:layers-outline source_field: manufacturer_data - min_length: 14 + 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 - min_length: 14 + length: 14 decode: { offset: 12, length: 2, type: string } # ────────────────────────────────────────────────────────────── From e38b2cc9547b2a3af4e00fb5aea69ccfe9771c30 Mon Sep 17 00:00:00 2001 From: eigger Date: Thu, 25 Jun 2026 12:12:51 +0900 Subject: [PATCH 2/6] Add templates.yaml for HassBle import template feature Include Jaalee JHT, parking beacon, OBD, and GATT starter templates. Update README for fixed config.yaml + templates.yaml layout. Co-authored-by: Cursor --- README.md | 20 ++++++-- config.yaml | 9 ++-- templates.yaml | 133 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 155 insertions(+), 7 deletions(-) create mode 100644 templates.yaml diff --git a/README.md b/README.md index 286256c..27ec6f6 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,23 @@ --- +## Repository files + +| File | Purpose | +|------|---------| +| `config.yaml` | Active gateway configuration (devices the app runs) | +| `templates.yaml` | Device templates for **Import template** in the Sensors tab | + +The app loads both from the repo root on the selected branch (`owner/repo` + branch — file names are fixed). + ## How It Works -The HassBle app downloads your `config.yaml` from a Git raw URL, 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. +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. + +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) @@ -51,8 +65,8 @@ Android Phone (BLE Scan) ## Quick Start 1. Fork or copy this repository to your GitHub account. -2. Edit `config.yaml` to describe your BLE devices. -3. In the HassBle app → **Sensors tab** → enter `your-username/hassble-config` → press **Browse** → select `config.yaml`. +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. diff --git a/config.yaml b/config.yaml index f3fb0ee..d78cadb 100644 --- a/config.yaml +++ b/config.yaml @@ -1,9 +1,10 @@ # HassBle Configuration File -# -# Host this config.yaml file in a Git repository (e.g., GitHub) and enter the RAW URL in the HassBle Android app. -# The app will download this configuration, decode BLE advertisements/sensors, and declare/update them in Home Assistant. # -# Do NOT put any Home Assistant credentials (URL/Token) in this file. Enter them directly in the app. +# 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. +# +# Do NOT put any Home Assistant credentials (URL/Token) in this file. Enter them in the app. version: 1 diff --git a/templates.yaml b/templates.yaml new file mode 100644 index 0000000..7342a05 --- /dev/null +++ b/templates.yaml @@ -0,0 +1,133 @@ +# Device templates for HassBle app → Sensors tab → Import template +# 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 + source_field: manufacturer_data + min_length: 14 + decode: { offset: 7, length: 4, type: timestamp } + - key: parking_battery + device_class: battery + unit: "%" + state_class: measurement + source_field: manufacturer_data + min_length: 14 + decode: { offset: 11, length: 1, type: uint8, scale: -1, offset_value: 256 } + - key: parking_location + platform: text_sensor + source_field: manufacturer_data + min_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: ["ATZ", "ATE0", "ATL0", "ATS0", "ATH0", "ATSP0"] + 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 } + + - 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: ["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: 0.5, min_interval: 60s } + - { key: gear, preset: gm_current_gear, update_interval: 1s } + - { key: prnd, preset: gm_prnd_status_alt, update_interval: 1s } + - { key: oil_pressure, preset: gm_oil_pressure, update_interval: 2s } + - { key: trans_temp, preset: gm_trans_temp, update_interval: 10s } + + - 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" } From b9f8396347419b28c6c21cef82296ea23dd447b5 Mon Sep 17 00:00:00 2001 From: eigger Date: Thu, 25 Jun 2026 12:14:16 +0900 Subject: [PATCH 3/6] docs: update Korean README for templates.yaml and fixed repo layout Co-authored-by: Cursor --- README.ko.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/README.ko.md b/README.ko.md index 8e55b71..511f708 100644 --- a/README.ko.md +++ b/README.ko.md @@ -29,9 +29,23 @@ --- +## 저장소 파일 + +| 파일 | 용도 | +|------|------| +| `config.yaml` | 게이트웨이 운영 설정 (실제로 동작하는 기기 목록) | +| `templates.yaml` | 센서 탭 **템플릿 가져오기**용 기기 템플릿 | + +앱은 선택한 브랜치의 리포 루트에서 두 파일을 고정 이름으로 불러옵니다 (`owner/repo` + 브랜치). + ## 동작 원리 -HassBle 앱은 Git raw URL에서 `config.yaml`을 다운로드하고, 정의한 규칙에 따라 BLE 데이터를 디코딩한 뒤, [ws_bridge](https://github.com/eigger/hass-ws-bridge) 통합을 통해 Home Assistant에 자동으로 센서를 등록합니다. 코드 수정 없이 YAML만 편집하면 됩니다. +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 스캔) @@ -51,8 +65,8 @@ Android Phone (BLE 스캔) ## 빠른 시작 1. 이 저장소를 자신의 GitHub 계정으로 Fork 또는 복사합니다. -2. `config.yaml`을 편집하여 BLE 기기를 정의합니다. -3. HassBle 앱 → **Sensors 탭** → `your-username/hassble-config` 입력 → **Browse** 버튼 → `config.yaml` 선택합니다. +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에 나타납니다. From 0fe6f0078294eee58eb1bf8f3352963a247d9973 Mon Sep 17 00:00:00 2001 From: eigger Date: Thu, 25 Jun 2026 12:22:19 +0900 Subject: [PATCH 4/6] fix: align parking_beacon template with config.yaml (parking_floor) Co-authored-by: Cursor --- templates.yaml | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/templates.yaml b/templates.yaml index 7342a05..de8383d 100644 --- a/templates.yaml +++ b/templates.yaml @@ -49,20 +49,21 @@ templates: sensors: - key: parking_time device_class: timestamp + icon: mdi:clock-time-four-outline source_field: manufacturer_data - min_length: 14 + length: 14 decode: { offset: 7, length: 4, type: timestamp } - - key: parking_battery - device_class: battery - unit: "%" - state_class: measurement + - key: parking_floor + icon: mdi:layers-outline source_field: manufacturer_data - min_length: 14 + 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 - min_length: 14 + length: 14 decode: { offset: 12, length: 2, type: string } - id: obd_standard From 94ddb8fddab92df316828871e1f686441591b780 Mon Sep 17 00:00:00 2001 From: eigger Date: Fri, 26 Jun 2026 09:00:48 +0900 Subject: [PATCH 5/6] Simplify OBD init command lists Remove redundant OBD initialization commands (ATZ, ATE0, ATL0, ATS0, ATH0) from configs. config.yaml now only uses ATSP6 for the device, and templates.yaml clears init_commands for one template and sets only ATSP6 for the other. This reduces unnecessary reset/echo/linefeed commands and relies on explicit protocol selection. --- config.yaml | 5 ----- templates.yaml | 4 ++-- 2 files changed, 2 insertions(+), 7 deletions(-) diff --git a/config.yaml b/config.yaml index d78cadb..d892c04 100644 --- a/config.yaml +++ b/config.yaml @@ -90,11 +90,6 @@ devices: rx_char_uuid: "2AF0" tx_delay: 50ms init_commands: - - "ATZ" - - "ATE0" - - "ATL0" - - "ATS0" - - "ATH0" - "ATSP6" sensors: #- { key: rpm, preset: rpm, update_interval: 1s } diff --git a/templates.yaml b/templates.yaml index de8383d..4a455cd 100644 --- a/templates.yaml +++ b/templates.yaml @@ -78,7 +78,7 @@ templates: tx_char_uuid: "FFF2" rx_char_uuid: "FFF1" tx_delay: 50ms - init_commands: ["ATZ", "ATE0", "ATL0", "ATS0", "ATH0", "ATSP0"] + init_commands: [] sensors: - { key: rpm, preset: rpm, update_interval: 1s } - { key: speed, preset: speed, update_interval: 1s } @@ -97,7 +97,7 @@ templates: tx_char_uuid: "2AF1" rx_char_uuid: "2AF0" tx_delay: 50ms - init_commands: ["ATZ", "ATE0", "ATL0", "ATS0", "ATH0", "ATSP6"] + init_commands: ["ATSP6"] sensors: - { key: rpm, preset: rpm, update_interval: 1s } - { key: speed, preset: speed, update_interval: 1s } From e787fab0b5b67a41924a01fe201cc72f66779350 Mon Sep 17 00:00:00 2001 From: eigger Date: Fri, 26 Jun 2026 09:12:59 +0900 Subject: [PATCH 6/6] docs: Add contribution guidelines and templates for English and Korean --- .../ISSUE_TEMPLATE/car_pid_contribution_en.md | 39 ++++++++ .../ISSUE_TEMPLATE/car_pid_contribution_ko.md | 39 ++++++++ .github/PULL_REQUEST_TEMPLATE.md | 25 +++++ .../pull_request_template_en.md | 25 +++++ .../pull_request_template_ko.md | 25 +++++ CONTRIBUTING.ko.md | 89 ++++++++++++++++++ CONTRIBUTING.md | 91 +++++++++++++++++++ README.ko.md | 9 +- README.md | 9 +- 9 files changed, 349 insertions(+), 2 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/car_pid_contribution_en.md create mode 100644 .github/ISSUE_TEMPLATE/car_pid_contribution_ko.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request_template_en.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request_template_ko.md create mode 100644 CONTRIBUTING.ko.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/car_pid_contribution_en.md b/.github/ISSUE_TEMPLATE/car_pid_contribution_en.md new file mode 100644 index 0000000..ff28247 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/car_pid_contribution_en.md @@ -0,0 +1,39 @@ +--- +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: diff --git a/.github/ISSUE_TEMPLATE/car_pid_contribution_ko.md b/.github/ISSUE_TEMPLATE/car_pid_contribution_ko.md new file mode 100644 index 0000000..c015b64 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/car_pid_contribution_ko.md @@ -0,0 +1,39 @@ +--- +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 앱을 통해 실제 차량에서 값이 정상적으로 읽히는 것을 확인했습니다. +* 추가 설명 및 작동 스크린샷: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..10a48e2 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,25 @@ +## 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 +``` diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template_en.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template_en.md new file mode 100644 index 0000000..10a48e2 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template_en.md @@ -0,0 +1,25 @@ +## 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 +``` diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template_ko.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template_ko.md new file mode 100644 index 0000000..b480c26 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template_ko.md @@ -0,0 +1,25 @@ +## 변경 사항 설명 (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 +# 여기에 추가된 템플릿 블록을 붙여넣어 주세요. +``` diff --git a/CONTRIBUTING.ko.md b/CONTRIBUTING.ko.md new file mode 100644 index 0000000..3cdc243 --- /dev/null +++ b/CONTRIBUTING.ko.md @@ -0,0 +1,89 @@ +# 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에 질문을 올려주세요. 커뮤니티가 기꺼이 변환 작성을 도와드립니다! + +소중한 기여를 통해 모두가 더 편하게 차량 상태를 통합할 수 있도록 도와주셔서 감사합니다! 🚗💨 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a7b641a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,91 @@ +# 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! 🚗💨 diff --git a/README.ko.md b/README.ko.md index 511f708..28663ee 100644 --- a/README.ko.md +++ b/README.ko.md @@ -2,7 +2,7 @@ > 이 저장소는 [HassBle](https://github.com/eigger/hassble-android) Android 앱의 기기 설정 파일(`config.yaml`)을 저장합니다. -**[English Documentation → README.md](README.md)** +**[English Documentation → README.md](README.md) | [기여 가이드 → CONTRIBUTING.ko.md](CONTRIBUTING.ko.md)** --- @@ -26,6 +26,7 @@ 12. [OBD 프리셋 목록](#obd-프리셋-목록) 13. [전체 예제](#전체-예제) 14. [주의사항](#주의사항) +15. [기여하기](#기여하기) --- @@ -717,6 +718,12 @@ update_interval: 1s --- +## 기여하기 + +본인 차량의 OBD-II PID 설정을 공유해 주시면 다른 사용자들에게 큰 도움이 됩니다! 자세한 공유 및 기여 방법은 [기여 가이드(CONTRIBUTING.ko.md)](CONTRIBUTING.ko.md)를 참고해 주세요. + +--- + ## 라이선스 MIT diff --git a/README.md b/README.md index 27ec6f6..6384ffc 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > This repository stores the device configuration (`config.yaml`) for the [HassBle](https://github.com/eigger/hassble-android) Android app. -**[한국어 문서 → README.ko.md](README.ko.md)** +**[한국어 문서 → README.ko.md](README.ko.md) | [Contributing Guide → CONTRIBUTING.md](CONTRIBUTING.md)** --- @@ -26,6 +26,7 @@ 12. [OBD Preset List](#obd-preset-list) 13. [Full Examples](#full-examples) 14. [Tips & Gotchas](#tips--gotchas) +15. [Contributing](#contributing) --- @@ -712,6 +713,12 @@ The app caches the last successfully loaded config. If the network is unavailabl --- +## 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