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.

Flowchart of a legacy firmware takeover in five phases: secure assets, reproducible build, reproduce faults, map and assess, and fix and release. A decision point after assessment chooses between targeted fixes and a partial rewrite, and each phase produces a written output.
Figure 1. Takeover phases and their outputs. The fix-or-rewrite decision comes after assessment, not before.

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:

AssetWhy it matters
Source code, all branches and archivesThe obvious one; look for more than one copy and compare
Toolchain installers and exact versionsCompiler versions change code generation and timing
Build scripts, IDE project files, linker scriptsCarry optimisation flags, memory layout and defines that are not in the source
Binaries currently in the field, with versionsProves which source matches which units
Bootloader source and keys, if anyWithout them you may not be able to update units
Programming tools and production line procedureNeeded to build new units
Hardware design files at each board revisionFirmware branches on board revision
Issue reports, field logs, customer emailsThe 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.

  1. Recreate the toolchain in a container or documented VM, pinning versions.
  2. Build and compare the output with the field binary. Differences in embedded build timestamps or paths are expected; differences in code are not.
  3. 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.
  4. 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:

AreaWhat we look for
StructureModules, layering, how hardware access is organised
ConcurrencyInterrupt handlers, RTOS tasks, shared data, priorities
MemoryStack sizes, heap use, buffer handling, static analysis findings
Error handlingWhat happens on peripheral failure, timeouts, watchdog use
Update pathWhether units can be updated, and how safely
TestsWhat exists, what can be added cheaply
Hardware couplingBoard-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?

IndicationPoints toward
Faults traced to a few specific defectsTargeted fixes
Product in the field with update path workingTargeted fixes, then gradual refactoring
New faults keep appearing from the same structural cause, such as unguarded shared state across tasksPartial rewrite of that subsystem
Hardware platform changing anywayRewrite can be considered with the new platform
No reproducible build and source missing for key partsRewrite 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

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.