Skip to content

SkyNode configuration

SkyNode’s runtime configuration is one file, skynode_config.json, validated as SkyNodeConfig and editable through the local GUI’s Settings pages.

You rarely need to edit the JSON directly — the GUI exposes everything important — but knowing the structure helps when you’re diagnosing a configuration issue, scripting a deployment, or copying a config between hosts.

The top-level shape:

{
"version": 3,
"node": { /* install metadata */ },
"node_type": "telescope" | "observatory",
"observatory_id": "<uuid>",
"telescope_id": "<uuid>", // required when node_type=telescope
"hardware": { /* cached hub records */ },
"device_configs": { /* driver bindings */ },
"last_sync_at": "<iso-datetime>",
"hub": { /* api + auth endpoints */ },
"local_broker": { /* optional MQTT */ },
"ui": { /* control authority */ },
"automation": { /* start/stop automation */ },
"controller_lifecycle": { /* startup/shutdown actions */ },
"plate_solving": { /* local solver settings */ },
"diagnostics": { /* diagnostics store retention */ },
"captures": { /* manual/autofocus frame retention */ },
"media": { /* IP camera publishing tools */ }
}

Static metadata about this install. Populated automatically at first run:

Field Meaning
install_id Stable UUID identifying this SkyNode install locally — used in MQTT topic names. It is not the hub’s installation id, and it survives unbinding and re-pairing
created_at First-run timestamp
updated_at Last config update timestamp

You normally don’t edit this section.


These three fields decide what the install is bound to.

  • node_type: "telescope" with an observatory_id requires telescope_id, and the telescope must belong to that observatory.
  • node_type: "observatory" requires only observatory_id.
  • A telescope_id always requires an observatory_id. An unbound node has neither.

The config has a model-level validator that rejects inconsistent combinations at load time, so if you’ve hand-edited the JSON and the backend won’t start, this is the first place to check.

See SkyNode → Overview for which to choose.


A cached copy of the relevant hub records:

Sub-field What’s in it
observatories The bound observatory and any siblings the install can see
telescopes The bound telescope (and siblings for observatory nodes)
instruments Instruments at the telescope
devices Every device in the install’s scope
sites The site record
filters Filter records (referenced by filter wheels)
filter_wheel_positions Per-filter-wheel slot mappings
operational_constraints The constraint definitions to evaluate
ip_cameras Legacy cache of IP cameras from older builds; IP cameras are now ordinary entries in devices, and a hub refresh empties this

The sync monitor compares this graph with the hub’s every 20 seconds, applies most differences live, and reports the ones that need a restart; the hub indicator in the status bar shows the live sync state. last_sync_at records when the graph was pulled at binding.

You don’t edit hardware directly — it’s a cache. Edit the underlying records in the website’s telescope settings page; SkyNode picks up the changes on the next sync.


This is where each device gets bound to a concrete driver. The shape is a map keyed by device UID:

{
"device_configs": {
"device_configs_by_id": {
"<device-uid>": {
"device_type": "mount" | "camera" | "filter_wheel" | …,
"driver": "mount.ascom" | "camera.maxim" | "mount.simulator" | "gbtwenty-mount" | …,
"managed_by": "this_node" | "another_node" | "no_node",
"auto_connect": false,
"driver_configs": {
"<driver-id>": { /* driver-specific params */ }
},
/* device-type-specific fields */
}
}
}
}

driver is a driver ID (<device type>.<driver>, except gbtwenty-mount and the IP camera drivers amcrest_cgi and onvif), and driver_configs is keyed by the same IDs. Every device config carries:

Field Meaning
managed_by Which node, if any, opens the driver. Default this_node; another_node is only valid for observatory-scoped devices (enclosures, weather sensors, site IP cameras); no_node means nothing drives it and SkyNode skips it
auto_connect Set by SkyNode, not by you: armed by your first successful Connect for the device, cleared when the driver or its options change and on unbind. Only armed devices connect at startup and reconnect on their own

Device-type-specific extras the schema layer adds today:

Device type Extra config
camera temperature_setpoint_tolerance_c (°C, default 0.5) — drives “is the camera at temperature yet” checks
enclosure managed_by (default another_node), allow_control (default false) — distinguishes monitor-only enclosure bindings from actively-controlled ones; also shutter_motion_timeout_sec, slit_alignment_margin_deg, require_rotation_stopped_at_start (default true), rotation_settle_sec
weather_sensor managed_by (default another_node) — same idea as enclosure, for sensor-only bindings
ota cover_motion_timeout_sec — lengthens the driver’s mirror-cover motion budget for slow covers
ip_camera login, publish, policy — the camera’s login (passwords live in the OS keyring, never in the file) and how this node publishes its stream

The list of driver options per device type is in Driver interfaces.


Hub endpoints and OAuth settings. An installed build defaults to the production hub shown here; see installation for the source-run defaults. The GUI does not edit this section.

{
"hub": {
"hub_id": "Skynet Global Telescope Network",
"api_server": "https://api.skynetgo.org/",
"gateway_api_server": "https://node.skynetgo.org/",
"auth": {
"method": "oauth",
"auth_server": "https://auth.skynetgo.org/",
"client_id": "skynode-client",
"redirect_uri": "skynode://auth/callback",
"scopes": []
}
}
}

hub_id is a human-readable label; the hub doesn’t validate it. api_server and gateway_api_server are the two URLs SkyNode talks to (public-api and sky-node-gateway). redirect_uri is not what sign-in uses today: the GUI signs in through a one-shot listener on 127.0.0.1.


Optional. Disabled by default. When enabled, SkyNode also publishes snapshots to a local MQTT broker for on-site subscribers (status displays, monitoring tools), under topics of the form skynode/<install_id>/…. Nodes sharing the broker read each other’s enclosure, weather-sensor and constraint snapshots from it before falling back to the hub. Edit it in Settings → Local Broker.

{
"local_broker": {
"enabled": true,
"host": "127.0.0.1",
"port": 1883,
"transport": "tcp", // or "websocket"
"websocket_path": "/mqtt",
"keepalive_s": 30,
"clean_session": true,
"client_id_prefix": "skynode",
"reconnect": {
"initial_backoff_s": 1,
"max_backoff_s": 30,
"jitter": true
},
"auth": { "username": null, "password": null },
"tls": {
"enabled": false,
"ca_file": null,
"cert_file": null,
"key_file": null,
"insecure_skip_verify": false
},
"publish": {
"device_snapshot": { "qos": 0, "retain": true },
"constraint_snapshot": { "qos": 1, "retain": true },
"operational_snapshot":{ "qos": 1, "retain": true }
},
"lwt": {
"enabled": true,
"topic": "skynode/{installation_uid}/status",
"online_payload": "{\"status\":\"online\"}",
"offline_payload": "{\"status\":\"offline\"}",
"qos": 1,
"retain": true
}
}
}

The Last Will and Testament (lwt) is what lets a subscriber detect that the SkyNode process has died (broker publishes the offline payload on the LWT topic when the keep-alive lapses).


Today this is just:

{ "ui": { "control_authority": "remote" } }

This is the node’s control authority itself (remote or manual), not a copy of a hub value: switching MANUAL/REMOTE in the GUI writes it here, it survives restarts, and SkyNode reports it to the hub in the telescope snapshot.


{ "automation": { "enabled": false } }

Whether the operator has started automation. Start automation in Settings → Startup & Shutdown sets it, Stop automation and unbinding clear it, and a node with it set resumes automation on every boot. A fresh or freshly bound install starts with it off.


Startup and shutdown actions the lifecycle supervisor performs.

{
"controller_lifecycle": {
"startup_actions": {
"unpark_mount": true,
"restore_cameras": false
},
"shutdown_actions": {
"park_mount": true,
"park_enclosure": false,
"enclosure_park_azimuth_deg": null,
"close_enclosure": true,
"close_covers": true,
"stop_fans": true,
"warm_cameras": false
}
}
}
  • Startup actions run when automation comes back after a shutdown interlock clears (unpark the mount, restore cameras to their cooling setpoints).
  • Shutdown actions run when the operator chooses Shut down the observatory, then quit in the quit dialog, in this order: stop tracking (always), park the mount, park the enclosure (rotate a dome to enclosure_park_azimuth_deg — for domes whose shutter needs a contact position; off by default and unavailable without an azimuth), close the enclosure, close the mirror covers, stop the mirror fans, warm the cameras. When a shutdown interlock fires, the lifecycle supervisor applies the same flags except the enclosure park: it requests the enclosure and covers closed and the fans stopped, then stops tracking and parks the mount, then warms the cameras. Each step runs only for a device this SkyNode manages and the driver can do: a status-only roof is never commanded, and a mount that reports it cannot park is reported, not retried.

The defaults are conservative — startup unparks the mount but doesn’t restart camera cooling; shutdown parks, closes the enclosure and covers and stops the fans, but doesn’t park the dome or warm cameras. Override these per site in Settings → Startup & Shutdown, or in the file. A configuration written before a key existed loads unchanged (the new keys take their defaults), and an older build ignores keys it does not know.


plate_solving, diagnostics, captures, media

Section titled “plate_solving, diagnostics, captures, media”
  • plate_solving — node-local solver access: catalog_path (local UCAC5 catalog; null uses the packaged default), solver_backend (atlas, the default, or an for astrometry.net), availability_enabled (node-wide switch, default true). Per-imager solve settings live on the optical imager on the hub, not here. Edit in Settings → Plate Solving.
  • diagnostics — retention of the local diagnostics store: retention_max_age_days (default 180), retention_max_rows (default 500000).
  • captures — retention of manual and autofocus frames, which stay on the node: retention_max_age_days (default 7), retention_max_total_gb (default 20).
  • media — the media tooling the IP camera publishers use.

Every field also accepts its camelCase form (controllerLifecycle, shutdownActions, parkMount, controlAuthority, …), and local_broker additionally accepts the legacy key mqtt. SkyNode writes the snake_case names, which are canonical. Older layouts are migrated on load: an enclosure or weather sensor’s boolean connect_locally becomes managed_by, and a pre-v3 file has auto_connect and automation.enabled seeded so an already-configured node keeps connecting and running after the upgrade.


The default location is %LOCALAPPDATA%\SkyNode\skynode_config.json on Windows (the platform’s user data directory elsewhere; logs sit beside it under logs). You can override it via the SKY_NODE_CONFIG_PATH environment variable — useful for ops that want the config in a specific volume or for running multiple installs on one host.

If an update leaves the file unreadable, SkyNode keeps a copy next to it (skynode_config.json.corrupt-<timestamp>.json) and tries to recover by dropping only the cached hardware graph, which re-syncs from the hub; the binding, device configs and install_id are kept. If that fails, it runs on defaults without overwriting your file and shows a banner until the config loads again.