# zigpy/bellows architecture

> Architecture diagram of the GitHub repository zigpy/bellows, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zigpy/bellows
- Repository: https://github.com/zigpy/bellows

## Overview

##### Project type and purpose
- bellows is not a web-app or microservice but a Python 3 library + CLI tool that implements the EZSP (EmberZNet Serial Protocol) interface to drive Silicon Labs EM35x/EFR32 Zigbee NCP hardware.
- Primary goal: give Home Assistant’s ZHA integration native control of Ember/EFR32-based USB sticks over UART.

##### High-level file structure & patterns
- bellows/cli – presentation layer: exposes subcommands (application, network, dump, backup, tone, stream, etc.)
- bellows/ash – implements ASH framing over UART
- bellows/uart – low-level serial port wrapper
- bellows/ezsp – protocol layer: versioned subpackages (v4–v14), fragmentation, config, protocol API
- bellows/zigbee – domain layer: ZDO, ZCL and device utilities
- bellows/types & bellows/config – shared data models and configuration
- tests/ – full coverage of commands, protocols, types, persistence
- scripts & CI configs for packaging, linting, publishing

##### Key insights from README
- Layered architecture from CLI → library API → EZSP → ASH → UART → NCP firmware → Zigbee network
- Supports multiple EZSP versions by swapping in the matching commands/config modules
- Provides an application framework including device state persistence, ZDO/ZCL functionality

##### Components
a. CLI Layer
­– bellows/cli/main.py & subcommands → invokes Core API
b. Core Library API & Application Framework
­– bellows/application.py, state persistence, high-level network operations
c. EZSP Protocol Handler
­– bellows/ezsp/protocol.py + versioned modules (v4–v14)
d. ASH Transport
­– bellows/ash.py handles framing, packet retry, keep-alive
e. Serial/UART Interface
­– bellows/uart.py wraps pyserial/socket URLs
f. NCP Firmware (external)
­– EmberZNet PRO on EM35x/EFR32 implements EZSP on the device side
g. Zigbee Network
­– IEEE 802.15.4 mesh of end devices, routers, coordinator

##### Relationships & data flow
– CLI invokes Core API → Core API calls EZSP Handler → EZSP Handler uses ASH → ASH frames over UART → NCP receives commands, manipulates Zigbee network → responses flow back up
– Core API also exposes callbacks/events (ZDO, ZCL notifications) back to CLI or to zigpy/Home Assistant

##### Architectural patterns & principles
- Layered design – clear separation between presentation (CLI), application logic, protocol, transport, hardware
- Pluggable protocol versions – version directories under bellows/ezsp for backward compatibility
- Single Responsibility – each module focuses on a single layer or function
- Extensibility points: add new EZSP versions, new CLI commands, new device repair utilities

##### Detail level reminder
- Essential architectural elements but avoid listing every single file.
- How CLI commands map to core API methods, how those map to EZSP calls, and how those traverse ASH/UART to the NCP.
- Persistence (state database) within the Core API block if desired.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        CLI["CLI Layer\n(bellows/cli)"]:::presentation
    end

    subgraph "Application Layer"
        CORE["Core API & App Framework\n(bellows/zigbee/application.py)"]:::application
    end

    subgraph "Protocol/Transport Layer"
        subgraph "EZSP Protocol Handler"
            EZSP["Protocol API\n(bellows/ezsp/protocol.py)"]:::protocol
            FRAG["Fragmentation\n(bellows/ezsp/fragmentation.py)"]:::protocol
            EZSPCONF["EZSP Config\n(bellows/ezsp/config.py)"]:::protocol
            subgraph "Versioned Modules"
                VERSIONS["v4–v14\n(bellows/ezsp/v4…v14)"]:::protocol
            end
        end
        ASH["ASH Transport\n(bellows/ash.py)"]:::protocol
        UART["Serial/UART Interface\n(bellows/uart.py)"]:::protocol
    end

    subgraph "Hardware Layer"
        NCP["NCP Firmware\n(EmberZNet PRO)"]:::hardware
        ZNET["Zigbee Network\n(IEEE 802.15.4 mesh)"]:::hardware
    end

    CLI -->|"invokes"| CORE
    CORE -->|"calls"| EZSP
    EZSP -->|"uses"| FRAG
    EZSP -->|"reads config"| EZSPCONF
    EZSP -->|"selects version"| VERSIONS
    EZSP -->|"frames data to"| ASH
    ASH -->|"UART write/read"| UART
    UART -->|"commands to"| NCP
    NCP -->|"manipulates network"| ZNET
    ZNET -->|"responses"| NCP
    NCP -->|"responses"| UART
    UART -->|"frames"| ASH
    ASH -->|"response to"| EZSP
    EZSP -->|"response to"| CORE
    CORE -->|"notifies"| CLI

    CORE -->|"events/callbacks"| HA["zigpy/Home Assistant ZHA"]:::external

    classDef presentation fill:#D0E6FF,stroke:#000
    classDef application fill:#DFF2BF,stroke:#000
    classDef protocol fill:#FFDDAA,stroke:#000
    classDef hardware fill:#E0E0E0,stroke:#000
    classDef external fill:#F0F0F0,stroke:#000

    click CLI "https://github.com/zigpy/bellows/blob/dev/bellows/cli/main.py"
    click CLI "https://github.com/zigpy/bellows/tree/dev/bellows/cli/"
    click CORE "https://github.com/zigpy/bellows/blob/dev/bellows/zigbee/application.py"
    click EZSP "https://github.com/zigpy/bellows/blob/dev/bellows/ezsp/protocol.py"
    click FRAG "https://github.com/zigpy/bellows/blob/dev/bellows/ezsp/fragmentation.py"
    click EZSPCONF "https://github.com/zigpy/bellows/blob/dev/bellows/ezsp/config.py"
    click ASH "https://github.com/zigpy/bellows/blob/dev/bellows/ash.py"
    click UART "https://github.com/zigpy/bellows/blob/dev/bellows/uart.py"
    click VERSIONS "https://github.com/zigpy/bellows/tree/dev/bellows/ezsp/v4"
```
