Your telemetry and command dictionary is the most-read interface control document on the program, and the only one you keep in two copies. The flight software builds and parses packets from one definition. The ground system decodes them from another, keyed in by a different team, on a different schedule, in a different tool. Every pass, both sides bet that the two copies still say the same thing.
A spacecraft's telemetry and command dictionary is the map from bytes to meaning. It names every parameter, assigns each packet an application process identifier, fixes the bit offsets and lengths and types, carries the calibration polynomial that turns a raw count into a temperature, sets the limits that turn a temperature into an alarm, and lists every command with its opcode and argument order. The flight software is built against it. So is the ground system — SCOS-2000, ITOS, COSMOS, whichever one sits in the control room. Two systems, one interface, and almost always two separate copies of it that somebody reconciles by hand.
The interface is the dictionary, and you keep two of it
On most programs the flight software team owns the real definition, because the real definition is whatever the code actually builds and parses. The ground team keeps a parallel database in the format their tool wants. When flight software adds a housekeeping packet, renumbers an APID, or re-scales a sensor, that change lands in the repository first. The ground database catches up when someone remembers to tell the ground team, or when a discrepancy report drags it into the open.
That gap is an uncontrolled interface. Nobody signed off on it, nobody put it under configuration control, and it moves every time a developer touches a struct. The document that everyone calls the ICD — the signed PDF in the data pack — describes the interface as it was frozen. The dictionary describes the interface as it runs today, and it is the one the operators actually depend on. It is also the one nobody manages like an ICD.
The failures are silent because the numbers still look like numbers
An interface error on a bus like MIL-STD-1553 tends to announce itself: the message does not arrive, or the checksum fails, and something visibly breaks. A dictionary error does the opposite. The packet arrives, decodes cleanly, and shows a number. The number is just wrong.
# flight software, battery telemetry, rev D apid 0x2A, offset 40, uint16 batt_temp_raw cal: degC = 0.0625 * raw - 40 # new thermistor, changed in rev D # ground database, still on rev C apid 0x2A, offset 40, uint16 batt_temp_raw cal: degC = 0.0500 * raw - 30 # old curve
Same APID, same offset, same type. Both sides parse the packet without an error. The console shows a battery temperature that is plausible, trends smoothly, and is off by several degrees for the whole pass. If that parameter feeds a limit check, the alarm fires early, or it never fires at all. Nobody sees a fault, because there is no fault to see. There are only two calibration curves that stopped agreeing three weeks ago, and a display that cannot tell you which one it used.
The command side fails the same quiet way. A command whose argument order changed in flight software, built against a stale ground definition, is not usually rejected. It is assembled, uplinked, accepted, and it does something. Verifying the command by watching telemetry does not save you, because the telemetry is being decoded through the same dictionary that built the command wrong.
The dictionary is the one interface your operators read every pass and the one interface nobody put under change control.
The standard already conceded the point
The industry has known the dictionary is a transfer problem long enough to have standardized the transfer. CCSDS publishes XTCE — the XML Telemetric and Command Exchange — for exactly this: moving a complete telemetry and command definition from one system to another without re-authoring it. XTCE exists because every ground system spoke its own database dialect, every mission was hand-translating dictionaries between them, and hand-translation is where the silent errors breed.
XTCE is the industry writing down, in a schema, that the dictionary is an interface to be handed over from a single authority rather than an artifact each tool re-keys. That is the right diagnosis. Most programs still stop at export: flight software emits an XTCE file, the ground team imports it, edits it to fit local conventions, and from that moment maintains a fork. The exchange format solved the syntax. It did not make anyone treat the dictionary as one source with two readers.
Generate the ground dictionary; don't retype it
The dictionary belongs where every interface belongs: in the code, generated, never authored twice. The packet layouts, the APID assignments, the calibration coefficients, the command arguments already live in the flight software, because the flight software is the thing that enforces them. That definition is the source. The flight decoder, the ground database, the XTCE file, and the human-readable ICD are all outputs of it, built together, versioned together, changed in one diff a reviewer can see.
When the battery thermistor changes in rev D, the calibration moves in one place. The ground database is regenerated from the same commit that changed the flight code, so it cannot lag, because there is nothing left to update by hand. A new APID that the flight software emits and the ground has never heard of stops being possible, because the ground dictionary is built from the list of packets the flight software actually produces. The reconciliation meeting goes away, not because everyone finally agreed, but because there was only ever one thing to agree with.
This is the same position we hold about every ICD: the document is an artifact of the code, not its source. The telemetry and command dictionary just makes the cost of getting it backwards easy to see, because you watch the wrong numbers scroll past in real time.
A stale ICD in a data pack is a latent risk. A stale dictionary in the control room is an active one. It is decoding this pass, right now, against a curve that expired three weeks ago. Generate it from the code that flies, or keep operating a spacecraft through a second copy of the truth that nobody promised to keep current.
