Skip to content

Command handling

Command cancellation

A command or mission request is queued in TethysDash as one or more SBD parts (a long request is split into several), which are then sent to the vehicle over cell or via satellite, according to the requested via.

A request can be canceled as long as none of its queued parts has been dispatched, that is, already on its way to the vehicle:

  • Cell: the part has been fetched by the vehicle, and is waiting for the vehicle's acknowledgment. It stays in the queue until then.
  • Satellite: the part's email to Iridium is being sent (normally a brief moment); once sent, the part leaves the queue.

Then:

  • Cancel (dash4: "Yes, discard"): removes all the parts of the request, with a note "Canceled request ...".
  • If any part is dispatched, the cancel is refused, and nothing is removed: "already sent to the vehicle; it can no longer be canceled".
  • Discard anyway (API: force=true): removes all the parts of the request, including dispatched ones, with a note "Discarded request ... (already sent to the vehicle; it may have been delivered)".
    • For a cell part, a late acknowledgment from the vehicle is still recorded (unless TethysDash is restarted in between).
    • An email already sent to Iridium cannot be recalled.
  • Once all the parts have been acknowledged (cell) or emailed (satellite), the request is no longer in the queue, so there is nothing to cancel.

Multipart requests

Only the parts still in the queue are considered, so a multipart request may reach the vehicle only partially:

  • Satellite: each part is sent separately. A cancel between sends removes only the parts still waiting, while the earlier ones have already been sent.
  • Cell: the vehicle fetches one part at a time, and a connection that is spotty may get some parts through promptly and others not. Then:
    • Discard anyway removes the remaining parts, while the earlier ones have already been received by the vehicle.
    • The cell timeout applies to each part not yet fetched. When it expires, a remaining cell-only part is discarded (with a "Timeout while waiting ..." note), even if the earlier parts were received. (A remaining cellsat part is sent via satellite instead.)

The resulting notes list the parts that were removed.

API

  • GET /api/commands/queue: queued parts by vehicle; dispatched is true for a part already on its way to the vehicle (such an entry keeps its via, but is no longer subject to the cell timeout).
  • DELETE /api/commands/queue?vehicle=...&refEventId=...: cancels the request.
    • If refused, the response is (HTTP 200, like other errors of this endpoint): {"error": "Request ... already sent to the vehicle; it can no longer be canceled"}
    • With force=true: discards it anyway.