# shadow5688/homebridge-atomberg-fan architecture

> Architecture diagram of the GitHub repository shadow5688/homebridge-atomberg-fan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shadow5688/homebridge-atomberg-fan
- Repository: https://github.com/shadow5688/homebridge-atomberg-fan

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Plugin Code"
        IDX["index.ts"]:::internal
        PLT["platform.ts"]:::internal
        ACC["platformAccessory.ts"]:::internal
        API["atombergApi.ts"]:::internal
        LST["broadcastListener.ts"]:::internal
        SET["settings.ts"]:::internal
        MOD["model.ts"]:::internal
    end

    CFG["config.schema.json\n(User Config)"]:::config
    HB["Homebridge Core + HAP"]:::homebridge
    CLOUD["Atomberg Public API"]:::cloud
    UDP["LAN Broadcast (UDP)"]:::broadcast

    CFG -->|loads via settings| SET
    IDX -->|initializes platform| PLT
    SET --> PLT
    PLT -->|creates accessories| ACC
    ACC -->|control requests| API
    ACC -->|listens to broadcasts| LST
    API -->|GET /devices| CLOUD
    API -->|POST /control| CLOUD
    CLOUD <-->|token refresh| API
    UDP -->|UDP status JSON| LST
    LST -->|emits updates| PLT
    PLT -->|registers accessories| HB
    HB -->|loads plugin| IDX
    ACC <-->|HAP characteristic updates| HB

    click IDX "https://github.com/shadow5688/homebridge-atomberg-fan/blob/latest/src/index.ts"
    click PLT "https://github.com/shadow5688/homebridge-atomberg-fan/blob/latest/src/platform.ts"
    click ACC "https://github.com/shadow5688/homebridge-atomberg-fan/blob/latest/src/platformAccessory.ts"
    click API "https://github.com/shadow5688/homebridge-atomberg-fan/blob/latest/src/atombergApi.ts"
    click LST "https://github.com/shadow5688/homebridge-atomberg-fan/blob/latest/src/broadcastListener.ts"
    click SET "https://github.com/shadow5688/homebridge-atomberg-fan/blob/latest/src/settings.ts"
    click MOD "https://github.com/shadow5688/homebridge-atomberg-fan/blob/latest/src/model.ts"
    click CFG "https://github.com/shadow5688/homebridge-atomberg-fan/blob/latest/config.schema.json"

    classDef internal fill:#D6EFFF,stroke:#333,stroke-width:1px
    classDef cloud fill:#CFFFCF,stroke:#333,stroke-width:1px
    classDef homebridge fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef broadcast fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef config fill:#FFF9C4,stroke:#333,stroke-width:1px
```
