[nakjiya]

배경

에어컨(airConditionerMode)/후드(samsungce.hoodFanSpeed) 실사용 중 발견한 이슈 3건을 고쳤습니다.

이후 실사용 중 추가로 발견한 회귀 수정 1건과 편의 기능 1건도 같은 PR에 포함했습니다 (아래 4, 5번).

1) select 엔티티가 s2h_mode_mapping을 인식하지 못함

select.py의 current_option/async_select_option은 s2h_state_mapping만 읽습니다. 그런데 climate/fan 쪽의 mode/preset_mode 필드는 관례상 s2h_mode_mapping을 씁니다. 이 이름 불일치 때문에 select에 s2h_mode_mapping을 쓴 설정(예: samsungce.hoodFanSpeed의 14~18 값을 smart/normal/.../max로 매핑하는 후드 팬속도 select)은 매핑이 통째로 무시되어:

• 읽기: 원본 숫자값이 그대로 current_option이 되어 options에 없는 값이라 HA가 unknown으로 표시
• 쓰기: 문자열이 매핑 없이 그대로 커맨드 인자로 전송되어 SmartThings API가 거부

수정: s2h_state_mapping이 없으면 s2h_mode_mapping을 fallback으로 사용하도록 변경 (기존 s2h_state_mapping 설정에는 영향 없음).

2) 매핑 키의 숫자/문자열 타입 불일치

YAML에서 "14": "smart"처럼 따옴표 붙은 숫자 키를 쓰면 문자열이 되어, SmartThings가 정수로 주는 실제 속성값(14)과 매칭이 안 됩니다. get_mapping_value/get_mapping_key가 문자열↔숫자 양쪽으로 매칭을 시도하고, 커맨드로 값을 되돌려 보낼 때도 숫자로 캐스팅하도록 해서 SmartThings API의 타입 검증을 통과하게 했습니다.

3) climate 전원 on + 모드 변경을 동시에 하면 다시 꺼짐으로 되튕기는 문제

async_set_hvac_mode가 꺼진 상태에서 다른 모드로 바꾸며 켤 때 switch on 커맨드와 setAirConditionerMode 커맨드를 지연 없이 바로 연달아 보냅니다. 클라우드로 실행되는 일부 에어컨(테스트한 삼성 벽걸이형 에어컨)은 전원이 켜진 걸 미처 인지하기 전에 모드 변경 커맨드가 도착하면 다시 꺼짐 상태로 튕겨나가는 것으로 보입니다. async_turn_on() 직후 1초 지연을 추가했습니다.

테스트

실제 삼성 에어컨(스탠드형/벽걸이형) + 삼성 후드로 검증:

• select.hood_fan_mode: unknown → 정상적으로 smart/normal/... 표시 및 실제 팬속도 변경 확인
• climate.wall_air: 꺼짐 → 다른 모드로 켜기를 3회 반복, 3회 모두 안정적으로 유지되고 꺼짐으로 되튕기는 현상 재현 안 됨
• climate.stand_air: 기존 동작 회귀 없음 확인

4) (회귀 수정) 매핑이 없는 값까지 숫자로 캐스팅되던 문제

2번 수정에서 넣은 "매핑 키가 숫자 문자열이면 int로 캐스팅" 처리가 원래 for 루프 바깥에 있어서, s2h_*_mapping이 아예 설정 안 된 값(예: climate fan_mode의 "3"처럼 그대로 전송해야 하는 pass-through 값)까지 무조건 int로 바뀌고 있었습니다. 실기기 테스트로 재현: SmartThings API가 "integer found, string expected"로 거부하면서 팬속도 수동 조절이 막혔습니다. 캐스팅을 실제로 매핑에서 매치를 찾은 분기 안으로 옮겨서, 매핑이 없는 값은 원래 타입 그대로 유지되도록 수정했습니다.

5) climate fan_mode에 상호 배타적인 대체 모드(예: 무풍)를 같은 드롭다운으로 통합하는 alt_mode 옵션 추가

삼성 무풍처럼 팬속도와는 별개 캐패빌리티(custom.airConditionerOptionalMode)로 켜고 끄지만, 기기 자체가 "팬속도를 바꾸면 무풍 해제, 무풍을 켜면 팬속도 auto로 리셋"하는 식으로 상호 배타적으로 동작하는 기능을 실기기로 확인했습니다. 이런 경우를 위해 fan_mode 서브캐패빌리티에 선택적 alt_mode 설정을 추가할 수 있게 했습니다:

- fan_mode:
    capability: airConditionerFanMode
    options:
      attribute: supportedAcFanModes
    command: setFanMode
    state:
      attribute: fanMode
    alt_mode:
      name: "무풍"
      capability: custom.airConditionerOptionalMode
      component: main
      command: setAcOptionalMode
      argument: ["windFree"]
      state:
        attribute: acOptionalMode
      on_state: ["windFree", "windFreeSleep"]

• fan_modes 옵션 목록에 alt_mode.name이 추가됩니다
• 그 값을 선택하면 alt_mode에 설정된 별도 capability/command로 커맨드를 보냅니다
• 현재 상태가 alt_mode의 on_state에 해당하면 (기기가 원래 캐패빌리티 값을 다른 값으로 리셋해도) alt_mode.name을 우선 표시합니다

alt_mode를 설정하지 않은 기존 구성에는 전혀 영향 없는 opt-in 기능입니다. 실기기(삼성 스탠드형 에어컨)로 옵션 목록 노출/선택 시 실제 전환/상태 표시/상호 자동 해제까지 전부 검증했습니다.

참고: s2h_action_mapping은 HVACAction enum 값을 써야 합니다

이번 PR 범위는 아니지만, hvac_action(s2h_action_mapping으로 매핑)은 HA의 HVACAction enum(off/heating/cooling/drying/idle/fan/preheating/defrosting)이어야 프론트엔드가 인식합니다. 한글 텍스트("냉방 청정" 등)를 넣으면 상태창에 정상 표시되지 않습니다 — README/예제에 이 제약을 명시하면 다른 사용자들의 혼동을 줄일 수 있을 것 같습니다.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CmJTDppSN12JBjtZJzFWza