Archived
docs: Add contribution guidelines and templates for English and Korean
This commit is contained in:
1 parent
94ddb8fdda
commit
e787fab0b5
9 files changed
+349
-2
No files matched your search
@@ -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:
|
||||
@@ -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 앱을 통해 실제 차량에서 값이 정상적으로 읽히는 것을 확인했습니다.
|
||||
* 추가 설명 및 작동 스크린샷:
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
# 여기에 추가된 템플릿 블록을 붙여넣어 주세요.
|
||||
```
|
||||
@@ -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에 질문을 올려주세요. 커뮤니티가 기꺼이 변환 작성을 도와드립니다!
|
||||
|
||||
소중한 기여를 통해 모두가 더 편하게 차량 상태를 통합할 수 있도록 도와주셔서 감사합니다! 🚗💨
|
||||
@@ -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! 🚗💨
|
||||
+8
-1
@@ -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
|
||||
@@ -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
|
||||
Reference in new issue
Block a user