# msfet7/kl05z_level_counter architecture

> Architecture diagram of the GitHub repository msfet7/kl05z_level_counter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/msfet7/kl05z_level_counter
- Repository: https://github.com/msfet7/kl05z_level_counter

## Overview

1. **Project type and target**
   - This is bare-metal firmware for the **NXP MKL05Z4 / FRDM-KL05Z** board, not a desktop or web app.
   - The runtime is a single MCU image built around **CMSIS** and the vendor device pack, with no RTOS visible in the tree.

2. **Core system role**
   - The firmware implements a **“Level Counter”**: it reads motion data from an **MMA8451Q accelerometer** and detects walking up/down stairs using a fused state machine.
   - The user-facing output is shown on a **2x16 LCD**, with a button and an extra header pin used as inputs.

3. **Platform and startup layer**
   - `.cmsis/` contains the ARM CMSIS core headers used across Cortex-M builds.
   - `.pack/myPack7x5/` contains the **MKL05Z4 device support package**: startup assembly, system clock setup, SVD files, and flash programming assets.
   - These files define the low-level execution boundary: reset/startup, device registers, and debugging/programming metadata.

4. **Board support / hardware abstraction**
   - `lib/frdm_bsp.h` and `lib/boardControl.c/.h` are the board-specific abstraction layer.
   - This layer centralizes pin mapping and electrical configuration from the README, including:
     - UART on **PTB1/PTB2**
     - shared I2C on **PTB3/PTB4**
     - button on **PTB6**
     - extra input/header on **PTB7**
     - accelerometer interrupt on **PTA10**
   - It is the boundary between generic application logic and the FRDM-KL05Z hardware wiring.

5. **Shared I2C bus**
   - `lib/i2c.c/.h` is the bus driver used by multiple peripherals.
   - Both the **MMA8451Q accelerometer** and the **LCD1602 I2C backpack** sit on the same I2C lines, so this module is a key shared dependency and serialization point.

6. **Accelerometer subsystem**
   - `lib/MMA.c/.h` encapsulates the MMA8451Q device behavior: initialization, register access, and motion data acquisition.
   - The accelerometer is the primary sensor input for the counting logic, and its interrupt line (**ACC_INT2**) is part of the event path for motion detection.

7. **Display / UI subsystem**
   - `lib/lcd1602.c/.h` drives the character LCD over I2C.
   - `lib/gui.c/.h` appears to be the presentation layer that turns internal state into screen content.
   - This is the output boundary of the system: the application computes state, then pushes human-readable feedback to the LCD.

8. **Application logic / state machine**
   - The actual step/level detection logic is concentrated in `main/main.c` and the higher-level modules under `lib/`.
   - The README’s “Fused State Machine” is the central algorithmic component: it combines accelerometer patterns and filtering to reduce false triggers and classify stair ascent/descent.
   - `lib/macroBlock.h` likely contains shared constants/macros/state definitions used by this logic.

9. **Input handling**
   - The design uses both **polled and interrupt-driven inputs**:
     - button and header pin as GPIO inputs with pull-ups
     - accelerometer interrupt to signal motion-related events
   - This suggests the firmware is event-driven at the hardware boundary, with the core logic reacting to sensor/input changes rather than continuously streaming data only.

10. **Build, toolchain, and IDE integration**
   - The repo is set up for embedded IDE workflows via `.eide/`, `.vscode/`, `SM_Project.code-workspace`, and Keil-related pack metadata.
   - The `.pack` directory also includes **flash algorithm** binaries and Keil project files, which matter for how the firmware is programmed onto the MCU but are not part of the runtime logic.

11. **Operational data flow**
   - Motion enters from the accelerometer over **I2C** and/or interrupt signals.
   - The detection state machine processes that input into step/level events.
   - The UI layer formats the result and sends it to the **LCD**.
   - GPIO inputs (button/header) likely control reset, mode changes, or calibration-related actions around the main detection flow.

12. **Architecture summary**
   - The repository is structured as a small embedded stack:
     - **vendor/platform layer**: CMSIS + device pack
     - **board/peripheral drivers**: GPIO, I2C, LCD, accelerometer
     - **application logic**: fused state machine and display logic
     - **entry point**: `main.c`
   - The key architectural boundary is between generic algorithmic logic and hardware-specific drivers, with I2C as the main shared transport between peripherals.

Main entry points: [`main/main.c`](https://github.com/msfet7/kl05z_level_counter/blob/main/main/main.c) (Main Entry), [`.pack/myPack7x5`](https://github.com/msfet7/kl05z_level_counter/blob/main/.pack/myPack7x5) (MKL05Z4 Pack), [`lib/boardControl.c`](https://github.com/msfet7/kl05z_level_counter/blob/main/lib/boardControl.c) (Board Control), [`lib/i2c.c`](https://github.com/msfet7/kl05z_level_counter/blob/main/lib/i2c.c) (I2C Bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform"]
  node_cmsis_core["CMSIS Core<br/>ARM headers<br/>[include]"]
  node_device_pack["MKL05Z4 Pack<br/>device support<br/>[myPack7x5]"]
  node_startup["Startup<br/>reset entry<br/>[startup_MKL05Z4.s]"]
  node_system_init["System Init<br/>clock setup<br/>[system_MKL05Z4.c]"]
end

subgraph group_board["Board Support"]
  node_board_ctrl["Board Control<br/>board HAL<br/>[boardControl.c]"]
  node_frdm_bsp["FRDM BSP<br/>pin map<br/>[frdm_bsp.h]"]
end

subgraph group_peripherals["Peripherals"]
  node_i2c_bus["I2C Bus<br/>bus driver<br/>[i2c.c]"]
  node_mma8451["MMA8451Q<br/>sensor driver<br/>[MMA.c]"]
  node_lcd1602["LCD1602<br/>display driver<br/>[lcd1602.c]"]
  node_gui["GUI<br/>presentation<br/>[gui.c]"]
end

subgraph group_app["Application"]
  node_macroblock["Macros<br/>shared defs<br/>[macroBlock.h]"]
  node_state_machine["Level Logic<br/>fused state machine<br/>[main.c]"]
  node_inputs(("Inputs<br/>[boardControl.h]"))
  node_entry_main{{"Main Entry<br/>application entry<br/>[main.c]"}}
end

subgraph group_tooling["Tooling"]
  node_flash_tools["Flash Tools<br/>programming assets<br/>[Flash]"]
  node_ide_cfg["IDE Config<br/>workspace config<br/>[.eide]"]
end

node_cmsis_core -->|"core headers"| node_device_pack
node_device_pack -->|"startup"| node_startup
node_device_pack -->|"system init"| node_system_init
node_startup -->|"reset to main"| node_entry_main
node_system_init -->|"init before app"| node_entry_main
node_frdm_bsp -->|"wiring"| node_board_ctrl
node_board_ctrl -->|"bus setup"| node_i2c_bus
node_board_ctrl -->|"gpio"| node_inputs
node_i2c_bus -->|"sensor link"| node_mma8451
node_i2c_bus -->|"display link"| node_lcd1602
node_mma8451 -->|"motion data"| node_state_machine
node_inputs -->|"events"| node_state_machine
node_state_machine -->|"state output"| node_gui
node_gui -->|"render"| node_lcd1602
node_macroblock -->|"shared defs"| node_state_machine
node_entry_main -->|"init hardware"| node_board_ctrl
node_entry_main -->|"run logic"| node_state_machine
node_entry_main -->|"update UI"| node_gui
node_flash_tools -.->|"programming"| node_device_pack
node_ide_cfg -.->|"build target"| node_entry_main

click node_cmsis_core "https://github.com/msfet7/kl05z_level_counter/blob/main/.cmsis/include"
click node_device_pack "https://github.com/msfet7/kl05z_level_counter/blob/main/.pack/myPack7x5"
click node_startup "https://github.com/msfet7/kl05z_level_counter/blob/main/.pack/myPack7x5/Device/Source/ARM/startup_MKL05Z4.s"
click node_system_init "https://github.com/msfet7/kl05z_level_counter/blob/main/.pack/myPack7x5/Device/Source/system_MKL05Z4.c"
click node_board_ctrl "https://github.com/msfet7/kl05z_level_counter/blob/main/lib/boardControl.c"
click node_frdm_bsp "https://github.com/msfet7/kl05z_level_counter/blob/main/lib/frdm_bsp.h"
click node_i2c_bus "https://github.com/msfet7/kl05z_level_counter/blob/main/lib/i2c.c"
click node_mma8451 "https://github.com/msfet7/kl05z_level_counter/blob/main/lib/MMA.c"
click node_lcd1602 "https://github.com/msfet7/kl05z_level_counter/blob/main/lib/lcd1602.c"
click node_gui "https://github.com/msfet7/kl05z_level_counter/blob/main/lib/gui.c"
click node_macroblock "https://github.com/msfet7/kl05z_level_counter/blob/main/lib/macroBlock.h"
click node_state_machine "https://github.com/msfet7/kl05z_level_counter/blob/main/main/main.c"
click node_inputs "https://github.com/msfet7/kl05z_level_counter/blob/main/lib/boardControl.h"
click node_entry_main "https://github.com/msfet7/kl05z_level_counter/blob/main/main/main.c"
click node_flash_tools "https://github.com/msfet7/kl05z_level_counter/blob/main/.pack/myPack7x5/Flash"
click node_ide_cfg "https://github.com/msfet7/kl05z_level_counter/blob/main/.eide"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmsis_core,node_device_pack,node_startup,node_system_init toneBlue
class node_board_ctrl,node_frdm_bsp toneAmber
class node_i2c_bus,node_mma8451,node_lcd1602,node_gui toneMint
class node_macroblock,node_state_machine,node_inputs,node_entry_main toneRose
class node_flash_tools,node_ide_cfg toneIndigo
```

## Components

### Platform

CMSIS core and MKL05Z4 device support package provide startup, registers, and system setup.

- [CMSIS Core](https://github.com/msfet7/kl05z_level_counter/blob/main/.cmsis/include): ARM headers · Common Cortex-M headers and compiler support used across the build. · `.cmsis/include`
- [MKL05Z4 Pack](https://github.com/msfet7/kl05z_level_counter/blob/main/.pack/myPack7x5): device support · Startup, system clock, SVD, and device definitions for the MCU. · `.pack/myPack7x5`
- [Startup](https://github.com/msfet7/kl05z_level_counter/blob/main/.pack/myPack7x5/Device/Source/ARM/startup_MKL05Z4.s): reset entry · Reset/vector startup assembly for MKL05Z4. · `.pack/myPack7x5/Device/Source/ARM/startup_MKL05Z4.s`
- [System Init](https://github.com/msfet7/kl05z_level_counter/blob/main/.pack/myPack7x5/Device/Source/system_MKL05Z4.c): clock setup · MCU system initialization and clock configuration. · `.pack/myPack7x5/Device/Source/system_MKL05Z4.c`

### Board Support

FRDM-KL05Z4 pin mapping and hardware abstraction.

- [Board Control](https://github.com/msfet7/kl05z_level_counter/blob/main/lib/boardControl.c): board HAL · Board-specific pin mapping and hardware setup for the FRDM-KL05Z4 board. · `lib/boardControl.c`
- [FRDM BSP](https://github.com/msfet7/kl05z_level_counter/blob/main/lib/frdm_bsp.h): pin map · Board support header defining the FRDM-KL05Z4 wiring and signals. · `lib/frdm_bsp.h`

### Peripherals

Shared bus and device drivers for sensor and display hardware.

- [I2C Bus](https://github.com/msfet7/kl05z_level_counter/blob/main/lib/i2c.c): bus driver · Shared I2C transport used by both the accelerometer and LCD backpack. · `lib/i2c.c`
- [MMA8451Q](https://github.com/msfet7/kl05z_level_counter/blob/main/lib/MMA.c): sensor driver · Accelerometer initialization, register access, and motion data acquisition. · `lib/MMA.c`
- [LCD1602](https://github.com/msfet7/kl05z_level_counter/blob/main/lib/lcd1602.c): display driver · I2C character LCD driver for the 2x16 display. · `lib/lcd1602.c`
- [GUI](https://github.com/msfet7/kl05z_level_counter/blob/main/lib/gui.c): presentation · Formats application state for display on the LCD. · `lib/gui.c`

### Application

Level counting logic, state machine, and user interaction.

- [Macros](https://github.com/msfet7/kl05z_level_counter/blob/main/lib/macroBlock.h): shared defs · Shared constants, state definitions, and compile-time helpers. · `lib/macroBlock.h`
- [Level Logic](https://github.com/msfet7/kl05z_level_counter/blob/main/main/main.c): fused state machine · Main stair/level counting algorithm that fuses sensor patterns and filtering. · `main/main.c`
- [Inputs](https://github.com/msfet7/kl05z_level_counter/blob/main/lib/boardControl.h): gpio inputs · Button and header-pin interaction paths used for control or mode changes. · `lib/boardControl.h`
- [Main Entry](https://github.com/msfet7/kl05z_level_counter/blob/main/main/main.c): application entry · Firmware entry point coordinating initialization, sensing, and display updates. · `main/main.c`

### Tooling

IDE, workspace, and flash/programming assets for embedded workflows.

- [Flash Tools](https://github.com/msfet7/kl05z_level_counter/blob/main/.pack/myPack7x5/Flash): programming assets · Keil flash algorithms and programmer support files for deploying the image. · `.pack/myPack7x5/Flash`
- [IDE Config](https://github.com/msfet7/kl05z_level_counter/blob/main/.eide): workspace config · Embedded IDE and workspace metadata for building and flashing the project. · `.eide`

## Connections

- CMSIS Core → MKL05Z4 Pack: core headers · CMSIS headers are used with the MCU device package.
- MKL05Z4 Pack → Startup: startup · Device pack provides the reset and vector startup file.
- MKL05Z4 Pack → System Init: system init · Device pack provides MCU system initialization code.
- Startup → Main Entry: reset to main · Startup code transfers control into the application entry.
- System Init → Main Entry: init before app · System setup runs before the main application flow.
- FRDM BSP → Board Control: wiring · Board control centralizes the FRDM-KL05Z4 pin mapping.
- Board Control → I2C Bus: bus setup · Board layer configures the shared I2C hardware.
- Board Control → Inputs: gpio · Board layer exposes the button and header input signals.
- I2C Bus → MMA8451Q: sensor link · The accelerometer communicates over the shared I2C bus.
- I2C Bus → LCD1602: display link · The LCD backpack communicates over the shared I2C bus.
- MMA8451Q → Level Logic: motion data · Accelerometer measurements feed the counting logic.
- Inputs → Level Logic: events · Button and header input events influence the application state.
- Level Logic → GUI: state output · The algorithm publishes its current level/state for presentation.
- GUI → LCD1602: render · GUI text and status are rendered to the LCD.
- Macros → Level Logic: shared defs · Macros and shared state definitions support the fused logic.
- Main Entry → Board Control: init hardware · Application entry initializes board-level hardware services.
- Main Entry → Level Logic: run logic · Main coordinates the level counting workflow.
- Main Entry → GUI: update UI · Main triggers UI refreshes based on application state.
- Flash Tools → MKL05Z4 Pack: programming · Flash assets belong to the device-pack tooling layer.
- IDE Config → Main Entry: build target · IDE metadata points the build at the firmware entry project.