Taking Over a Legacy Embedded Codebase
Direct answer. Taking over legacy firmware starts with securing what exists and making the build reproducible, then reproducing the reported field faults on a bench unit. Only after that do we map the code, write down the risks, and fix the safest high-value issues first. A rewrite is considered only when the evidence shows the old structure keeps producing new faults.
1.0 The usual starting point
A typical takeover: the original developer or vendor has moved on. The source is in an archive, or partly on someone’s laptop. The build works on one machine with a toolchain nobody remembers installing. Devices are in the field, and reports are coming in: resets, lockups, a feature that fails with one model of phone. Pressure is on to fix the fault quickly.
The temptation is to start reading code and patching. Without a reproducible build and a reproduced fault, a patch aimed at the wrong cause ships a second fault next to the first one.
2.0 Phase 1: secure the assets
Collect everything before it disappears:
| Asset | Why it matters |
|---|---|
| Source code, all branches and archives | The obvious one; look for more than one copy and compare |
| Toolchain installers and exact versions | Compiler versions change code generation and timing |
| Build scripts, IDE project files, linker scripts | Carry optimisation flags, memory layout and defines that are not in the source |
| Binaries currently in the field, with versions | Proves which source matches which units |
| Bootloader source and keys, if any | Without them you may not be able to update units |
| Programming tools and production line procedure | Needed to build new units |
| Hardware design files at each board revision | Firmware branches on board revision |
| Issue reports, field logs, customer emails | The fault evidence |
Put the source under version control immediately if it is not already, with the archive as the first commit, unchanged. Signing keys and credentials go into proper key storage, not the repository.
Talk to anyone who worked on the product while they are still reachable: the previous developer, the production line, the support team. An hour with the previous developer can explain a build quirk or a field workaround that would take days to rediscover from the code. Write the notes down and keep them with the repository.
3.0 Phase 2: make the build reproducible
The goal is to produce, from source, a binary identical to the one in the field, or to explain each difference.
- Recreate the toolchain in a container or documented VM, pinning versions.
- Build and compare the output with the field binary. Differences in embedded build timestamps or paths are expected; differences in code are not.
- If they do not match, look for the source revision that does. If no revision matches, record that as a finding: the field firmware may contain changes that were never committed.
- Add a build script and continuous integration so anyone can build it with one command.
The Reproducible Builds project’s definition is a useful standard to aim at. Even partial reproducibility tells you whether you are working on the code that actually runs in the field.
4.0 Phase 3: reproduce the faults
Set up one or more bench units matching field hardware revisions. For each reported fault:
- Write down the reported symptoms and the conditions: firmware version, hardware revision, environment, sequence of actions.
- Add logging or tracing if the firmware lacks it, in a separate build that otherwise matches the field version.
- Try to reproduce, varying the suspected conditions: power quality, temperature, radio environment, long runtime, specific host devices.
- Record what reproduced, what did not, and how confident you are.
Some faults will not reproduce on the bench. That result is stated plainly, along with the hypotheses and what field data would help, such as a logging build on field units you select.
5.0 Phase 4: map and assess
Now read the code with purpose. We write a short assessment that covers:
| Area | What we look for |
|---|---|
| Structure | Modules, layering, how hardware access is organised |
| Concurrency | Interrupt handlers, RTOS tasks, shared data, priorities |
| Memory | Stack sizes, heap use, buffer handling, static analysis findings |
| Error handling | What happens on peripheral failure, timeouts, watchdog use |
| Update path | Whether units can be updated, and how safely |
| Tests | What exists, what can be added cheaply |
| Hardware coupling | Board-revision dependencies, magic numbers tied to parts |
Static analysis tools and compiler warnings at higher levels produce long lists in old code. We triage them by the likelihood of causing the reported faults rather than trying to clear them all.
6.0 Phase 5: fix, verify and release
Fix the issues with the best ratio of impact to risk first, each as a small, reviewed change with a test that reproduces the fault before the fix and passes after. Ship fixes in versions that change as little as possible. Your team decides when a release goes out and when it reaches the fleet, using the test evidence we provide.
6.1 Fix or rewrite?
| Indication | Points toward |
|---|---|
| Faults traced to a few specific defects | Targeted fixes |
| Product in the field with update path working | Targeted fixes, then gradual refactoring |
| New faults keep appearing from the same structural cause, such as unguarded shared state across tasks | Partial rewrite of that subsystem |
| Hardware platform changing anyway | Rewrite can be considered with the new platform |
| No reproducible build and source missing for key parts | Rewrite of the missing parts is unavoidable |
A full rewrite of field firmware carries its own risk: the old code encodes fixes for problems nobody wrote down. When we recommend rewriting part of the system, we say why, and we keep the old behaviour as a test reference.
7.0 What you get at each phase
- Asset inventory and repository with the original archive as the base.
- Reproducible build with documented toolchain and CI.
- Fault reproduction report.
- Code assessment with ranked risks.
- Fixes with tests and release notes.
These outputs are useful whether or not the work continues with us. The Legacy Firmware and Field Rescue page describes how an engagement starts, and Embedded Firmware covers new firmware work. To describe your situation, use Discuss a Project.
References
- Reproducible Builds, definition: https://reproducible-builds.org/docs/definition/
Frequently asked questions
The previous vendor will not give us the source. What can be done?
Start with what you have: the binaries, the devices and any documentation. Some behaviour can be understood from those, and the assessment will show which parts would need to be rewritten. Check the contract with your previous vendor too; it may already contain source delivery terms.
How long before you can fix the first bug?
That depends on how quickly the build becomes reproducible and the fault reproduces. Those two steps vary more than the fix itself, so we report progress on each and give an estimate for fixes once both are done.
Can you work without access to field units?
We start on bench units at the same hardware revision; field access is needed only when the fault depends on installation, wiring or RF environment. Then a logging build on field units you pick is the practical way to get data.
Will you change the code style or structure?
Only where it reduces risk. Early fixes stay small and close to the existing style so they can be reviewed. Larger refactoring is proposed separately, with the reason, once tests are in place.