NT$220으로 자가발전 스위치를 Home Assistant에 연결하기

# ─────────────────────────────────────────────────────────────────────────
# rf-bridge —— ESP32-C3 SuperMini + CC1101 433MHz 송수신 게이트웨이
#
# 목적: 거실/방의 "자가발전 무선 스위치"를 HA에 넣을 수 없는 문제를 해결한다.
#   • RM4 Pro는 이런 스위치를 못 받는다(RF는 특정 프로토콜만 인식하고, 시간 해상도도 부족하다)
#   • CC1101은 임의의 OOK 원시 파형을 엿들을 수 있다 → 스위치 코드를 녹화 → 같은 보드로 수신기에 송신
#
# 사용법은 두 단계:
#   1단계(녹화): dump: raw로 두고 벽 스위치를 눌러, 로그에 찍히는 원시 타이밍을 본다.
#               이때 이 장치를 스위치 옆으로 가져가서(보조배터리 전원) 확실히 수신되게 한다.
#   2단계(조명 제어): 녹화한 코드를 아래 script의 transmit_raw에 채우고, 두 방 모두 닿는 위치에 상주시킨다.
#
# 핀은 ESP32-C3 SuperMini의 실크스크린 기준:
#   SPI는 보드에 원래 표시된 SCK(IO4) / MISO(IO5) / MOSI(IO6) / SS(IO7)
#   GDO 두 개는 보드에서 "부팅이나 시스템 역할이 전혀 없는" 자유 핀 IO3과 IO10
#   (나머지 자유 핀 IO0 / IO1은 예비로 남겨 둠)
# IO2 / IO8 / IO9 세 개의 strapping 핀과 IO20 / IO21 두 개의 UART 핀은 피한다.
# 참고: IO4~IO7은 데이터시트상 JTAG(MTMS/MTDI/MTCK/MTDO)로 표시돼 있지만, C3는 USB-JTAG가 내장돼 있어서
#     외부 JTAG를 쓰지 않는다면 SPI로 쓰는 게 정상적인 사용법이고, 보드 제조사가 표시한 용도도 그것이다.
# ─────────────────────────────────────────────────────────────────────────

substitutions:
  name: rf-bridge
  friendly_name: "RF Bridge (CC1101)"

esphome:
  name: ${name}
  friendly_name: ${friendly_name}
  min_version: 2024.6.0
  on_boot:
    # 안전장치: CC1101이 부팅하자마자 수신 모드로 들어가도록 명시한다.
    # 공식 예제는 "송신 완료 후"에만 begin_rx를 하고 부팅 시 초기 상태는 언급하지 않아서,
    # 녹화 단계에서 아무것도 안 잡히면 신호가 없는 건지 수신을 안 하는 건지 구분하기 어렵다.
    priority: -100
    then:
      - cc1101.begin_rx: transceiver
      # 기억해 둔 조명 상태를 HA에 "표시"만 한다. publish만 하고 동작은 실행하지 않으므로 RF 신호는 전혀 보내지 않는다
      - lambda: |-
          id(room_light).publish_state(id(room_light_saved));
          id(mom_light).publish_state(id(mom_light_saved));

esp32:
  board: esp32-c3-devkitm-1     # C3 SuperMini는 이 board 설정이면 된다
  framework:
    type: esp-idf

logger:
  # 평소엔 INFO. 새 리모컨을 다시 녹화할 때는 DEBUG로 되돌리고, 아래 remote_receiver의
  # dump: raw를 켜야 원시 µs 타이밍이 보인다.
  level: INFO
  # ⚠️ ESP32-C3의 logger는 기본적으로 UART0(물리 핀 GPIO20/21)으로 출력하는데,
  #    그 두 핀엔 아무것도 연결돼 있지 않다 → USB로 로그를 읽으면 텅 비어 있다(처음 구웠을 때 밟았다).
  #    칩 내장 USB Serial/JTAG로 명시해야 부팅 메시지가 보인다.
  hardware_uart: USB_SERIAL_JTAG

api:
  # HA용 "표시만 바꾸고 송신은 안 하는" 명령: HA가 조도 센서로 상태 불일치를 발견했을 때 호출한다.
  # publish_state는 on_state를 트리거하므로 플래시에 저장된 상태도 함께 갱신된다.
  actions:
    - action: set_room_light_state
      variables:
        state: bool
      then:
        - lambda: id(room_light).publish_state(state);
    - action: set_mom_light_state
      variables:
        state: bool
      then:
        - lambda: id(mom_light).publish_state(state);
  encryption:
    key: !secret rf_bridge_api_key

ota:
  - platform: esphome
    password: !secret rf_bridge_ota_password

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  # ⚠️ 절전은 반드시 꺼야 한다. ESP32-C3의 WiFi light sleep은 두 가지 문제를 일으킨다(둘 다 실제로 겪음):
  #   1. LAN ping 지연이 67~147ms로 치솟고 심하게 흔들린다 —— 즉각 반응해야 하는 RF 브리지로선 용납 불가
  #   2. USB Serial/JTAG도 같이 죽어서 시리얼 포트가 텅 비고, 한때 칩이 멈춘 줄 알았다
  power_save_mode: NONE
  # ⚠️ 서버 / PC의 USB 3.0 포트에 오래 꽂아 두지 말 것: 거기 2.4GHz 노이즈 때문에 하루 17번 끊겼고,
  #    휴대폰 충전기로 옮긴 뒤 2일간 0번.
  #    output_power: 8.5dB도 시도해 봤지만 → 전원을 껐다 켜도 아예 연결이 안 돼서 기본값보다 나빴다. 삭제함.
  # 끊길 때마다 한 번씩 기록해 두면, 다시 연결된 뒤 HA에서 이번 부팅 동안 몇 번 끊겼는지 볼 수 있다
  on_disconnect:
    - lambda: id(wifi_drops) += 1;
  # 수신이 불안정할 때 쓰는 예비 핫스팟(최초 설정용)
  ap:
    ssid: "rf-bridge-setup"
    password: !secret rf_bridge_ap_password

globals:
  - id: wifi_drops
    type: int
    restore_value: no
    initial_value: '0'
  # 두 조명의 마지막 상태. 플래시에 저장해 두고 재부팅 후 HA 표시를 복원하는 데 쓴다
  - id: room_light_saved
    type: bool
    restore_value: yes
    initial_value: 'false'
  - id: mom_light_saved
    type: bool
    restore_value: yes
    initial_value: 'false'
  # 마지막 송신 시각 기록. on_raw의 쿨다운 판단용
  - id: last_tx_ms
    type: uint32_t
    initial_value: '0'

captive_portal:

# 내장 웹 UI —— HA에 연결하기 전에 버튼을 바로 테스트하는 용도.
# 나중에 빼려면 이 부분을 지우면 된다(flash가 조금 절약된다).
web_server:
  port: 80
  version: 3

# 처음 USB 시리얼로 플래싱한 뒤에는 WiFi OTA로 올릴 수 있다
improv_serial:

# ─── SPI 버스: 소프트웨어 SPI, 지뢰 핀을 피한 일반 GPIO 사용 ───
spi:
  clk_pin: GPIO4
  miso_pin: GPIO5
  mosi_pin: GPIO6

# ─── CC1101 본체 ───
# 주파수는 433.92로 고정(내 스위치 크리스털 26.2982×16.5로 환산한 값).
cc1101:
  id: transceiver
  cs_pin: GPIO7
  frequency: 433.92MHz
  modulation_type: ASK/OOK
  # 350kHz는 너무 넓어서 AGC가 노이즈 플로어까지 증폭한다. 200kHz로 좁혀 노이즈를 억제한다.
  # (실측: 325kHz일 때 스위치를 한 번 누를 때마다 길이가 제각각인 조각이 8개씩 들어왔다)
  filter_bandwidth: 200kHz
  # ⚠️ symbol_rate는 CC1101의 데이터 필터 대역폭에 영향을 준다. "송신할 때만 의미 있는" 값이 아니다.
  #    원래는 5000(5 kbaud = 200µs/심볼)이었는데, 실측한 신호의 기본 시간 단위는 25µs였다
  #    (모든 펄스 폭이 25의 정수배: 25/50/75/100/.../475/875).
  #    8배나 빠른 셈이라 필터가 빠른 변화를 뭉개 버린다 → 복조할 때마다 결과가 달라진다.
  #    40000 baud = 25µs/심볼, 신호의 최소 특징과 정확히 맞는다.
  symbol_rate: 40000
  output_power: 10             # dBm, 최대 약 +11
  # 참고: cc1101에는 rssi / lqi라는 설정 항목이 없다(처음에 잘못 썼다가 compile에서 바로 막혔다).
  #     RSSI와 LQI는 packet_mode의 on_packet 트리거 안에서 변수로만 쓸 수 있고,
  #     async 모드(지금 쓰는 것)에서는 얻을 수 없으며 센서 엔티티로도 못 뽑는다.

# ─── 수신(2핀 배선, GDO2) ───
remote_receiver:
  id: rx
  pin:
    number: GPIO3               # CC1101 GDO2에 연결
  # 녹화할 때는 `dump: raw`를 켜야 원시 µs 타이밍이 보인다.
  # ⚠️ dump: all은 쓰지 말 것 —— 그건 "프로토콜 디코더"만 켜고 원시 파형은 포함하지 않으며,
  #    노이즈를 Pronto / Beo4 같은 적외선 프로토콜에 억지로 끼워 맞춰서 로그만 도배하고 쓸모가 없다.
  # 평소엔 꺼 둔다: 역방향 감지는 아래 on_raw에 의존하므로 dump 없이도 동작하고,
  #          켜 두면 이웃집 리모컨과 노이즈까지 전부 로그에 찍힌다.
  # dump: raw
  # ⚠️ filter는 단순히 "짧은 펄스를 버리는" 게 아니라, 짧은 펄스 양쪽의 신호를 "합쳐" 버린다:
  #      실제 185하이 / 60로우 / 185하이  →  filter 90µs 이후 단일 430µs 하이
  #    그래서 90µs일 때 녹화된 477 / 327은 이렇게 만들어진 가짜 값일 가능성이 높다.
  #    가까이서 녹화하면 신호가 노이즈보다 훨씬 강하므로 filter를 낮춰야 실제 구조가 잡힌다.
  filter: 20us
  # idle을 늘려서 한 번 누를 때의 반복 프레임이 전부 한 건 안에 담기고 잘리지 않게 한다
  idle: 25ms
  tolerance: 45%
  # 참고: 수신 측에는 on_transmit / on_complete가 필요 없다(받아 주지도 않는다).
  #     모드 전환은 전부 remote_transmitter 쪽이 담당하고, 송신이 끝나면 알아서 rx로 돌아간다.
  #
  # ── 역방향 감지: 누군가 실제 스위치를 누르면 HA의 상태를 뒤집는다 ──
  # ESPHome 내장 raw 비교는 쓰지 않는다. 그건 프레임 시작부터 정렬돼야 하는데,
  # 우리 캡처는 시작 위상이 일정하지 않다(한 번 누르면 반복이 2~4번 들어오고 시작점도 제각각).
  # 대신 직접 26 bit로 디코딩해서 값을 비교하므로, 어디서 시작하든 알아본다.
  on_raw:
    then:
      - lambda: |-
          // 송신 후 1초 동안은 무시한다. 내가 보낸 신호 때문에 상태가 두 번 뒤집히는 걸 막기 위해
          static uint32_t last_seen = 0;
          if (millis() - id(last_tx_ms) < 1000) return;

          uint32_t code = 0; int nbits = 0;
          for (size_t i = 0; i + 1 < x.size(); i += 2) {
            int32_t m = x[i], sp = -x[i+1];
            if (m < 20 || sp < 20) { code = 0; nbits = 0; continue; }
            if (sp > 400) {            // 동기 간격 → 한 프레임 끝
              code = 0; nbits = 0; continue;
            }
            code = (code << 1) | (m > sp ? 1 : 0);
            if (++nbits > 26) { code &= 0x3FFFFFF; nbits = 26; }

            if (nbits == 26) {
              if (millis() - last_seen < 800) break;   // 같은 누름의 반복 프레임은 한 번만 센다
              if (code == 0x0000000UL) {     // 방 조명의 26 bit 값으로 바꿀 것
                last_seen = millis();
                ESP_LOGI("rf", "偵測到實體開關：房間燈");
                id(room_light).publish_state(!id(room_light).state);
                break;
              } else if (code == 0x0000001UL) {   // 엄마 방 조명의 26 bit 값으로 바꿀 것
                last_seen = millis();
                ESP_LOGI("rf", "偵測到實體開關：媽媽房間燈");
                id(mom_light).publish_state(!id(mom_light).state);
                break;
              }
            }
          }

# ─── 송신(2핀 배선, GDO0) ───
remote_transmitter:
  id: tx
  pin:
    number: GPIO10              # CC1101 GDO0에 연결
  carrier_duty_percent: 100%
  on_transmit:
    then:
      - lambda: 'id(last_tx_ms) = millis();'
      - cc1101.begin_tx: transceiver
  on_complete:
    then:
      - cc1101.begin_rx: transceiver

# ─── 조명 스위치 엔티티 ───
# button 대신 switch를 쓴다. 그래야 HA에 "켜짐/꺼짐" 상태가 생겨서 표시하고 자동화에 쓸 수 있다.
# 이런 RF 스위치는 "토글" 동작 하나뿐이라(켜기/끄기 명령이 따로 없음),
# turn_on과 turn_off가 같은 코드를 보내고, optimistic으로 상태를 유지한다.
# 누군가 실제 스위치를 누르면 위 remote_receiver의 on_raw가 상태를 뒤집는다.
#
# 두 스위치의 코드(2026-09-09 녹화, 각각 모듈에 붙이고 열 번씩 눌러 합의값을 취함):
#   방 조명       26 bit = <직접 녹화한 코드>
#   엄마 방 조명  26 bit = <직접 녹화한 코드>
#   앞 10 bit는 같고(같은 모델의 제조사 코드), 그 뒤로 갈라진다 → 서로 간섭하지 않는다
switch:
  - platform: template
    name: "房間燈"
    id: room_light
    icon: "mdi:ceiling-light"
    optimistic: true
    # ⚠️ 기본 restore_mode는 ALWAYS_OFF라서, 부팅 시 "실제로 turn_off를 한 번 실행"한다.
    #    그런데 turn_off가 보내는 건 토글 코드다 → 재부팅할 때마다 조명이 한 번씩 토글된다. 그래서 반드시 DISABLED로 하고,
    #    상태는 위 globals에 기억해 두고, on_boot에서는 표시만 하고 송신은 하지 않는다.
    restore_mode: DISABLED
    on_state:
      - lambda: id(room_light_saved) = x;
    turn_on_action: &toggle_room
      - script.execute: tx_room_light
    turn_off_action: *toggle_room

  - platform: template
    name: "媽媽房間燈"
    id: mom_light
    icon: "mdi:ceiling-light"
    optimistic: true
    # ⚠️ 기본 restore_mode는 ALWAYS_OFF라서, 부팅 시 "실제로 turn_off를 한 번 실행"한다.
    #    그런데 turn_off가 보내는 건 토글 코드다 → 재부팅할 때마다 조명이 한 번씩 토글된다. 그래서 반드시 DISABLED로 하고,
    #    상태는 위 globals에 기억해 두고, on_boot에서는 표시만 하고 송신은 하지 않는다.
    restore_mode: DISABLED
    on_state:
      - lambda: id(mom_light_saved) = x;
    turn_on_action: &toggle_mom
      - script.execute: tx_mom_light
    turn_off_action: *toggle_mom

# ─── 송신 대기열 ───
# HA에서 연타할 때 두 신호열이 붙어 버리면 조명은 한 번 누른 걸로 받아들이는데, HA는 이미 두 번 뒤집었다 → 불일치.
# 그래서 조명마다 queued script를 하나씩 둔다: 한 번에 한 신호열만 보내고, 다 보낸 뒤 최소 700ms를 두고 다음을 보낸다.
script:
  - id: tx_room_light
    mode: queued
    max_runs: 6
    then:
      - remote_transmitter.transmit_raw:
          code: [<캡처한 코드로 교체>]
          repeat:
            times: 8
            wait_time: 0s
      - delay: 700ms
  - id: tx_mom_light
    mode: queued
    max_runs: 6
    then:
      - remote_transmitter.transmit_raw:
          code: [<캡처한 코드로 교체>]
          repeat:
            times: 8
            wait_time: 0s
      - delay: 700ms

# ─── 진단 ───
sensor:
  - platform: wifi_signal
    name: "${friendly_name} WiFi"
    update_interval: 60s
    entity_category: diagnostic
  - platform: uptime
    name: "${friendly_name} 開機時間"
    update_interval: 60s
    entity_category: diagnostic
  - platform: template
    name: "${friendly_name} WiFi 斷線次數"
    lambda: return id(wifi_drops);
    accuracy_decimals: 0
    state_class: measurement
    update_interval: 60s
    entity_category: diagnostic

text_sensor:
  - platform: wifi_info
    ip_address:
      name: "${friendly_name} IP"
    bssid:
      name: "${friendly_name} BSSID"
  - platform: debug
    reset_reason:
      name: "${friendly_name} 重開原因"

debug:
  update_interval: 5min