# wirepas/wm-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/wirepas/wm-sdk
- Repository: https://github.com/wirepas/wm-sdk

## Overview

##### Project type and purpose
- It is an embedded Single-MCU SDK for Wirepas wireless mesh applications.
- Purpose: provide HAL, board support, libraries, APIs, bootloader, build scripts, and examples to compile a complete firmware image (.hex/.a) that runs on various MCUs (nRF, EFR32, etc.) with the Wirepas binary stack.

##### Main components
1.  Host environment
– GCC Arm toolchain
– Python 3.x + pycryptodome
– Make, Doxygen, Docker (for docs)
– Python helper scripts under tools/
2.  Build system
– Top-level Makefile + makefile_common.mk
– Sub-makefiles: makefile_app.mk, makefile_stack.mk, makefile_bootloader.mk, etc.
– Invokes compilation and linking of each layer
3.  Wirepas binaries (proprietary)
– .a, .hex, .conf files placed in image/
– Linked into final firmware images
4.  Core SDK layers (source/)
a. API layer (api/*.h) – public C interfaces exposed to application
b. HAL & MCU drivers (mcu/, board/) – board support packages, peripheral drivers, CMSIS, linker scripts, INI files
c. Libraries (libraries/) – positioning, provisioning, scheduler, dual-MCU, shared_xxx modules
d. Utility code (util/) – CRC, AES, CBOR, debug, pack, ring buffers, etc.
5.  Bootloader (bootloader/)
– early_init, external_flash, hardware interface
– buildable as standalone image or integrated
6.  Example & reference applications (source/example_*/, source/reference_*/, source/unitary_*/)
– Demonstrate usage of API and libraries
7.  Documentation (projects/doxygen/)
– Doxygen templates, CSS, scripts
– Generates HTML hosted at wirepas.github.io/wm-sdk

##### Relationships & data flow
– Toolchain, Python & scripts, Makefiles, Doxygen.
- Build System orchestrates:
– Compile HAL & board support → produce object files
– Compile util & libraries → static libs (.a)
– Compile application source → object files
– Link application + libraries + API + Wirepas binaries → final firmware (.hex)
– Build bootloader similarly
- That Wirepas binaries in image/ are injected at link time.
- Output: firmware images per board/app under build/<board>/<app>/

##### Architectural patterns & principles
– Layered architecture: Hardware Abstraction → Core Libraries → API → Application
– Board-abstraction via board/ + mcu/
– Plug-in examples: easy to swap apps without touching SDK internals
– Modular libraries: single responsibility (e.g., provisioning, positioning)
– Build-system driven by make macros for maximum portability

##### Putting it all together
– In the middle, stack the layered SDK components from bottom (HAL) up to top (Application).
– Optionally, include a separate “Documentation Generator” flow from source code → Doxygen → HTML.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Environment
    subgraph "Host Environment"
        direction TB
        Toolchain(["GCC Arm Toolchain"]):::host
        Python(["Python 3.x + pycryptodome"]):::host
        Make(["Make"]):::host
        Doxygen(["Doxygen"]):::host
        Scripts(["Python Helper Scripts"]):::host
    end
    click Scripts "https://github.com/wirepas/wm-sdk/tree/master/tools/"

    %% CI & Docs Workflows
    CI(["CI & Docs Workflows"]):::host
    click CI "https://github.com/wirepas/wm-sdk/tree/master/.github/workflows/"

    %% Build System
    subgraph "Build System" 
        direction TB
        Makefile(["Top-level Makefile"]):::build
        CommonMk(["makefile_common.mk"]):::build
        AppMk(["makefile_app.mk"]):::build
        StackMk(["makefile_stack.mk"]):::build
        BootMk(["makefile_bootloader.mk"]):::build
    end
    click Makefile "https://github.com/wirepas/wm-sdk/tree/master/makefile"
    click CommonMk "https://github.com/wirepas/wm-sdk/blob/master/makefile_common.mk"
    click AppMk "https://github.com/wirepas/wm-sdk/blob/master/makefile_app.mk"
    click StackMk "https://github.com/wirepas/wm-sdk/blob/master/makefile_stack.mk"
    click BootMk "https://github.com/wirepas/wm-sdk/blob/master/makefile_bootloader.mk"

    %% SDK Layers
    subgraph "Wirepas SDK" 
        direction TB
        subgraph "HAL & MCU Drivers"
            direction TB
            Board(["board/"]):::sdk
            MCU(["mcu/"]):::sdk
        end
        click Board "https://github.com/wirepas/wm-sdk/tree/master/board/"
        click MCU "https://github.com/wirepas/wm-sdk/tree/master/mcu/"

        Util(["Utility Code"]):::sdk
        click Util "https://github.com/wirepas/wm-sdk/tree/master/util/"

        Libraries(["Core Libraries"]):::sdk
        click Libraries "https://github.com/wirepas/wm-sdk/tree/master/libraries/"

        API(["API Layer"]):::sdk
        click API "https://github.com/wirepas/wm-sdk/blob/master/api/wms_app.h"

        subgraph "Bootloader"
            direction TB
            BootSrc(["bootloader/"]):::boot
            BootTest(["bootloader_test/"]):::boot
        end
        click BootSrc "https://github.com/wirepas/wm-sdk/tree/master/bootloader/"
        click BootTest "https://github.com/wirepas/wm-sdk/tree/master/bootloader_test/"

        subgraph "Examples & Applications"
            direction TB
            Examples(["Example Apps"]):::app
            Reference(["Reference Apps"]):::app
            Unitary(["Unitary/Test Apps"]):::app
        end
        click Examples "https://github.com/wirepas/wm-sdk/tree/master/source/example_apps/"
        click Reference "https://github.com/wirepas/wm-sdk/tree/master/source/reference_apps/"
        click Unitary "https://github.com/wirepas/wm-sdk/tree/master/source/unitary_apps/"
    end

    %% Proprietary Binaries
    Binaries(["Wirepas Proprietary Binaries"]):::binary
    click Binaries "https://github.com/wirepas/wm-sdk/tree/master/image/"

    %% Outputs
    Artifacts(["Firmware Images"]):::binary

    %% Documentation Generator
    DoxGen(["Doxygen Generator"]):::host
    click DoxGen "https://github.com/wirepas/wm-sdk/tree/master/projects/doxygen/"

    %% Connections
    Toolchain -->|invoke make| Makefile
    Python --> Makefile
    Make --> Makefile
    Scripts --> Makefile
    CI --> Makefile
    Doxygen --> DoxGen

    Makefile -->|"includes"| CommonMk
    CommonMk --> AppMk
    CommonMk --> StackMk
    CommonMk --> BootMk

    Makefile -->|"orchestrates"| Board
    Makefile --> MCU
    Makefile --> Util
    Makefile --> Libraries
    Makefile --> API
    Makefile --> Examples
    Makefile --> Reference
    Makefile --> Unitary
    Makefile --> Binaries

    Board -->|"compile"| Util
    MCU --> Util
    Util --> Libraries
    Libraries --> API
    API --> Examples
    API --> Reference
    API --> Unitary

    AppMk -->|"compile app"| Examples
    StackMk -->|"link stack"| Binaries
    BootMk -->|"build bootloader"| BootSrc

    Binaries -->|"link into"| Artifacts
    Examples --> Artifacts
    Reference --> Artifacts
    Unitary --> Artifacts
    BootSrc --> Artifacts

    Artifacts -->|"deploy to"| Board

    %% Styles
    classDef host fill:#add8e6,stroke:#000;
    classDef sdk fill:#90ee90,stroke:#000;
    classDef binary fill:#ffa500,stroke:#000;
    classDef app fill:#ffff99,stroke:#000;
    classDef boot fill:#d3d3d3,stroke:#000;
    classDef build fill:#dda0dd,stroke:#000;
```
