ha-sunriser

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, 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 (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

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

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

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

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

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

03 — 시스템 아키텍처

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과 제휴하거나 공식 지원을 받지 않습니다.