CLOVA Home extension 컴포넌트 입니다. CEK를 통해 CLOVA와 홈어시스턴트 사이의 커뮤니케이션을 지원합니다.

초기 버전보다 많은 기능이 업데이트 되었습니다.

1. 메뉴얼을 작성했습니다.
   설정가능한 변수가 많이 추가되어 따로 메뉴얼을 작성했습니다.

2. 스키마 파일을 따로 작성하여 유효성 검사를 강화했습니다.
   configuration.yaml을 작성하고 서버를 재시작하기전에 유효성 검사를 통해 설정파일이 잘 작성되었는지 확인하여 재로딩 시간을 줄일 수 있습니다. response도 유효성 검사를 적용하려했지만 템플릿 언어를 적용했다는 사실을 잊은채 스키마를 작성하여 유효성 검사를 통과하지 못하여 이번 버전에서는 적용하지 않았습니다..

3. 디바이스 설정을 자유롭게 할 수 있습니다.
   디바이스 이름이나 제조사, 태그 등을 자유롭게 변경할 수 있습니다. 클로바 서버에서 인식하는 디바이스 타입도 설정할 수 있습니다.

4. 커스텀 액션을 수행할 수 있습니다.
   디바이스의 actionDetails를 설정하여 다른 서비스를 실행하고 사용자가 지정한 응답 메시지를 반환하도록 할 수 있습니다. 클로바의 디바이스 타입이 세세하게 나눠져 있어서 홈어시스턴트의 도메인에 매칭되는 타입이 제한됩니다. 이때 actionDetails를 설정하여 액션마다 실행하는 서비스를 지정할 수 있고 사용자가 작성한 응답 메시지를 반환할 수 있습니다.(응답 메시지는 타입별로 형태가 정해져있습니다.)

카카오 페이

• HA 설치 경로 아래 custom_components에 clova폴더 안의 전체 파일을 복사해줍니다.
  <config directory>/custom_components/clova/
  
• Home-Assistant 를 재시작합니다
  

• HACS > Integretions > 우측상단 메뉴 > Custom repositories 선택
• 'https://github.com/huimang2/clova' 주소 입력, Category에 'integration' 선택 후, 저장
• HACS > Integretions 메뉴 선택 후, '[KR] 클로바홈EX' 검색하여 설치

참고

• 아래 페이지를 참고하여 CLOVA Home extension을 등록하세요. https://developers.naver.com/console/clova/home_ext/DevConsole/Guides/Register_Clova_Home_Extension.md

• HA 도메인은 SSL 인증서를 사용하여 외부에서 Home Assistnat에 접근 가능해야 합니다.

• 심사신청은 하지마세요!

1) CLOVA Developers Consor β에 접속하여 CLOVA Home extension 만들기를 클릭하세요.

2) 서버 설정은 다음과 같이 입력합니다.

• Extension 서버 URL: https://HA주소/api/clova
• 로그인 URL: https://HA주소/auth/authorize
• 클라이언트ID: https://prod-ni-cic.clova.ai/
• Access token URI: https://HA주소/auth/token?grant_type=authorization_code
• Access token 재발급 URI (선택): https://HA주소/auth/token?>grant_type=refresh_token
• 클라이언트 secret: 아무 글자나 입력

3) 로고는 250 * 250 사이즈의 이미지, 배너는 750 * 500 사이즈의 이미지를 사용합니다.

1) 클로바 어플리케이션 다운로드 후 실행

2) 하단에 위치한 스마트홈 아이콘 클릭

3) + 기기 추가하기 클릭

4) 추가한 extension 클릭

5) 로그인을 클릭하여 홈어시스턴트 아이디로 로그인

6) 연동된 기기 확인

클로바홈EX를 실행시키기 위해서는 configuration.yaml 파일을 설정해야 합니다.

clova:

clova:
  expose_by_default: False
  exposed_domains:
    - switch
    - climate
  customCommands: []
  entity_config: ...

참고 : 클로바 서버에 값을 전달해도 해당 명령어가 내 명령어에 표시되지 않습니다.
아직 미구현 상태입니다.

clova:
  customCommands:
    - name: "외출모드"
      actions:
        - entity_id: switch.geosil_jeondeung
          action: TurnOff
        - entity_id: switch.jubang_jeondeung
          action: TurnOff
        - entity_id: switch.keunbang_jeondeung
          action: TurnOff

참고 : entity_config를 설정하여 각각의 디바이스마다 커스텀화가 가능합니다.

clova:
  expose_by_default: false
  entity_config:
    switch.geosil_jeondeung:
      expose: true
      name: 거실 전등
      manufacturer: 삼성
      model: 2021년형
      version: v1.1
      description: 2021년형 삼성 LED 등입니다.
      type: SWITCH
      ir: false
      location: LIVING_ROOM
      tags: [거실]
      actionDetails: ...

type 값은 지정된 디바이스 타입을 입력해야 합니다. 디바이스 타입마다 사용할 수 있는 액션이 정해져 있습니다. 소문자로 입력해도 대문자로 변환되어 전달됩니다.

홈어시스턴트의 도메인은 다음과 같은 타입으로 변환됩니다.

참고 : 완전히 구현된 도메인은 switch, climate, fan, group 입니다.
나머지 도메인은 기본적인 ON/OFF 액션만 구현된 상태입니다.

location 값은 지정된 장소 타입을 입력해야 합니다. 해당 장소 타입은 지정된 그룹으로 편성됩니다. tags 변수를 통해서도 그룹 지정이 가능하므로 값이 지정된 location 보다는 tags를 사용하는 것이 더 편합니다.

actionDetails을 설정하여 사용자가 지정한 서비스를 불러오는 것이 가능합니다. 또한 allowableValue를 설정하여 클로바 서버로 해당 액션이 허용하는 값을 전달할 수 있습니다.

액션명은 클로바 플랫폼 가이드를 참고하세요.

"actionDetails": {
  "액션명": {
    "service": "domain.service",
    "data": dict,
    "response": dict,
    "allowableValue": {
      "type": "타입",
      "minValue": int,
      "maxValue": int,
      "enumValues": list
    }
  }
}

clova:
  entity_config:
    switch.geosil_jeondeung:
      actionDetails:
        TurnOn:
          service: input_text.set_value
          data:
            entity_id: input_text.test
            value: {{ states("switch.geosil_jeondeung") }} 상태

switch.geosil_jeondeung으로 TurnOn 액션 요청이 오면 input_text 도메인의 set_value 서비스를 실행하여 input_text.test 구성요소에 switch.geosil_jeondeung 구성요소의 의 상태를 기록하게 됩니다.

참고 : 홈어시스턴트의 템플릿 언어를 사용하여 데이터를 전달할 수 있습니다.

Request값은 자체적인 문법을 사용합니다. @경로@ 형식으로 입력합니다.

경로는 payload 아래 경로를 입력합니다.

예를들어

{
  "header": {
    "messageId": "33da6561-0149-4532-a30b-e0de8f75c4cf",
    "name": "SetModeRequest",
    "namespace": "ClovaHome",
    "payloadVersion": "1.0"
  },
  "payload": {
    "accessToken": "92ebcb67fe33",
    "appliance": {
        "applianceId": "device-006"
    },
    "mode": {
        "value": "hotwater"
    }
  }
}

다음과 같은 형식의 요청이 들어오고 mode의 value값을 이용하고 싶다면 @mode.value@ 라고 입력하면 됩니다.

clova:
  expose_by_default: false
  entity_config:
    input_text.test:
      expose: true
      type: RICECOOKER
      actionDetails:
        SetMode:
          service: input_text.set_value
          data:
            entity_id: input_text.test
            value: "@mode.value@"
          response:
            mode:
              value: "@mode.value@"

input_text.test 구성요소를 만들고 다음과 같이 작성하면 밥솥에 대한 SetMode 액션을 실행할 수 있습니다.

clova:
  expose_by_default: false
  entity_config:
    sensor.electricity_monitor_energy:
      expose: true
      type: building_electric_meter
      actionDetails:
        GetConsumption:
          response:
            - name: 전기사용량
              value: "{{ states('sensor.electricity_monitor_energy') | int }}"
              unit: KW

• 네이버 카페 : HomeAssistant (https://cafe.naver.com/koreassistant)
• 클로바 플랫폼 가이드 (https://developers.naver.com/console/clova/home_ext/)