# heyokay/halobattery architecture

> Architecture diagram of the GitHub repository heyokay/halobattery, 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/heyokay/halobattery
- Repository: https://github.com/heyokay/halobattery

## Overview

Halo Battery is a Windows system-tray app that discovers wireless peripherals, reads their battery state through device-specific protocols or Windows APIs, and presents a separate icon per device. The main flow is polling providers, normalizing readings as device status, then rendering tray icons and exposing details and controls. Provider registration and shared HID discovery are useful internal layers. The README documents user-facing features and device support; source excerpts confirm selected provider and rendering behavior, but not the full application wiring.

Main entry points: [`providers/__init__.py`](https://github.com/heyokay/halobattery/blob/main/providers/__init__.py) (Provider registry), [`providers/hidlist.py`](https://github.com/heyokay/halobattery/blob/main/providers/hidlist.py) (HID discovery), [`providers/base.py`](https://github.com/heyokay/halobattery/blob/main/providers/base.py) (Device status), [`halo_battery.pyw`](https://github.com/heyokay/halobattery/blob/main/halo_battery.pyw) (App runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Tray application"]
  node_entry["App runtime<br/>[halo_battery.pyw]"]
  node_flyout["Tray controls<br/>[flyout.py]"]
  node_icons["Icon rendering<br/>[icons.py]"]
  node_history[("Battery history<br/>[history.py]")]
end

subgraph group_providers["Battery providers"]
  node_registry["Provider registry<br/>[__init__.py]"]
  node_hid_audio["HID audio providers<br/>[audeze.py]"]
  node_hid_brands["HID brand providers<br/>[razer.py]"]
  node_logitech["Logitech HID++<br/>[logitech.py]"]
  node_steelseries["SteelSeries devices<br/>[steelseries.py]"]
  node_wlmouse["WLmouse devices<br/>[wlmouse.py]"]
  node_bluetooth["Bluetooth provider<br/>[bluetooth.py]"]
  node_playstation["PlayStation provider<br/>[playstation.py]"]
  node_xinput["Xbox-style provider<br/>[xinput.py]"]
end

subgraph group_internal["Shared internals"]
  node_hid["HID discovery<br/>[hidlist.py]"]
  node_status["Device status<br/>[base.py]"]
end

subgraph group_platform["Windows and devices"]
  node_hid_devices{{"USB/HID devices"}}
  node_windows["Windows APIs"]
  node_bluetooth_devices{{"Bluetooth devices"}}
end

node_user(("User"))

node_user -->|"launches"| node_entry
node_entry -.->|"polls providers"| node_registry
node_registry -->|"registers"| node_hid_audio
node_registry -->|"registers"| node_hid_brands
node_registry -->|"registers"| node_logitech
node_registry -->|"registers"| node_steelseries
node_registry -->|"registers"| node_wlmouse
node_registry -->|"registers"| node_bluetooth
node_registry -->|"registers"| node_playstation
node_registry -->|"registers"| node_xinput
node_hid_audio -->|"enumerates"| node_hid
node_hid_brands -->|"enumerates"| node_hid
node_logitech -->|"enumerates"| node_hid
node_steelseries -->|"enumerates"| node_hid
node_wlmouse -->|"enumerates"| node_hid
node_playstation -->|"enumerates"| node_hid
node_xinput -->|"enumerates"| node_hid
node_hid_audio -->|"returns readings"| node_status
node_hid_brands -.->|"returns readings"| node_status
node_logitech -.->|"returns readings"| node_status
node_steelseries -->|"returns readings"| node_status
node_wlmouse -->|"returns readings"| node_status
node_bluetooth -->|"queries battery"| node_windows
node_bluetooth -.->|"returns readings"| node_status
node_windows -->|"reads state"| node_bluetooth_devices
node_playstation -->|"returns readings"| node_status
node_xinput -->|"queries reports"| node_windows
node_xinput -->|"returns readings"| node_status
node_hid -->|"discovers"| node_hid_devices
node_entry -.->|"shows controls"| node_flyout
node_flyout -.->|"configures display"| node_icons
node_entry -->|"renders tray"| node_icons
node_entry -.->|"tracks levels"| node_history
node_user -->|"opens controls"| node_flyout
node_user -->|"views status"| node_icons

click node_entry "https://github.com/heyokay/halobattery/blob/main/halo_battery.pyw"
click node_flyout "https://github.com/heyokay/halobattery/blob/main/flyout.py"
click node_icons "https://github.com/heyokay/halobattery/blob/main/icons.py"
click node_history "https://github.com/heyokay/halobattery/blob/main/history.py"
click node_registry "https://github.com/heyokay/halobattery/blob/main/providers/__init__.py"
click node_hid "https://github.com/heyokay/halobattery/blob/main/providers/hidlist.py"
click node_status "https://github.com/heyokay/halobattery/blob/main/providers/base.py"
click node_hid_audio "https://github.com/heyokay/halobattery/blob/main/providers/audeze.py"
click node_hid_brands "https://github.com/heyokay/halobattery/blob/main/providers/razer.py"
click node_logitech "https://github.com/heyokay/halobattery/blob/main/providers/logitech.py"
click node_steelseries "https://github.com/heyokay/halobattery/blob/main/providers/steelseries.py"
click node_wlmouse "https://github.com/heyokay/halobattery/blob/main/providers/wlmouse.py"
click node_bluetooth "https://github.com/heyokay/halobattery/blob/main/providers/bluetooth.py"
click node_playstation "https://github.com/heyokay/halobattery/blob/main/providers/playstation.py"
click node_xinput "https://github.com/heyokay/halobattery/blob/main/providers/xinput.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_entry,node_flyout,node_icons,node_history,node_user toneBlue
class node_registry,node_hid_audio,node_hid_brands,node_logitech,node_steelseries,node_wlmouse,node_bluetooth,node_playstation,node_xinput toneAmber
class node_hid,node_status toneMint
class node_hid_devices,node_windows,node_bluetooth_devices toneRose
```

## Components

### Tray application

- [App runtime](https://github.com/heyokay/halobattery/blob/main/halo_battery.pyw): `halo_battery.pyw`
- [Tray controls](https://github.com/heyokay/halobattery/blob/main/flyout.py): `flyout.py`
- [Icon rendering](https://github.com/heyokay/halobattery/blob/main/icons.py): `icons.py`
- [Battery history](https://github.com/heyokay/halobattery/blob/main/history.py): `history.py`

### Battery providers

- [Provider registry](https://github.com/heyokay/halobattery/blob/main/providers/__init__.py): `providers/__init__.py`
- [HID audio providers](https://github.com/heyokay/halobattery/blob/main/providers/audeze.py): `providers/audeze.py`
- [HID brand providers](https://github.com/heyokay/halobattery/blob/main/providers/razer.py): `providers/razer.py`
- [Logitech HID++](https://github.com/heyokay/halobattery/blob/main/providers/logitech.py): `providers/logitech.py`
- [SteelSeries devices](https://github.com/heyokay/halobattery/blob/main/providers/steelseries.py): `providers/steelseries.py`
- [WLmouse devices](https://github.com/heyokay/halobattery/blob/main/providers/wlmouse.py): `providers/wlmouse.py`
- [Bluetooth provider](https://github.com/heyokay/halobattery/blob/main/providers/bluetooth.py): `providers/bluetooth.py`
- [PlayStation provider](https://github.com/heyokay/halobattery/blob/main/providers/playstation.py): `providers/playstation.py`
- [Xbox-style provider](https://github.com/heyokay/halobattery/blob/main/providers/xinput.py): `providers/xinput.py`

### Shared internals

- [HID discovery](https://github.com/heyokay/halobattery/blob/main/providers/hidlist.py): `providers/hidlist.py`
- [Device status](https://github.com/heyokay/halobattery/blob/main/providers/base.py): `providers/base.py`

### Windows and devices

- **USB/HID devices**
- **Windows APIs**
- **Bluetooth devices**

### Other components

- **User**

## Connections

- User → App runtime: launches (evidence: `README.md`)
- App runtime → Provider registry: polls providers
- Provider registry → HID audio providers: registers (evidence: `providers/__init__.py`)
- Provider registry → HID brand providers: registers (evidence: `providers/__init__.py`)
- Provider registry → Logitech HID++: registers (evidence: `providers/__init__.py`)
- Provider registry → SteelSeries devices: registers (evidence: `providers/__init__.py`)
- Provider registry → WLmouse devices: registers (evidence: `providers/__init__.py`)
- Provider registry → Bluetooth provider: registers (evidence: `providers/__init__.py`)
- Provider registry → PlayStation provider: registers (evidence: `providers/__init__.py`)
- Provider registry → Xbox-style provider: registers (evidence: `providers/__init__.py`)
- HID audio providers → HID discovery: enumerates (evidence: `providers/audeze.py`)
- HID brand providers → HID discovery: enumerates (evidence: `providers/razer.py`)
- Logitech HID++ → HID discovery: enumerates (evidence: `providers/logitech.py`)
- SteelSeries devices → HID discovery: enumerates (evidence: `providers/steelseries.py`)
- WLmouse devices → HID discovery: enumerates (evidence: `providers/wlmouse.py`)
- PlayStation provider → HID discovery: enumerates (evidence: `providers/playstation.py`)
- Xbox-style provider → HID discovery: enumerates (evidence: `providers/xinput.py`)
- HID audio providers → Device status: returns readings (evidence: `providers/audeze.py`)
- HID brand providers → Device status: returns readings (evidence: `providers/razer.py`)
- Logitech HID++ → Device status: returns readings (evidence: `providers/logitech.py`)
- SteelSeries devices → Device status: returns readings (evidence: `providers/steelseries.py`)
- WLmouse devices → Device status: returns readings (evidence: `providers/wlmouse.py`)
- Bluetooth provider → Windows APIs: queries battery (evidence: `providers/bluetooth.py`)
- Bluetooth provider → Device status: returns readings (evidence: `providers/bluetooth.py`)
- Windows APIs → Bluetooth devices: reads state
- PlayStation provider → Device status: returns readings (evidence: `providers/playstation.py`)
- Xbox-style provider → Windows APIs: queries reports (evidence: `providers/xinput.py`)
- Xbox-style provider → Device status: returns readings (evidence: `providers/xinput.py`)
- HID discovery → USB/HID devices: discovers (evidence: `providers/hidlist.py`)
- App runtime → Tray controls: shows controls
- Tray controls → Icon rendering: configures display
- App runtime → Icon rendering: renders tray (evidence: `README.md`)
- App runtime → Battery history: tracks levels
- User → Tray controls: opens controls (evidence: `README.md`)
- User → Icon rendering: views status (evidence: `README.md`)
