ESP32-CAM Home Assistant Integration (ESPHome)

Outline

ESP32-CAM을 Home Assistant에 추가하고자 했다. Home Assistant의 Card에 추가하기 위해서는 ESP32-CAM의 영상이 스트리밍 서버 형태로 제공되어야 한다. 나는 자동화 기기들은 대부분 local로 HA와 연결하고, 외부와의 interfacing은 HA가 전적으로 담당하는 형태로 네트워크를 구성하고자 했다. 그러려면 현재 HA가 설치되어있는 라즈베리파이와 ESP32-CAM이 같은 네트워크에 속해 있어야 한다.

 

이를 위해 두가지 방법을 시도했다.

 

1. ESP32의 Arduino Framework로 HTTP Stream Server를 만들어 HA에 통합

2. ESP Home Framework로 HA에 통합

 

결과적으로는 2번 방법이 내 요구사항을 잘 만족하는 방법이었다.

 

1. Arduino Framework에서 HTTP StreamServer를 이용한 Integration

첫번째 방법은 ESP32의 Arduino Framework의 Examples 중에서 ESP32-CAM을 위한 "CameraWebServer"예제를 살짝 수정해서 이용하였다.

ESP32-CAM이 공유기 무선네트워크(WiFi)에 연결하고, ESP32-CAM이 http stream server 역할을 한다. 이 server url을 HA의 lovelace UI에 Picture Card로 추가하는 것이다.

void TY_startStreamServer()
{
    httpd_config_t config = HTTPD_DEFAULT_CONFIG();
    config.server_port = 80;

    httpd_uri_t index_uri = {
        .uri = "/",
        .method = HTTP_GET,
        .handler = stream_handler,
        .user_ctx = NULL
    };

    // Serial.printf("Starting web server on port: '%d'\n", config.server_port);
    if (httpd_start(&stream_httpd, &config) == ESP_OK)
    {
        httpd_register_uri_handler(stream_httpd, &index_uri);
    }
};

Streaming Server는 위와 같이 구성하였다.

Lovelace UI에서의 카드 추가

코드를 ESP32-CAM에 올리고 동작하고, HA에서는 위처럼 Picture Card에 HTTP URL로 접속하였다.

정상동작 모습

그러면 위 사진처럼 Card가 추가되고, 정상적으로 동작한다.(일단 연결만 테스트하려고 화질은 따로 설정하지 않았다.)

 

외부 네트워크에서 접속했을때 URL로 접근하지 못함

그런데 문제점이 있었는데, 외부 네트워크에서 HA page에 접속했을 때 이 URL로 접근하지 못한다는 것이었다.

코드와 HA Integration은 정상적으로 동작했다. 그러나 HA와 ESP32-CAM이 둘다 속해있는 네트워크에서 접속하지 않으면 위처럼 Stream Server URL로 접근하지 못했다. 접속하는 기기의 기준으로 URL을 접근하기 때문인것 같았다.

 

이 경우 Stream Server의 URL도 외부 접속이 가능하도록 DNS와 포트포워딩을 하면 가능하긴 하다. 그러나 내가 추구했던 방향은 외부와의 interfacing은 HA만으로 온전히 이루어지는 것이기 때문에 별로 바람직한 방향은 아니었다.

 

그래서 ESP Home을 이용한 두번째 방법을 시도했다.

 

2. ESPHome을 이용한 Integration

이 방법은 Arduino Framework를 이용하는 것이 아니라 ESPHome system을 이용해 ESP32-CAM과 HA를 연결하는 방법이다. 결과적으로는 내가 의도한대로 외부네트워크 접속시에도 정상적으로 카메라 스트리밍을 볼 수 있었다.

 

ESPHome — ESPHome

 

Native API Component

1번 방법에서는 WiFi Stack 위에서 HTTP protocol로 camera streaming을 진행했다.

ESPHome을 이용할 경우에는 마찬가지로 WiFi stack 위에서 동작하지만, custom TCP protocol에 기반한 ESPHome Native API의 protocol을 이용한다.

 

 

전체적인 과정은 다음과 같다.

 

1) HA의 ESPHome Add-on에서 YAML로 scripting

2) YAML Script를 컴파일한 binary 파일을 ESP32-CAM에 업로드

3) ESP32-CAM이 HA와 같은 네트워크의 WiFi에 연결

4) HA에서 ESP32-CAM을 entity로 추가

5) HA의 Lovelace UI에서 'Picture Entity Card'로 ESP32-CAM의 stream을 출력

 

HA의 ESPHome Addon

먼저 Home Assistant에서 ESPHome Addon을 설치한다.

ESPHome Addon WEB UI

그러면 Addon의 WEB UI에 접근할 수 있게 되는데, 여기서 ESP32-CAM device를 추가하고 관리할 수 있다. 기기를 USB Serial port로 연결하면 기기를 인식하게 된다.

이후 인식된 device에 위 사진의 "EDIT"으로 YAML scripting을 진행한다.

ESP32-CAM을 위한 YAML script 일부

YAML에서는 위처럼 네트워크와 camera pinning에 대한 부분을 설정하게 된다. Arduino framework를 이용했을때보다 훨씬 짧은 코드로, 마치 config파일의 설정만 몇개 바꾸듯이 scripting을 하면 된다.

WiFi의 경우는, 위처럼 static local ip를 할당해서 HA와 같은 network에 연결하도록 했다.

 

ESPHome Web

ESPHome에서는 web dashboard를 제공해서, compile과 flashing을 위한 별도 설치가 필요없다. ESP32-CAM을 USB Serial port에 연결해 두었다면, 위처럼 인식하고 web에서 compile과 flashing작업을 모두 수행할 수 있다.

 

최초에는 직접 USB로 연결하고 flashing을 해야 하지만, 이후에 ESP Device가 WiFi network에 연결되어 있다면 YAML 수정 및 재컴파일 시에 OTA로도 update가 가능하다.

 

ESPHome dashboard에서 log 확인

ESP32-CAM device가 WiFi에 성공적으로 연결되면, ESPHome의 web dashboard에서 위처럼 log를 확인할 수 있다.

HA Integration

그리고 Home Assistant에서 ESP32-CAM device의 camera와 flashlight를 HA entity로 등록한다.

HA Lovelace UI card

이 entity를 HA의 Lovelace UI에서 'Picture Entity Card'에 등록한다. 우선은 camera entity만 넣었다. Flashlight entity도 넣으면 card의 toggle 등을 통해 HA에서 ESP32-CAM의 flashlight를 제어할 수 있다.

 

Result

HA dashboard에 추가된 ESP32-CAM

정상적으로 과정이 진행되면, HA의 Lovelace UI에서 위처럼 추가된 ESP32-CAM의 camera stream을 확인할 수 있다. 이번에는 HA와 ESP32-CAM이 속해있는 네트워크 이외의 외부 네트워크에서 HA에 접근해도 camera stream이 정상적으로 출력되게 된다.

 

이번에 ESPHome을 처음 사용해 보았는데, 역시 Home Assistant와의 연동에 특화된 system이라 scripting부터 integration까지 매우 간단하게 진행할 수 있도록 구성되어 있었다. 물론 세부적인 customizing을 하거나 다른 기능들을 구현하려면 framework에서 직접 programming을 해야 겠지만, HA system에 간단하게 sensor node들을 integrating하기 위해서는 아주 좋은 선택인 것으로 보인다.