M7-T19: Configuration management

Learning objectives

After this lesson, you should be able to:

• List the configuration items that determine a UAV’s behaviour.
• Define baselines, change control and a release procedure with approvals.
• Create and verify a flight manifest with content hashes.
• Detect configuration drift between the approved baseline and the vehicle.

Conceptual explanation

Established Configuration management is standard engineering practice, with formal requirements in aviation and safety standards. The tooling here (git, hashes, manifests) is one practical way to achieve it for a small team.

Configuration items for a UAV, any of which can change behaviour:

• Firmware: autopilot build (version, commit hash, board, build flags).
• Companion software: repositories at commits, container images by digest, OS image and kernel, ROS 2 distribution and package versions, model weights.
• Parameters: the autopilot parameter file and the companion’s configuration files.
• Calibration: camera intrinsics, extrinsics, sensor calibrations, with their date and conditions.
• Hardware: airframe, motors, propellers, battery, sensors, with serial numbers and revisions.
• Documents and procedures: the checklist and the test card used.

A baseline is an approved, identified set of configuration items; changes to it go through change control (request, impact analysis against the traceability matrix, review, approval, regression test, new baseline). A flight manifest records the baseline identifier and the hashes of the actual items on the vehicle at take-off.

Engineering intuition

Most unexplained differences between two flights are configuration differences nobody noticed: a parameter changed during a bench test, a calibration file copied from another vehicle, a container image updated overnight. The remedy is boring and effective: compute hashes of everything, store them with the log, and compare automatically before take-off against the approved baseline.

Reproducibility has a second meaning: building the same source twice gives the same binary. Pin dependencies (lock files, image digests), record compiler versions, and avoid “latest”. If you cannot rebuild what flew, you cannot fix it without changing something else.

Mathematical formulation

Integrity checks use cryptographic hashes: a manifest is a map from item name to hash $h$(x) = SHA-256(x). Two configurations are identical iff their manifests are equal, and the manifest itself has a hash (a Merkle-style root over sorted entries) that serves as the configuration identifier in the log:

Drift detection is the set difference between the vehicle’s manifest and the baseline’s: added, removed and changed items. The probability that two different files share a SHA-256 hash is negligible (about $2^{-128}$ by the birthday bound for collisions among $2^{64}$ files), so a hash mismatch is real and a match is, for practical purposes, identity. Parameters should be compared by value, not only by file hash, so the report can name the parameters that differ.

$h$(x)

SHA-256 hash of the content $x$.

id(config)

identifier of a configuration derived from its items.

Architecture and data flow

Source repositories (git tags) → CI build (pinned, reproducible; artefact hashes recorded) → release package (firmware, container digests, parameter file, calibration files) with a signed baseline manifest → vehicle installation → pre-flight script computes the vehicle manifest and compares it with the baseline (differences must be zero or approved) → manifest written into the flight log and the test record → archive. Changes: issue → impact analysis → review → merge → new baseline.

Real-world UAV applications

• Pre-flight check that the vehicle matches the approved baseline.
• Tracing a regression to the change that introduced it.
• Reproducing a flight in SITL with the same parameters and software.
• Audit trail for a safety review or incident investigation.

Implementation example

This runs as shown. A manifest builder and a drift checker: it hashes configuration files in a temporary directory, builds the configuration identifier, then modifies one parameter and one calibration file and reports the drift, including the parameter-level difference.

import hashlib, json, tempfile, pathlib

def sha(b): return hashlib.sha256(b).hexdigest()
def build_manifest(root):
    items = {str(p.relative_to(root)): sha(p.read_bytes()) for p in sorted(pathlib.Path(root).rglob('*')) if p.is_file()}
    cid = sha(''.join(n + h for n, h in sorted(items.items())).encode())
    return {'items': items, 'id': cid}
def drift(base, now):
    a, b = base['items'], now['items']
    return {'added': sorted(set(b) - set(a)), 'removed': sorted(set(a) - set(b)), 'changed': sorted(k for k in set(a) & set(b) if a[k] != b[k])}
def parse_params(text): return {k: v for k, v in (l.split(None, 1) for l in text.splitlines() if l and not l.startswith('#'))}

with tempfile.TemporaryDirectory() as d:
    root = pathlib.Path(d); (root / 'params').mkdir(); (root / 'calib').mkdir()
    (root / 'params' / 'px4.params').write_text("# parameters\nEKF2_EV_DELAY 55\nEKF2_HGT_REF 3\nCOM_OF_LOSS_T 1.0\n")
    (root / 'calib' / 'cam0.yaml').write_text("fx: 612.0\nfy: 608.0\n")
    (root / 'VERSION').write_text("fw v1.15.4 abc1234\n")
    base = build_manifest(root); base_params = parse_params((root / 'params' / 'px4.params').read_text())
    assert build_manifest(root)['id'] == base['id']                                  # the identifier is deterministic
    (root / 'params' / 'px4.params').write_text("# parameters\nEKF2_EV_DELAY 80\nEKF2_HGT_REF 3\nCOM_OF_LOSS_T 1.0\n")
    (root / 'calib' / 'cam1.yaml').write_text("fx: 590.0\n")
    now = build_manifest(root); dr = drift(base, now)
    now_params = parse_params((root / 'params' / 'px4.params').read_text())
    pdiff = {k: (base_params[k], now_params[k]) for k in base_params if base_params[k] != now_params.get(k)}
    print("baseline id", base['id'][:12], "-> current id", now['id'][:12]); print("drift:", json.dumps(dr)); print("parameter differences:", pdiff)
    assert now['id'] != base['id'] and dr['changed'] == ['params/px4.params'] and dr['added'] == ['calib/cam1.yaml'] and pdiff == {'EKF2_EV_DELAY': ('55', '80')}

Common engineering mistakes

Failure modes

Debugging approach

1. Compare the manifests of a good and a bad flight and list the differences.
2. Rebuild from the tag and compare the binary hash with the flown one.
3. Check the pre-flight manifest comparison for approved exceptions.
4. Diff parameter values, not only files.

Practical exercises

1. Define the configuration items and baseline identifier for your vehicle.
2. Extend the manifest script to record package versions (pip freeze, apt list) and container digests.
3. Write the change-control checklist for a parameter change.
4. Reproduce a past flight in SITL from its manifest and compare the logs.

Interview questions

Write an answer in your own words, then reveal the model answer. Nothing is sent anywhere.

References and further reading

Primary papers, official documentation and standards. Each claim above that is specific to a tool or version points here.

• Reproducible Builds: documentation
• PX4: Parameters
• NASA Systems Engineering Handbook (NASA/SP-2007-6105), configuration management
• Pro Git (version control)

What’s next