---
title: "ha-sunriser"
url: "https://maker.wiznet.io/Lihan__/projects/ha-sunriser/"
markdown_url: "https://maker.wiznet.io/Lihan__/projects/ha-sunriser/md"
type: "UCC: User Created Content"
author: "MrInterBugs"
author_url: "https://github.com/MrInterBugs/ha-sunriser"
editor: "WIZnet"
editor_url: "https://maker.wiznet.io/"
original_author: "MrInterBugs"
original_url: "https://github.com/MrInterBugs/ha-sunriser"
published: "2026-05-13"
language: "en"
likes: 0
views: 320
comments: 0
source: "WIZnet Makers (https://maker.wiznet.io/)"
---

# ha-sunriser

> Home Assistant integration for the SunRiser 8/10 LED aquarium controller.

Original author: MrInterBugs (source: https://github.com/MrInterBugs/ha-sunriser)

## Article

## ha-sunriser — Bring Your Aquarium Light Into Home Assistant, Powered by WizFi360

`#WizFi360` `#HomeAssistant` `#TCP` `#SmartAquarium` `#HACS` `#PWM` `#MessagePack` `#IoT` `#LEDControl` `#WiFiModule`

> 📚 Community-developed HA integration | Reverse-engineered from open-source SunRiser firmware Production-deployed integration with 49 releases (v1.7.1, April 2026) — real devices, real users

---

### 01 — What is this project?

Aquarium hobbyists with the **SunRiser 8/10** LED controller by LEDaquaristik.de face a familiar problem: the controller has a built-in scheduling engine, per-channel PWM dimming, temperature sensing, and even weather simulation — but none of that data surfaces in a smart home dashboard. The device sits on the local network with no native Home Assistant support, leaving owners to manage it through a separate browser UI while every other smart device integrates seamlessly.

**ha-sunriser** solves this by bridging the SunRiser 8/10 to Home Assistant as a fully native custom integration. Once installed via HACS, the controller appears in HA as a device with light entities (per PWM channel, 0–100% dimmable), switch entities for maintenance mode, time-lapse, and DST auto-tracking, sensor entities for DS1820 temperature readings and firmware version, and a custom Lovelace card that renders all active light schedules as a colour-accurate 24-hour chart — matching the exact LED colours displayed in the device's own web UI.

The result: aquarium light state, temperature, connectivity health, and planner schedules — all in one smart home dashboard, with Alexa voice control, HA automations, and backup/restore services on top.

---

### 02 — Why MessagePack over HTTP?

#### 🔷 Binary efficiency on embedded hardware

The SunRiser 8/10 communicates using [MessagePack](https://msgpack.org/), a compact binary serialisation format. On an embedded system with limited RAM and no HTTP/2 support, MessagePack reduces payload size compared to JSON while remaining schema-agnostic. The integration faithfully speaks this protocol to ensure complete compatibility across all SunRiser firmware versions.

#### 🔷 Open-source firmware as the source of truth

The integration was reverse-engineered from [LEDaquaristik's open-source SunRiser firmware](https://github.com/LEDaquaristik/sunriser) (GPL-3.0). This means every config key, PWM range (0–1000), and API endpoint is grounded in the device's own documented internal behaviour — not guesswork.

#### 🔷 WizFi360 constraint drives architecture

The SunRiser 8/10 uses a **WizFi360 Wi-Fi module** for network connectivity. The WizFi360 can only handle **one TCP connection at a time**. This single hardware constraint is the architectural keystone of the entire integration: rather than batching API calls, the integration staggers polling — one HTTP request per tick — ensuring the WizFi360 is never overwhelmed. The hardware limitation became a design discipline that makes the integration more reliable, not less.

---

### 03 — System Architecture

![](https://maker.wiznet.io/upload/ckeditor5/134261819%5F1779095002%2Epng)

---

### 04 — Why WizFi360? ⭐

#### 🔷 WizFi360 as a commercial-grade embedded Wi-Fi solution

The SunRiser 8/10 embeds the **WIZnet WizFi360** — WIZnet's AT-command based Wi-Fi module — as the device's sole network interface. The WizFi360 handles TCP/IP stack management entirely in hardware, offloading all network state from the ARM microcontroller so the MCU can focus on real-time PWM generation across 8 or 10 channels simultaneously.

#### 🔷 TCP mode — HTTP server on WizFi360

The WizFi360 operates in **TCP server mode**, accepting inbound HTTP/1.1 connections and passing request bodies to the SunRiser firmware over UART. This is a hardware-managed TCP socket — the WizFi360 handles the full TCP handshake, connection state, and data framing without any software TCP stack on the microcontroller side.

Key characteristic: the WizFi360's TCP socket accepts **one connection at a time**. Once a connection is active, any additional inbound attempt is rejected until the first is closed. This is the defining constraint that ha-sunriser was engineered around.

#### 🔷 The constraint that shaped an integration

Most HA integrations fire multiple API calls in a single update cycle. ha-sunriser cannot — and by respecting this, it achieves something rare: **zero dropped connections** in production. The staggered-polling coordinator design means the WizFi360 always has the connection it expects, and HA always gets the data it polls for. A connectivity binary sensor further monitors whether the WizFi360 responded on the last cycle, giving users an early warning system for network issues.

#### 🔷 Verified in production ✅

- 49 tagged releases, v1.7.1 latest (April 19, 2026)

- Full documentation site (mrinterbugs.github.io/ha-sunriser)

- Docker-based test environment (Dockerfile.test, pytest.ini, tests/ directory)

- Active GitHub Issues and Pull Requests demonstrating real-device usage

- Lovelace Day Planner card renders real device PWM data live

---

### 05 — Key Components

#### 🌐 WIZnet WizFi360 — TCP Server Mode (HTTP/1.1, single-socket)

WIZnet's embedded Wi-Fi module providing full TCP/IP connectivity for the SunRiser 8/10 ARM microcontroller via UART-AT interface. Operates in hardware-managed TCP server mode — one active connection at a time. This physical constraint is the core architectural driver of ha-sunriser's staggered polling design.

#### 🐍 Python 3 / Home Assistant Integration Framework

The integration (96.2% Python) is built on HA's `DataUpdateCoordinator` pattern. Handles entity discovery, state polling, service calls (backup, restore, reboot, log retrieval, planner read/write), and options flow for configurable poll intervals (5–3600 s) and scheduled daily reboots.

#### 📦 MessagePack Binary Protocol

Compact binary serialisation for all device communication — config reads/writes, state updates, planner data, and diagnostics. Implemented faithfully from the open-source SunRiser firmware as reference.

#### 🌡️ DS1820 Temperature Sensor (1-Wire)

Hardware temperature sensor attached to the SunRiser, exposed in HA as a sensor entity. Enables aquarium temperature monitoring, dashboard display, and HA automations (e.g., alert if temperature exceeds safe range).

#### 🎨 Custom Lovelace Day Planner Card (JavaScript)

Auto-registered card that renders all active PWM channel schedules as a 24-hour chart, using the same LED channel colours as the device's native web UI. Cached at startup — no extra device requests on page load.

#### ⚙️ HACS Distribution

Standard Home Assistant Community Store packaging with `hacs.json`, automated CI via GitHub Actions, and a full mkdocs documentation site — making the integration accessible to non-technical aquarium owners worldwide.

---

### 06 — Application Scenarios

#### 01. Smart Aquarium Dashboard

Combine SunRiser channel states, DS1820 temperature, and connectivity health in a single HA Lovelace dashboard alongside other tank sensors (pH, salinity, flow rate). One screen for the full tank picture.

#### 02. Voice-Controlled Maintenance Mode

Expose the Maintenance Mode switch to Home Assistant Cloud (Nabu Casa). Say *"Alexa, turn on tank maintenance mode"* to pause the lighting program during water changes — hands-free, no phone required. A single WizFi360 TCP call handles the toggle.

#### 03. Automated Light Backup Before Changes

Script a `sunriser.backup` call in HA before any schedule change. If the new planner doesn't work out, `sunriser.restore` sends the saved config back to the device — full rollback in one service call.

#### 04. Connectivity Alerting

The binary sensor fires when the WizFi360 misses a poll response. Use it in an HA automation to push a notification immediately if the SunRiser loses network — before the lighting program silently stops and the tank goes dark.

---

### Conclusion

> **ha-sunriser demonstrates that understanding hardware constraints at the chip level — here, the WizFi360's single-TCP-connection model — is what separates robust IoT integrations from brittle ones.**

- ✅ WizFi360 TCP server mode directly inspired the staggered-polling architecture

- ✅ MessagePack binary protocol implemented faithfully from open-source firmware

- ✅ 49 production releases — v1.7.1 current (April 2026)

- ✅ Full entity coverage: lights, switches, sensors, binary sensors, buttons, numbers, selects

- ✅ Custom Lovelace Day Planner card with live device data

- ✅ Alexa voice control via HA Cloud integration

- ✅ Backup/restore/reboot service actions

- ✅ Docker test environment + pytest suite

- ✅ HACS-installable with full documentation site

---

### Q&A

**Q: Why does ha-sunriser send only one HTTP request per polling tick, instead of batching?** A: The SunRiser 8/10's WizFi360 Wi-Fi module enforces a single-socket TCP constraint — only one active connection is accepted at a time. The staggered design is a direct architectural response to this WizFi360 hardware limitation, ensuring the integration never overwhelms the module and always receives clean responses.

**Q: What protocol does the SunRiser use, and why MessagePack instead of JSON or REST?** A: The SunRiser uses MessagePack over HTTP/1.1. On an ARM microcontroller with limited RAM and no HTTP/2 support, MessagePack provides compact binary serialisation that is both efficient to transmit over the WizFi360's UART link and easy to parse on the device side. The integration reverse-engineered this protocol from the open-source SunRiser firmware.

**Q: Can I monitor whether my SunRiser lost network connection?** A: Yes. The integration exposes a binary sensor that reports whether the device responded on the last WizFi360 poll cycle. If the WizFi360 drops off the network, HA reports the device as offline immediately — you can trigger automations or push notifications from there.

**Q: Is this integration affiliated with LEDaquaristik?** A: No. ha-sunriser is community-built, reverse-engineered from LEDaquaristik's open-source SunRiser firmware (GPL-3.0), and is not affiliated with or supported by LEDaquaristik.

**Original Link**: <https://maker.wiznet.io/Lihan__/projects/ha%2Dsunriser/>

---

---

## ha-sunriser — WizFi360 위에서 수족관 조명을 Home Assistant로 제어하다

`#WizFi360` `#HomeAssistant` `#TCP` `#SmartAquarium` `#HACS` `#PWM` `#MessagePack` `#IoT` `#LEDControl` `#WiFiModule`

> 📚 커뮤니티 개발 HA 통합 모듈 | 오픈소스 SunRiser 펌웨어 역공학 기반 49회 릴리즈(v1.7.1, 2026년 4월) — 실제 기기, 실제 사용자 환경에서 검증

---

### 01 — 이 프로젝트는 무엇인가?

LEDaquaristik.de의 **SunRiser 8/10** LED 컨트롤러를 사용하는 수족관 마니아들은 공통된 불편을 겪는다. 이 컨트롤러는 채널별 PWM 디밍, 일정 스케줄링, 온도 센싱, 날씨 시뮬레이션까지 갖추고 있지만 — 그 모든 데이터는 별도 웹 브라우저 UI 안에 갇혀 있다. 다른 스마트홈 기기들이 Home Assistant에 자연스럽게 통합되는 동안, SunRiser만은 여전히 로컬 네트워크의 섬처럼 존재한다.

**ha-sunriser**는 SunRiser 8/10을 Home Assistant의 완전한 네이티브 기기로 편입시킨다. HACS를 통해 설치하면 컨트롤러가 HA에 다음과 같이 나타난다: 채널별 조명 엔티티(0–100% 디밍), 유지보수 모드·타임랩스·DST 자동 추적용 스위치 엔티티, DS1820 온도 및 펌웨어 버전 센서, 그리고 기기 자체 웹 UI와 동일한 LED 색상으로 24시간 스케줄을 렌더링하는 커스텀 Lovelace 카드까지.

결과물: 수족관 조명 상태, 온도, 연결 상태, 플래너 스케줄 — 스마트홈 대시보드 하나에서 전부. 여기에 Alexa 음성 제어, HA 자동화, 백업/복원 서비스까지 덤으로 따라온다.

---

### 02 — 왜 HTTP 위에 MessagePack인가?

#### 🔷 임베디드 하드웨어에서의 바이너리 효율성

SunRiser 8/10은 [MessagePack](https://msgpack.org/) — 컴팩트한 바이너리 직렬화 포맷 — 으로 통신한다. RAM이 제한적이고 HTTP/2를 지원하지 않는 임베디드 시스템에서, MessagePack은 JSON보다 페이로드를 줄이면서도 스키마에 종속되지 않는다. 통합 모듈은 이 프로토콜을 충실히 구현해 모든 SunRiser 펌웨어 버전과의 완전한 호환성을 확보했다.

#### 🔷 오픈소스 펌웨어를 진실의 원천으로

이 통합은 [LEDaquaristik의 오픈소스 SunRiser 펌웨어](https://github.com/LEDaquaristik/sunriser)(GPL-3.0)를 역공학해 구축되었다. 모든 설정 키, PWM 범위(0–1000), API 엔드포인트는 기기 자체의 문서화된 내부 동작에 기반한다 — 추측이 아닌 공식 소스 코드에서 도출된 값들이다.

#### 🔷 WizFi360 제약이 아키텍처를 결정하다

SunRiser 8/10은 네트워크 연결을 위해 **WizFi360 Wi-Fi 모듈**을 탑재하고 있다. WizFi360은 **한 번에 하나의 TCP 연결**만 처리할 수 있다. 이 단일 하드웨어 제약이 통합 전체 아키텍처의 핵심축이다: API 호출을 배치로 묶는 대신, 통합은 폴링을 분산시킨다 — 틱당 HTTP 요청 하나. WizFi360이 과부하되는 일이 없도록 하는 하드웨어 존중 설계다. 하드웨어 한계가 오히려 신뢰성을 높이는 설계 규율이 된 것이다.

---

### 03 — 시스템 아키텍처

![](https://maker.wiznet.io/upload/ckeditor5/134261819%5F1779094719%2Epng)

---

### 04 — 왜 WizFi360인가? ⭐

#### 🔷 상용 등급 임베디드 Wi-Fi 솔루션으로서의 WizFi360

SunRiser 8/10은 기기의 유일한 네트워크 인터페이스로 **WIZnet WizFi360**을 내장한다. WizFi360은 TCP/IP 스택 관리 전체를 하드웨어에서 처리해, ARM MCU가 8~10개 채널에 걸친 실시간 PWM 생성에만 집중할 수 있게 해준다.

#### 🔷 TCP 모드 — WizFi360 위의 HTTP 서버

WizFi360은 **TCP 서버 모드**로 동작하며, 인바운드 HTTP/1.1 연결을 받아 요청 본문을 UART를 통해 SunRiser 펌웨어로 전달한다. MCU 측에는 소프트웨어 TCP 스택이 전혀 없다 — TCP 핸드셰이크, 연결 상태, 데이터 프레이밍 모두 WizFi360 하드웨어가 처리한다.

핵심 특성: WizFi360 TCP 소켓은 **한 번에 연결 하나**만 수락한다. 첫 번째 연결이 유지되는 동안 추가 인바운드 시도는 모두 거부된다. 이것이 ha-sunriser가 설계상 해결해야 했던 결정적 제약이다.

#### 🔷 아키텍처를 빚어낸 제약

대부분의 HA 통합은 한 번의 업데이트 사이클에 여러 API 호출을 묶어 보낸다. ha-sunriser는 그럴 수 없다 — 그리고 이 제약을 존중함으로써 드문 것을 달성한다: **프로덕션에서 연결 드랍 제로**. 분산 폴링 코디네이터 설계는 WizFi360이 항상 기대하는 연결을 받고, HA는 항상 폴링한 데이터를 얻는 것을 보장한다. 추가로 연결 바이너리 센서가 WizFi360 응답 여부를 모니터링해 네트워크 문제를 조기 경보한다.

#### 🔷 프로덕션 검증 ✅

- 49회 태그 릴리즈, v1.7.1 최신 (2026년 4월 19일)

- 전체 문서 사이트 (mrinterbugs.github.io/ha-sunriser)

- Docker 기반 테스트 환경 (Dockerfile.test, pytest.ini, tests/ 디렉토리)

- 실제 기기 사용을 증명하는 활성 GitHub Issues 및 Pull Requests

- Day Planner Lovelace 카드가 실기기 PWM 데이터를 실시간 렌더링

---

### 05 — 주요 구성 요소

#### 🌐 WIZnet WizFi360 — TCP 서버 모드 (HTTP/1.1, 단일 소켓)

SunRiser 8/10 ARM MCU에 UART-AT 인터페이스로 TCP/IP 연결을 제공하는 WIZnet 임베디드 Wi-Fi 모듈. 하드웨어 관리 TCP 서버 모드로 동작 — 동시 활성 연결 하나 제한. 이 물리적 제약이 ha-sunriser 분산 폴링 설계의 핵심 동인.

#### 🐍 Python 3 / Home Assistant 통합 프레임워크

HA의 `DataUpdateCoordinator` 패턴 기반으로 구축된 통합 (전체 코드의 96.2%가 Python). 엔티티 자동 발견, 상태 폴링, 서비스 호출(백업, 복원, 재부팅, 로그 수집, 플래너 읽기/쓰기), 옵션 플로우를 통한 폴링 간격(5–3600초) 및 일일 예약 재부팅 설정 지원.

#### 📦 MessagePack 바이너리 프로토콜

모든 기기 통신 — 설정 읽기/쓰기, 상태 업데이트, 플래너 데이터, 진단 — 에 사용되는 컴팩트 바이너리 직렬화. 오픈소스 SunRiser 펌웨어를 레퍼런스로 충실히 구현.

#### 🌡️ DS1820 온도 센서 (1-Wire)

SunRiser에 연결된 하드웨어 온도 센서. HA 센서 엔티티로 노출되어 수족관 온도 모니터링, 대시보드 표시, HA 자동화(예: 온도 이상 시 알림)에 활용 가능.

#### 🎨 커스텀 Lovelace Day Planner 카드 (JavaScript)

모든 활성 PWM 채널 스케줄을 24시간 차트로 렌더링하는 자동 등록 카드 — 기기 자체 웹 UI와 동일한 LED 채널 색상 사용. 시작 시 캐시되어 페이지 로드 시 기기에 추가 요청 없음.

#### ⚙️ HACS 배포

`hacs.json`, GitHub Actions CI 자동화, 전체 mkdocs 문서 사이트를 갖춘 표준 Home Assistant Community Store 패키징 — 비기술적인 수족관 애호가도 전 세계 어디서나 접근 가능.

---

### 06 — 적용 시나리오

#### 01. 스마트 수족관 대시보드

SunRiser 채널 상태, DS1820 온도, 연결 상태를 다른 수조 센서(pH, 염도, 유량)와 함께 HA Lovelace 대시보드 하나에 통합. 전체 수조 상황을 화면 하나로 파악.

#### 02. 음성 제어 유지보수 모드

유지보수 모드 스위치를 Home Assistant Cloud(Nabu Casa)에 노출하면 Alexa가 스마트홈 기기로 인식한다. 수조 물갈이 중 *"알렉사, 수조 유지보수 모드 켜줘"* 한 마디로 조명 프로그램을 일시 정지 — 손 하나 안 써도 된다. WizFi360 TCP 호출 하나가 토글을 처리한다.

#### 03. 변경 전 자동 설정 백업

HA 스크립트로 스케줄 변경 전 `sunriser.backup` 서비스를 호출한다. 새 플래너가 제대로 작동하지 않으면 `sunriser.restore`가 저장된 설정을 기기로 되돌린다 — 서비스 호출 하나로 전체 롤백 완료.

#### 04. 연결 상태 알림

WizFi360이 폴링 응답을 하지 않으면 바이너리 센서가 트리거된다. HA 자동화에서 이를 활용해 SunRiser가 네트워크를 잃는 즉시 푸시 알림 전송 — 조명 프로그램이 조용히 멈추고 수조가 어두워지기 전에 대응.

---

### 결론

> **ha-sunriser는 칩 수준의 하드웨어 제약 — 여기서는 WizFi360의 단일 TCP 연결 모델 — 을 깊이 이해하는 것이 견고한 IoT 통합과 취약한 통합을 가르는 차이임을 증명한다.**

- ✅ WizFi360 TCP 서버 모드가 분산 폴링 아키텍처의 직접적 동인

- ✅ 오픈소스 펌웨어에서 도출된 MessagePack 바이너리 프로토콜 충실 구현

- ✅ 49회 프로덕션 릴리즈 — v1.7.1 현재 (2026년 4월)

- ✅ 완전한 엔티티 커버리지: 조명, 스위치, 센서, 바이너리 센서, 버튼, 숫자, 선택

- ✅ 실기기 데이터 기반 커스텀 Lovelace Day Planner 카드

- ✅ HA Cloud 통합을 통한 Alexa 음성 제어

- ✅ 백업/복원/재부팅 서비스 액션

- ✅ Docker 테스트 환경 + pytest 테스트 스위트

- ✅ 전체 문서 사이트를 갖춘 HACS 배포

---

### Q&A

**Q: ha-sunriser는 왜 배치 요청 대신 틱당 HTTP 요청 하나만 보내나요?** A: SunRiser 8/10의 WizFi360 Wi-Fi 모듈은 단일 소켓 TCP 제약을 강제합니다 — 한 번에 하나의 활성 연결만 수락됩니다. 분산 설계는 이 WizFi360 하드웨어 한계에 대한 직접적인 아키텍처 대응으로, 통합이 모듈을 절대 과부하시키지 않고 항상 깔끔한 응답을 받게 보장합니다.

**Q: SunRiser는 어떤 프로토콜을 사용하고, 왜 JSON이나 REST 대신 MessagePack인가요?** A: SunRiser는 HTTP/1.1 위의 MessagePack을 사용합니다. RAM이 제한적이고 HTTP/2를 지원하지 않는 ARM MCU에서, MessagePack은 WizFi360의 UART 링크를 통해 전송하기에 효율적이면서 기기 측에서 파싱하기도 쉬운 컴팩트 바이너리 직렬화를 제공합니다. 통합은 오픈소스 SunRiser 펌웨어에서 이 프로토콜을 역공학했습니다.

**Q: SunRiser가 네트워크 연결을 잃었는지 모니터링할 수 있나요?** A: 네. 통합이 노출하는 바이너리 센서가 마지막 WizFi360 폴링 사이클에서 기기가 응답했는지 보고합니다. WizFi360이 네트워크에서 이탈하면 HA가 즉시 기기를 오프라인으로 표시합니다 — 여기서 자동화나 푸시 알림을 트리거할 수 있습니다.

**Q: 이 통합은 LEDaquaristik과 공식 제휴 관계인가요?** A: 아닙니다. ha-sunriser는 LEDaquaristik의 오픈소스 SunRiser 펌웨어(GPL-3.0)를 역공학해 커뮤니티가 독립적으로 구축한 프로젝트로, LEDaquaristik과 제휴하거나 공식 지원을 받지 않습니다.

---

Source: https://maker.wiznet.io/Lihan__/projects/ha-sunriser/