Telecommands · Stellar Control

POST/v1/tc

Submit telecommand#

Submit a direct telecommand

Resolves the telecommand against the current configuration (its name alone when unique in the platform, else component.name; arguments as written in a run request, converted into their unit, checked against their range, completed by their defaults) and submits it to the executor, which runs it as an implicit one-step procedure: requires, then ACK 1 (driver), ACK 2 (gateway) and ACK 3 (verify). An id chosen by the client makes the submission idempotent.

Request body application/jsonrequired

targetrequired

string

Target.

telecommandrequired

string

Telecommand: its name alone when unique in the platform, else component.name.

instance

string

Instance of a multi-instance component, or file id for files.

args

map of InputArg

Arguments: 100 V, enum values, booleans, hexadecimal bytes.

link

string

Link, when not the default one.

environment

string

Environment, which selects the parameters of the link; required when the link overrides them by environment and the target is engaged in several.

id

string

Identifier chosen by the client, to make the submission idempotent.

Responses

202Accepted: follow it on GET /v1/tc/{target}/{id}/events.application/json

idrequired

string

Identifier of the telecommand.

duplicaterequired

boolean

Whether the same identifier was already submitted: nothing new is sent.

400Invalid body or identifier: api::invalid-body, api::invalid-id.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

404Unknown target.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

409The target is held by a run: tc::target-held.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

422The telecommand does not resolve: unknown telecommand or instance, invalid argument, component not carried by the link (tc::link-component), environment required (tc::environment-required)…application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl -X POST "http://localhost:8080/v1/tc" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "string",
  "telecommand": "string",
  "instance": "string",
  "args": {
    "key": true
  },
  "link": "string",
  "environment": "string",
  "id": "string"
}'

import requests

BASE_URL = "http://localhost:8080"

response = requests.post(
    f"{BASE_URL}/v1/tc",
    json={
        "target": "string",
        "telecommand": "string",
        "instance": "string",
        "args": {
            "key": True,
        },
        "link": "string",
        "environment": "string",
        "id": "string",
    },
)
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .post(format!("{base_url}/v1/tc"))
    .json(&serde_json::json!({
      "target": "string",
      "telecommand": "string",
      "instance": "string",
      "args": {
        "key": true
      },
      "link": "string",
      "environment": "string",
      "id": "string"
    }))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "id": "string",
  "duplicate": true
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

POST/v1/encode

Encode telecommand#

Encode a telecommand without sending it

Resolves the telecommand as POST /v1/tc does (catalogue, types, ranges, defaults, environment), then asks the driver bound to its link (or the one named by driver) what it makes of it, in the context of the link: its parameters in the environment, the mode of the target and its parameters. Nothing is sent and no lease is taken; a driver keeping a state (a sequence counter) may still advance it. The frame is the frame of the medium on a link without transport, the unit handed to the transport otherwise.

Request body application/jsonrequired

targetrequired

string

Target.

telecommandrequired

string

Telecommand: its name alone when unique in the platform, else component.name.

instance

string

Instance of a multi-instance component, or file id for files.

args

map of InputArg

Arguments: 100 V, enum values, booleans, hexadecimal bytes.

link

string

Link, when not the default one.

environment

string

Environment, which selects the parameters of the link.

driver

string

Driver instance to ask, when not the one bound to the link: a driver being developed.

Responses

200The frame.application/json

targetrequired

string

Target.

linkrequired

string

Link.

driverrequired

string

Driver instance that encoded it.

environment

string

Environment of the parameters of the link.

telecommandrequired

string

The telecommand, as written: tcu[TCU1].set_mode.

argsrequired

map of any

Its arguments, resolved: numbers in the unit of their argument, defaults applied.

framerequired

string

The frame, in hexadecimal: the frame of the medium on a link without transport, the unit the driver hands to the transport otherwise.

sizerequired

integer

Its size, in bytes.

≥ 0

text

string

The frame as text, when it is printable text (SCPI and other text protocols).

400Invalid body: api::invalid-body.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

404Unknown target.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

409No driver bound to the link and none named: driver::unbound.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

422The telecommand does not resolve (the codes of POST /v1/tc), or the driver fails to encode it: driver::encode-failed.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

501The driver does not answer the verb: driver::no-verb.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

504The driver does not answer: driver::no-answer.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl -X POST "http://localhost:8080/v1/encode" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "string",
  "telecommand": "string",
  "instance": "string",
  "args": {
    "key": true
  },
  "link": "string",
  "environment": "string",
  "driver": "string"
}'

import requests

BASE_URL = "http://localhost:8080"

response = requests.post(
    f"{BASE_URL}/v1/encode",
    json={
        "target": "string",
        "telecommand": "string",
        "instance": "string",
        "args": {
            "key": True,
        },
        "link": "string",
        "environment": "string",
        "driver": "string",
    },
)
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .post(format!("{base_url}/v1/encode"))
    .json(&serde_json::json!({
      "target": "string",
      "telecommand": "string",
      "instance": "string",
      "args": {
        "key": true
      },
      "link": "string",
      "environment": "string",
      "driver": "string"
    }))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "target": "string",
  "link": "string",
  "driver": "string",
  "environment": "string",
  "telecommand": "string",
  "args": {
    "key": null
  },
  "frame": "string",
  "size": 0,
  "text": "string"
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

POST/v1/decode

Decode frame#

Decode a frame without publishing it

Asks the driver bound to a link of the target (or the one named by driver) for the raw samples of a frame, in the context of the link, and calibrates them with the catalogue of the target. Nothing is published: the current values and the archives do not change. On a link with a transport, the frame is the unit the transport hands to the driver.

Request body application/jsonrequired

targetrequired

string

Target.

frame

string

The frame in hexadecimal (56 4f 4c 54, spaces allowed); or text.

text

string

The frame as text, for a text protocol (VOLT 28.0); or frame.

link

string

Link, when not the default one.

environment

string

Environment, which selects the parameters of the link.

driver

string

Driver instance to ask, when not the one bound to the link.

Responses

200The samples of the frame.application/json

targetrequired

string

Target.

linkrequired

string

Link.

driverrequired

string

Driver instance that decoded it.

environment

string

Environment of the parameters of the link.

samplesrequired

array of DecodedSample

Samples, in the order the driver gives them.

DecodedSample · 7 fields

componentrequired

string

Component.

instance

string

Instance of a multi-instance component.

measurerequired

string

Measure.

rawrequired

any

Raw value, as the driver gives it.

value

any

Value in the unit of the measure, through its calibration; None when the catalogue has no such measure or the calibration does not cover the raw value.

unit

string

Unit of the measure.

onboard_time

string

On-board time, when the frame carries it.

400Invalid body or frame: api::invalid-body, api::invalid-frame.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

404Unknown target: api::unknown-target.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

409No driver bound to the link and none named: driver::unbound.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

422Unknown link or environment (api::unknown-link, api::unknown-environment), or the driver fails to decode the frame: driver::decode-failed.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

501The driver does not answer the verb: driver::no-verb.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

504The driver does not answer: driver::no-answer.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl -X POST "http://localhost:8080/v1/decode" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "string",
  "frame": "string",
  "text": "string",
  "link": "string",
  "environment": "string",
  "driver": "string"
}'

import requests

BASE_URL = "http://localhost:8080"

response = requests.post(
    f"{BASE_URL}/v1/decode",
    json={
        "target": "string",
        "frame": "string",
        "text": "string",
        "link": "string",
        "environment": "string",
        "driver": "string",
    },
)
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .post(format!("{base_url}/v1/decode"))
    .json(&serde_json::json!({
      "target": "string",
      "frame": "string",
      "text": "string",
      "link": "string",
      "environment": "string",
      "driver": "string"
    }))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "target": "string",
  "link": "string",
  "driver": "string",
  "environment": "string",
  "samples": [
    {
      "component": "string",
      "instance": "string",
      "measure": "string",
      "raw": null,
      "value": null,
      "unit": "string",
      "onboard_time": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

GET/v1/tc/{target}/{id}/events

Follow telecommand#

Follow a telecommand (WebSocket)

Replays the events of the telecommand, then follows the new ones, and closes on a final state (REJECTED, ENCODE_FAILED, SEND_FAILED, VERIFIED, VERIFY_FAILED, VERIFY_TIMEOUT, COMPLETE). Each message is a TcEvent.

Path parameters

targetrequired

string

Target, as named in the topology (sim-1).

idrequired

string

Telecommand identifier (ULID).

Responses

101WebSocket: one TcEvent per message.application/json

atrequired

string

Time of the transition.

conforming

boolean

For an ECHO event: whether the echo conforms.

detail

string

Explanation: failed precondition, error of the driver or the gateway, echo…

staterequired

TcState

New state.

tcrequired

string

Telecommand.

telecommand

one of TcRef | null

For a PENDING event: the telecommand, for sent_at in derived measures.

404Invalid target or identifier.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/tc/<target>/<id>/events"

import requests

BASE_URL = "http://localhost:8080"
target = "<target>"  # Target, as named in the topology (`sim-1`).
id = "<id>"  # Telecommand identifier (ULID).

response = requests.get(f"{BASE_URL}/v1/tc/{target}/{id}/events")
response.raise_for_status()

let base_url = "http://localhost:8080";
let target = "<target>"; // Target, as named in the topology (`sim-1`).
let id = "<id>"; // Telecommand identifier (ULID).

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/tc/{target}/{id}/events"))
    .send()
    .await?
    .error_for_status()?;

Response

{
  "at": "string",
  "conforming": true,
  "detail": "string",
  "state": "PENDING",
  "tc": "string",
  "telecommand": {
    "component": "string",
    "instance": "string",
    "telecommand": "string"
  }
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

GET/v1/tc/watch

Watch telecommands#

Follow every telecommand (WebSocket)

The events of the telecommands of every target (or of target) from now, in order, each with its target: PENDING names the telecommand, the next ones follow its chain of acknowledgements. Each message is a TcWatched.

Query parameters

target

string

Only the telecommands of this target.

Responses

101WebSocket: one TcWatched per message.application/json

targetrequired

string

Target of the telecommand.

eventrequired

TcEvent

The event.

TcEvent · 6 fields

atrequired

string

Time of the transition.

conforming

boolean

For an ECHO event: whether the echo conforms.

detail

string

Explanation: failed precondition, error of the driver or the gateway, echo…

staterequired

TcState

New state.

tcrequired

string

Telecommand.

telecommand

one of TcRef | null

For a PENDING event: the telecommand, for sent_at in derived measures.

404Invalid target.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/tc/watch"

import requests

BASE_URL = "http://localhost:8080"

response = requests.get(f"{BASE_URL}/v1/tc/watch")
response.raise_for_status()

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/tc/watch"))
    .send()
    .await?
    .error_for_status()?;

Response

{
  "target": "string",
  "event": {
    "at": "string",
    "conforming": true,
    "detail": "string",
    "state": "PENDING",
    "tc": "string",
    "telecommand": {
      "component": "string",
      "instance": "string",
      "telecommand": "string"
    }
  }
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}