Skip to main content

Example Usage

In this section we will walk through tasking the constellation to orient towards a target on the ground, record radio frequency from that target, process that recording, and queue the results for download. Once downloaded, files will appear in the customer's S3 bucket.

NOTE: The Python used in these examples uses some f-string types, and thus requires a Python version of 3.6 or higher.

Authenticate​

First, we set the authentication token that identifies the user and is passed to every request to the API.

HOST="https://api.orb.spire.com"
AUTH_HEADER="Authorization: Bearer YOUR_AUTH_TOKEN"

Select satellite​

To start the tasking process, we retrieve the list of taskable satellites and their supported window types. This step can be skipped if the desired satellite is already known.

We see here that FM123 has the desired capabilities (PAYLOAD_SDR is supported).

curl -X GET -H "${AUTH_HEADER}" "${HOST}/tasking/satellites"

{
  "data": [
    {
        "id": "FM123",
        "norad_id": "12345",
        "supported_windows": [
            "PAYLOAD_SDR",
            "PAYLOAD_SABERTOOTH",
        ]
    }
  ]
}

Upload processing executable​

We then upload the desired post-processing binary to the selected satellite. This can be skipped if the binary has previously been uploaded as uploads persist on the satellite.

NOTE: Any stdout/stderr of an executable will not automatically be downloaded. They can, however, be included in the execute logs by using "exec" in a given uploaded script.

The destination path of the uploaded executable will be used later when we reserve our SDR window. The server will respond to the request with a JSON payload containing the ID of the upload request. See the example JSON response to the right.

SATELLITE_ID="satellite_id=FM123"
PAYLOAD="payload=SDR"
DESTINATION_PATH="destination_path=/persist/bin/phase1"
EXECUTABLE="executable=true"
QUERY_PARAMS="${SATELLITE_ID}&${PAYLOAD}&${DESTINATION_PATH}&${EXECUTABLE}"

# Create test file to upload
echo "test" > phase1

curl -X POST "${HOST}/tasking/upload?${QUERY_PARAMS}" \
-H "${AUTH_HEADER}"  \
-F "file=@phase1"
{"data": {"id": "8f76a939-609e-4042-8c97-079031af0320"}}

Check upload progress​

Once submitted, the constellation will upload the requested file over subsequent contact(s). To check on the status of the upload we can make a GET request on the /upload endpoint.

Once the executable has successfully been uploaded to the satellite the response will have status "UPLOADED". See the example JSON response to the right.

curl -X GET -H "${AUTH_HEADER}" "${HOST}/tasking/uploads"
{
  "data": [
    {
      "satellite_id": "FM123",
      "payload": "SDR",
      "destination_path": "/persist/bin/phase1",
      "executable": true,
      "status": "UPLOADED",
      "id": "71c92e3c57bc440ea89d76c94cdf387f",
    }
  ]
}

Look for available time slot​

With the desired analysis script on the satellite, the PAYLOAD_SDR window can be scheduled. To discover when the satellite is available for tasking, the /availability endpoint is used. Here we check for times the satellite is available for tasking during a 24 hour period.

This will return a list of periods when the satellite can be tasked for this operation. See the example JSON response to the right.

SATELLITE_ID="satellite_id=FM123"
WINDOW_TYPE="window_type=PAYLOAD_SDR"
START="start=$(date -u +%s)"
DURATION="duration=86400"  # One day
QUERY_PARAMS="${SATELLITE_ID}&${WINDOW_TYPE}&${START}&${DURATION}"

curl -X GET -H "${AUTH_HEADER}" "${HOST}/tasking/availability?${QUERY_PARAMS}"


{
  "data": {
    "available": [
      { "start": 1599445000, "end": 1599473800 },
      { "start": 1599474400, "end": 1599503200 },
      { "start": 1599503800, "end": 1599531400 }
    ]
  }
}

Schedule window​

We now schedule the operation. We create a 10 minute PAYLOAD_SDR window with a 60 second IQ capture over the Bermuda Triangle. This analysis script analyzes this file and outputs a single file results.txt for download with an estimated file size is 10.5 kb.

The constellation will use the download size estimate to allocate contact time for download. If generated files are larger than the downlink budget, file retrieval latency may be affected.

The server will respond to the request with the ID of the scheduled window in a JSON payload. See the example JSON response to the right.

curl -X POST "${HOST}/tasking/window" \
-H "${AUTH_HEADER}" \
-H "Content-Type: application/json" \
-d @- << EOF
{
    "type": "PAYLOAD_SDR",
    "satellite_id": "FM123",
    "start": 1599445000,
    "duration": 600,
    "parameters": {
        "downlink_budget": 10.5,
        "adcs_config": {
            "mode": "NADIR",
            "aperture": "VHF"
        },
        "user_command": {
            "executable": "/persist/bin/phase1",
            "executable_arguments": [
                "--cap-time", "60",
                "--output", "/outbox/results.txt"
            ]
        }
    }
}
EOF


{"data": {"id": "3014288"}}

Receive data​

After the window successfully completes, the results.txt file written to /outbox will be automatically downloaded and, once received, will be pushed directly to the customer's specified S3 bucket.