Entity workflow

Run RF propagation from a radio entity

Create a located entity with a radio, run RF propagation, wait for the job, and retrieve the generated map tile.

POST/api/terrain-analysis/rf-propagation/entities

01 · Create a radio entity

Create a located entity with a radio capability.

The operation and map must be the ones you created in Getting Started. API keys need theENTITIES scope. The example location is the center of the Getting Started boundary. Blue fills in the remaining radio and antenna defaults for these known models.

Create the radio entity

curl --request POST "$BLUE_API_URL/api/operations/$BLUE_OPERATION_ID/entities/" \
  --header "Authorization: Bearer $BLUE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "profile": {
      "unit_name": "Hilltop Relay",
      "sidc": "10031000001211000000",
      "affiliation": "friendly",
      "capabilities": [
        {
          "id": "primary-radio",
          "type": "communications.radio",
          "schema_version": 1,
          "model": "RT1523_ASIP",
          "config": {
            "network_name": "command",
            "selected_power_level_id": "HI",
            "operating_frequency_mhz": 51.5,
            "antenna": {"model": "AS3900A"}
          }
        }
      ]
    },
    "current_state": {
      "location": {"type": "Point", "coordinates": [-93.0826, 31.10815]}
    }
  }'

Copy the returned entity id.

Use this entity

export BLUE_ENTITY_ID="YOUR_ENTITY_ID"

02 · Start RF

Run RF with the entity's radio.

Start RF propagation

curl --request POST "$BLUE_API_URL/api/terrain-analysis/rf-propagation/entities" \
  --header "Authorization: Bearer $BLUE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "map_id": "'"$BLUE_MAP_ID"'",
    "quality_preset": "balanced",
    "entities": [
      {
        "entity_id": "'"$BLUE_ENTITY_ID"'",
        "radio_capability_ids": ["primary-radio"]
      }
    ]
  }'

Copy the returned job_id.

Use this RF job

export BLUE_RF_JOB_ID="YOUR_JOB_ID"

03 · Poll

Poll until the job succeeds.

Run the curl again until status is success. Stop if it returns failed orcancelled. The Python example performs the polling loop for you.

Poll the RF job

curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer $BLUE_API_KEY" \
  "$BLUE_API_URL/api/terrain-analysis/rf-propagation/jobs/$BLUE_RF_JOB_ID"

04 · Get the tile

Download a tile from the generated RF collection.

List the map-owned tile collections after the RF job succeeds.

List RF collections

curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer $BLUE_API_KEY" \
  "$BLUE_API_URL/api/maps/$BLUE_MAP_ID/ogc/tiles/collections"

Copy the returned collection id. RF collection IDs use the formlayer--{map_layer_id}.

Use this RF collection

export BLUE_RF_COLLECTION_ID="layer--YOUR_LAYER_ID"

This WebMercatorQuad tile covers the example entity location. Tile URLs use{zoom}/{row}/{column}.png order.

Download the RF coverage tile

curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer $BLUE_API_KEY" \
  --output rf-coverage.png \
  "$BLUE_API_URL/api/maps/$BLUE_MAP_ID/ogc/tiles/collections/$BLUE_RF_COLLECTION_ID/tiles/WebMercatorQuad/12/1675/988.png"