Registration Service¶

The Registration Service (gva-registry) is the platform's identity, capability and configuration register. It implements the Def Stan 23-009 Platform Configuration and Registry Service Specification v1.0 (PCRS) and the Command Response Pattern v2.0 (CRP).

Every subsystem on the vehicle — human-machine interfaces, weapon controllers, sensors, gateways, third-party apps — completes a handshake with gva-registry at startup, is assigned a numeric resource ID, and only then may publish anything else on the DDS bus. The service also owns the platform configuration: the set of logical roles the vehicle can be operated in, the set of resources approved for those roles, and the running mapping between the two.

Overview¶

The Registration Service handles:

• Allocation of resource IDs to LRUs and applications, with UUID-based persistence so a given resource keeps the same ID across restarts (§8.2.10 / GVA_PCRR_010);
• Publication of the Configured Platform Specification — the roles the vehicle can be set to, the mandatory / optional resource slots in each role, and the approved hardware / software for each slot;
• Runtime tracking of which allocated resources are mapped to a logical role, which are conflicted, and which mandatory slots are unmapped (§5.2.5, GVA_PCRS_010/016);
• The §6.1 approval state machine — for every runtime resource, the service computes one of Unapproved, Hardware_Approved_No_Software_Approval, Hardware_Approved_Software_Unapproved or Fully_Approved based on the resource's own manufacturer / model / versioned-items report;
• The full non-discoverable resource lifecycle — hard-wired ancillaries (batteries, harnesses, external mounts) whose state cannot be reported by an LRU are configured in JSON, published on the wire, and mutated by operator commands (setStatus, setSerialNumber);
• Operator commands: setOperatingMode, setCurrentRole, mapDescriptor, unmapDescriptor, clearConflict, clearFlags;
• Persistence across power cycles — every allocation, mapping, role selection, ND-resource status and serial number is written to PostgreSQL and restored on start (§3.2.3, GVA_PCRS_026/027);
• Response to every command via the Def Stan 23-009 Command Response Pattern (CRP §3, GVA_CRP_1..10) on both the Resource_ID_Allocation and Platform_Configuration domains.

The service is a headless daemon backed by PostgreSQL. All inter-process traffic is DDS; every DDS interaction is defined by an IDL contract in the shipped Reference Model.

Roles on the wire¶

The registry is the single source of truth for platform configuration. It is never optional — an LRU that cannot register is required by §8.2.8 to keep retrying and MUST NOT fall back to a hard-coded resource ID.

Registration handshake¶

Registration is a two-topic request/response over DDS. Both topics belong to the Resource_ID_Allocation PSM.

Auto-mapping (GVA_PCRS_052)¶

A resource that has never registered before is normally left unmapped — the registry publishes Missing_Resource_Mapping and an operator must issue mapDescriptor to bind it to a logical role. A Discoverable_Resource_Specification flagged autoMapResource: true in platform-config.json skips that wait: if the incoming requestResourceId's reported resourceInstance/versionedItems uniquely matches exactly one such spec, and the resulting approval state would be Fully_Approved or Hardware_Approved_No_Software_Approval (never Hardware_Approved_Software_Unapproved), the registry maps the resource to that spec's logical role immediately as part of the same handshake — Missing_Resource_Mapping is never raised and no mapDescriptor command is needed. Ambiguous matches (more than one spec matches) always fall back to the manual Missing_Resource_Mapping/mapDescriptor path. See the registry-auto-map SDK example.

Idempotency¶

requestResourceId is idempotent. Publishing the same (UUID, referenceNum) twice — for example after a partial startup — results in the registry re-serving the same supplyResourceId sample. The registry logs an INFO trace on the duplicate but does not treat it as an error.

Persistence — the crux¶

Every LRU MUST persist:

1. its UUID, generated once on first boot, and
2. the resourceId supplied by the registry.

On subsequent boots the LRU replays requestResourceId with the stored UUID. Because the registry keys allocations on UUID (§3.2.3, GVA_PCRS_003), the same resourceId is re-issued. Every downstream service (alarms register, UACM usage history, HMI mapping tables) can therefore correlate history across power cycles.

Losing the UUID forces the registry to allocate a fresh ID and breaks that correlation — every stored fault, every stored usage record, every mapped alias points at a resource that no longer exists.

The reference implementation for this behaviour is gva::GvaResource (in qt6-gva-resource-lib), which every internal Qt6 application uses. The raw-DDS reference is the registration SDK example, which supports --persist-path=<file> for a minimal key=value UUID + resourceId store.

Platform Configuration¶

The platform configuration is loaded from platform-config.json on start. It defines:

• Logical roles the vehicle can be operated in (Patrol, Combat, Recon, Maintenance…). Each role is published as a Role_Definition sample.
• The discoverable resource specifications for each role — the set of mandatory / optional resource slots and, for each slot, the list of Approved_Resource_Definition records (manufacturer / model / version-match sets). Published as Discoverable_Resource_Specification samples.
• The non-discoverable resource specifications — resources whose state cannot be reported over DDS (harnesses, mechanical fixtures, external stores). Published as Non_Discoverable_Resource_Specification samples.

At start, the service also selects an initial currentRole:

• if the DB records a role that was current at the last clean shutdown, that role is restored;
• otherwise the role flagged default: true in the JSON is used;
• if neither exists, the first role in the JSON is used.

Configured_Platform_Specification is published as a single transient-local sample cross-referencing every role. Any subscriber that joins later gets the full configuration replayed.

Configured_Platform_With_Registry (CPW) — the health broadcast¶

CPW is the central "platform is healthy" broadcast. It aggregates the state of every allocated resource against the current role and tracks three orthogonal problem sets:

Every mutation on the wire (a Registered_Platform_Resource sample arriving, a mapDescriptor command being processed, a role change, etc.) causes CPW to be re-published so subscribers always see a consistent snapshot.

Resource approval — the §6.1 state machine¶

For every allocated discoverable resource, the registry publishes a C_Discoverable_Resource sample whose A_approval field carries one of four values:

The evaluation is performed by the ApprovalEvaluator class inside the service. Downstream HMIs can render the four states directly (e.g. green / amber / red badge on the platform-config page).

Whether versionNumber fields are matched as plain text or as regular expressions is a whole-configuration choice (GVA_PCRS_050); the service auto-detects the encoding from the JSON at load time and refuses to start if the file mixes the two.

Non-Discoverable Resources¶

Non-discoverable resources are hardware fixtures the platform is required to know about but which cannot advertise themselves over DDS — a fitted harness, an armour panel, a wire-guided-missile stowage rack, an external battery. They are declared in platform-config.json and driven exclusively by operator commands.

For each configured ND resource the service publishes:

• one Non_Discoverable_Resource_Specification sample describing the resource (role descriptor, approved status list, mandatory flag) — transient-local, re-emitted on demand;
• one Non_Discoverable_Resource sample carrying the current A_status and A_serialNumber. Updated on every setStatus and setSerialNumber command.

Status transitions¶

The operator or maintainer mutates state via Non_Discoverable_Resource_setStatus:

The default status when no DB row exists is Fully_Functional. Every mutation is persisted to PostgreSQL (GVA_PCRS_019/020/023) and survives power cycles.

Serial-number tracking¶

Non_Discoverable_Resource_setSerialNumber updates the resource's A_serialNumber for accountability / maintenance history purposes. This is mandated by §5.4.4 (Table 2 line 559) — the service must subscribe to both setStatus and setSerialNumber. The two commands are independent: setting a serial number does not change status and vice-versa.

Operator commands¶

The registry accepts nine operator commands, split across two Def Stan 23-009 PSM domains. Every command carries CRP envelope fields (A_recipientID, A_referenceNum, A_metadata, A_responseRequired).

Resource_ID_Allocation domain¶

Platform_Configuration domain¶

Recipient filtering¶

Every set* command carries A_recipientID. The registry silently drops any command whose recipient is not the registry's own resourceID — an HMI must address A_recipientID.A_resourceId = 10000 (the registry's well-known ID) on any command it wants the registry to act on. This matches §5.5.29 / GVA_PCRS_009.

Command responses (CRP)¶

Every command handler funnels through one of two response publishers (RIDA or Platform_Configuration) driven by the CRP §3 requirements:

• If the command's A_responseRequired == true, the service publishes exactly one T_CommandResponseType sample carrying the same A_referenceNum and a T_ResultType describing the outcome (GVA_CRP_1..4).
• If A_responseRequired == false, no response is emitted (GVA_CRP_2).

Persistence¶

The registry is stateful. Every one of the following is written to PostgreSQL and restored on start:

platform-config.json is static configuration — it is loaded on start but never written back. Runtime state that mutates in response to commands lives entirely in the DB.

Reserved-ID discipline¶

Def Stan 23-009 §3.2.3 / GVA_PCRS_003 reserves resource IDs 0..9999 for well-known static entities. The registry enforces this in code:

An LRU that hard-codes a resourceId in the reserved range is non-conformant and will be rejected on registration.

The Registered_Platform_Resource topic¶

Registered_Platform_Resource is the per-resource identity broadcast. Under §4.1.4 + Table 3 it is published by each individual resource — the LRU announces itself once its handshake completes — and the registry only subscribes to correlate with allocations.

For backwards-compatibility with subscribers that have historically consumed an aggregated stream from the service, the current build also publishes an aggregate Registered_Platform_Resource covering every allocated resource by default. Deployments running the strict compliance harness disable the aggregate with:

gva-registry --disable-registry-aggregator ...

When the flag is set, the service subscribes only, and every LRU is solely responsible for its own Registered_Platform_Resource publication.

Configuration¶

platform-config.json¶

Resolution order (highest to lowest precedence):

1. -c/--config=<file> on the command line — explicit path, wins outright.
2. /etc/gva/registry/platform-config.local.json — operator override. Never shipped by the package, so it is never overwritten on upgrade. Use this to customise the platform configuration without editing the package-owned default in place.
3. /etc/gva/registry/platform-config.json — the packaged default, installed by the gva-registry-service package. Overwritten unconditionally on every upgrade.
4. Dev-tree fallbacks — ./platform-config.json, <appDir>/etc/platform-config.json, <appDir>/platform-config.json — only relevant when running an unpacked build out of build/bin without installing.

The first file found wins; the service logs a warning and runs without platform configuration if none of the search paths resolve.

The file has four top-level sections:

1. platform — human-readable platform descriptor and the setCurrentRoleSupported / setOperatingModeSupported booleans;
2. roles — the list of Role_Definition entries. Exactly one entry should carry default: true;
3. discoverableResources — the mandatory / optional discoverable slots per role, with Approved_Resource_Definition records;
4. nonDiscoverableResources — the ND resources declared for the platform.

See the packaged default at /etc/gva/registry/platform-config.json — it doubles as a worked example for a Patria XA-185 Pasi variant (see placeholder slots below).

Placeholders and platform-integrator responsibilities¶

The shipped sample platform-config.json contains 11 deliberate placeholder slots — approved-resource entries that describe the shape of what should be fitted to a Patria XA-185 Pasi variant, but carry stub manufacturer and model data because the actual LRU choice is a platform-integrator decision.

The convention (also documented in the file's own _notice block) is:

• "manufacturer" prefixed with TODO- — typically TODO-PLATFORM-INTEGRATOR
• and/or "model" ending with -PLACEHOLDER (RMWS-PLACEHOLDER, CDR-DISP-PLACEHOLDER, TGN-DISP-PLACEHOLDER, DRV-DISP-PLACEHOLDER, PWR-MGMT-PLACEHOLDER, LSA-PLACEHOLDER, COMMS-PLACEHOLDER, BMS-PLACEHOLDER, ECU-PLACEHOLDER, TRANS-PLACEHOLDER, VHM-PLACEHOLDER).

At startup the registry parses these entries normally — they satisfy §6.1 / GVA_PCRS_047 (each spec has ≥1 approvedResources entry) — and then emits a compact qWarning() summary listing every placeholder slot it detected. Example:

[PlatformConfigLoader] ⚠ 11 placeholder resource slot(s) in
    /etc/gva/registry/platform-config.json — platform integrator must
    replace TODO- entries with real manufacturer/model/versionedItems
    before deployment. This is NOT a service error; the registry runs
    normally with placeholders.
    ↳ TODO-PLATFORM-INTEGRATOR  (role: ROLE::RMWS, model: RMWS-PLACEHOLDER)
    ↳ TODO-PLATFORM-INTEGRATOR  (role: ROLE::CommanderDisplay, model: CDR-DISP-PLACEHOLDER)
    …

This warning is expected on the shipped sample and does not indicate a service error. The registry is functioning normally; the warning is a checklist for the platform integrator.

To resolve each placeholder:

1. Identify the LRU actually fitted for that role (RMWS = Remote Weapon Station, LSA = Local Situational Awareness, etc.).
2. Edit /etc/gva/registry/platform-config.json — replace the manufacturer, model, referenceNumber and every versionedItems entry (name / version / optional checksum) inside versionMatchSets with the real fielded values.
3. Restart gva-registry. The warning line should now show a lower count (or vanish entirely once every slot is resolved).

Placeholders never block registration: an LRU that ships the correct logicalRoleDescriptor and matches the placeholder approved-resource descriptor will still register — but its Discoverable_Resource approval status will be Unapproved until the integrator fills in the real approved-resource data, so the CPW missingResources list will still flag it. This is the intended behaviour: the placeholder acts as a wire-visible reminder that the platform config still needs work.

PostgreSQL¶

The registry expects a database provisioned by gva-db-init.sh (/usr/libexec/gva-db-init.sh, run once from the dedicated gva-db-init-service package's postinst at install/upgrade time — it is not a command an operator invokes directly). That script creates the gva_user role and the shared gva_alarms_db database (the same database alarms and UACM use, distinguished by schema).

Connection settings are read from environment variables, not a CLI flag — set them in /etc/default/gva-registry:

Tables are created idempotently (CREATE TABLE IF NOT EXISTS) on every start; there is no separate migration step to run.

DDS domain¶

Every process on the vehicle — HMI, LRUs, gateways, this service — must run on the same DDS domain ID. The default is 0, overridable via --domain=<N>.

Database maintenance CLI¶

Two one-shot recovery actions are exposed on the gva-registry binary. Both perform the requested action at startup, then the service continues normal boot; there is no separate one-shot systemd unit.

--db-truncate and --db-clear are mutually exclusive; passing both together aborts with exit code 2 before any rows are touched.

Typical use cases:

• Dev / test: after landing a schema change or after a batch of LRUs churned through fresh UUIDs, --db-truncate clears the legacy allocation slush without stomping on immutable platform content.
• Field re-fit: when the platform integrator swaps a placeholder entry (§Placeholders above) for a real LRU and wants the fleet to rediscover cleanly, --db-clear is the sledgehammer that guarantees no leftover state.
• Factory refurbishment: on a returned vehicle, --db-clear followed by a fresh platform-config.json deploy gives a clean starting point.

Both actions log every row count they delete, per table, to journald. Example:

[Registry-DB] ✓ Truncated 16 dynamic resource allocation(s) (resource_id >= 20001)
[gva-registry] --db-truncate complete: 16 dynamic allocation(s) deleted.
Continuing normal service boot; affected LRUs will re-request resource
IDs on next boot.

For per-row surgery (delete a specific allocation without touching anything else) use the operator-facing DDS commands instead: unmapDescriptor disposes an allocation and, if deallocateResourceId is set, releases the ID back into the pool.

Startup, restart and shutdown¶

• Startup — the service loads platform-config.json, connects to PostgreSQL, rehydrates every allocation, publishes Configured_Platform_Specification, every Role_Definition, every Discoverable_Resource_Specification, every Non_Discoverable_Resource_Specification, restores the last currentRole and operatingMode, and only then begins accepting request/supply handshakes.
• Runtime resource restart — when an LRU restarts it re-sends requestResourceId with its stored UUID; the registry re-issues the same resourceId and emits an INFO log line for the idempotent path.
• Registry restart — on restart the service replays every transient-local state topic from the DB. Late joiners (including the HMI) receive the current snapshot without any special handling.
• Orphan reclaim — an allocation that was created more than the grace window ago and never followed up with a Platform_Resource_Specification sample is silently reclaimed. The UUID is retained so a very late follow-up still gets the same resourceId back.

Troubleshooting¶

SDK examples¶

Every wire-level behaviour on this page is covered by a raw-DDS SDK example under /usr/share/ldm-sdk/examples/ (installed by the ldm-sdk-examples package). See the SDK — Registry Examples reference page for the per-example index and build instructions.