# flip-dots/solixble architecture

> Architecture diagram of the GitHub repository flip-dots/solixble, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flip-dots/solixble
- Repository: https://github.com/flip-dots/solixble

## Overview

SolixBLE is a Python library for discovering, monitoring, and controlling Anker Solix/Prime devices over Bluetooth. Its user-facing workflow is scanning for devices, selecting a supported model, connecting and negotiating a session, then exchanging telemetry and control commands. Device-specific modules define model behavior; shared packet structures and protocol implementations support the runtime. The README documents the capabilities and BLE workflow, but several implementation links are omitted because the supplied excerpts do not show their call sites.

Main entry points: [`SolixBLE/device.py`](https://github.com/flip-dots/solixble/blob/main/SolixBLE/device.py) (Device connection), [`SolixBLE/factory.py`](https://github.com/flip-dots/solixble/blob/main/SolixBLE/factory.py) (Device factory), [`SolixBLE/utilities.py`](https://github.com/flip-dots/solixble/blob/main/SolixBLE/utilities.py) (BLE scanning), [`SolixBLE/devices`](https://github.com/flip-dots/solixble/tree/main/SolixBLE/devices) (Supported models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery and selection"]
  node_scan["BLE scanning<br/>[utilities.py]"]
  node_advertisement["Advertisement parsing<br/>[advertisement.py]"]
  node_factory["Device factory<br/>[factory.py]"]
end

subgraph group_runtime["Device runtime"]
  node_device["Device connection<br/>[device.py]"]
  node_prime["Prime behavior<br/>[prime_device.py]"]
  node_transport["BLE transport<br/>[transport.py]"]
end

subgraph group_models["Device models"]
  node_models["Supported models"]
  node_states["Telemetry states<br/>[states.py]"]
end

subgraph group_protocol["Protocol and encoding"]
  node_constants["Protocol constants<br/>[const.py]"]
  node_packet["Packet encoding<br/>[constructs.py]"]
  node_session["Negotiated session<br/>[session.py]"]
  node_ecdh["ECDH key exchange<br/>[ecdh.py]"]
  node_outer["Outer protocol<br/>[outer.py]"]
end

node_user(("Library user"))
node_bleak["Bleak Bluetooth"]

node_user -->|"scans for"| node_scan
node_scan -->|"uses scanner"| node_bleak
node_factory -->|"parses records"| node_advertisement
node_factory -->|"selects models"| node_models
node_models -->|"specializes"| node_device
node_prime -->|"specializes"| node_device
node_device -->|"builds packets"| node_packet
node_session -->|"sends negotiation"| node_device
node_ecdh -->|"advances stages"| node_session

click node_scan "https://github.com/flip-dots/solixble/blob/main/SolixBLE/utilities.py"
click node_advertisement "https://github.com/flip-dots/solixble/blob/main/SolixBLE/advertisement.py"
click node_factory "https://github.com/flip-dots/solixble/blob/main/SolixBLE/factory.py"
click node_device "https://github.com/flip-dots/solixble/blob/main/SolixBLE/device.py"
click node_prime "https://github.com/flip-dots/solixble/blob/main/SolixBLE/prime_device.py"
click node_transport "https://github.com/flip-dots/solixble/blob/main/SolixBLE/transport.py"
click node_models "https://github.com/flip-dots/solixble/tree/main/SolixBLE/devices"
click node_states "https://github.com/flip-dots/solixble/blob/main/SolixBLE/states.py"
click node_constants "https://github.com/flip-dots/solixble/blob/main/SolixBLE/const.py"
click node_packet "https://github.com/flip-dots/solixble/blob/main/SolixBLE/constructs.py"
click node_session "https://github.com/flip-dots/solixble/blob/main/SolixBLE/protocols/session.py"
click node_ecdh "https://github.com/flip-dots/solixble/blob/main/SolixBLE/protocols/ecdh.py"
click node_outer "https://github.com/flip-dots/solixble/blob/main/SolixBLE/protocols/outer.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_scan,node_advertisement,node_factory,node_user toneBlue
class node_device,node_prime,node_transport toneAmber
class node_models,node_states toneMint
class node_constants,node_packet,node_session,node_ecdh,node_outer toneRose
class node_bleak toneIndigo
```

## Components

### Discovery and selection

- [BLE scanning](https://github.com/flip-dots/solixble/blob/main/SolixBLE/utilities.py): `SolixBLE/utilities.py`
- [Advertisement parsing](https://github.com/flip-dots/solixble/blob/main/SolixBLE/advertisement.py): `SolixBLE/advertisement.py`
- [Device factory](https://github.com/flip-dots/solixble/blob/main/SolixBLE/factory.py): `SolixBLE/factory.py`

### Device runtime

- [Device connection](https://github.com/flip-dots/solixble/blob/main/SolixBLE/device.py): `SolixBLE/device.py`
- [Prime behavior](https://github.com/flip-dots/solixble/blob/main/SolixBLE/prime_device.py): `SolixBLE/prime_device.py`
- [BLE transport](https://github.com/flip-dots/solixble/blob/main/SolixBLE/transport.py): `SolixBLE/transport.py`

### Device models

- [Supported models](https://github.com/flip-dots/solixble/tree/main/SolixBLE/devices): `SolixBLE/devices`
- [Telemetry states](https://github.com/flip-dots/solixble/blob/main/SolixBLE/states.py): `SolixBLE/states.py`

### Protocol and encoding

- [Protocol constants](https://github.com/flip-dots/solixble/blob/main/SolixBLE/const.py): `SolixBLE/const.py`
- [Packet encoding](https://github.com/flip-dots/solixble/blob/main/SolixBLE/constructs.py): `SolixBLE/constructs.py`
- [Negotiated session](https://github.com/flip-dots/solixble/blob/main/SolixBLE/protocols/session.py): `SolixBLE/protocols/session.py`
- [ECDH key exchange](https://github.com/flip-dots/solixble/blob/main/SolixBLE/protocols/ecdh.py): `SolixBLE/protocols/ecdh.py`
- [Outer protocol](https://github.com/flip-dots/solixble/blob/main/SolixBLE/protocols/outer.py): `SolixBLE/protocols/outer.py`

### Other components

- **Library user**
- **Bleak Bluetooth**

## Connections

- Library user → BLE scanning: scans for (evidence: `README.md`)
- BLE scanning → Bleak Bluetooth: uses scanner (evidence: `SolixBLE/utilities.py`)
- Device factory → Advertisement parsing: parses records (evidence: `SolixBLE/factory.py`)
- Device factory → Supported models: selects models (evidence: `SolixBLE/factory.py`)
- Supported models → Device connection: specializes (evidence: `SolixBLE/devices/c1000.py`)
- Prime behavior → Device connection: specializes (evidence: `SolixBLE/prime_device.py`)
- Device connection → Packet encoding: builds packets (evidence: `SolixBLE/device.py`)
- Negotiated session → Device connection: sends negotiation (evidence: `SolixBLE/protocols/session.py`)
- ECDH key exchange → Negotiated session: advances stages (evidence: `SolixBLE/protocols/ecdh.py`)
