# tuxt/max17048-smbus architecture

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

- Interactive diagram: https://gitdiagram.com/tuxt/max17048-smbus
- Repository: https://github.com/tuxt/max17048-smbus

## Overview

##### Project type and purpose
- This is an open-source Python library for communicating with the MAX17048/49 battery fuel gauge over SMBus/I²C on Linux (e.g., Raspberry Pi).
- It exposes a high-level Python API (MAX17048 class) for reading state-of-charge and voltage, while abstracting over multiple SMBus backends (`smbus`, `smbus2`, `smbus3`).

##### File structure
- Top level
- pyproject.toml / README.md / LICENSE / .gitignore – packaging & metadata
- max1704x_smbus/ – library source code
- tests/ – unit tests
- In max1704x_smbus/
- core.py – `MAX17048` entry point, public API
- smbus_loader.py – backend selection & dynamic import of `smbus`/`smbus2`/`smbus3`
- i2c_device.py – generic I²C device read/write wrapper
- register.py – bit-field abstraction for registers
- protocols.py – constants (addresses, command sequences)

##### README for additional insights
- Describes features (SoC, voltage) and dependency on an external SMBus backend.

a. Main components
- User application (Python script or REPL)
- max1704x_smbus library
– core (MAX17048 class)
– smbus_loader (backend adapter)
– i2c_device (I²C abstraction)
– register & protocols (register maps/bitfields)
- SMBus backend module (smbus / smbus2 / smbus3)
- Linux I²C kernel driver (OS level)
- MAX17048 hardware device

b. Relationships & interactions
1. User code → calls MAX17048 methods (core).
2. Core → on init, invokes smbus_loader to select and import backend.
3. MAX17048 uses i2c_device to perform read/write operations.
4. i2c_device delegates to the chosen SMBus backend API.
5. SMBus backend issues ioctl calls through Linux I²C kernel driver.
6. I²C bus wires communicate with the MAX17048 chip, which returns register data.
7. register & protocols modules interpret raw reads into human-readable SoC/voltage.

c. Architectural patterns & principles
- Adapter pattern: smbus_loader abstracts over multiple backend implementations.
- Layered architecture:
- High-level API (core)
- Device abstraction (i2c_device)
- Backend drivers (smbus modules)
- Physical I²C bus & hardware
- Single responsibility: each module focuses on one concern (protocol mapping, I²C I/O, class interface).

d. Key technologies & libraries
- Python ≥3.8
- smbus / smbus2 / smbus3 (I²C backends)
- Linux I²C subsystem (kernel)
- pytest (tests)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Application Layer"
        User["User Application\n(Python Script / REPL)"]:::external
    end

    subgraph "Library Internals"
        Init["Library Init\n(__init__.py)"]:::internal
        Core["MAX17048 Core API\n(core.py)"]:::internal
        Loader["SMBus Backend Loader\n(smbus_loader.py)"]:::internal
        Device["I²C Device Abstraction\n(i2c_device.py)"]:::internal
        Register["Register Bit-field Definitions\n(register.py)"]:::internal
        Protocols["Protocol Constants\n(protocols.py)"]:::internal
    end

    subgraph "Backend Modules"
        SMBus["smbus"]:::backend
        SMBus2["smbus2"]:::backend
        SMBus3["smbus3"]:::backend
    end

    subgraph "OS & Hardware"
        Kernel["Linux I²C Kernel Driver"]:::os
        Hardware["MAX17048 Hardware Device"]:::hardware
    end

    subgraph "Testing Suite"
        Conftest["Test Config & Fixtures\n(conftest.py)"]:::tests
        TestI2C["Test I²C Device\n(test_i2c_device.py)"]:::tests
        TestReg["Test Register Module\n(test_register.py)"]:::tests
    end

    subgraph "Documentation & Packaging"
        Pyproject["Project Metadata & Packaging\n(pyproject.toml)"]:::docs
        Readme["Documentation & Usage Guide\n(README.md)"]:::docs
        License["License Information\n(LICENSE)"]:::docs
        Gitignore["Git Ignore Rules\n(.gitignore)"]:::docs
    end

    %% Connections
    User -->|"uses"| Core
    Core -->|"imports on init"| Loader
    Core -->|"uses"| Device
    Core -->|"interprets data via"| Register
    Core -->|"interprets data via"| Protocols
    Loader -->|"selects backend"| SMBus
    Loader -->|"selects backend"| SMBus2
    Loader -->|"selects backend"| SMBus3
    Device -->|"delegates I²C calls to"| SMBus
    Device -->|"delegates I²C calls to"| SMBus2
    Device -->|"delegates I²C calls to"| SMBus3
    SMBus -->|"ioctl calls via"| Kernel
    SMBus2 -->|"ioctl calls via"| Kernel
    SMBus3 -->|"ioctl calls via"| Kernel
    Kernel -->|"I²C bus communication"| Hardware
    Hardware -->|"sends data back"| Kernel
    Kernel -->|"returns data to"| Device
    Conftest --> TestI2C
    Conftest --> TestReg
    TestI2C -->|"tests"| Device
    TestReg -->|"tests"| Register

    %% Click Events
    click Core "https://github.com/tuxt/max17048-smbus/blob/main/max1704x_smbus/core.py"
    click Loader "https://github.com/tuxt/max17048-smbus/blob/main/max1704x_smbus/smbus_loader.py"
    click Device "https://github.com/tuxt/max17048-smbus/blob/main/max1704x_smbus/i2c_device.py"
    click Register "https://github.com/tuxt/max17048-smbus/blob/main/max1704x_smbus/register.py"
    click Protocols "https://github.com/tuxt/max17048-smbus/blob/main/max1704x_smbus/protocols.py"
    click Init "https://github.com/tuxt/max17048-smbus/blob/main/max1704x_smbus/__init__.py"
    click TestI2C "https://github.com/tuxt/max17048-smbus/blob/main/tests/test_i2c_device.py"
    click TestReg "https://github.com/tuxt/max17048-smbus/blob/main/tests/test_register.py"
    click Conftest "https://github.com/tuxt/max17048-smbus/blob/main/tests/conftest.py"
    click Pyproject "https://github.com/tuxt/max17048-smbus/blob/main/pyproject.toml"
    click Readme "https://github.com/tuxt/max17048-smbus/blob/main/README.md"
    click License "https://github.com/tuxt/max17048-smbus/tree/main/LICENSE"
    click Gitignore "https://github.com/tuxt/max17048-smbus/blob/main/.gitignore"

    %% Styles
    classDef internal fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef backend fill:#cceeff,stroke:#333,stroke-width:1px
    classDef os fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef hardware fill:#ffd9b3,stroke:#333,stroke-width:1px
    classDef external fill:#ffffff,stroke:#333,stroke-width:1px
    classDef tests fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef docs fill:#f2f2f2,stroke:#333,stroke-width:1px
```
