How home-assistant-libs/aioshelly works
Aioshelly is an asynchronous Python library for controlling Shelly devices across generations. Its principal workflow is that a caller supplies connection options and a session, creates a generation-appropriate device client, and then reads status or invokes device operations. Gen1 uses CoAP plus HTTP; Gen2+ uses RPC over WebSocket, with separate BLE scanning and provisioning capabilities. The graph reflects documented workflows and source-index references; unsampled subsystem internals and uncertain links are omitted.
Main entry points: rpc_device/device.py RPC device client · common.py Connection utilities · block_device/device.py Block device client · scanner.py BLE scanner
Components 20
Shared foundations
- Connection utilities
aioshelly/common.py - Device catalog
aioshelly/const.py - Error types
aioshelly/exceptions.py - JSON helpers
aioshelly/json.py
Gen1 CoAP
- Block device client
aioshelly/block_device/device.py - CoAP transport
aioshelly/block_device/coap.py - Device blocks
aioshelly/block_device/device.py
Gen2+ RPC
- RPC device client
aioshelly/rpc_device/device.py - WebSocket RPC
aioshelly/rpc_device/wsrpc.py - BLE RPC transport
aioshelly/rpc_device/blerpc.py - RPC models
aioshelly/rpc_device/models.py - WebSocket server
aioshelly/rpc_device/wsrpc.py
Bluetooth LE
- BLE script control
aioshelly/ble/__init__.py - BLE scanner
aioshelly/ble/backend/scanner.py - Advertisement parser
aioshelly/ble/parser.py - Manufacturer data
aioshelly/ble/manufacturer_data.py - BLE provisioning
aioshelly/ble/provisioning.py
Other components
- Library caller
- Shelly device
- Bluetooth scanner host
Connections 24
- Library caller → Block device client: creates Gen1 client
README.md - Library caller → RPC device client: creates RPC client
README.md - Block device client → CoAP transport: sends CoAP requests
aioshelly/block_device/device.py - Block device client → Device blocks: builds blocks
aioshelly/block_device/device.py - Block device client → Connection utilities: processes options
aioshelly/block_device/device.py - CoAP transport → Shelly device: exchanges CoAP
aioshelly/block_device/coap.py - RPC device client → WebSocket RPC: uses transport
aioshelly/rpc_device/device.py - RPC device client → BLE RPC transport: uses BLE RPC
aioshelly/rpc_device/device.py - RPC device client → RPC models: uses models
aioshelly/rpc_device/device.py - RPC device client → Connection utilities: processes options
aioshelly/rpc_device/device.py - RPC device client → Shelly device: calls device RPC
README.md - WebSocket server → RPC device client: serves callbacks
aioshelly/rpc_device/device.py - BLE scanner → Advertisement parser: parses events
aioshelly/ble/backend/scanner.py - BLE scanner → BLE script control: toggles scan mode
aioshelly/ble/backend/scanner.py - BLE scanner → Bluetooth scanner host: provides advertisements
- BLE provisioning → Connection utilities: uses connection options
aioshelly/ble/provisioning.py - BLE provisioning → RPC models: uses RPC models
aioshelly/ble/provisioning.py - Connection utilities → Shelly device: fetches device info
aioshelly/common.py - Connection utilities → Device catalog: uses device settings
aioshelly/common.py - Connection utilities → Error types: raises connection errors
aioshelly/common.py - Block device client → Error types: raises device errors
aioshelly/block_device/device.py - RPC device client → Error types: raises RPC errors
aioshelly/rpc_device/device.py - WebSocket RPC → JSON helpers: encodes RPC frames
aioshelly/rpc_device/wsrpc.py - CoAP transport → JSON helpers: uses JSON helpers
aioshelly/block_device/coap.py