The Embedded Project Cookbook: A Step-by-Step Guide for Microcontroller Projects

Learn how to create and release an embedded system in a fast and reliable manner. This book will help you build and release a commercially viable product that meets industry standards for quality. The book is not just about code: it covers non-code artifacts such as software processes, requirements, software documentation, continuous integration, design reviews, and code reviews. While specifically targeting microcontroller applications, the processes in this book can be applied to most software projects, big or small. Additionally, the book provides an open-source C++ framework that can be used to quick start any embedded project. This framework has an OSAL (OS Abstraction Layer) and essential middleware that is needed for many embedded systems. Using a hands-on approach of building-and-testing the software application first allows you to develop a significant amount of production quality code even before the hardware is available, dramatically reducing the start-to-release duration for a project. As you follow the recipes in this book, you will learn essential software development processes, perform just in time design, create testable modules, and incorporate continuous integration (CI) into your day-to-day developer workflow. The end-result is quality code that is maintainable and extensible, and can be reused for other projects, even when presented with changing or new requirements. The Embedded Project Cookbook is focused on the how of developing embedded software. For a discussion of the why , readers are invited to refer to the optional companion book Patterns in the Machine: A Software Engineering Guide to Embedded Development . What You Will Learn Separate software architecture from software design Write software documents that are intrinsically resistant to going out-of-date. Identify the processes, workflows, and best practices for the team to follow. Initiate code reviews before code is checked intoa stable branch. Design testable modules and implement automated unit testing that doesn’t require hardware. Incorporate continuous integration into the day-to-day developer workflow, including automated integration testing. Create a code base that can be reused on other projects. Who This Book Is For Mid-level developers and software leads who are looking to get up and running without all the underlying theories. This book is also for professionals looking to learn how to productize a concept or technology and sell the results to a customer. Table of Contents About the Authors About the Technical Reviewer Preface Chapter 1: Introduction Software Development Processes Software Development Life Cycle Outputs and Artifacts What You’ll Need to Know Coding in C and C++ What Toys You Will Need Regulated Industries What Is Not Covered Conclusion Chapter 2: Requirements Formal Requirements Functional vs. Nonfunctional Sources for Requirements Challenges in Collecting Requirements Exiting the Requirements Step GM6000 Summary Chapter 3: Analysis System Engineering GM6000 System Architecture Software Architecture Moving from Inputs to Outputs Hardware Interfaces Performance Constraints Display Temperature Sensor Threading Programming Languages Subsystems Application BSP Diagnostics Drivers Graphics Library Heating Persistent Storage UI Subsystem Interfaces Interfaces Process Model Process Model Thread Priorities Data Integrity Functional Simulator Simulator Cybersecurity Cybersecurity Memory Allocation Inter-thread and Inter-process Communication Message Passing (ITC) File and Directory Organization Localization and Internationalization Requirement Traceability Summary Chapter 4: Software Development Plan Project-Independent Processes and Standards Project-Specific Processes and Standards Additional Guidelines Care and Feeding of Your SDP SDP for the GM6000 Housekeeping Roles and Responsibilities Software Items Documentation Outputs Requirements Software Development Life Cycle Processes Cybersecurity Tools Software Configuration Management (SCM) Testing Deliverables Summary Chapter 5: Preparation GitHub Projects GitHub Wiki Continuous Integration Requirements Jenkins Summary Chapter 6: Foundation SCM Repositories Source Code Organization Build System and Scripts Skeleton Applications CI “Build-All” Script Software Detailed Design Summary Chapter 7: Building Applications with the Main Pattern About the Main Pattern Operating System Abstraction Layer Hardware Abstraction Layer More About Main Implementing Main Application Variant Marketing Abstraction Layer Ajax Main and Eros Main Build Scripts Preprocessor Simulator The Fine Print Summary Chapter 8: Continuous Integration Builds Example Build-All Scripts for GM6000 The CI Server Directory Organization Naming Conventions Windows build_all Script Linux build_all Script Summary Chapter 9: Requirements Revisited Analysis Requirements vs. Design Statements Design Statement for Control Algorithm Design Statement for User Interface Missing Formal Requirements Requirements Tracing Summary Chapter 10: Tasks 1) Requirements 2) Detailed Design 3) Source Code and Unit Tests 4) Code Review 5) Merge The Definition of Done Task Granularity Tasks, Tickets, and Agile Summary Chapter 11: Just-in-Time Detailed Design Examples Subsystem Design [SDD-24] Persistent Storage [SDD-54] Frequency of Updates [SDD-55] Records [SDD-55] Records: Class Diagram [SDD-55] Records: Location [SDD-55] Records: Simulator [SDD-56] Memory Map I2C Driver Design [SDD-53] I2C Driver Button Driver Design [SDD-36] Button Driver Fuzzy Logic Controller Design [SDD-34] Fuzzy Logic Controller Graphics Library [SDD-19] Graphics Library Screen Manager Design [SDD-44] Screen Manager [SDD-44] Screen Manager: State Machine [SDD-44] Screen Manager Class Diagram [SDD-44] Screen Manager: Graphics Library [SDD-44] Screen Manager: Location Design Reviews Review Artifacts Summary Chapter 12: Coding, Unit Tests, and Pull Requests Check-In Strategies Pull Requests Granularity Examples I2C Driver Screen Manager Summary Chapter 13: Integration Testing Smoke Tests Simulator Summary Chapter 14: Board Support Package Compiler Toolchain Encapsulating the Datasheet Encapsulating the Board Schematic BSPs in Practice Structure Dos and Don’ts Bootloader Summary Chapter 15: Drivers Binding Times Public Interface Hardware Abstract Layer (HAL) Facade Example PWM Driver The STM32 Implementation of PWM Arduino Framework Implementation of PWM Simulator Implementation of PWM Separation of Concerns Example Button Driver STM32 MCU Implementation of the Button Driver Arduino Framework Implementation of the Button Driver Simulator Implementation of the Button Driver LHeader Caveats Unit Testing Polymorphism Example I2C Driver STM32 Implementation of the I2C Driver Arduino Framework Implementation of the I2C Driver Dos and Don’ts Summary Chapter 16: Release About Builds and Releases Tightening Up the Change Control Process Software Bill of Materials (SBOM) Anomalies List Release Notes Deployment Over-the-Air (OTA) Updates QMS Deliverables Archiving Build Tools Summary Appendix A: Getting Started with the Source Code Repository Organization Windows Prerequisites for Windows Getting the Source Code on Windows Compiler Configuration on Windows Building on Windows Building the Functional Simulator Building for the Hardware Targets on Windows Build Directories on Windows Linux Prerequisites for Linux Getting the Source Code on Linux Compiler Configuration on Linux Building on Linux Build Directories on Linux Additional Tools STM32 Cube IDE STM32 Cube MX Segger Tools Segger J-Link Tools Segger Ozone Debugger Segger SystemView Terminal Emulator PuTTY Tera Term Doxygen Code Coverage RATT State Machine Tools Outcast Appendix B: Running the Example Code Ajax Application Provisioning Console Password Functional Simulator Hardware Target Console Commands Heating Mode, Fan Mode, and Setpoint Temperature Heating and Fan PWM Outputs Generating UI Events from the Console General-Purpose Commands Eros Provisioning Functional Simulator Hardware Target Screen Test Console Commands Hardware Outputs and Inputs Micro Applications EEPROM Testing Common Commands Appendix C: Introduction to the Data Model Architecture More Details Appendix D: LHeader and LConfig Patterns LHeader Implementation Example Caveat Implementor LConfig Appendix E: CPL C++ Framework Organization and Namespaces About src/Cpl Checksum Container Data Model Model Point Types Persistent Storage TShell Io Serial Ports Sockets Files Itc Json Logging MApp Math Memory Persistent System Assert Elapsed Time Event Flags Event Loop Fatal Error Interface Global Lock Initialization and Scheduling Mutexes Periodic Scheduler Semaphores Shell Sleep Shutdown Simulated Time Software Timers Thread-Local Storage (TLS) Threads and Runnable Objects Tracing Text Encoding Formatting and Parsing Framing Standardized String Operations String Class Text to/from Binary Tokenizer TShell Commands Type About src/Bsp About src/Driver Porting Decoupling Techniques Runtime Initialization Interfaces Assert Elapsed Time Fatal Error File and Directory Management File and Stream IO Global Lock Mutex Newline Semaphore Shell Shutdown System API Threads Create Thread Thread Priorities Native Thread vs. Cpl Thread Thread-Local Storage Tracing Appendix F: NQBP2 Build System Installing NQBP2 Usage Build Model Object Files vs. Libraries Build Variants Build Scripts Selecting What to Build with NQBP Compiler Toolchains Toolchain Details mytoolchain.py Build Variant Build Values Specifying Toolchain Linking Specifying an Entire Directory of Object Files Preprocessing Scripts How Preprocessing Scripts Work Preprocessing Script Examples Source Tree Script: preprocess.py Preprocessing Script: scripts/preprocess_base.py Enabling the Preprocessing Script Reverse-Engineering Compiler Options Extras Appendix G: RATT Installing Test Scripts Usage Script Locations Example Scripts Caveats Recommended Conventions Appendix H: GM6000 Requirements Marketing Requirements Document Name and Number Overview Glossary Document References Requirements Change Log Product Requirements Document Name and Number Overview Glossary Document References Requirements Change Log Software Requirements Document Name and Number Overview Glossary Document References Requirements Change Log Hardware Requirements Document Name and Number Overview Glossary Document References Requirements Change Log Appendix I: GM6000 System Architecture Document Name and Number Overview Glossary Document References Block Diagram Change Log Appendix J: GM6000 Software Architecture Document Name and Number Scope Requirements Tracing Overview Glossary Document References Hardware Interfaces Performance Constraints Data Storage Display Display Backlight User Inputs LEDs Heater Control Heater Safety Indication Blower Control Temperature Sensor Console Wireless Module Control Algorithm Password Hashing Threading Summary Programming Languages Subsystems [SWA-10] Alert Management [SWA-11] Application [SWA-12] Bootloader [SWA-13] BSP [SWA-14] Console [SWA-15] Crypto [SWA-16] Data Model [SWA-17] Diagnostics [SWA-18] Drivers [SWA-19] Graphics Library [SWA-20] Heating [SWA-21] Logging [SWA-22] OS [SWA-23] OSAL [SWA-24] Persistent Storage [SWA-25] Sensor Comms [SWA-26] Software Update [SWA-27] System Services [SWA-28] UI [SWA-31] Interfaces [SWA-32] Process Model [SWA-33] Thread Priorities [SWA-39] Data Integrity [SWA-34] Simulator [SWA-35] Cybersecurity [SWA-36] Memory Allocation [SWA-37] Message Passing (ITC) [SWA-38] File and Directory Organization [SWA-40] Localization and Internationalization [SWA-42] Unit Testing [SWA-41] Engineering and Manufacturing Testing Change Log Appendix K: GM6000 Software Development Plan Document Name and Number Overview Glossary Document References Roles and Responsibilities Software Items Documentation Outputs Requirements Software Development Life Cycle Process (SDLC) Cybersecurity Tools Software Configuration Management (SCM) Testing Deliverables Change Log Appendix L: GM6000 Software Detailed Design (Initial Draft) Document Name and Number Scope Requirements Tracing Overview Glossary Document References Software Architecture Overview [SDD-35] Source Code [SDD-62] Unit Testing [SDD-31] Subsystems [SDD-10] Alert Management [SDD-11] Application [SDD-32] Creation and Startup (Application) [SDD-12] Bootloader [SDD-13] BSP [SDD-14] Console [SDD-15] Crypto [SDD-16] Data Model [SDD-17] Diagnostics [SDD-18] Drivers [SDD-36] Button Driver [SDD-37] GPIO Output Driver [SDD-39] Pico Display Driver [SDD-40] PWM Driver [SDD-42] SPI Driver [SDD-19] Graphics Library [SDD-20] Heating [SDD-21] Logging [SDD-22] OS [SDD-23] OSAL [SDD-24] Persistent Storage [SDD-25] Sensor Communications [SDD-26] Software Update [SDD-27] System Services [SDD-28] UI [SDD-29] Functional Simulator [SDD-30] Engineer Test Application [SDD-33] Creation and Startup (Test Application) Change Log Appendix M: GM6000 Software Detailed Design (Final Draft) Document Name and Number Scope Requirements Tracing Overview Glossary Document References Software Architecture Overview [SDD-35] Source Code [SDD-62] Unit Testing [SDD-31] Subsystems [SDD-10] Alert Management [SDD-11] Application [SDD-32] Creation and Startup (Application) [SDD-12] Bootloader [SDD-13] BSP [SDD-69] alpha1 [SDD-70] alpha1-atmel [SDD-14] Console [SDD-61] Console Security [SDD-15] Crypto [SDD-58] ED25519 [SDD-59] Password Hashing [SDD-60] Random Number [SDD-16] Data Model [SDD-71] Model Point Change Notification [SDD-17] Diagnostics [SDD-72] POST [SDD-73] Metrics [SDD-18] Drivers [SDD-74] Onboard Analog Driver [SDD-36] Button Driver [SDD-84] GPIO In Driver [SDD-37] GPIO Out Driver [SDD-53] I2C Driver [SDD-38] LCD Controller [SDD-39] PicoDisplay Driver [SDD-40] PWM Driver [SDD-41] RGB LED Driver [SDD-42] SPI Driver [SDD-43] TPipe Driver [SDD-19] Graphics Library [SDD-20] Heating [SDD-63] Supervisor [SDD-64] Model Points [SDD-85] IO [SDD-34] Fuzzy Logic Controller [SDD-65] House Simulation [SDD-21] Logging [SDD-52] Persistent Storage [SDD-22] OS [SDD-23] OSAL [SDD-24] Persistent Storage [SDD-54] Frequency of Updates [SDD-55] Records [SDD-56] Memory Map [SDD-25] Sensor Communications [SDD-26] Software Update [SDD-27] System Services [SDD-28] UI [SDD-44] Screen Manager [SDD-45] Events [SDD-51] Button Events [SDD-46] Screens [SDD-47] About Screen [SDD-67] Edit Screen [SDD-50] Error Screen [SDD-66] Home Screen [SDD-49] Shut-Down Screen [SDD-48] Splash Screen [SDD-68] Status Indicator [SDD-29] Functional Simulator [SDD-30] Engineer Test Application [SDD-33] Creation and Startup [SDD-81] Provisioning [SDD-75] Tests [SDD-76] Button [SDD-77] Cycling [SDD-78] EEPROM [SDD-86] Hardware Safety Limit Input [SDD-79] LCD [SDD-83] PWM [SDD-82] RGB LED [SDD-80] Temperature Monitor Change Log Appendix N: GM6000 Fuzzy Logic Temperature Control Document Name and Number Overview Glossary Document References Fuzzification Fuzzy Inference Defuzzification Change Log Appendix O: Software C/C++ Embedded Coding Standard Document Name and Number Overview Scope Deviation from the Standard Glossary Document References Coding Standards Language (REQ) No Dynamic Memory Allocation (REQ) No Recursion (REQ) Use const Wherever Possible No Type Casting (REQ) No Compiler Warnings (REQ) No Explicit Constants (REQ) No goto Statements (REQ) Use nullptr (REQ) Conditionally Compiled Code Is Not Allowed Within a Function Body (REQ) Virtual Destructors (REQ) Rule of Five (REQ) Pass and Return Objects by Reference Protect Header Files with the #ifndef Read-Once Latch (REQ) Minimize the #include Statements in Your Header Files (REQ) Avoid the Global Namespace Unless Absolutely Necessary Use Standard Integer Types (REQ) Do Not Use Nonportable Constructs Array Indices (REQ) Pointer Check (REQ) Coding Style Comments Header Files (REQ) Use Doxygen Comments in Header Files (REQ) C|CPP Files File Organization Organize by Namespace (REQ) README.txt (REQ) Non-namespace Directories (REQ) Namespace Directories (REQ) Files (REQ) Single Module or Class in a Namespace Keep Header and Source Files Together (REQ) Fully Qualified Header include Statements (REQ) Naming C++ Namespaces, Classes, Methods, and Variables (REQ) C Functions, Variables, Typedefs, and Structs (REQ) Preprocessor and Macros (REQ) Statically Scoped Variables (REQ) Global Variables (REQ) Reserved Function and Method Names (REQ) Formatting Indenting Spacing (REQ) Braces (REQ) Flow Control Statements (REQ) Elimination of Dead Code Change Log Appendix P: GM6000 Software Requirements Trace Matrix Document Name and Number Overview Glossary Document References Software Requirements Traced to PRS and MRS Software Requirements Traced to Software Architecture Software Architecture Traced to Requirements Software Architecture Traced to Detailed Software Design Detailed Software Design Traced to Software Architecture Change Log Appendix Q: GM6000 Software Bill of Materials Document Name and Number Overview Glossary Document References Packages Versions Change Log Appendix R: GM6000 Software Release Notes Document Name and Number Overview Glossary Document References RC2 Changes Bug Fixes Known Issues RC1 Changes Bug Fixes Known Issues Change Log Index