Working with assets

Put sensors and vehicles in the registry, feed a sensor's detections into the picture, and read the tracks back.

Uses $DOME, $KEY and $WS from Authentication. Every field: Asset model, Observation model.

1. Find the catalogue value

# Sensor profiles. A profile fixes a sensor's reach, field of view and accuracy,
# so none of them is typed by hand
curl -s $DOME/catalog/sensor-profiles \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  | jq -c '.data[] | {id, modality}'
# → {"id":"ground-radar-360","modality":"radar"}
#   {"id":"rf-df","modality":"rf"}
#   {"id":"acoustic-array","modality":"acoustic"}  …

# Airframes. A type id fixes speed, endurance, ceiling and what it carries
curl -s $DOME/catalogue/types \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  | jq -r '.data.types[].id' | grep mavic
# → dji/mavic-3-pro
#   dji/mavic-3  …

2. Place a sensor

MAST=$(curl -s -X POST $DOME/assets \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MAST-1",
    "kind": "sensor",
    "catalog": "ground-radar-360",
    "placement": {
      "lat": 1.3644,
      "lon": 103.9915,
      "height_m": 12,
      "boresight_deg": 90
    }
  }' | jq -r '.data.id')
# name        unique in the workspace, and the sensor id its detections will carry
# kind        sensor. Leave it out and you are registering a vehicle
# catalog     a profile id from step 1
# placement   where it stands. Latitude first; a swapped pair is refused
# height_m    above ground
# boresight   the direction a directional sensor faces, degrees from north
# → MAST=ast_4c1cce01830f454b88799cb047b8d197

A sensor with no placement is 400: with no position it cannot localise anything.

3. Register a vehicle

# Declare it from the catalogue. It is on the friendly list from the next fusion cycle,
# and waits NOT HEARD until a link carries it
HAWK=$(curl -s -X POST $DOME/assets \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HAWK-1",
    "catalog": "dji/mavic-3-pro",
    "spec": { "remote_id_serial": "1581F5FHD228Q00A1234" }
  }' | jq -r '.data.id')
# catalog   a type id from step 1
# spec      laid over the catalogue entry key by key: here, the serial it broadcasts
# → HAWK=ast_339a78dc2b9146aa8736bf2c05a4ccbb

# Or adopt one a link has already heard. List what is announcing itself ...
curl -s $DOME/discoveries \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS"
# → {"ok":true,"data":[ … one entry per vehicle, with the address it was heard on … ]}

# ... and register it by that address. The link comes attached
curl -s -X POST $DOME/assets \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  -H "Content-Type: application/json" \
  -d '{ "name": "HAWK-2",
        "connection": { "integration": "mavlink", "address": "mav-udp-14550-42" } }'
# an address nobody has heard is 404; an address another asset holds is 409

4. Check what is registered

# Every sensor, with where it stands and whether anything has reported as it
curl -s "$DOME/assets?kind=sensor" \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  | jq -c '.data[] | {id, name, profile, placement, link: .link.state}'
# → {"id":"ast_4c1c…","name":"MAST-1","profile":"ground-radar-360",
#    "placement":{"lat":1.3644,"lon":103.9915,"height_m":12,"boresight_deg":90},"link":"unlinked"}

# Vehicles nearest a point, leaving out any a plan has already committed
curl -s "$DOME/assets?kind=vehicle&free=true&nearest=1.3644,103.9915" \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  | jq -c '.data[] | {id, name, link: .link.state}'

5. Send the sensor's detections

# One tick of detections in one request
curl -s -X POST $DOME/signals \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "live",
    "observations": [
      {
        "schema": "obs.v1",
        "obs_id": "mast1-000148",
        "t": "'"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)"'",
        "platform": { "id": "MAST-1",
                      "geo": { "lat": 1.3644, "lon": 103.9915, "alt_m_agl": 12 } },
        "sensor":   { "id": "MAST-1", "modality": "radar" },
        "detection": {
          "class": "uav_multirotor",
          "class_conf": 0.9,
          "geo": { "lat": 1.3712, "lon": 103.9950, "alt_m": 110 },
          "signal": { "modality": "radar" }
        },
        "provenance": { "decoder": "my-bridge/1.2" },
        "quality": { "confidence": 0.9, "geoloc_sigma_m": 15 }
      }
    ]
  }'
# source      live: a real sensor saw it. simulated keeps it out of the live picture
# obs_id      yours, unique. It comes back on the track as evidence
# t           when the sensor saw it, not when you sent it
# platform    where the sensor stands. Height is alt_m_agl here
# sensor.id   the registered name, so the returns count against MAST-1
# detection   what and where. Height is alt_m here. signal is required
# quality     how sure, and the position error in metres
# → {"ok":true,"data":{"accepted":1}}

• One request per tick, up to 5000 observations. A request per detection is a pipeline pass per detection.
• A bearing-only sensor sends "signal": { "modality": "rf", "bearing_deg": 206 } and no detection.geo. Two bearing sensors on the same emitter triangulate.

Every field: Observation model.

6. Read it back

# The sensor as the picture sees it: how many returns, and how long since the last
curl -s $DOME/picture \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  | jq '.data.sensors[] | select(.sensor_id == "MAST-1") | {state, activity}'
# → { "state": "searching",
#     "activity": { "returns_total": 1, "returns_per_min": 1, "silent_for_s": 0 } }

# Tracks. evidence lists the obs_ids behind each one
curl -s $DOME/tracks \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  | jq '.data[] | {track_id, affiliation: .classification.affiliation,
                   status: .existence.status, geo: .kinematics.geo, evidence}'
# → { "track_id": "T-00481", "affiliation": "suspect", "status": "confirmed",
#     "geo": {…}, "evidence": ["mast1-000148", …] }

One detection is not a track. Keep sending at the sensor's update rate, and a contact that keeps being seen is confirmed within a few ticks.

7. Move or remove

# Turn the mast to face south-west. Send only what changes
curl -s -X POST $DOME/assets/$MAST \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS" \
  -H "Content-Type: application/json" \
  -d '{ "placement": { "lat": 1.3644, "lon": 103.9915, "boresight_deg": 225 } }'
# the answer is the stored record, with the change under spec

# Remove it. 204, or 404 if it is already gone.
# A vehicle removed in flight becomes an unknown contact, so land it first
curl -s -X DELETE $DOME/assets/$HAWK \
  -H "X-Api-Key: $KEY" -H "X-Workspace-Id: $WS"

Next: Commanding assets. All asset routes and refusals: Assets & commands.