How shadow5688/homebridge-atomberg-fan works
Project type and purpose
• This is a Homebridge platform plugin written in TypeScript.
• Its purpose is to discover and control Atomberg smart fans in HomeKit, using Atomberg’s public REST APIs and listening to LAN broadcasts for state updates.
File structure
• Top-level config files:
– package.json / tsconfig.json / config.schema.json define build, runtime, and Homebridge config schema.
– nodemon.json and .eslintrc are developer tools.
• src/ directory (core logic):
– atombergApi.ts: wrapper around Atomberg REST API for fetch, control, token refresh.
– broadcastListener.ts: listens for UDP/JSON status broadcasts from fans on the local network.
– model.ts: defines TypeScript interfaces for device state.
– settings.ts: loads and validates user config (apiKey, refreshToken).
– platform.ts: implements Homebridge’s Platform API (registers accessories, handles polling/updates).
– platformAccessory.ts: maps each physical fan to a HomeKit Accessory, wiring characteristics to API calls or broadcasts.
– index.ts: entry point that tells Homebridge to load your platform.
README for insights
• Confirms this is a Homebridge plugin (platform).
• Mentions two data sources: Atomberg public API and LAN broadcasts.
• Describes setup and configuration via Homebridge UI or config.json.
Main components & interactions
a. Homebridge Core
– Loads your plugin (index.ts → platform.ts).
– Hosts the HAP-NodeJS engine that mediates HomeKit traffic.
b. Plugin Configuration
– settings.ts + config.schema.json
– User supplies apiKey & refreshToken via Homebridge UI or config.json.
c. Atomberg Public Cloud API
– atombergApi.ts calls REST endpoints to list devices, read/write state, refresh tokens.
d. LAN Broadcast Channel
– broadcastListener.ts opens a UDP socket on local network to receive unsolicited status updates from fans.
e. Platform Module
– platform.ts orchestrates:
• On startup: load settings, call atombergApi.listDevices(), instantiate platformAccessory for each fan.
• On HomeKit characteristic set: route through platformAccessory → atombergApi control call.
• On broadcast message: update the corresponding accessory’s state in HAP.
f. PlatformAccessory
– platformAccessory.ts implements the Homebridge Accessory API to map device state ↔ HomeKit characteristics.
Architectural patterns & design principles
• Plugin Pattern (Homebridge Platform)
• Event-driven updates (broadcastListener emitting updates)
• Adapter Layer (platformAccessory adapts Atomberg model to HAP)
• Configuration Schema (config.schema.json) driving dynamic platform creation.