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