# jvandervyver/libvoltronic architecture

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

- Interactive diagram: https://gitdiagram.com/jvandervyver/libvoltronic
- Repository: https://github.com/jvandervyver/libvoltronic

## Overview

##### Project type and purpose
- This is a C-based driver library (“libvoltronic”) that exposes a single uniform API (voltronic_dev_t) for talking to Voltronic inverter devices.
- It supports multiple transport backends (RS-232 serial, USB HID) but shares a common protocol and CRC logic.
- The library is meant to be embedded in client applications (see src/serial_main.c and src/usb_main.c as examples).

##### File structure
- Top‐level files:
- Makefile, checkout_dependencies.sh – build and fetch vendored libs
- README.md, LICENSE – documentation & licensing
- / – public headers defining the API and transport interfaces:
- voltronic_dev.h (core API)
- voltronic_dev_serial.h, voltronic_dev_usb.h (factory functions for each backend)
- voltronic_crc.h (CRC helper)
- src/ – implementation of:
- Core protocol logic and API: voltronic_dev.c, voltronic_crc.c
- Concrete backends: voltronic_dev_serial_libserialport.c, voltronic_dev_usb_hidapi.c
- Example mains: serial_main.c, usb_main.c
- lib/ – vendored external dependencies: hidapi, libserialport, libusb
- obj/ – build artifacts

##### README for additional insights
- Describes the common command/response protocol with CRC16-XMODEM and reserved chars.
- Outlines supported transports: RS232 (via libserialport), USB HID (via HIDAPI/libusb), Bluetooth, RS485 (future).
- Explains build steps and target OS quirks.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Applications Layer
    subgraph "Client Applications"
        direction TB
        SerialMain["serial_main.c"]:::client
        USBMain["usb_main.c"]:::client
    end

    %% Public API Layer
    subgraph "Public API Layer"
        direction TB
        VoltronicDevH["voltronic_dev.h"]:::api
        VoltronicDevSerialH["voltronic_dev_serial.h"]:::api
        VoltronicDevUsbH["voltronic_dev_usb.h"]:::api
        VoltronicCrcH["voltronic_crc.h"]:::api
    end

    %% Core Protocol Engine Layer
    subgraph "Core Protocol Engine"
        direction TB
        VoltronicDevC["voltronic_dev.c"]:::core
        VoltronicCrcC["voltronic_crc.c"]:::core
        VoltronicDevImplH["voltronic_dev_impl.h"]:::core
    end

    %% Backend Adapters Layer
    subgraph "Backend Adapters"
        direction TB
        SerialBackendC["voltronic_dev_serial_libserialport.c"]:::backend
        SerialBackendH["voltronic_dev_serial.h"]:::backend
        UsbBackendC["voltronic_dev_usb_hidapi.c"]:::backend
        UsbBackendH["voltronic_dev_usb.h"]:::backend
    end

    %% External Dependencies Layer
    subgraph "External Dependencies"
        direction TB
        LibSerialPort["lib/libserialport"]:::external
        Hidapi["lib/hidapi"]:::external
        Libusb["lib/libusb"]:::external
    end

    %% OS/HW Layer
    subgraph "OS / Hardware"
        direction TB
        TTYDriver["Kernel TTY Driver"]:::oshw
        USBHIDStack["OS USB HID Stack"]:::oshw
    end

    %% Physical Device
    Device["Voltronic Inverter (Physical Device)"]:::device

    %% Build & Docs
    Makefile["Makefile"]:::build
    CheckoutDeps["checkout_dependencies.sh"]:::build
    Readme["README.md"]:::doc
    License["LICENSE"]:::doc

    %% Connections: Client to API
    SerialMain -->|calls| VoltronicDevH
    USBMain -->|calls| VoltronicDevH

    %% API to Core
    VoltronicDevH -->|implements| VoltronicDevC
    VoltronicCrcH -->|implements| VoltronicCrcC
    VoltronicDevC -->|includes| VoltronicDevImplH

    %% Core to Backends
    VoltronicDevC -->|delegates to| SerialBackendC
    VoltronicDevC -->|delegates to| UsbBackendC

    %% Backends to External libs
    SerialBackendC -->|uses| LibSerialPort
    UsbBackendC -->|uses| Hidapi
    UsbBackendC -->|uses| Libusb

    %% External libs to OS/HW
    LibSerialPort -->|via termios / DCB| TTYDriver
    Hidapi -->|via USB HID Raw| USBHIDStack
    Libusb -->|via USB HID Raw| USBHIDStack

    %% OS/HW to Device
    TTYDriver -->|RS-232| Device
    USBHIDStack -->|USB HID| Device

    %% Response paths (back)
    Device -->|returns data| USBHIDStack
    Device -->|returns data| TTYDriver
    USBHIDStack -->|read| UsbBackendC
    TTYDriver -->|read| SerialBackendC
    UsbBackendC -->|callback| VoltronicDevC
    SerialBackendC -->|callback| VoltronicDevC
    VoltronicDevC -->|returns payload| VoltronicDevH
    VoltronicDevH -->|delivers| SerialMain
    VoltronicDevH -->|delivers| USBMain

    %% Build & Documentation
    Makefile -->|builds| VoltronicDevC
    CheckoutDeps -->|fetches| LibSerialPort
    CheckoutDeps -->|fetches| Hidapi
    CheckoutDeps -->|fetches| Libusb
    Readme -.->|describes| VoltronicDevH
    Readme -.->|describes| SerialBackendC
    License -.->|applies to| VoltronicDevC

    %% Click Events
    click SerialMain "https://github.com/jvandervyver/libvoltronic/blob/master/src/serial_main.c"
    click USBMain "https://github.com/jvandervyver/libvoltronic/blob/master/src/usb_main.c"
    click VoltronicDevH "https://github.com/jvandervyver/libvoltronic/blob/master/include/voltronic_dev.h"
    click VoltronicDevSerialH "https://github.com/jvandervyver/libvoltronic/blob/master/include/voltronic_dev_serial.h"
    click VoltronicDevUsbH "https://github.com/jvandervyver/libvoltronic/blob/master/include/voltronic_dev_usb.h"
    click VoltronicCrcH "https://github.com/jvandervyver/libvoltronic/blob/master/include/voltronic_crc.h"
    click VoltronicDevC "https://github.com/jvandervyver/libvoltronic/blob/master/src/voltronic_dev.c"
    click VoltronicCrcC "https://github.com/jvandervyver/libvoltronic/blob/master/src/voltronic_crc.c"
    click VoltronicDevImplH "https://github.com/jvandervyver/libvoltronic/blob/master/src/voltronic_dev_impl.h"
    click SerialBackendC "https://github.com/jvandervyver/libvoltronic/blob/master/src/voltronic_dev_serial_libserialport.c"
    click SerialBackendH "https://github.com/jvandervyver/libvoltronic/blob/master/include/voltronic_dev_serial.h"
    click UsbBackendC "https://github.com/jvandervyver/libvoltronic/blob/master/src/voltronic_dev_usb_hidapi.c"
    click UsbBackendH "https://github.com/jvandervyver/libvoltronic/blob/master/include/voltronic_dev_usb.h"
    click LibSerialPort "https://github.com/jvandervyver/libvoltronic/tree/master/lib/libserialport"
    click Hidapi "https://github.com/jvandervyver/libvoltronic/tree/master/lib/hidapi"
    click Libusb "https://github.com/jvandervyver/libvoltronic/tree/master/lib/libusb"
    click Makefile "https://github.com/jvandervyver/libvoltronic/tree/master/Makefile"
    click CheckoutDeps "https://github.com/jvandervyver/libvoltronic/blob/master/checkout_dependencies.sh"
    click Readme "https://github.com/jvandervyver/libvoltronic/blob/master/README.md"
    click License "https://github.com/jvandervyver/libvoltronic/tree/master/LICENSE"

    %% Styles
    classDef client fill:#B3E5FC,stroke:#0288D1,color:#000
    classDef api fill:#BBDEFB,stroke:#1976D2,color:#000
    classDef core fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef backend fill:#FFE0B2,stroke:#F57C00,color:#000
    classDef external fill:#E0E0E0,stroke:#9E9E9E,color:#000
    classDef oshw fill:#90CAF9,stroke:#1976D2,color:#000
    classDef device fill:#1E88E5,stroke:#0D47A1,color:#fff
    classDef build fill:#F0F4C3,stroke:#827717,color:#000
    classDef doc fill:#F8BBD0,stroke:#C2185B,color:#000
```
