DEV Community: UNITED UAV Official

Designing a Dual-Sensor Data Contract for a Thermal VTOL Pipeline

UNITED UAV Official — Fri, 28 Aug 2026 11:30:37 +0000

A dual-sensor UAV can produce visible video, thermal frames, aircraft position, attitude, gimbal angles, target detections, and operator events at different rates. The difficult part is not collecting every stream. It is proving which observations belong together without inventing precision that the source system never provided.

This article develops a data contract for that problem. It uses the UNITED UAV UVH2 dual-sensor fixed-wing VTOL drone as a concrete product context. The current listing describes a K8T-V2 payload with an 8 MP visible channel, 4K visible recording, a native 640 × 512 thermal detector, processed 1280 × 1024 thermal super-resolution, and Ethernet, serial, and SBUS interfaces. It also identifies the communication protocol as proprietary.

That last detail defines the software boundary: obtain the supported interface-control document and use an approved adapter. The schemas and code below describe a downstream observation pipeline. They are not the UVH2 command protocol, do not reverse-engineer it, and must not be placed in a flight-critical control path.

Commercial disclosure: UNITED UAV Official publishes this technical article and links to a product sold through the UNITED UAV store.

Why a filename pair is not a data contract

A common first implementation writes visible_001.jpg and thermal_001.jpg, then assumes the matching number proves that the files were captured together. That assumption breaks when one encoder drops a frame, a camera restarts, a buffer flushes late, or a transmission path reorders messages.

The pipeline needs to preserve three different facts:

what each source reported;
how the integration correlated the sources;
how confident the integration is in that correlation.

Those facts should remain visible to every downstream consumer. An inspection model may accept a 200 ms pairing tolerance. A moving-target workflow may require a much tighter limit. A reviewer should never have to infer that tolerance from filenames or application code.

Define an immutable capture bundle

Treat every correlated observation as an immutable bundle. Large media files stay in object storage; the event carries their checksums, dimensions, formats, timestamps, and references.

{
  "schema_version": 1,
  "capture_id": "01J6FGP8B0V5TGQ1M9A2X4K7CZ",
  "vehicle_id": "uvh2-field-07",
  "mission_id": "roof-baseline-2026-08-28-r3",
  "observed_at": "2026-08-28T06:18:42.481Z",
  "source_clock_ns": 5842284190031,
  "clock_epoch": "payload-boot-0194",
  "visible": {
    "object_uri": "s3://uav-raw/2026/08/28/visible/01J6F.jpg",
    "sha256": "...",
    "width": 3840,
    "height": 2160,
    "encoding": "jpeg",
    "source_sequence": 18422
  },
  "thermal": {
    "object_uri": "s3://uav-raw/2026/08/28/thermal/01J6F.bin",
    "sha256": "...",
    "width": 640,
    "height": 512,
    "representation": "native_detector",
    "source_sequence": 9211
  },
  "correlation": {
    "method": "source_clock_nearest",
    "delta_ms": 18.4,
    "max_allowed_delta_ms": 50,
    "quality": "accepted"
  },
  "pose": {
    "position_source": "aircraft_telemetry",
    "attitude_source": "aircraft_telemetry",
    "gimbal_source": "payload_telemetry",
    "sample_delta_ms": 11.2
  },
  "adapter": {
    "version": "2.3.1",
    "interface_document_revision": "vendor-approved-revision"
  }
}

The example deliberately avoids claiming that every payload exposes the same fields. The adapter should record null plus a reason when the supported interface does not provide a value. Fabricated defaults are more dangerous than missing data.

Use two clocks, not one

Wall-clock time answers when an observation occurred in a shared timeline. A monotonic source clock answers how events were ordered inside one boot session. Both are necessary.

observed_at should use UTC with an explicit offset. source_clock_ns should never move backward during one clock_epoch. A payload restart creates a new epoch even if its sequence counter returns to zero. The ingestion service can then distinguish a reboot from delayed delivery.

Store clock-quality metadata separately:

synchronization source, such as GNSS, PTP, NTP, or platform-provided time;
last successful synchronization time;
estimated offset and uncertainty;
detection of an unexpected time step;
adapter receive time and storage time.

A precise-looking timestamp is not proof of accurate synchronization. If uncertainty is unknown, say so and lower the correlation quality.

Keep native and derived thermal imagery distinct

The UVH2 listing separates the native 640 × 512 detector from 1280 × 1024 thermal super-resolution output. A data model should preserve that distinction. Upscaled or enhanced output is useful, but it is not a higher-resolution detector measurement.

Use an explicit representation field:

native_detector
processed_super_resolution
colorized_preview
visible_thermal_overlay

Derived assets should reference their parents and record the processing version, parameters, and checksum. Never overwrite the native input with an enhanced image. If a later model produces a different result, both versions should remain reproducible.

Thermal observation also does not automatically mean calibrated temperature measurement. If radiometric values are required, the contract needs documented units, calibration state, emissivity handling, reflected-temperature assumptions, measurement range, accuracy, and invalid-pixel behavior. When the source interface does not provide those fields, the pipeline should label the asset as qualitative thermal imagery.

Make partial pairs first-class events

A dual-sensor pipeline must tolerate one channel arriving late or not arriving at all. Use an explicit lifecycle:

received_visible_only
received_thermal_only
paired_pending_validation
paired_accepted
paired_rejected
expired_unpaired

Do not keep an event in memory forever while waiting for its partner. Persist the first observation, start a bounded correlation window, and finalize it as expired_unpaired when the deadline passes. A late partner can create a new reconciliation record without rewriting history.

The difference matters operationally. A missing visible frame may still leave a useful thermal observation. A missing thermal frame may still preserve visual context. Downstream systems can decide whether a partial bundle is usable, but they should not be told that a complete pair exists.

Validate at ingestion

Validation should reject malformed events before analytics or indexing. A dependency-free Python example can enforce some basic invariants:

from datetime import datetime, timezone


ALLOWED_THERMAL_REPRESENTATIONS = {
    "native_detector",
    "processed_super_resolution",
    "colorized_preview",
    "visible_thermal_overlay",
}


def parse_utc(value: str) -> datetime:
    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
    if parsed.tzinfo is None:
        raise ValueError("observed_at requires a timezone")
    return parsed.astimezone(timezone.utc)


def validate_bundle(bundle: dict) -> None:
    if bundle.get("schema_version") != 1:
        raise ValueError("unsupported schema_version")

    for field in ("capture_id", "vehicle_id", "mission_id", "clock_epoch"):
        if not isinstance(bundle.get(field), str) or not bundle[field].strip():
            raise ValueError(f"missing {field}")

    parse_utc(bundle["observed_at"])

    correlation = bundle["correlation"]
    delta = float(correlation["delta_ms"])
    limit = float(correlation["max_allowed_delta_ms"])
    if delta < 0 or limit <= 0:
        raise ValueError("invalid correlation timing")
    if correlation["quality"] == "accepted" and delta > limit:
        raise ValueError("accepted pair exceeds timing limit")

    thermal = bundle.get("thermal")
    if thermal and thermal["representation"] not in ALLOWED_THERMAL_REPRESENTATIONS:
        raise ValueError("unknown thermal representation")

    for channel in ("visible", "thermal"):
        asset = bundle.get(channel)
        if not asset:
            continue
        if asset["width"] <= 0 or asset["height"] <= 0:
            raise ValueError(f"invalid {channel} dimensions")
        if len(asset["sha256"]) != 64:
            raise ValueError(f"invalid {channel} checksum")

Production validation should use a versioned schema format and bounded payload sizes. Keep rejected metadata in a quarantine stream with reason codes; do not silently discard it or mix it with accepted observations. Media decoders need their own resource limits because image dimensions in metadata cannot be trusted until the bytes are inspected.

Make idempotency content-aware

Networks retry. Edge computers reboot. Upload workers receive the same message twice. A stable event identity prevents those normal behaviors from multiplying observations.

Use capture_id as the business identity and verify that any repeat has the same immutable digest. The outcomes should be:

same ID, same digest: harmless retry;
same ID, different digest: conflict requiring investigation;
new ID, same source sequences and clock epoch: probable duplicate from an upstream identity defect;
new ID, same media checksums: duplicate asset or repeated capture requiring a documented decision.

Write the event and its asset references atomically, or keep an explicit state such as metadata_committed_assets_pending. A database row that points to missing media is not a complete ingestion result.

Separate observation from inference

Target recognition, tracking, anomaly scoring, mapping, and thermography interpretation are downstream results. Store them as derived records that point back to the immutable capture bundle. Each result should include:

model or algorithm name and version;
model-file checksum;
input capture ID and asset representation;
thresholds and preprocessing version;
output coordinate system;
confidence and known limitations;
reviewer state when a human decision is required.

Do not write a detection back into the source event as if the camera observed a semantic truth. The camera produced pixels and metadata; an algorithm produced an interpretation. That separation makes reprocessing, disagreement analysis, and incident review possible.

Protect operational and personal data

Visible and thermal UAV data may reveal people, vehicles, infrastructure, precise locations, schedules, and operational patterns. Minimize collection to the approved mission, encrypt data in transit and at rest, use short-lived scoped credentials, and log access to original media.

Keep raw media separate from public application paths. Derived previews should remove unnecessary metadata and use redaction when the workflow requires it. Retention policy should apply to raw files, thumbnails, detections, exports, backups, and cached edge copies—not only to the primary database.

The adapter that reads the supported payload interface should have no broader command permission than it needs. Observation ingestion must not become an undocumented route to aircraft or gimbal control.

Test the failure modes

Before relying on the pipeline, replay at least these scenarios:

visible frames arrive before, after, and without thermal frames;
sequence counters restart after a payload reboot;
wall time jumps while the monotonic clock continues;
a processed thermal asset is incorrectly labelled as native;
the same capture ID arrives with a different checksum;
object storage succeeds but metadata commit fails, and vice versa;
the adapter version changes during a mission;
media is truncated, oversized, or declares false dimensions;
telemetry and gimbal samples are older than the configured limit;
a late event arrives after the correlation window expires.

For each test, define the expected event state and evidence before running it. A pipeline that merely avoids crashing is not necessarily correct. It should expose why a bundle was accepted, rejected, left partial, or quarantined.

A practical readiness checklist

Before production use, confirm that:

the delivered payload and approved interface document match the adapter version;
every boot session has a distinct clock epoch;
wall-clock accuracy and monotonic ordering are recorded separately;
pairing tolerance is explicit and mission-appropriate;
native and processed thermal representations cannot be confused;
partial and late observations have bounded, auditable states;
media bytes are verified independently of metadata;
retries are idempotent and digest conflicts stop processing;
inference outputs never overwrite source observations;
retention, redaction, encryption, and access logging cover edge and cloud copies.

A strong dual-sensor pipeline does not hide uncertainty. It turns timing, derivation, missing data, and interface revision into fields that can be tested. That makes the resulting data more useful to developers and more defensible to operators and reviewers.

Review the current UVH2 product page for the published platform and payload starting point. For a real integration, request the current K8T-V2 interface-control document, supported command and telemetry definitions, connector details, licensing terms, sample files, and a configuration-specific acceptance procedure.

Designing a Fail-Closed API Integration for an Autonomous Drone Dock

UNITED UAV Official — Fri, 28 Aug 2026 11:23:30 +0000

Autonomous drone docks sit at an awkward boundary: they look like IoT devices, but a command can eventually affect a real aircraft. That makes a conventional "send request and retry on failure" integration unsafe. The software must distinguish observation from authorization, reject stale or ambiguous commands, and fail closed whenever state cannot be proven.

This article presents a reference architecture for that integration problem. It uses the UNITED UAV UK03 drone docking station as a concrete product context because its current listing includes API availability, RTK, internal and external cameras, weather sensing, optional edge computing, optional mesh networking, and optional SIM-based 4G. The listing does not publish an endpoint schema, so every endpoint and payload below is deliberately illustrative. A production implementation must use the current vendor documentation and the approved aircraft-management workflow.

Commercial disclosure: UNITED UAV Official publishes this technical article and links to a product sold through the UNITED UAV store.

Start by separating four kinds of state

Many integrations become dangerous because they compress several questions into one boolean such as ready: true. A safer model records at least four independent states:

Observed state — what the dock, aircraft, weather sensors, and network last reported.
Validated state — whether those observations are recent, internally consistent, and within the operating envelope.
Authorized intent — which mission was approved, by whom, for which aircraft, site, route, and time window.
Executed state — what the vendor platform accepted and what later telemetry proves actually happened.

A positive observation is not authorization. An accepted API response is not proof of aircraft motion. A dashboard that has stopped updating is not evidence that conditions remain unchanged. Keeping these states separate makes the system easier to audit and prevents a stale green status from becoming a launch decision.

Put an adapter in front of the vendor API

Do not let schedulers, dashboards, or business applications call the dock API directly. Put a narrow adapter between them:

Planner -> Intent Store -> Safety Gate -> Dock Adapter -> Vendor Platform
              |               |              |
              v               v              v
          Audit Log      State Snapshot   Readback Worker

The adapter should expose only the small set of operations the organization has approved. It can normalize vendor-specific status codes, enforce request IDs, apply timeouts, and redact secrets from logs. If the vendor API changes, only the adapter should need to understand the new schema.

This boundary is also where command and telemetry permissions can be separated. A monitoring service may need read-only access to weather, dock health, charging state, and alarms. It should not automatically inherit permission to open the dock, schedule a route, or dispatch an aircraft.

Make every command an expiring intent

A mission request should be an immutable record, not a transient button click. For example:

{
  "intent_id": "01J6E7Y9M2K8Q4R5T6V7W8X9ZA",
  "site_id": "solar-north-01",
  "aircraft_id": "uis220-07",
  "mission_revision": 4,
  "approved_by": "ops-review-queue",
  "not_before": "2026-08-28T02:00:00Z",
  "expires_at": "2026-08-28T02:10:00Z",
  "required_state_revision": 1842
}

The intent_id becomes the idempotency key. mission_revision prevents an older route from being dispatched after an edit. expires_at prevents a delayed queue message from starting a mission outside its approval window. required_state_revision binds the decision to a particular validated snapshot instead of whatever state happens to exist later.

If the vendor API supports an idempotency header, pass the intent ID through. If it does not, the adapter must keep its own durable command ledger and query vendor state before deciding whether a retry is safe. Never generate a new intent ID merely to make an uncertain request succeed.

Validate freshness before values

A weather value can be numerically safe and operationally useless if it is old. Every safety-relevant observation should carry three timestamps:

when the sensor measured it;
when the platform received it;
when the integration read it.

The safety gate should reject missing timestamps, future timestamps beyond an allowed clock-skew window, and observations older than the system's documented freshness limit. Apply the same rule to dock-door state, aircraft-in-place detection, charging state, RTK status, network health, and camera availability.

A compact TypeScript-style check might look like this:

type GateResult =
  | { ok: true; snapshotRevision: number }
  | { ok: false; reasons: string[] };

function validateSnapshot(s: Snapshot, nowMs: number): GateResult {
  const reasons: string[] = [];

  if (nowMs - s.observedAtMs > 15_000) reasons.push("snapshot_stale");
  if (!s.aircraftInPlace) reasons.push("aircraft_not_confirmed");
  if (s.activeAlarmCount > 0) reasons.push("active_alarm");
  if (!s.weather.dataQualityOk) reasons.push("weather_quality_unknown");
  if (!s.network.commandPathHealthy) reasons.push("command_path_unhealthy");
  if (s.maintenanceLock) reasons.push("maintenance_lock");

  return reasons.length
    ? { ok: false, reasons }
    : { ok: true, snapshotRevision: s.revision };
}

The example intentionally does not hard-code wind, temperature, rainfall, or battery thresholds. Those limits must come from the most restrictive verified value across the aircraft, payload, dock configuration, route, regulation, and operator procedure.

Use a command state machine

A boolean sent field cannot represent an external command safely. Use explicit states:

prepared
  -> rejected_prewrite
  -> dispatch_requested
  -> accepted_unverified
  -> verified
  -> outcome_uncertain

rejected_prewrite means no external write occurred. It is safe to prepare a new intent after correcting the reason. accepted_unverified means the vendor acknowledged the request, but independent state has not yet proved the result. outcome_uncertain means a timeout or connection loss happened after transmission may have begun. That state must trigger readback, not a blind retry.

Persist the transition before and after the external call. The log should contain the intent ID, payload digest, vendor request correlation ID when available, response status, timestamps, adapter version, state revision, and redacted error class. It should never contain API keys, session tokens, or complete signed URLs.

Read back the effect independently

After a command is accepted, query the authoritative state surface. For a scheduled mission, verify the mission identifier, route revision, aircraft, dock, planned time, and enabled status. For a door or charging operation, verify the resulting hardware state and its observation timestamp.

Use a different read path when the platform provides one. For example, a command endpoint may acknowledge queueing while a mission-status endpoint reports execution. Telemetry can then confirm physical progress. These layers answer different questions and should not be treated as duplicates.

A successful readback should be narrow and deterministic:

const accepted = await adapter.dispatch(intent);
await ledger.markAccepted(intent.intent_id, accepted.correlationId);

const finalState = await adapter.readMission(accepted.missionId);
assert(finalState.intentId === intent.intent_id);
assert(finalState.revision === intent.mission_revision);
assert(finalState.aircraftId === intent.aircraft_id);

await ledger.markVerified(intent.intent_id, finalState);

If any assertion fails, preserve both records and escalate. Do not overwrite the mismatch with the newest response.

Keep humans at the right boundary

Human approval should apply to a complete, reviewable mission intent. The reviewer should see the route revision, aircraft and payload, launch window, forecast and live weather, site status, airspace or operating approval, expected communications path, and defined abort behavior.

The integration may automate collection, validation, expiry, and readback. It should not silently broaden an approval when a route, aircraft, payload, time window, safety limit, or site changes. Those changes create a new revision and may require a new approval.

This distinction also helps during incidents. Operators can determine whether a bad outcome came from incorrect source data, a validation defect, an authorization error, an adapter failure, vendor-platform behavior, or a physical-system fault.

Design network loss as a normal state

The UK03 listing describes optional 4G and mesh capabilities, but multiple bearers do not make a network infallible. Define behavior for at least these cases:

the adapter cannot reach the vendor platform before dispatch;
the request times out after bytes may have been transmitted;
telemetry continues but the command channel is unavailable;
the dock is reachable but the aircraft link is degraded;
the WAN fails during a mission;
buffered events arrive out of order after reconnection.

For each case, document which component owns the safe response. Flight-critical failsafes belong in the validated aircraft and approved control system, not in a remote web service. The external integration should observe and report those states without pretending it can replace them.

Test faults before unattended operation

A staging environment is useful, but it is not enough. The production configuration should go through controlled acceptance tests with the real dock, supported aircraft, network path, and management platform. Include:

duplicate command delivery with the same intent ID;
an expired intent arriving late;
a route revision changing after approval;
stale weather and dock-status observations;
API timeout before and after request transmission;
loss and recovery of WAN, RTK corrections, and telemetry;
an aircraft not correctly detected in the dock;
an active maintenance lock or unresolved alarm;
a readback that disagrees with the accepted command;
adapter restart during every state-machine transition.

Record the expected safe state and pass criterion before each test. A fault-injection exercise is successful when the system prevents or contains the unsafe action and preserves evidence, not merely when it emits an error message.

A practical production checklist

Before enabling an autonomous dock integration, confirm that:

vendor API documentation matches the delivered hardware, licenses, and software version;
read-only and command credentials are separated and can be rotated;
every intent is immutable, versioned, expiring, and idempotent;
observations include freshness and data-quality checks;
command outcomes have explicit uncertain and verified states;
retries require readback after any ambiguous transmission;
logs are durable, redacted, time-synchronized, and reviewable;
human approval covers the exact mission revision and operating window;
aircraft and dock failsafes work without the external automation;
controlled fault tests have been completed and defects closed.

The central design principle is simple: an automation system should only advance when it can prove that the required state, authorization, and prior outcome all match. Anything less becomes a stop condition. That approach may produce more visible refusals during development, but it also makes the integration understandable, testable, and safer to operate.

Review the current UK03 product listing for the published configuration starting point, then request the applicable API documentation, supported-aircraft matrix, licensing details, and acceptance procedure for the actual deployment.