This repository has been archived on 2026-11-06. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
hassble-config/README.ko.md
T
eigger b4fc6f799f feat(advertise): add BLE advertising TX schema, templates, and validation
- Update scripts/validate.py with advertise block and control action validation
- Update templates.yaml with mytown_parking_beacon advertising TX template
- Add commented parking beacon TX/RX example to config.yaml
- Document advertise schema, counter_mode, counter_start, and control actions in README.md / README.ko.md
2026-08-28 21:55:05 +09:00

32 KiB
Raw Blame History

HassBle Config

이 저장소는 HassBle Android 앱의 기기 설정 파일(config.yaml)을 저장합니다.

English Documentation → README.md | 기여 가이드 → CONTRIBUTING.ko.md


목차

  1. 동작 원리
  2. 빠른 시작
  3. 루트 구조
  4. defaults — 발행 규칙
  5. 기기 타입
  6. source: advertisement — BLE 수동 스캔
  7. source: gatt_notify — GATT 연결
  8. source: obd — ELM327 OBD 폴링
  9. sensors — 센서 설정
  10. controls — HA 제어
  11. publish — 센서별 발행 필터
  12. OBD 프리셋 목록
  13. 전체 예제
  14. 주의사항
  15. 기여하기

저장소 파일

파일 용도
config.yaml 게이트웨이 운영 설정 (실제로 동작하는 기기 목록)
templates.yaml 센서 탭 템플릿 가져오기용 기기 템플릿

앱은 선택한 브랜치의 리포 루트에서 두 파일을 고정 이름으로 불러옵니다 (owner/repo + 브랜치).

동작 원리

HassBle 앱은 이 저장소에서 config.yaml과 templates.yaml을 다운로드하고, 정의한 규칙에 따라 BLE 데이터를 디코딩한 뒤, 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 / 토큰)을 이 파일에 절대 저장하지 마세요.
앱 설정에서만 입력하세요.


루트 구조

version: 1

defaults:
  publish:
    on_change_only: true
    min_interval: 10s

devices:
  - id: ...
필드 타입 기본값 설명
version int 1 스키마 버전. 항상 1.
defaults.publish object 아래 참조 모든 센서에 적용되는 기본 발행 필터.
devices list [] 기기 설정 목록.

defaults — 발행 규칙

센서 값을 HA에 얼마나 자주, 어떤 조건에서 전송할지를 제어합니다. 기기별 또는 센서별로 덮어쓸 수 있습니다.

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 응답을 파싱합니다.

모든 기기 타입에 공통인 필드:

- 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 / advertisement(action 전용)
필드 타입 필수 설명
id string ✅ 고유 식별자. HA 엔티티 unique_id에 사용됩니다. 소문자, 숫자, _ 사용.
name string ✅ HA 기기에 표시되는 이름.
source enum ✅ 데이터 소스 타입 (위 참조).
publish object ❌ 기기 수준의 발행 규칙 덮어쓰기.
sensors list ❌ 센서 정의 목록.
controls list ❌ 제어 정의 목록.

source: advertisement — BLE 수동 스캔

연결 없이 BLE 광고 패킷을 수신합니다. match를 사용하여 패킷을 필터링합니다.

- 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 엔티티를 공유합니다. 마지막으로 수신된 패킷이 상태를 덮어씁니다. 주차 비콘, 클리커 등에 유용합니다.

advertise — BLE 광고 송신 (TX)

지하주차장 위치 요청 비콘처럼 앱에서 스마트폰의 BLE 광고를 송신하여 주변 비콘을 깨우고 응답을 유도하는 기능입니다.

- id: mytown_parking
  name: "마이타운 주차위치"
  source: advertisement
  instance_mode: shared
  match:
    manufacturer_id: 861             # 0x035D — kaml 파싱을 위해 10진수(decimal) 사용 권장
    manufacturer_hex_prefix: "06"    # 06 응답 포맷 매칭
    manufacturer_min_length: 18
  advertise:
    manufacturer_id: 861
    payload: "05CB34447B91F8C69BBE41157C70BB631C40{counter:02X}"
    counter_mode: reset              # reset(기본) | persist
    counter_start: 0                 # reset 모드 시작값, persist 모드 초기 시드값 (0~255)
    mode: balanced                   # low_power (~1s) | balanced (~250ms) | low_latency (~100ms)
    tx_power: high                   # ultra_low | low | medium | high
    timeout: 15s                     # 이 시간 지나면 자동 송신 중단
    repeat_interval: 1s              # (선택) 이 주기로 payload 갱신 = counter 증가
    stop_on_response: true           # match 조건에 부합하는 광고 수신 시 즉시 송신 중단
    connectable: false
    scannable: true
  controls:
    - key: request_location
      type: button
      name: "주차위치 요청"
      action: advertise              # command 대신 앱 내부 광고 송신 동작 실행
      icon: mdi:car-search
필드 필수 기본값 설명
manufacturer_id ✅ BLE Company Identifier (10진수). 예: 861 (=0x035D).
payload ✅ Manufacturer Data payload hex (Company ID 제외). {counter}(10진수) 또는 {counter:02X}(2자리 hex) 토큰 사용 가능. 레거시 광고 24바이트 제한.
counter_mode reset 카운터 모드: reset (누를 때마다 counter_start부터 시작, 버스트 내에서만 증가) | persist (앱 재시작 후에도 이전 값에서 이어짐).
counter_start 0 카운터 시작값 (0~255). reset 모드 시 매 요청 시작값, persist 모드 시 최초 영속 전 초기 시드값.
mode balanced 광고 주기: low_power (~1s) | balanced (~250ms) | low_latency (~100ms).
tx_power high 송신 출력: ultra_low | low | medium | high.
timeout 15s 광고 송신 최대 지속 시간 (지나면 자동 중단).
repeat_interval null 지정 시 해당 주기마다 counter를 증가시키며 payload 갱신 (생략 시 1회 세팅 후 대기).
stop_on_response true 이 기기의 match 조건을 만족하는 응답 패킷 수신 시 즉시 광고 송신 중단.
connectable false BLE 연결 가능 여부.
scannable true Scannable 광고 여부.
include_device_name false 기기 이름 포함 여부 (31바이트 예산 절약을 위해 기본 false 권장).

알림: advertise 블록이 설정된 기기는 HA에 {id}_advertising 진단 바이너리 센서(binary_sensor)가 자동으로 생성되어 현재 광고 송신 진행 여부(on/off)를 보고합니다.


source: gatt_notify — GATT 연결

특정 BLE 기기에 연결하여 GATT 캐릭터리스틱을 구독하고 알림을 수신합니다. 선택적으로 hex 명령을 역방향으로 전송할 수 있습니다.

- 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를 직접 정의할 수 있습니다.

- 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 수식. at가 응답의 019번째 바이트. 예: "(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 절과 같습니다.

# 현대 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를 생략하면 되고, 복원 헤더를 직접 지정해야 할 때만 씁니다:

obd:
  init_commands: ["ATSP6"]
  default_commands: ["ATSH7E0"]   # 브로드캐스트(7DF) 대신 엔진 ECU 직접 지정

sensors — 센서 설정

sensors 목록의 각 항목은 하나의 HA 엔티티를 정의합니다.

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

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로 디코딩. length: 0 지정 시 잔여 바이트 전체를 가변 길이로 읽고 공백/null을 자동 트림합니다. platform: text_sensor와 함께 사용.

controls — HA 제어

HA에서 제어 시 BLE 쓰기 명령을 전송하는 HA 엔티티를 정의합니다. gatt_notify와 obd 소스에서만 사용 가능합니다.

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에 따라 키가 다릅니다 (위 예제 참조). action이 없을 때 필수.
action enum ❌* 앱 내부 동작 트리거 (advertise | stop_advertise). action 사용 시 command 생략 가능.
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)에 유용합니다.

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 온도·습도)

# 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 — 커스텀 서비스 데이터 센서

# 서비스 데이터에 센서 값이 포함된 커스텀 기기
- 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 센서 + 스위치 제어

# 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 프리셋 + 커스텀 발행 규칙

# 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 — 값 매핑 (상태 코드)

# 상태 코드를 문자열로 매핑하는 예제
- 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진수로 변환하세요:

# ❌ 잘못된 방법 — 파싱 오류 가능
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)을 지원합니다.

tx_delay: 50ms
min_interval: 10s
heartbeat: 5m
update_interval: 1s

설정은 캐시됨

앱은 마지막으로 성공적으로 불러온 설정을 캐시합니다. 시작 시 네트워크가 없으면 캐시를 사용합니다. 이 경우 앱 상단에 "캐시된 설정 사용 중"이 표시됩니다.


기여하기

본인 차량의 OBD-II PID 설정을 공유해 주시면 다른 사용자들에게 큰 도움이 됩니다! 자세한 공유 및 기여 방법은 기여 가이드(CONTRIBUTING.ko.md)를 참고해 주세요.


라이선스

MIT