# atmosic/openair architecture

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

- Interactive diagram: https://gitdiagram.com/atmosic/openair
- Repository: https://github.com/atmosic/openair

## Overview

##### Project Type and Purpose
- This is an embedded‐firmware SDK (Atmosic Zephyr SDK) built on top of the Zephyr RTOS.
- It provides board support (ATMx2xx, ATM33xx), HAL modules, drivers, device trees, libraries, example applications, build‐tooling scripts, and west manifest integration to enable rapid development for Atmosic SoCs.

##### High‐Level Architectural Layers
- Host Toolchain & Orchestration
- Zephyr Build System (CMake + Kconfig + west)
- Zephyr RTOS Core & Subsystems
- Atmosic SoC Support (soc/, modules/hal_atmosic/, dts/)
- Platform Abstraction (drivers/, lib/)
- Board Support & Device Trees (boards/, applications/fmna_tag/)
- Firmware Artifacts (samples/, applications/, tests/)
- Deployment & Programming Tools (tools/scripts/)

##### Main Components and Relationships
a. Host Toolchain & Orchestration
- west (west.yml, west/…)
- Python scripts under tools/scripts/ (e.g., atm_openocd.py, atm_otp.py)
→ Orchestrates repo cloning, dependency fetch, build invocation, flashing, DFU.

b. Zephyr Build System
- CMakeLists.txt at top level, cmake/common.cmake
- Kconfig, Kconfig.sysbuild
- Uses west to assemble modules & passes configuration to CMake/Kconfig for building.

c. Zephyr RTOS Core & Subsystems
- zephyr/module.yml (pulls in the actual Zephyr kernel)
- subsys/ (settings, mgmt, etc.)
- dts/arm/atmosic/ and dts/bindings/ for device‐tree includes.

d. Atmosic SoC Support
- soc/atmosic/{ATM33, ATMx2}/ provides linker scripts, soc.c/h, default-configs.
- modules/hal_atmosic provides Hardware Abstraction Layer (power, PMU, AES, SHA, vendor drivers, BLE radio stack, OpenOCD scripts).

e. Platform Abstraction Libraries
- drivers/ (adc, gpio, i2c, serial, sensor, etc.)
- lib/ (utility libraries: atm_utils, mcuboot hooks, debug/auth, test_common)
→ Built as static objects or linked into the firmware.

f. Board Support & Device Trees
- boards/atmosic/… defines board .dts, .yaml, defconfigs, overlays.
- applications/fmna_tag/ a concrete example application with its own board overlays, project config, sample.yaml, main.c.

g. Firmware Artifacts
- samples/ and tests/ show example usage of drivers and subsystems.
- each sample has CMakeLists.txt, Kconfig, prj.conf, sample.yaml, source code, overlay files.
→ Illustrate how end users will write and build their own firmware.

h. Deployment & Programming Tools
- tools/scripts/ for partition info, DFU, tag data generation, secure‐boot unlocking, OpenOCD server scripts.
- sysbuild/ and scripts/sysbuild/ for sample project generation.

##### Architectural Patterns & Principles
- Layered / Separation of Concerns: each layer (kernel, HAL, drivers, board, app) is loosely coupled via build config and device‐tree includes.
- Modularity via west manifests, allowing independent inclusion and versioning of modules (hal_atmosic, soc, drivers).
- Hardware Abstraction: HAL (modules/hal_atmosic) sits between RTOS and SoC hardware.
- Configuration through Kconfig/prj.conf and YAML overlays ensures portable builds across boards.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "1. Host Toolchain & Orchestration"
        westManifest["west manifest"]:::buildTool
        westDir["west extensions"]:::buildTool
        scriptsOpenOCD["atm_openocd.py"]:::buildTool
        scriptsOTP["atm_otp.py"]:::buildTool
        scriptPartition["gen_atm_partition_info.py"]:::buildTool
        scriptTag["gen_tag_data_bin_file.py"]:::buildTool
        scriptDebug["sec_debug_unlock.py"]:::buildTool
        sysbuildUtils["sysbuild_utils.py"]:::buildTool
        sysbuildDir["sysbuild/"]:::buildTool
    end

    subgraph "2. Zephyr Build System"
        CMakeTop["CMakeLists.txt"]:::buildTool
        cmakeCommon["cmake/common.cmake"]:::buildTool
        KconfigTop["Kconfig"]:::config
        KconfigSysbuild["Kconfig.sysbuild"]:::config
    end

    subgraph "3. Zephyr RTOS Core & Subsystems"
        zephyrModule["zephyr/module.yml"]:::runtime
        subsys["subsys/"]:::runtime
        settingsSubsys["subsys/settings/"]:::runtime
        dtsArm["dts/arm/atmosic/"]:::runtime
        dtsBindings["dts/bindings/"]:::runtime
    end

    subgraph "4. Atmosic SoC Support"
        socATM33["soc/atmosic/ATM33/"]:::runtime
        socATMx2["soc/atmosic/ATMx2/"]:::runtime
        halATM33["modules/hal_atmosic/ATM33xx-5/"]:::runtime
        halATMx2["modules/hal_atmosic/ATMx2xx-x1x/"]:::runtime
    end

    subgraph "5. Platform Abstraction Libraries"
        driversDir["drivers/"]:::runtime
        libDir["lib/"]:::runtime
    end

    subgraph "6. Board Support & Device Trees"
        boardsDir["boards/atmosic/"]:::board
        appBoardOver["applications/fmna_tag/boards/"]:::board
        appDts["applications/fmna_tag/dts/"]:::board
    end

    subgraph "7. Firmware Artifacts"
        samplesDir["samples/"]:::app
        appFMNATag["applications/fmna_tag/"]:::app
        testsDir["tests/"]:::app
    end

    subgraph "8. Deployment & Programming Tools"
        sysbuildDir2["sysbuild/"]:::deploy
        scriptsSysbuild["tools/scripts/sysbuild/"]:::deploy
    end

    westManifest -->|"orchestrates"| CMakeTop
    westManifest -->|"orchestrates"| KconfigTop
    CMakeTop -->|"configures"| zephyrModule
    CMakeTop -->|"includes"| subsys
    CMakeTop -->|"includes"| settingsSubsys
    CMakeTop -->|"includes"| dtsArm
    CMakeTop -->|"includes"| dtsBindings
    CMakeTop -->|"includes"| socATM33
    CMakeTop -->|"includes"| socATMx2
    CMakeTop -->|"includes"| halATM33
    CMakeTop -->|"includes"| halATMx2
    CMakeTop -->|"includes"| driversDir
    CMakeTop -->|"includes"| libDir
    CMakeTop -->|"includes"| boardsDir
    CMakeTop -->|"produces"| samplesDir
    CMakeTop -->|"produces"| appFMNATag
    CMakeTop -->|"produces"| testsDir
    appFMNATag -->|"flashed via"| scriptsOpenOCD

    click westManifest "https://github.com/atmosic/openair/blob/main/west.yml"
    click westDir "https://github.com/atmosic/openair/tree/main/west/"
    click scriptsOpenOCD "https://github.com/atmosic/openair/blob/main/tools/scripts/atm_openocd.py"
    click scriptsOTP "https://github.com/atmosic/openair/blob/main/tools/scripts/atm_otp.py"
    click scriptPartition "https://github.com/atmosic/openair/blob/main/tools/scripts/gen_atm_partition_info.py"
    click scriptTag "https://github.com/atmosic/openair/blob/main/tools/scripts/gen_tag_data_bin_file.py"
    click scriptDebug "https://github.com/atmosic/openair/blob/main/tools/scripts/sec_debug_unlock.py"
    click sysbuildUtils "https://github.com/atmosic/openair/blob/main/tools/scripts/sysbuild_utils.py"
    click sysbuildDir "https://github.com/atmosic/openair/tree/main/tools/scripts/sysbuild/"
    click CMakeTop "https://github.com/atmosic/openair/blob/main/CMakeLists.txt"
    click cmakeCommon "https://github.com/atmosic/openair/blob/main/cmake/common.cmake"
    click KconfigTop "https://github.com/atmosic/openair/tree/main/Kconfig"
    click KconfigSysbuild "https://github.com/atmosic/openair/blob/main/sysbuild/Kconfig.sysbuild"
    click zephyrModule "https://github.com/atmosic/openair/blob/main/zephyr/module.yml"
    click subsys "https://github.com/atmosic/openair/tree/main/subsys/"
    click settingsSubsys "https://github.com/atmosic/openair/tree/main/subsys/settings/"
    click dtsArm "https://github.com/atmosic/openair/tree/main/dts/arm/atmosic/"
    click dtsBindings "https://github.com/atmosic/openair/tree/main/dts/bindings/"
    click socATM33 "https://github.com/atmosic/openair/tree/main/soc/atmosic/ATM33/"
    click socATMx2 "https://github.com/atmosic/openair/tree/main/soc/atmosic/ATMx2/"
    click halATM33 "https://github.com/atmosic/openair/tree/main/modules/hal_atmosic/ATM33xx-5/"
    click halATMx2 "https://github.com/atmosic/openair/tree/main/modules/hal_atmosic/ATMx2xx-x1x/"
    click driversDir "https://github.com/atmosic/openair/tree/main/drivers/"
    click libDir "https://github.com/atmosic/openair/tree/main/lib/"
    click boardsDir "https://github.com/atmosic/openair/tree/main/boards/atmosic/"
    click appBoardOver "https://github.com/atmosic/openair/tree/main/applications/fmna_tag/boards/"
    click appDts "https://github.com/atmosic/openair/tree/main/applications/fmna_tag/dts/"
    click samplesDir "https://github.com/atmosic/openair/tree/main/samples/"
    click appFMNATag "https://github.com/atmosic/openair/tree/main/applications/fmna_tag/"
    click testsDir "https://github.com/atmosic/openair/tree/main/tests/"
    click sysbuildDir2 "https://github.com/atmosic/openair/tree/main/sysbuild/"
    click scriptsSysbuild "https://github.com/atmosic/openair/tree/main/tools/scripts/sysbuild/"

    classDef buildTool fill:#88ccff,stroke:#333,stroke-width:1px
    classDef runtime fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef board fill:#ffcc88,stroke:#333,stroke-width:1px
    classDef app fill:#ffccff,stroke:#333,stroke-width:1px
    classDef deploy fill:#ff8888,stroke:#333,stroke-width:1px
    classDef config fill:#dddddd,stroke:#333,stroke-width:1px
```
