Alpaca transport

Alpaca is the cross-platform, HTTP/JSON evolution of ASCOM. Drivers are HTTP services; you talk to them with GET/PUT calls. Works on Windows, Linux, macOS, anywhere — the Alpaca server can even be running on a different machine on your network from the one running Starship.

Enabling Alpaca

Alpaca is off by default. Turn it on in Settings → Connections (the first tab of the Equipment group): tick Alpaca transport enabled, save, and restart Starship. Until you do, the Alpaca slots stay dormant and nothing polls the network. Find devices works either way, so you can see what is on the network before turning the transport on.

Per-role

Same model as ASCOM: each equipment role connects independently. Starship exposes an Alpaca slot for every role:

You can mix transports freely: run the mount over ASCOM and the camera over Alpaca, or any other combination. Each role picks its own transport.

Setup flow

Every role has a Transport selector in its Settings block with three choices: ASCOM (Windows COM), Alpaca (HTTP/JSON), and None. Pick Alpaca, then:

  1. Press Find devices. Starship searches the network for Alpaca servers (it takes about three seconds) and fills the dropdown next to the button with every device of the right kind, shown as device name - server name (address:port) #number.
  2. Choose your device from the dropdown. That fills in Host, Port and Device number below it. You can also type them yourself, for a server the search cannot reach.
  3. Auto-connect on service start — tick this to have Starship connect the device automatically every time it launches.

The three fields:

Save your settings. Connect and Disconnect under the fields try the device straight away, using whatever the fields say, saved or not; the line under them shows whether it is connected and, if not, why. Connect also makes the device the running Starship's current choice, as choosing an ASCOM driver does; Save writes it to config.toml so it survives a restart. If the role is already connected to a different device, Connect asks first, because it disconnects that one (and anything it is doing, such as an exposure). Connecting needs the Alpaca transport turned on. For the whole rig, use Connect all on the console (or rely on auto-connect). Connect all connects every role that has a host set, across both ASCOM and Alpaca, and also brings up guiding. Once connected, each role reports live status and properties just like an ASCOM device.

The follower train's camera, focuser and filter wheel (Settings → Follower train, with piggyback on) have the same Find devices, dropdown and Connect / Disconnect.

Finding devices on the network

Find devices uses the ASCOM Alpaca Discovery protocol, the same search NINA's refresh button runs. Starship sends a small UDP message (alpacadiscovery1) to port 32227 as a broadcast: to 255.255.255.255 and to the broadcast address of each of this PC's networks (Windows sends a 255.255.255.255 broadcast out of one network adapter only). It also asks this PC directly at 127.0.0.1, because a server on the same computer may not answer its own machine's broadcast. Every Alpaca server that hears the message replies with its HTTP port; Starship then asks each server for its name and its devices. The dropdown lists only the devices that fit the role:

If the search finds nothing:

A server that answered the search but could not list its devices is named under the dropdown with the reason, for example a server that wants a password.

Hand-editing the config

You can also set everything directly in config.toml. Turn the transport on with [alpaca] enabled = true, then add a block per role:


[alpaca]
enabled = true
poll_interval_s = 5.0

[alpaca.camera]
host = "192.168.1.50"
port = 11111
device_number = 0
auto_connect = true

poll_interval_s controls how often Starship refreshes each connected device's readings.

How it works

Alpaca is just HTTP. To read the mount's RA: GET http://host:port/api/v1/telescope/0/rightascension. To slew: PUT http://host:port/api/v1/telescope/0/slewtocoordinates with form-encoded RA and Dec. Starship handles all of this for you — the endpoints above are just what's happening under the hood.

Every device is polled on a background thread while connected, so temperature, position, shutter state, filter, switches and the rest stay current in the console and dashboard without you refreshing anything. If a device drops off the network, its slot flips to disconnected and reports the error rather than showing stale numbers.

Starship's Alpaca client is pure-stdlib Python — no requests, no httpx, no alpyca. It uses urllib. That means the Alpaca transport has no external dependencies, which matters for the open-core philosophy. Properties a given device doesn't implement (a filter wheel with no focus offsets, a camera with no cooler) are quietly skipped rather than treated as errors, so a minimal driver still connects cleanly.

When to prefer ASCOM

When the only driver available is COM-based, you don't have a choice — use ASCOM. ZWO ASI cameras work via either, but native ASI SDK access is faster than ASCOM. QHY cameras: direct SDK > Alpaca > ASCOM in performance terms. The right choice depends on the camera. Alpaca's advantage is reach — it's the way to drive gear on another machine, on Linux/macOS, or over the network.

Authentication

Alpaca supports HTTP Basic Auth, and Starship can send credentials to a server that requires them (an ASCOM Remote server with authentication switched on, for example). There is no field for this in Settings; set it in config.toml:

[alpaca] auth_user = "name" auth_password = "password"

The same credentials are sent to every Alpaca device. Blank (the default) sends no Authorization header, which is right for the usual LAN bridge with authentication off. The password is stored in the config file as plain text, is never sent back to the browser, is left out of diagnostics bundles, and is kept when Settings is saved.

Basic Auth over plain HTTP does not protect the password on the wire. For remote Alpaca (driving the observatory from outside the LAN), use a VPN or a reverse proxy with TLS in front.

Astroworx Starship v23.1.2 · this page is the in-app help of that buildDownload · HTTP API