Skip to content

Commands

Commands are what you send when you want a telescope to do something — slew the mount, take an exposure, move a focuser, acquire a manual control lease. They’re published over the /v1/ws/commands WebSocket as publish_command messages, and results flow back as event_command_result.

Only a user can publish, and only against a telescope whose manual control lease that user holds (the lease commands themselves excepted). SkyNode installations receive commands and publish their results over the SkyNode gateway; an installation cannot publish a command. A token issued with scopes cannot open this endpoint.

To receive the results of the commands you publish, subscribe to the command results on the same connection you publish on (CommandStreamName values: command, command_result):

{
"kind": "subscribe_commands",
"schema_version": 1,
"id": "<client-chosen request id>",
"stream": "command_result",
"filter": {
"telescope_uid": "<telescope uid>"
}
}

The server answers with an ack carrying the server-assigned subscription_id. What a subscription reads:

  • command_result with filter.scope session (the default) — the results, and the event_command_progress updates, of the commands this connection published.
  • command_result with filter.scope telescope — every command result on the telescope, whoever published the command. Needs VIEW on the telescope.
  • command — every command issued on the telescope, as event_command messages. Needs VIEW on the telescope.

To publish a command:

{
"kind": "publish_command",
"schema_version": 1,
"id": "<client-chosen request id>",
"telescope_uid": "<telescope uid>",
"lease_id": <the id of your active lease>,
"client_request_id": "<client-chosen uuid>",
"timeout_ms": 330000,
"command": {
"command_type": "mount.track",
"params": { "ra_deg": 83.822, "dec_deg": -5.391 }
}
}

The server answers with an ack that echoes your id and carries the server-assigned command_id — your correlation key to match against event_command_result. The client_request_id deduplicates retries: a second publish with the same one within 30 seconds is refused with conflict (details.error_code: duplicate_command). timeout_ms is how long the command may run before it expires; it defaults to 60 seconds.

The command_type field discriminates among the commands; params carries that command’s parameters. Parameter names are accepted in snake_case or camelCase, and an unknown parameter is rejected. Which of these a telescope can run right now depends on its hardware and its SkyNode build: GET /v1/telescopes/{uid}/manual-command-catalog returns the catalog the telescope’s node last published (404 when no node has published one).

Every mount command takes an optional device_uid; it defaults to the telescope’s mount.

Command type Params What it does
mount.slew frame (icrs or altaz), ra_deg + dec_deg or az_deg + alt_deg Slew to a fixed position and stop there, without tracking
mount.point exactly one of: ra_deg + dec_deg, target_position, body Slew to where the target is now and stop there, without tracking
mount.track exactly one of: ra_deg + dec_deg, target_position, body Slew to the target and track it; body names a major solar-system body
mount.jog east_arcsec, north_arcsec Nudge the tracked position by a small on-sky offset (at most 1800 arcsec per axis)
mount.stop none Stop all mount motion
mount.stop_tracking none Stop tracking
mount.park / mount.unpark none Park or unpark the mount
mount.find_home none Find the mount’s home position
mount.push_site none Write the site’s location into the mount driver
mount.map.start center, pattern Start a radio map (raster or daisy) around a center
mount.map.pause / mount.map.resume / mount.map.stop none Pause, resume or stop the running map

Imager (optical-imaging instrument) commands

Section titled “Imager (optical-imaging instrument) commands”
Command type Params What it does
imager.expose imager_uid, exposure_time_sec, optional exposure_type, count (0 loops until canceled), binning, subframe, filter_position_uid Take one or more exposures
imager.autofocus imager_uid, step, exposure_time_sec, optional filters (current, all or selected), filter_position_uids, points, apply (none, move or save), binning, max_change Run an autofocus sweep

The website does not offer these two yet; the wire carries them.

Command type Params What it does
filter_wheel.select device_uid, position_uid Move the filter wheel to one of its configured positions
Command type Params What it does
focuser.move_absolute device_uid, position Move the focuser to an absolute position, in the focuser’s own units
focuser.move_relative device_uid, delta Move the focuser by a relative offset, in the focuser’s own units
focuser.stop device_uid Stop the focuser
Command type Params What it does
rotator.move_absolute device_uid, angle_deg Move the instrument rotator to an absolute angle
rotator.move_relative device_uid, delta_deg Move by a relative offset
rotator.stop device_uid Stop the rotator
Command type Params What it does
enclosure.request_open / enclosure.request_close none Ask the enclosure controller to open or close
enclosure.set_follow enabled, optional imager_uid Make the slit follow the telescope, or stop following
ota.open_cover / ota.close_cover device_uid Open or close the mirror cover
ota.fans_on / ota.fans_off device_uid Turn the OTA fans on or off
Command type Params What it does
receiver.set_noise_diode device_uid, level Set the noise diode level
receiver.set_polarization device_uid, polarization Select the polarization
receiver.set_attenuation device_uid, value_db Set the attenuation
receiver.select_radio_filter device_uid, radio_filter_id Select a radio filter
receiver.set_lo_frequency device_uid, frequency_mhz Set the local oscillator frequency
Command type Params What it does
ip_camera.ptz_move camera_uid, pan, tilt, zoom (each -1 to 1), duration_s (at most 5) Pan, tilt or zoom for a bounded time
ip_camera.ptz_stop camera_uid Stop the camera
ip_camera.ptz_goto_preset camera_uid, preset Move the camera to a named preset
ip_camera.ptz_frame camera_uid, x0, y0, x1, y1 (fractions of the video frame) Center and zoom on a box drawn on the video
ip_camera.ir_set camera_uid, mode Set the IR light mode

A telescope lease covers its own telescope’s cameras. A camera can also be leased on its own (a device lease, below), which then covers only that camera’s commands.

The lease commands take their fields directly on command, not under params. They act on the envelope’s telescope, or, when device_uid is set, on that one device (an IP camera), and then the envelope names no telescope_uid.

Command type Fields What it does
manual_control_lease.acquire optional duration_s (30 s to 24 h), reason, device_uid Take the manual control lease — pauses automated task execution and gives the caller manual command rights. Without duration_s the lease does not expire on its own
manual_control_lease.renew optional duration_s, is_renewable, device_uid Extend your lease to duration_s from now
manual_control_lease.release optional device_uid Release the lease, returning the telescope to automated operation

A lease command is answered with an ack and no command result; the lease’s new state arrives on the manual_control_lease stream on /v1/ws/stream (see Streams), whose payload carries the lease id you put in lease_id. Acquiring is refused while another user holds the lease.

Command type Params What it does
system.abort_manual_control none Cancel every hub command running on the telescope, then stop the mount

The telescope’s operator can revoke anyone’s lease from SkyNode (DELETE /v1/telescopes/{uid}/current-control-lease as the installation); there is no owner-side force-revoke over the WebSocket.

When SkyNode finishes a command, its result arrives as an event_command_result with the same command_id:

{
"kind": "event_command_result",
"schema_version": 1,
"telescope_uid": "<telescope uid>",
"command_id": "<the command_id from the ack>",
"lease_id": <lease id>,
"result": {
"status": "completed | failed | cancelled | rejected | expired",
"completed_at": "<timestamp>",
"message": "<optional human-readable message>",
"error_code": "<optional stable code>",
"retryable": false,
"data": { /* per-command-type result data */ }
}
}

While a command runs, a session subscriber may also receive event_command_progress messages (at most two a second per command) with a progress object carrying an optional fraction (0 to 1), message and data. Progress is lossy by design; the result is what counts.

Publish a cancel_command referencing the command_id you want canceled:

{
"kind": "cancel_command",
"schema_version": 1,
"id": "<client-chosen request id>",
"telescope_uid": "<telescope uid>",
"lease_id": <lease id>,
"command_id": "<the command_id from the ack>"
}

A cancel needs a lease that would authorize the command it cancels, whoever issued it, and works with the server switch off. Cancellation is a request; SkyNode stops the command and reports back through event_command_result with status: cancelled. A command that already finished is refused with conflict (command_finalized); an unknown one with not_found (unknown_command).

Publishing a command requires:

  1. An access token issued without scopes, for a user (not an installation).
  2. UPDATE permission on the telescope, and its active manual control lease held by you and named in lease_id.

Refusals arrive as an error message whose id echoes your request. forbidden covers a missing or mismatched lease and the permission checks; its details.error_code, when present, is one of manual_control_disabled, ip_camera_out_of_lease_scope, lease_not_authorized, device_leased, device_route_mismatch or policy_forbids. conflict covers duplicate_command, and telescope_busy / camera_busy when another command is still running: one command runs on a telescope at a time (one per camera for the camera commands), and the stop commands (mount.stop, mount.stop_tracking, mount.map.stop, focuser.stop, rotator.stop, ip_camera.ptz_stop, system.abort_manual_control) are never refused as busy.

  1. On /v1/ws/stream, subscribe to manual_control_lease for your telescope. On /v1/ws/commands, subscribe to command_result for it.
  2. Publish manual_control_lease.acquire, and read the lease id from the lease event that follows.
  3. Publish mount.track with the target.
  4. Wait for the command’s event_command_result, or the mount’s device snapshot on /v1/ws/stream, to confirm the mount is tracking.
  5. Publish imager.expose.
  6. Wait for the corresponding event_command_result.
  7. Publish manual_control_lease.release.
  1. Acquire a lease.
  2. Publish imager.autofocus with the imager, step, exposure time and filters.
  3. Watch event_command_progress and the focuser’s device snapshots for the sweep’s progress.
  4. The command result arrives when the sweep completes.
  5. Release the lease.

The command envelope and each command’s parameters are in the API reference schemas (CommandsWSMessage and the per-command parameter models).