# home-assistant-libs/aioshelly architecture

> Architecture diagram of the GitHub repository home-assistant-libs/aioshelly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/home-assistant-libs/aioshelly
- Repository: https://github.com/home-assistant-libs/aioshelly

## Overview

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: [`aioshelly/rpc_device/device.py`](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/device.py) (RPC device client), [`aioshelly/common.py`](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/common.py) (Connection utilities), [`aioshelly/block_device/device.py`](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/block_device/device.py) (Block device client), [`aioshelly/ble/backend/scanner.py`](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/backend/scanner.py) (BLE scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared foundations"]
  node_common["Connection utilities<br/>[common.py]"]
  node_constants["Device catalog<br/>[const.py]"]
  node_errors["Error types<br/>[exceptions.py]"]
  node_json["JSON helpers<br/>[json.py]"]
end

subgraph group_gen1["Gen1 CoAP"]
  node_gen1client["Block device client<br/>[device.py]"]
  node_coap["CoAP transport<br/>[coap.py]"]
  node_gen1blocks["Device blocks<br/>[device.py]"]
end

subgraph group_rpc["Gen2+ RPC"]
  node_rpcclient["RPC device client<br/>[device.py]"]
  node_wsrpc["WebSocket RPC<br/>[wsrpc.py]"]
  node_blerpc["BLE RPC transport<br/>[blerpc.py]"]
  node_rpcmodels["RPC models<br/>[models.py]"]
  node_wsserver["WebSocket server<br/>[wsrpc.py]"]
end

subgraph group_ble["Bluetooth LE"]
  node_bleconfig["BLE script control<br/>[__init__.py]"]
  node_blescanner["BLE scanner<br/>[scanner.py]"]
  node_bleparser["Advertisement parser<br/>[parser.py]"]
  node_blemanufacturer["Manufacturer data"]
  node_bleprovision["BLE provisioning<br/>[provisioning.py]"]
end

node_caller(("Library caller"))
node_shelly(("Shelly device"))
node_bleactor(("Bluetooth scanner host"))

node_caller -->|"creates Gen1 client"| node_gen1client
node_caller -->|"creates RPC client"| node_rpcclient
node_gen1client -->|"sends CoAP requests"| node_coap
node_gen1client -->|"builds blocks"| node_gen1blocks
node_gen1client -->|"processes options"| node_common
node_coap -->|"exchanges CoAP"| node_shelly
node_rpcclient -->|"uses transport"| node_wsrpc
node_rpcclient -->|"uses BLE RPC"| node_blerpc
node_rpcclient -->|"uses models"| node_rpcmodels
node_rpcclient -->|"processes options"| node_common
node_rpcclient -->|"calls device RPC"| node_shelly
node_wsserver -.->|"serves callbacks"| node_rpcclient
node_blescanner -->|"parses events"| node_bleparser
node_blescanner -->|"toggles scan mode"| node_bleconfig
node_blescanner -.->|"provides advertisements"| node_bleactor
node_bleprovision -->|"uses connection options"| node_common
node_bleprovision -->|"uses RPC models"| node_rpcmodels
node_common -->|"fetches device info"| node_shelly
node_common -->|"uses device settings"| node_constants
node_common -->|"raises connection errors"| node_errors
node_gen1client -->|"raises device errors"| node_errors
node_rpcclient -->|"raises RPC errors"| node_errors
node_wsrpc -->|"encodes RPC frames"| node_json
node_coap -->|"uses JSON helpers"| node_json

click node_gen1client "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/block_device/device.py"
click node_coap "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/block_device/coap.py"
click node_gen1blocks "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/block_device/device.py"
click node_rpcclient "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/device.py"
click node_wsrpc "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/wsrpc.py"
click node_blerpc "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/blerpc.py"
click node_rpcmodels "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/models.py"
click node_wsserver "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/wsrpc.py"
click node_bleconfig "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/__init__.py"
click node_blescanner "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/backend/scanner.py"
click node_bleparser "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/parser.py"
click node_blemanufacturer "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/manufacturer_data.py"
click node_bleprovision "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/provisioning.py"
click node_common "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/common.py"
click node_constants "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/const.py"
click node_errors "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/exceptions.py"
click node_json "https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/json.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_common,node_constants,node_errors,node_json toneBlue
class node_gen1client,node_coap,node_gen1blocks toneAmber
class node_rpcclient,node_wsrpc,node_blerpc,node_rpcmodels,node_wsserver toneMint
class node_bleconfig,node_blescanner,node_bleparser,node_blemanufacturer,node_bleprovision toneRose
class node_caller,node_shelly,node_bleactor toneIndigo
```

## Components

### Shared foundations

- [Connection utilities](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/common.py): `aioshelly/common.py`
- [Device catalog](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/const.py): `aioshelly/const.py`
- [Error types](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/exceptions.py): `aioshelly/exceptions.py`
- [JSON helpers](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/json.py): `aioshelly/json.py`

### Gen1 CoAP

- [Block device client](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/block_device/device.py): `aioshelly/block_device/device.py`
- [CoAP transport](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/block_device/coap.py): `aioshelly/block_device/coap.py`
- [Device blocks](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/block_device/device.py): `aioshelly/block_device/device.py`

### Gen2+ RPC

- [RPC device client](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/device.py): `aioshelly/rpc_device/device.py`
- [WebSocket RPC](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/wsrpc.py): `aioshelly/rpc_device/wsrpc.py`
- [BLE RPC transport](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/blerpc.py): `aioshelly/rpc_device/blerpc.py`
- [RPC models](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/models.py): `aioshelly/rpc_device/models.py`
- [WebSocket server](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/rpc_device/wsrpc.py): `aioshelly/rpc_device/wsrpc.py`

### Bluetooth LE

- [BLE script control](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/__init__.py): `aioshelly/ble/__init__.py`
- [BLE scanner](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/backend/scanner.py): `aioshelly/ble/backend/scanner.py`
- [Advertisement parser](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/parser.py): `aioshelly/ble/parser.py`
- [Manufacturer data](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/manufacturer_data.py): `aioshelly/ble/manufacturer_data.py`
- [BLE provisioning](https://github.com/home-assistant-libs/aioshelly/blob/main/aioshelly/ble/provisioning.py): `aioshelly/ble/provisioning.py`

### Other components

- **Library caller**
- **Shelly device**
- **Bluetooth scanner host**

## Connections

- Library caller → Block device client: creates Gen1 client (evidence: `README.md`)
- Library caller → RPC device client: creates RPC client (evidence: `README.md`)
- Block device client → CoAP transport: sends CoAP requests (evidence: `aioshelly/block_device/device.py`)
- Block device client → Device blocks: builds blocks (evidence: `aioshelly/block_device/device.py`)
- Block device client → Connection utilities: processes options (evidence: `aioshelly/block_device/device.py`)
- CoAP transport → Shelly device: exchanges CoAP (evidence: `aioshelly/block_device/coap.py`)
- RPC device client → WebSocket RPC: uses transport (evidence: `aioshelly/rpc_device/device.py`)
- RPC device client → BLE RPC transport: uses BLE RPC (evidence: `aioshelly/rpc_device/device.py`)
- RPC device client → RPC models: uses models (evidence: `aioshelly/rpc_device/device.py`)
- RPC device client → Connection utilities: processes options (evidence: `aioshelly/rpc_device/device.py`)
- RPC device client → Shelly device: calls device RPC (evidence: `README.md`)
- WebSocket server → RPC device client: serves callbacks (evidence: `aioshelly/rpc_device/device.py`)
- BLE scanner → Advertisement parser: parses events (evidence: `aioshelly/ble/backend/scanner.py`)
- BLE scanner → BLE script control: toggles scan mode (evidence: `aioshelly/ble/backend/scanner.py`)
- BLE scanner → Bluetooth scanner host: provides advertisements
- BLE provisioning → Connection utilities: uses connection options (evidence: `aioshelly/ble/provisioning.py`)
- BLE provisioning → RPC models: uses RPC models (evidence: `aioshelly/ble/provisioning.py`)
- Connection utilities → Shelly device: fetches device info (evidence: `aioshelly/common.py`)
- Connection utilities → Device catalog: uses device settings (evidence: `aioshelly/common.py`)
- Connection utilities → Error types: raises connection errors (evidence: `aioshelly/common.py`)
- Block device client → Error types: raises device errors (evidence: `aioshelly/block_device/device.py`)
- RPC device client → Error types: raises RPC errors (evidence: `aioshelly/rpc_device/device.py`)
- WebSocket RPC → JSON helpers: encodes RPC frames (evidence: `aioshelly/rpc_device/wsrpc.py`)
- CoAP transport → JSON helpers: uses JSON helpers (evidence: `aioshelly/block_device/coap.py`)
