Version Control and Documentation in Embedded Projects

Why Version Control Is Critical

Version Complexity in Embedded Systems

Embedded system projects are a unique engineering domain where hardware and software intertwine. Version control here is far more complex than in pure software projects, because the versions of several components — hardware revisions, firmware releases, bootloader versions, FPGA bitstreams and configuration parameters — must all be kept compatible with each other. A pin change in a hardware revision can render the device unusable until the firmware is updated; a firmware update can be incompatible with earlier hardware revisions. Managing that web of dependencies is impossible without a systematic version control strategy. Digital project tracking tools give the process structure.

The consequences of poor version control are particularly destructive in embedded projects. Not knowing which firmware release is installed on devices in the field, being unable to match a bug report to the relevant design files, loading the wrong firmware on the production line, or being unable to determine which hardware revision a customer is using are the problems project teams face most often. Each of them results in lost time, budget overrun and customer dissatisfaction.

Product Life Cycle and Traceability

Embedded products usually have long life cycles. In industrial control, medical devices, automotive electronics and defence systems, products are expected to be supported for ten years or more. Over that period, product revisions are unavoidable because of component end-of-life, security patches, performance improvements and regulatory change. Complete traceability of each revision is the fundamental condition for supporting the product across its whole life.

Sector standards such as IEC 62304 (medical device software life cycle), ISO 26262 (automotive functional safety), DO-178C (airborne software) and IEC 61508 (industrial functional safety) make version control and traceability mandatory. Complying with them is not merely a legal requirement but an indicator of engineering discipline and product quality.

Hardware Version Management

PCB Revision Strategy

Hardware version management differs fundamentally from software version control because hardware changes require physical manufacture and cannot be undone. A PCB revision numbering system must clearly reflect the scope and impact of a change. One widely used approach is major revision letters (Rev A, Rev B, Rev C), where Rev A is the first prototype and each subsequent major revision represents a new PCB build incorporating schematic or layout changes.

Each PCB revision should be accompanied by an Engineering Change Order (ECO) listing the changes. The ECO covers the reason for the change, the detail of what changed, the components affected, backward compatibility status and verification requirements. The ECO number is matched to the PCB revision number, and all related documents (schematic, layout, BOM, Gerber files) are archived under the same revision.

Using distributed version control systems such as Git for schematic and layout files is becoming increasingly common. Altium Designer 365, KiCad and other modern EDA tools support Git integration. Because of binary file formats, however, text-based diff and merge may not be directly possible. KiCad's text-based file format offers a significant advantage here. In every case it is critical that each commit message states the reason and scope of the change and that meaningful tags are used.

BOM Version Control

The bill of materials is an inseparable part of the hardware version. Each PCB revision should have its own BOM version. A BOM change may be needed even for the same PCB revision, however — moving to an alternative component because one has gone end-of-life, for instance. In that case the BOM version updates while the PCB revision stays the same. Using BOM version numbering in combination with the PCB revision (Rev B, BOM v2.1, for example) provides clear traceability.

Critical points in BOM management include tracking component life cycle status (active production, last-time-buy warning, obsolete), the verification status of alternative components (has form-fit-function compatibility been tested?), consistency between component reference designators and the schematic, and versioning production notes alongside the BOM.

Firmware Versioning Strategies

Semantic Versioning

Semantic Versioning offers a clear, consistent framework for firmware. In the MAJOR.MINOR.PATCH format, MAJOR represents backward-incompatible changes (support for a new hardware revision, a protocol change), MINOR represents backward-compatible new features (support for a new sensor, a performance improvement) and PATCH represents backward-compatible bug fixes.

In embedded projects it is recommended to include a build number and hardware compatibility information alongside the firmware version. A format such as v2.3.1-build1847-hwRevC makes the firmware release (2.3.1), the exact build (1847) and the compatible hardware revision (Rev C) clear at a glance. That information should be embedded in the firmware binary and made readable from the device through a firmware query command.

Git Branching Strategy

Adopting an appropriate Git branching strategy directly affects team productivity and code quality. Gitflow is a widely preferred approach for embedded projects. Its core components are a main branch (stable production code), a develop branch (active development), feature branches, release branches (release preparation) and hotfix branches (urgent fixes).

One issue needing particular attention in embedded work is supporting multiple hardware revisions. Where the same firmware codebase must support several revisions, conditional compilation directives or a hardware abstraction layer (HAL) can be used. The alternative — separate branches per hardware revision — increases maintenance burden. The optimal strategy is HAL-based abstraction, with a single codebase covering every supported revision.

Firmware Update and Distribution

Updating firmware on devices in the field, over the air or by cable, is the most critical application of version management. A secure and reliable update mechanism should include cryptographic signature verification (integrity and origin of the update file), a rollback mechanism (automatic return to the previous release if an update fails), hardware compatibility checking (preventing the wrong firmware being loaded), update status reporting (success or failure relayed to the server) and support for partial updates (only changed modules being updated).

The AECKraft platform allows firmware release history, distribution status and device-to-firmware mapping to be tracked centrally. Information such as which firmware is running on which device, update history and pending updates gives the project team full visibility.

Documentation Standards

Hardware Documentation

Hardware documentation on an embedded project requires design decisions to be recorded together with their rationale. The core documents are the Hardware Requirement Specification (HRS, the functional and performance requirements the hardware must meet), the Hardware Design Document (HDD, circuit design decisions, calculations, component selection rationale), schematic and PCB layout files (versioned EDA projects), the BOM (versioned, including approved alternatives), test procedures and test reports for each revision, and EMC and safety test reports.

Justifying design decisions is the most valuable yet most frequently skipped part of hardware documentation. Why was this microcontroller chosen? Why this power topology? Why was this component value calculated? The answers are invaluable to engineers who will revise the design in future. Without them, every revision becomes a rediscovery exercise from scratch.

Firmware Documentation

Firmware documentation goes far beyond in-code comments. The Firmware Architecture Document defines the software architecture (modules, layers, interfaces, communication mechanisms). API documentation details each module's external interface (function prototypes, parameters, return values, error codes) and can be generated automatically from the code with Doxygen or similar tools. The Hardware Abstraction Layer document defines hardware-specific access functions and register maps. The Bootloader document explains the device start-up sequence, memory map and firmware update mechanism.

A consistent standard for in-code documentation should be set and applied across the team: file purpose, author, date and licence information at the head of every file; a short description, parameter definitions and return value at the head of every function; step-by-step explanation of complex algorithms; and meaningful constants and enums instead of magic numbers. Compliance with coding standards such as MISRA C or CERT C improves both code quality and documentation consistency.

The Interface Control Document

The ICD, which defines the interfaces between hardware and software, is one of the most critical documents on an embedded project. It covers register maps (address, bit fields, access type, default values), communication protocols (message formats, timing diagrams, error handling), pin assignments (GPIO functions, alternate functions, electrical characteristics), interrupt definitions (priority, trigger condition, service time requirements) and the memory map (flash partitioning, RAM usage, shared resources).

The ICD is the shared reference point for hardware and software teams. Both sides must work from the same document and changes must go through mutual approval. Keeping the ICD under version control with a change history is critical to preventing incompatibility problems.

Integrated Management With Digital Tools

Tool Chain Integration

Modern embedded development requires the coordinated use of many tools. EDA tools (Altium, KiCad, OrCAD), IDEs (STM32CubeIDE, IAR, Keil), version control systems (Git, SVN), CI/CD platforms (Jenkins, GitLab CI), issue trackers (Jira, Bugzilla) and documentation tools (Confluence, Doxygen) form the core of that chain. Integrating them, automating data flow and establishing repeatable processes substantially raises team productivity.

Continuous integration is increasingly common in firmware development. CI pipelines running automatic builds, static code analysis, unit tests and, where possible, hardware simulation on every commit ensure errors are caught early. Automatically versioning, archiving and packaging the firmware binary for distribution is also part of the CI process.

A Central Project Management Platform

Central platforms such as AECKraft form the digital backbone bringing every component of an embedded project together. When hardware documents, firmware source references, test reports, bug records, meeting notes and project plans are managed on one platform, information silos disappear and the whole team gains full visibility.

In multi-disciplinary teams especially — hardware engineers, firmware developers, test engineers, project managers — managing information flow through a central platform prevents communication breakdowns. Integrated workflows such as a hardware revision automatically notifying the firmware team, a bug report linking to the relevant design files, and a test result updating the project timeline give holistic control of the project.

The Traceability Matrix

A traceability matrix is a critical document showing every link from requirements to design, design to implementation and implementation to test. On embedded projects it covers the links between hardware requirements and schematic design elements, firmware requirements and code modules, test requirements and test procedures, and certification requirements and verification evidence. It exists to reveal whether any requirement is unmet and whether any design element exists without a requirement.

On the AECKraft platform, the links between tasks, documents and tags allow the traceability matrix to be managed digitally. That greatly eases the preparation of traceability evidence for auditors during certification processes such as CE, FCC and UL.

Frequently Asked Questions

Is Git suitable for hardware design files?

Git is an excellent version control system for firmware and text-based files. For hardware design files it depends. With EDA tools using text-based file formats, such as KiCad, Git is very effective because line-by-line diff and merge are possible. With tools using binary formats, such as Altium Designer, Git can store the files and keep history but meaningful diff is not possible. In that case tool-specific version control solutions such as Altium 365, or Git together with LFS (Large File Storage), are recommended. In every case, commit messages explaining changes in detail and meaningful tags remain critical.

How is compatibility between firmware and hardware versions managed?

Build a compatibility matrix showing clearly which hardware revisions each firmware release supports. The firmware should include a hardware revision detection mechanism (reading GPIO, or a revision code from EEPROM or a resistor divider) and should refuse to run on incompatible hardware. In the CI/CD process, compiling and testing each firmware build for every supported hardware revision should be automated. Keeping the compatibility matrix and hardware-firmware mapping current in central documentation prevents incompatibility problems in the field.

How can the documentation burden be eased in small teams?

Comprehensive documentation may not be practical in small teams, but a minimum level must be maintained. Adopt the code-as-documentation principle: write self-explanatory code and use Doxygen comments with discipline. Templates shorten the time to create new documents. README files should record project setup, build instructions and basic architecture. Recording the rationale for design decisions, even as short notes, is far better than not recording it at all. Task descriptions and comments in digital project management tools can serve as informal documentation and build valuable institutional knowledge over time.