# uv-software/pcanbasic-wrapper architecture

> Architecture diagram of the GitHub repository uv-software/pcanbasic-wrapper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uv-software/pcanbasic-wrapper
- Repository: https://github.com/uv-software/pcanbasic-wrapper

## Overview

##### Project Type and Purpose
- This is not a web or full-stack app but a hardware-interface wrapper library plus companion CLI tools, examples, and tests.
- Its core role is to provide a CAN API V3-compatible interface on Windows by wrapping PEAK-System’s PCANBasic DLL in both C++ (uvPeakCAN) and C (u3canpcb) flavors, and to ship command-line utilities (can_send, can_moni, can_test), usage examples (C++ and Python), and a GoogleTest-based test suite.

##### File Structure Analysis
- Top-level “Libraries” and “Sources” folders define two wrapper DLL projects:
- Libraries/CANAPI & Sources/CANAPI → C++ base classes and V3 API definitions
- Libraries/PeakCAN & Sources/PCANBasic → PeakCAN-specific wrapper implementations (uvPeakCAN DLL & u3canpcb DLL) built atop PCANBasic.lib/.dll
- Sources/Wrapper → C entry-point wrapper (can_api.h/.c)
- “Utilities” contains three standalone CLI tools, each with its own project and main()
- “Examples” are consumer code for C++ and Python that link/load the wrapper DLL
- “Tests” uses GoogleTest to exercise the wrapper through the public API
- Build scripts (.bat) and GitHub Actions MSBuild workflow orchestrate compilation for x86/x64; Doxygen directory holds doc config

##### README Insights
- Emphasizes a layered “wrapper over vendor DLL” architecture
- Describes two build targets (uvPeakCAN & u3canpcb) plus CLI utilities
- Notes external dependency on PCANBasic.dll and linkage via PCANBasic.lib
- Mentions Python example (likely using ctypes to load the C/C++ DLL)

a. Main Components
1) External PCANBasic DLL (vendor-provided, Windows)
2) Wrapper Layer
– uvPeakCAN.dll (C++ class CPeakCAN inheriting CCanApi)
– u3canpcb.dll (C API functions in can_api.h)
– Common core code in Sources/CANAPI, Sources/Wrapper
3) Consumer Applications
– CLI Tools: can_send.exe, can_moni.exe, can_test.exe
– Examples: C++ executables, Python scripts loading the DLL via CANAPI.py
– Test Suite: GoogleTest harness linking against u3canpcb.dll/uvPeakCAN.dll
4) Build & CI Infrastructure
– MSBuild .vcxproj files, .bat scripts, GitHub Actions
5) Documentation
– Doxygen-generated docs
– READMEMd, Deployment.md
b. Relationships & Data Flows
- The wrapper DLLs import PCANBasic symbols (via PCANBasic.lib) and expose a uniform CAN API
- Consumers (CLI, examples, tests) call into wrapper DLLs to send/receive CAN messages
- The wrapper marshals calls to PCANBasic.dll, which interacts with the hardware driver and USB device
- Build scripts sequence: generate build number → compile Sources → produce DLLs → link executables → run tests → publish artifacts
c. Architectural Patterns & Principles
- Layered Architecture:
[Applications / Tests] → [Wrapper DLL Layer] → [Vendor DLL] → [OS/Driver/Hardware]
- Wrapper/Adapter Pattern: unify multiple vendor interfaces under CAN API V3
- Separation of Concerns: core API definitions in CANAPI folder; PEAK-specific code in PeakCAN folders; CLI logic in Utilities
- Test-Driven: comprehensive GoogleTest suite for public API
d. Key Technologies & Frameworks
- C++11/C in Visual Studio (MSBuild .vcxproj)
- PCANBasic.lib/.dll (external)
- GoogleTest (unit tests)
- Doxygen (documentation)
- Python ctypes or similar (Examples/Python/CANAPI.py)
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Applications"
        CLI_SEND["can_send.exe"]:::clients
        CLI_MONI["can_moni.exe"]:::clients
        CLI_TEST_EXE["can_test.exe"]:::clients
        EX_CPP_SEND["C++ Example: can_send"]:::clients
        EX_CPP_RECV["C++ Example: can_recv"]:::clients
        EX_PY_SEND["Python Example: can_send.py"]:::clients
        EX_PY_RECV["Python Example: can_recv.py"]:::clients
        TEST_SUITE["GoogleTest Suite"]:::clients
    end

    subgraph "Wrapper Layer"
        CORE_API["Core API Definitions"]:::wrapper
        CPP_WRAPPER["uvPeakCAN.dll"]:::wrapper
        C_WRAPPER["u3canpcb.dll"]:::wrapper
    end

    subgraph "Vendor Layer"
        PCANBASIC["External PCANBasic.dll/lib"]:::vendor
    end

    OS_HW["OS Driver / Hardware"]:::vendor

    subgraph "Infrastructure"
        CI["GitHub Actions CI"]:::infra
        SCRIPTS["Build Scripts (.bat)"]:::infra
    end

    subgraph "Documentation"
        DOXY["Doxygen Docs"]:::docs
        README["README.md / Deployment.md"]:::docs
    end

    %% Data Flows
    CLI_SEND -->|"API calls"| CPP_WRAPPER
    CLI_MONI -->|"API calls"| CPP_WRAPPER
    CLI_TEST_EXE -->|"API calls"| C_WRAPPER
    EX_CPP_SEND -->|"Link/Load DLL"| CPP_WRAPPER
    EX_CPP_RECV -->|"Link/Load DLL"| CPP_WRAPPER
    EX_PY_SEND -->|"ctypes Load"| C_WRAPPER
    EX_PY_RECV -->|"ctypes Load"| C_WRAPPER
    TEST_SUITE -->|"Link against DLLs"| CPP_WRAPPER
    TEST_SUITE -->|"Link against DLLs"| C_WRAPPER

    CPP_WRAPPER -->|"Load via PCANBasic.lib"| PCANBASIC
    C_WRAPPER -->|"Load via PCANBasic.lib"| PCANBASIC
    PCANBASIC -->|"Driver interaction over USB CAN frames"| OS_HW

    SCRIPTS -->|build| CORE_API
    SCRIPTS -->|build| CPP_WRAPPER
    SCRIPTS -->|build| C_WRAPPER
    SCRIPTS -->|build| CLI_SEND
    SCRIPTS -->|build| CLI_MONI
    SCRIPTS -->|build| CLI_TEST_EXE
    SCRIPTS -->|build| TEST_SUITE

    CI -->|runs| SCRIPTS
    CI -->|runs tests| TEST_SUITE

    DOXY -->|"generates docs from code"| CORE_API
    README -->|"guides users"| CLI_SEND

    %% Click Events
    click PCANBASIC "https://github.com/uv-software/pcanbasic-wrapper/blob/main/Sources/PCANBasic/x64/PCANBasic.lib"
    click CORE_API "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Libraries/CANAPI"
    click CPP_WRAPPER "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Libraries/PeakCAN"
    click C_WRAPPER "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Sources/Wrapper"
    click CLI_SEND "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Utilities/can_send"
    click CLI_MONI "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Utilities/can_moni"
    click CLI_TEST_EXE "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Utilities/can_test"
    click EX_CPP_SEND "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Examples/C++"
    click EX_CPP_RECV "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Examples/C++"
    click EX_PY_SEND "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Examples/Python"
    click EX_PY_RECV "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Examples/Python"
    click TEST_SUITE "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Tests/GoogleTest"
    click CI "https://github.com/uv-software/pcanbasic-wrapper/blob/main/.github/workflows/msbuild.yml"
    click SCRIPTS "https://github.com/uv-software/pcanbasic-wrapper/blob/main/build_no.bat"
    click DOXY "https://github.com/uv-software/pcanbasic-wrapper/tree/main/Doxygen/Doxyfile"
    click README "https://github.com/uv-software/pcanbasic-wrapper/blob/main/README.md"

    %% Styles
    classDef wrapper fill:#bbdefb,stroke:#1e88e5,stroke-width:1px;
    classDef vendor fill:#c8e6c9,stroke:#43a047,stroke-width:1px;
    classDef clients fill:#ffe0b2,stroke:#fb8c00,stroke-width:1px;
    classDef infra fill:#e0e0e0,stroke:#757575,stroke-width:1px;
    classDef docs fill:#fff9c4,stroke:#fbc02d,stroke-width:1px;
```
