# tjoms99/xiao_sense_nrf52840_battery_lib architecture

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

- Interactive diagram: https://gitdiagram.com/tjoms99/xiao_sense_nrf52840_battery_lib
- Repository: https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib

## Overview

##### Project Type and Purpose
- This is an embedded firmware library project for the XIAO BLE and XIAO BLE Sense (nRF52840) boards.
- It provides a Zephyr‐based battery management subsystem: reading battery voltage via ADC, computing percentage, controlling charge current, and firing callbacks for voltage sampling and charge‐state changes.

##### File Structure Analysis
- Top‐level CMakeLists.txt and prj.conf: standard Zephyr build and configuration.
- boards/ + dts/: Zephyr board overlay files and device-tree bindings define hardware peripherals (ADC channels, charger GPIO lines).
- src/battery/: the battery management library implementation (battery.c/.h).
- src/main.c: example application showing library usage.

##### Key README Insights
- Describes API functions (voltage read, percentage, charge‐mode set, sampling, callbacks).
- Mentions Zephyr RTOS, Nordic nRF Connect SDK, Adafruit UF2 bootloader, and serial logging.

##### Main Components
A. Hardware Layer
- LiPo battery (3.7 V)
- Battery charger IC (connected to battery and MCU via GPIO/I²C)
- nRF52840 MCU with onboard ADC and GPIO
- USB interface for UF2 bootloader / serial logging
B. Zephyr RTOS Layer
- Kernel (scheduling, threads, timers)
- Device Drivers
– ADC driver (reads battery voltage pin)
– GPIO or I2C driver (toggles charger mode pin or communicates with charger IC)
- Device Tree & Board Overlays (boards/*.overlay, dts/*.yaml)
C. Battery Management Library
- Initialization (battery_init)
- ADC sampling logic (one‐shot and periodic via Zephyr work queue or timer)
- Charge‐mode control (fast/slow)
- Callback registry (charging state, sample ready)
D. Application Layer (main.c example)
- Calls battery_init()
- Registers callbacks
- Starts periodic sampling
- Receives callbacks → handles logging or UI

##### Relationships & Data Flow
1. On boot → Zephyr kernel initializes hardware per device tree.
2. battery_init() sets up ADC channel and charger control GPIO via Zephyr APIs.
3. One‐shot or periodic sampling:
– Library schedules a Zephyr timer or work item.
– ADC driver reads battery voltage.
– Measured millivolt value flows back to library.
– Library computes percentage and invokes registered sample callbacks.
4. Charge mode changes (battery_set_fast_charge / slow): library calls GPIO or I2C driver → charger IC.
5. Charger IC state changes trigger an interrupt or polling → library invokes charging state callback.
6. main.c application callback handlers log to serial console (via Zephyr logging subsystem).

##### Architectural Patterns & Principles
- Layered architecture: Hardware → Zephyr RTOS → Device Drivers → Battery Library → Application.
- Inversion of Control via callbacks: library does work, application supplies handlers.
- Decoupling via Device Tree: hardware details abstracted away from C code.
- RTOS primitives (timers, work queues) for scheduling periodic sampling.

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Hardware Layer"
    LiPo["LiPo Battery"]:::hardware
    Charger["Charger IC"]:::hardware
    MCU["nRF52840 MCU (ADC, GPIO)"]:::hardware
    USB["USB Interface (UF2 Bootloader / Serial)"]:::hardware
  end

  subgraph "Zephyr RTOS Layer"
    DTOver1["boards/xiao_ble_nrf52840.overlay"]:::config
    DTOver2["boards/xiao_ble_nrf52840_sense.overlay"]:::config
    DTBind["dts/bindings/xiao-ble-battery.yaml"]:::config
    Kernel["Zephyr Kernel"]:::rtos
    ADCDrv["ADC Driver"]:::rtos
    GPIODrv["GPIO/I2C Driver"]:::rtos
    Log["Logging Subsystem"]:::rtos
  end

  subgraph "Battery Management Library"
    API["Battery API (battery.h)"]:::library
    Init["battery_init()"]:::library
    Sampling["ADC Sampling Logic"]:::library
    ChargeCtrl["Charge-mode Control"]:::library
    Callbacks["Callback Registry"]:::library
  end

  subgraph "Application Layer"
    App["main.c Application"]:::app
  end

  subgraph "Build & Documentation"
    CMake["CMakeLists.txt"]:::config
    Prj["prj.conf"]:::config
    README["README.md"]:::config
  end

  LiPo -->|Voltage Source| ADCDrv
  Charger -->|Charge Control| GPIODrv
  USB -->|Serial Logging| Log

  DTOver1 --> Kernel
  DTOver2 --> Kernel
  DTBind --> Kernel

  Kernel --> ADCDrv
  Kernel --> GPIODrv
  Kernel --> Log

  API --> Init
  Init --> ADCDrv
  Init --> GPIODrv

  Sampling -->|schedule via Kernel| Kernel
  Sampling --> ADCDrv
  ADCDrv -->|millivolts| Sampling
  Sampling -->|invoke| Callbacks

  ChargeCtrl --> GPIODrv
  GPIODrv -->|set charger state| Charger
  Charger -->|state change| Callbacks

  Callbacks -->|notify| App
  App -->|calls| Init
  App -->|calls| Sampling
  App -->|calls| ChargeCtrl
  App -->|uses| Log

  CMake -->|configures build| Kernel
  Prj -->|RTOS config| Kernel
  README -->|docs| App

  click DTOver1 "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/boards/xiao_ble_nrf52840.overlay"
  click DTOver2 "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/boards/xiao_ble_nrf52840_sense.overlay"
  click DTBind "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/dts/bindings/xiao-ble-battery.yaml"
  click API "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/src/battery/battery.h"
  click Init "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/src/battery/battery.c"
  click Sampling "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/src/battery/battery.c"
  click ChargeCtrl "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/src/battery/battery.c"
  click Callbacks "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/src/battery/battery.c"
  click App "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/src/main.c"
  click CMake "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/CMakeLists.txt"
  click Prj "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/prj.conf"
  click README "https://github.com/tjoms99/xiao_sense_nrf52840_battery_lib/blob/main/README.md"

  classDef hardware fill:#cccccc,stroke:#333,stroke-width:1px
  classDef rtos fill:#88ccff,stroke:#333,stroke-width:1px
  classDef library fill:#88ff88,stroke:#333,stroke-width:1px
  classDef app fill:#ffcc88,stroke:#333,stroke-width:1px
  classDef config fill:#ccffee,stroke:#333,stroke-width:1px
```
