How zigpy/bellows works
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.