Home Assistant에 Ulanzi Desktop Clock 연동하기

스마트홈을 구축하다 보면 결국 상태를 한눈에 보고싶은 욕망이 들곤 합니다.
“지금 집이 어떤 상태인지, 가장 빠르게 확인할 수 있는 방법은 무엇일까?”

스마트폰 앱을 열어 확인할 수도 있지만, 항상 손에 들고 다니는 것도 아니고 매번 앱을 여는 과정 자체가 번거롭습니다. 만약 집 안의 주요 상태를 탁상 위에서 자연스럽게 확인할 수 있다면 이야기가 달라집니다. 시간과 함께 날씨, 센서 값, 알림이 흘러가듯 표시된다면 그 자체로 스마트홈의 완성도는 한 단계 올라갑니다.

이번 글에서는 Home Assistant(이하 HA)에 Ulanzi Desktop Clock을 연동해, 집 안의 다양한 정보를 자동으로 표시하는 과정을 정리했습니다.

 

1. Ulanzi Desktop Clock은 어떤 장치인가

Ulanzi Desktop Clock은 ESP32를 기반으로 한 LED 매트릭스 탁상시계입니다. 대표 모델은 TC001 입니다. 겉보기에는 단순한 디지털 시계처럼 보이지만, 내부적으로는 네트워크에 연결된 소형 디스플레이 장치에 가깝습니다. Wi-Fi를 통해 외부 시스템과 통신하며, 시간뿐 아니라 날씨, 알림, 센서 데이터 같은 정보를 자유롭게 표시할 수 있도록 설계되어 있습니다.

주요 특징을 정리하면 다음과 같습니다.

• ESP32 마이크로컨트롤러 내장으로 Wi-Fi 통신 지원
• 8×32 RGB LED 매트릭스 디스플레이
• AWTRIX 3 펌웨어 기반 (MQTT, HTTP API 제공)
• 사용자 정의 앱 및 애니메이션 아이콘 표시
• 부저 또는 DFPlayer 모듈을 통한 사운드 출력 확장 가능

 

2. ESP32가 담당하는 역할

Ulanzi 시계의 중심에는 ESP32 마이크로컨트롤러가 있습니다. ESP32는 Wi-Fi와 Bluetooth를 기본으로 내장한 듀얼코어 SoC로, IoT 분야에서 사실상 표준처럼 사용되는 칩입니다.

전원이 인가되면 ESP32는 내부 부트로더를 통해 AWTRIX 펌웨어를 실행하고, 저장된 Wi-Fi 및 MQTT 설정을 기반으로 네트워크에 자동으로 연결됩니다. 이후부터는 외부에서 들어오는 메시지를 받아 LED 매트릭스에 렌더링하는 역할을 수행합니다.

하드웨어 관점에서 보면 다음과 같은 구성으로 이해할 수 있습니다.

• 듀얼코어 CPU에서 통신 처리와 디스플레이 렌더링을 분리
• RAM/PSRAM을 활용해 아이콘과 프레임 버퍼를 캐싱
• GPIO를 통해 LED 매트릭스, 버튼, 사운드 모듈 제어
• USB 5V 입력을 받아 내부적으로 3.3V 로직 전원 변환

이 덕분에 비교적 저전력 환경에서도 안정적으로 네트워크 통신과 화면 출력을 동시에 처리할 수 있습니다.

 

3. AWTRIX 3 펌웨어 구조 이해하기

AWTRIX는 단순히 “텍스트를 찍어주는 펌웨어”가 아닙니다. 내부적으로는 앱(App)과 프레임(Frame)이라는 개념을 중심으로 동작합니다.

하나의 앱은 하나의 기능 단위이며, 앱 안에는 여러 개의 프레임이 존재할 수 있습니다. 각 프레임은 실제 LED 매트릭스에 표시되는 한 장의 화면으로, 텍스트, 아이콘, 색상, 표시 시간 같은 정보를 포함합니다. 알림(Notification)은 기존 앱 흐름을 잠시 중단하고 우선적으로 표시되는 단일 메시지라고 보면 됩니다.

이 구조 덕분에 시간 표시, 온도 표시, 알림 같은 요소들이 충돌 없이 자연스럽게 순환하며 출력됩니다.

 

4. Home Assistant와의 통신 흐름

HA와 Ulanzi 시계는 두 가지 방식으로 통신합니다.

• MQTT: 상태 변화나 주기적인 업데이트처럼 지속적인 데이터 전달에 적합
• HTTP REST API: 단발성 알림이나 즉시 표시해야 하는 메시지에 적합

일반적인 흐름은 다음과 같습니다.
HA가 이벤트를 감지하거나 센서 상태가 변경되면, MQTT 브로커를 통해 메시지를 발행하거나 시계의 HTTP API로 직접 요청을 보냅니다. 시계는 이를 수신해 내부 AWTRIX 렌더 루프에서 처리한 뒤 LED 매트릭스에 반영합니다.

 

5. Home Assistant 측 준비

MQTT 방식을 사용하려면 HA에 브로커가 필요합니다. 대부분의 환경에서는 애드온으로 제공되는 Mosquitto를 사용하면 충분합니다. 애드온 설치 후 configuration.yaml에 브로커 정보를 추가하고 HA를 재시작하면 MQTT 통신이 활성화됩니다.

mqtt:
  broker: homeassistant.local
  username: your_username
  password: your_password

 

이 과정은 Ulanzi에 국한된 설정이라기보다, HA에서 MQTT 기반 장치를 연동할 때 공통적으로 필요한 준비 단계라고 보면 됩니다.

6. Ulanzi(AWTRIX) 설정

시계를 Wi-Fi에 연결한 뒤, 브라우저에서 시계의 IP 주소로 접속하면 AWTRIX 관리 화면에 접근할 수 있습니다. 여기서 MQTT 설정 메뉴로 이동해 브로커 주소, 포트, 인증 정보를 입력합니다.

항목	예시
Broker	homeassistant.local
Port	1883
Username	HA에서 설정한 계정
Password	비밀번호
Topic Prefix	awtrix

 

정상적으로 연결되면 상태가 “Connected to MQTT”로 표시됩니다. 이 시점부터 시계는 HA가 발행하는 메시지를 실시간으로 수신할 수 있는 상태가 됩니다.

7. Home Assistant에서 제어하기

REST API 방식은 설정이 직관적입니다. rest_command를 정의해 두면 자동화나 스크립트에서 간단히 호출할 수 있습니다. 예를 들어 현관문이 열렸을 때 즉시 시계에 알림을 띄우는 식의 사용이 가능합니다.

configuration.yaml에 다음을 추가합니다.

 

rest_command:
  awtrix_notify:
    url: "http://ulanzi-clock.local/api/notify"
    method: post
    headers:
      Content-Type: "application/json"
    payload: >
      {
        "text": "{{ message }}",
        "icon": "bell",
        "duration": 5,
        "color": [255, 255, 255]
      }

 

이제 알림을 호출할 수 있습니다.

automation:
  - alias: "현관문 열림 알림"
    trigger:
      - platform: state
        entity_id: binary_sensor.front_door
        to: "on"
    action:
      - service: rest_command.awtrix_notify
        data:
          message: "현관문이 열렸습니다!"

 

MQTT 방식은 조금 더 유연합니다. 특정 센서 값이 바뀔 때마다 텍스트를 갱신하거나, 앱 단위로 정보를 관리할 수 있어 장기적으로는 MQTT가 더 잘 맞는 경우가 많습니다.

 

automation:
  - alias: "온도 표시 업데이트"
    trigger:
      - platform: state
        entity_id: sensor.living_room_temperature
    action:
      - service: mqtt.publish
        data:
          topic: "awtrix/notify"
          payload: >
            {
              "text": "거실 온도 {{ states('sensor.living_room_temperature') }}°C",
              "icon": "temp",
              "color": [255, 200, 0]
            }

 

8. 커스텀 앱으로 확장하기

AWTRIX의 강점은 “표시할 수 있는 정보의 한계가 없다”는 점입니다. 날씨, 온도, 일정, 서버 상태 같은 데이터도 HA 자동화를 통해 얼마든지 가공해 보낼 수 있습니다. 일정 주기로 데이터를 갱신하도록 설정하면, 시계는 항상 최신 상태를 유지하게 됩니다.

이 단계부터는 단순 연동을 넘어, 집 안의 정보를 어떻게 시각화할지 고민하는 영역에 가깝습니다.

예를들어 날씨 예보 표시 앱을 만든다고 한다면, 이런식으로 30분마다 현재 날씨를 갱신해 시계에 표시할 수 있습니다.

automation:
  - alias: "날씨 업데이트"
    trigger:
      - platform: time_pattern
        minutes: "/30"
    action:
      - service: rest_command.awtrix_notify
        data:
          message: "{{ states('weather.home') }} {{ state_attr('weather.home', 'temperature') }}°C"

 

마치며

Ulanzi Desktop Clock은 단순한 탁상시계를 넘어, Home Assistant의 상태를 시각적으로 표현하는 미니 디스플레이로 활용할 수 있습니다.
MQTT와 REST API를 함께 활용하면 자동화된 알림, 센서 데이터, 일정 등 다양한 정보를 실시간으로 보여줄 수 있습니다.

ESP32의 확장성과 AWTRIX의 유연한 구조 덕분에, 사용자 정의 앱을 만들거나 디자인을 변경하는 것도 어렵지 않습니다.
작은 LED 매트릭스지만, 집안의 정보를 가장 직관적으로 보여주는“작은 스마트 허브”가 되어줄 것입니다.

 

 

 

참고 자료

• AWTRIX 3 공식 GitHub
• Ulanzi 공식 홈페이지
• Home Assistant MQTT 문서