goalpaca-devices

ASCOM Alpaca drivers for astronomy hardware, built on goalpaca. Run a driver on the computer connected to the device, then connect an Alpaca client over the network. Use alpacahurd to manage several drivers.

Drivers

Type	Driver	Hardware
Telescope	tenmicron	10Micron GM-series, TCP
Telescope	asiam5	ZWO AM-series, serial or TCP
Telescope	rst	Rainbow Astro RST, USB-serial
Telescope	onstep	OnStep / OnStepX, serial or TCP
Camera	astrocam	USB astronomy cameras like the ASI6200
Camera	ptpcam	Fujifilm and Sony USB PTP cameras
Camera	polemaster	QHY PoleMaster
Focuser	asieaf	ZWO EAF
Focuser	focuscube	Pegasus FocusCube / DMFC
Focuser	focuslynx	Optec FocusLynx / ThirdLynx
Focuser	oasisfoc	Astroasis Oasis
Filter wheel	asiefw	ZWO EFW
Filter wheel	oasisfw	Astroasis Oasis
Observing conditions	mgpbox	Astromi.ch MGPBox weather and GPS
Observing conditions	unihedron	Unihedron SQM
Switch	asiair	ZWO ASIAIR power board; runs on its Pi
Switch / Focuser	smpro	StellarMate SM Pro; runs on its Pi
Simulator	sim	Coupled telescope and guide camera

Install and build

Release packages target Debian Trixie only, on amd64 and arm64. PoleMaster is included on both architectures. ASIAIR and SM Pro packages are arm64 only because they access Pi hardware. The default build produces 33 packages; the optional ZWO SDK drivers and standalone simulator are excluded. CI builds in Trixie and checks installation on both native architectures.

Debian packages and installation instructions are in the APT archive. See releases for release assets.

For a source build, install Go 1.25 or later. All drivers are packages in one Go module, github.com/mikefsq/goalpaca-devices. The root go.mod records shared, released library dependencies; one root tag versions every driver. Individual executables and Debian packages remain separate.

Third-party code can import a single package, such as github.com/mikefsq/goalpaca-devices/asiam5; only that package and its dependencies are compiled into the application. When migrating from older releases, remove the individual goalpaca-devices/<driver> module requirements and require the new root module release instead.

Run make deps to download the recorded versions, make test vet to check the SDK-free drivers (make test-sdk checks the optional ZWO SDK drivers), and make tidy after deliberate dependency changes. From this directory:

make tenmicron      # build bin/tenmicron
make                # build drivers that do not need a vendor SDK
make pi             # build Raspberry Pi drivers for Linux arm64
make help

The SDK drivers require cgo and their ZWO libraries; see their READMEs. Some macOS USB transports also require cgo and Apple's command-line tools.

make install (or make install in a driver directory) records each binary in /etc/alpacahurd/drivers.conf, alongside the existing disabled seed in devices.d/. The registry contains one absolute executable path per line. Updating the registry does not execute the driver or create runtime state. Upgrades preserve existing device configurations. Uninstall removes the binary's registry entry and keeps device configurations. Debian packages maintain the same registry, using their /usr/bin paths.

For a binary installed before this registry was introduced, register it without rebuilding or starting it:

sudo sh build/register-driver /usr/local/bin/asiam5 /etc/alpacahurd/drivers.conf

The Add device page in alpacahurd reads this catalogue on each visit and can create additional disabled instances from a binary's -schema commented output. Legacy launchers without schema support can be recorded, but cannot generate configuration through that page. On macOS, per-driver installs place the registry beside the configured devices.d directory; REGISTRYFILE overrides that location.

Discover hardware

Run <driver> -discover to list detected hardware as JSON and exit without loading configuration, constructing a device, starting an Alpaca server, or writing state. This is distinct from -discovery, which controls Alpaca network advertising. Explicit -discover scans regardless of any supplied config pin.

The output includes driver, supported, ordered identity configuration keys, and devices, each with a label and values containing usable configuration selectors. Unknown selectors are omitted. A busy device may be listed without a serial; discovery must not interrupt the process using it.

No devices found returns an empty devices array. Drivers without a scanner return supported: false and an empty array. Scan failures include error in the JSON and exit nonzero; diagnostics go to stderr. Scans receive a ten-second context deadline, which each scanner must honor.

All launchers using goalpaca/devicemain inherit this flag. The custom Astrocam and simulator launchers also support it (the simulator has no hardware to scan). Rebuild installed binaries to obtain the new flag.

Run

./bin/tenmicron -addr 192.168.1.50:3492 -port 11200

Most drivers default to HTTP port 11111; choose a different -port for each server on the same machine. The guide simulator defaults to 11110. Open http://localhost:11200/setup for the example above.

Drivers answer Alpaca discovery on UDP port 32227. When using a discovery proxy, select -discovery register -discovery-server host:32227. Use -discovery off to connect by address only.

Configuration

Most drivers accept a JSONC device file, with // comments:

./bin/tenmicron -schema commented > mount.json
./bin/tenmicron -config mount.json -check
./bin/tenmicron -config mount.json

Edit the generated file before checking it. -check validates configuration without opening hardware. Flags override file values; -help lists the available flags. The simulator uses command-line flags only.

The setup page allows changes to live settings that are not fixed by the file or flags. Change hardware selectors in the file and reload or restart the driver. Use stable serial identifiers where supported; the EAF currently selects by enumeration index only.

Writing a driver

See DRIVERS.md for registration, hardware lifecycle, and testing, and SETUP_FORMS.md for browser settings.

License

MIT.

Driver command contract

Every packaged driver exposes the same management commands:

• -schema json: machine-readable configuration fields.
• -schema commented: a flat, disabled prototype with optional fields commented out.
• -discover: structured device identities, or supported: false when the driver cannot scan.
• -config FILE -check: validate configuration without connecting hardware.

Astrocam uses the shared schema implementation while retaining support for existing multi-camera configuration arrays. New prototypes configure one camera, like the other standalone drivers. The sim development server and roiprobe diagnostic utility are not packaged device drivers.

make test builds each SDK-free driver executable and checks its actual schema commands and management flags. Set ALPACA_TEST_SDK=1 to include the SDK drivers when their vendor libraries are installed.