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.
Command stream
Section titled “Command stream”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_resultwithfilter.scopesession(the default) — the results, and theevent_command_progressupdates, of the commands this connection published.command_resultwithfilter.scopetelescope— every command result on the telescope, whoever published the command. Needs VIEW on the telescope.command— every command issued on the telescope, asevent_commandmessages. 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.
Command catalog
Section titled “Command catalog”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).
Mount commands
Section titled “Mount commands”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.
Filter wheel commands
Section titled “Filter wheel commands”| Command type | Params | What it does |
|---|---|---|
filter_wheel.select |
device_uid, position_uid |
Move the filter wheel to one of its configured positions |
Focuser commands
Section titled “Focuser commands”| 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 |
Rotator commands
Section titled “Rotator commands”| 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 |
Enclosure and OTA commands
Section titled “Enclosure and OTA commands”| 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 |
Radio receiver commands
Section titled “Radio receiver commands”| 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 |
IP camera commands
Section titled “IP camera commands”| 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.
Manual control lease commands
Section titled “Manual control lease 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.
System commands
Section titled “System commands”| 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.
Command results
Section titled “Command results”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.
Canceling
Section titled “Canceling”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).
Permissions and auth
Section titled “Permissions and auth”Publishing a command requires:
- An access token issued without scopes, for a user (not an installation).
UPDATEpermission on the telescope, and its active manual control lease held by you and named inlease_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.
Patterns
Section titled “Patterns”Manual slew-and-expose sequence
Section titled “Manual slew-and-expose sequence”- On
/v1/ws/stream, subscribe tomanual_control_leasefor your telescope. On/v1/ws/commands, subscribe tocommand_resultfor it. - Publish
manual_control_lease.acquire, and read the leaseidfrom the lease event that follows. - Publish
mount.trackwith the target. - Wait for the command’s
event_command_result, or the mount’s device snapshot on/v1/ws/stream, to confirm the mount is tracking. - Publish
imager.expose. - Wait for the corresponding
event_command_result. - Publish
manual_control_lease.release.
Autofocus sweep
Section titled “Autofocus sweep”- Acquire a lease.
- Publish
imager.autofocuswith the imager, step, exposure time and filters. - Watch
event_command_progressand the focuser’s device snapshots for the sweep’s progress. - The command result arrives when the sweep completes.
- Release the lease.
Reference
Section titled “Reference”The command envelope and each command’s parameters are in the API reference schemas (CommandsWSMessage and the per-command parameter models).