Keyfob Firmware

NOTE: This firmware is under development and is not for productional purposes

Summary

• Introduction
• Project Structure
• Development Guidlines
  • Source Code Documents
  • Prerequisites
  • How To Compile
  • Commit Message Conventions
  • Coding Styles
  • Versioning
• Authors
• License
• Acknowledgments

Introduction

Project Structure

The structure of the root folder :

Folder Name	Description
/	Root of the project
src	Contains all the source codes
tests	Contains all the test codes
docs	Contains all pages and assets used for documentation
external	Contains all thirdparties modules
scripts	Contains all scripts used for CI/CD and etc.
docker	Contains the dockerfile used as build container in the CI system
cmake	Contains all required cmake modules
templates	Contains all templates used in the code-base

The structure of the source folder :

Folder Name	Description
app	Contains all business related source codes
common	Contains all source codes shared between different system layers
bsp	Contains all board-related source codes (Board-Support-Package)
middleware	Contains all third-parties source codes like DS, Protocol Stacks and etc
drivers	Conaints all high-level source codes as drivers for external chips on the board
hal	Contains all source codes for developed Hardware-Abstraction-Layer
hll	Contains all source codes for developed Hardware-Low-Layer

Architecture and dependencies

In this project, we have a layerd architecture. As you can see in the following graph, The HLL (Hardware Low Layer) layer is the only dependency that exists between the firmware and the hardware. So, we can increase the development speed by faking the HLL and doing our unit tests on the development host (dual targeting approach). Eventually, we can cross compile our tests and run them on the actual hardware for further investigation.

Development Guidlines

Prerequisites

App	Description	Version	How to install
arm-none-eabi-	Cross compiler for arm MCU	10.3.1
CMake	Build System Generator	3.26.4	sudo snap install cmake --clasic
GNU-Make	Source builder	4.2.1	sudo apt install make
Cppcheck	C/C++ static analyzer	1.90	sudo apt install cppcheck
Lizard	Cyclomatic Complexity Analyzer	1.17.10	sudo pip install lizard
Flawfinder	Vulnerabilities scanner	2.0.19	pip install flawfinder
Clangformat	C/C++ code linter	10.0.0	sudo apt-get install clang-format
Doxygen	Automatic document generator from source codes	1.8.17	sudo apt install doxygen
Lcov	Report generator from gcov	1.14	sudo apt install lcov
Docker	Containerization technology	24.0.2	Installation guide
STM32CubeProgrammer	STM32 programming suite	2.13.0	Wiki
Google Test	Google test harness	v1.13.0	-

How To Compile

1- Install docker on your machine - Installation guide
2- Write following commands in the terminal:

 docker pull mohammadniaraki/stm32_build:latest
 docker run -it stm32_build:latest

3- After running the container in interactive mode, write following commands in the terminal:

 git clone https://www.github.com/niaraki/keyfob_firmware --recursive
 cd keyfob_firmware 
 make clean && make prepare && make release

4- Final artifacts (keyfob_firmware.[elf | hex | bin]) are generated under the "build/src" directory.
5- Read the Makefile for other build targets

Commit Message Conventions

1. The first line of the commit message should be like the below format:
   [type-icon] [type-name]: [scope*]: [message title]
   Type Table:

   icon	name	description
   📦	NEW	we use this type when we have added something
   👌	ENH	we use this type when we have modified or enhance something
   🐛	FIX	we use this type when we have fixed a bug
   🎭	MRG	we use this type when we want to merge two branches

   • Scope can be a filename, a module name (*it is and optional field)
   • Use simple present tense for the title - for example add instead of added
2. After the first line, we have the commit body which explains more about the commit
3. An optional footer part comes after the body and it should be like this:
   resolved #[The specific issue number which is targeted by this commit]
4. Don't use fast-forward merging, because merge commits can show the history of changes better
   You can disable it on your machine by using the following command:
   git config --global merge.ff no

Coding Styles

This project uses the c-coding style introduced by barrgroup. The configurations are also available here.

Versioning

We use SemVer for versioning.

Authors

• Mohammad Niaraki

License

This project is licensed under the MIT License - see the License.md file for details

Acknowledgments

I present this to all of you with ❤️