How msfet7/kl05z_level_counter works
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.c Main Entry · myPack7x5 MKL05Z4 Pack · boardControl.c Board Control · i2c.c I2C Bus
Components 16
Platform
CMSIS core and MKL05Z4 device support package provide startup, registers, and system setup.
- CMSIS Core · Common Cortex-M headers and compiler support used across the build.
.cmsis/include - MKL05Z4 Pack · Startup, system clock, SVD, and device definitions for the MCU.
.pack/myPack7x5 - Startup · Reset/vector startup assembly for MKL05Z4.
.pack/myPack7x5/Device/Source/ARM/startup_MKL05Z4.s - System Init · MCU system initialization and clock configuration.
.pack/myPack7x5/Device/Source/system_MKL05Z4.c
Board Support
FRDM-KL05Z4 pin mapping and hardware abstraction.
- Board Control · Board-specific pin mapping and hardware setup for the FRDM-KL05Z4 board.
lib/boardControl.c - FRDM BSP · 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 · Shared I2C transport used by both the accelerometer and LCD backpack.
lib/i2c.c - MMA8451Q · Accelerometer initialization, register access, and motion data acquisition.
lib/MMA.c - LCD1602 · I2C character LCD driver for the 2x16 display.
lib/lcd1602.c - GUI · Formats application state for display on the LCD.
lib/gui.c
Application
Level counting logic, state machine, and user interaction.
- Macros · Shared constants, state definitions, and compile-time helpers.
lib/macroBlock.h - Level Logic · Main stair/level counting algorithm that fuses sensor patterns and filtering.
main/main.c - Inputs · Button and header-pin interaction paths used for control or mode changes.
lib/boardControl.h - Main 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 · Keil flash algorithms and programmer support files for deploying the image.
.pack/myPack7x5/Flash - IDE Config · Embedded IDE and workspace metadata for building and flashing the project.
.eide
Connections 20
- 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.