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.
node_type, observatory_id, telescope_id
Section titled “node_type, observatory_id, telescope_id”These three fields decide what the install is bound to.
node_type: "telescope"with anobservatory_idrequirestelescope_id, and the telescope must belong to that observatory.node_type: "observatory"requires onlyobservatory_id.- A
telescope_idalways requires anobservatory_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.
hardware
Section titled “hardware”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.
device_configs
Section titled “device_configs”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.
local_broker (MQTT)
Section titled “local_broker (MQTT)”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
Section titled “automation”{ "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.
controller_lifecycle
Section titled “controller_lifecycle”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, oranfor 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.
Backwards-compatible aliases
Section titled “Backwards-compatible aliases”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.
Where the file lives
Section titled “Where the file lives”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.