Repository navigation
A. Plugin Developers Guide
This guide is for developers who want to extend Galileo without modifying core application code: adding a new device backend, a new session block, or a new UI panel.
Status: plugins are ZIP packages (a
plugin.tomlmanifest plus a Python package) installed from Options > Plugins, either from a local file or the Marketplace, and loaded at start-up or, when installed or updated from Options > Plugins, immediately. The first-party plugins live in the Galileo-Plugins repository, whose README covers the manifest, packaging and CI. Bumpversioninplugin.tomlfor a release: the Marketplace tags installed copies with an Update available badge when its version is higher. The "Loading your plugin" notes in §2 describe the in-process loading path used in tests and during development.
Galileo has no separate "plugin API" — a plugin registers against exactly the same port interfaces (galileo.core.devices.DeviceBackend, galileo.session_exec.BlockRegistry) that the built-in INDI/Alpaca adapters and built-in session blocks use. This is a deliberate architectural choice (Software Design Description §2.2, §6.3): if core's own code and a plugin's code go through the same door, that door is forced to stay well-designed, and a disabled plugin leaves nothing special behind.
Write a plugin when you want to:
- Add support for a device category's new hardware (e.g. a software-only Tier 2 safety monitor that classifies cloud cover from an all-sky camera, rather than reading one from a dedicated sensor) — see §3.
- Add a new block type to the Sessions screen's block palette (e.g. a custom pause condition) — see §4.
- Add a whole new top-level or nested screen to the app (VSTarget's "Variable Stars" tab is the reference example) — see §5.
- Call back into a specific core service (submitting a Scheduler job, reading the event bus) without a hard import dependency on that core module — see §6.
Don't write a plugin for a change that belongs in core: a bug fix to an existing adapter, a change to an existing screen's layout, or anything that needs to reach into UI/adapter internals a plugin isn't given access to (see §8).
Every plugin is a Python class subclassing PluginBase (galileo/plugins/__init__.py):
from galileo.plugins import PluginBase, PluginContext
class MyPlugin(PluginBase):
name = "MyPlugin" # unique identifier used by the PluginManager
version = "1.0.0" # your plugin's own version
api_version = "1" # Galileo's plugin API version you were built against
panel_level = "secondary" # "primary" (top-level tab) or "secondary" (nested)
panel_label = "My Plugin" # leave "" to register no UI panel at all
def activate(self, ctx: PluginContext) -> None:
"""Called once when the plugin is loaded and enabled.
Register device backends, instruction types, etc. here.
"""
def deactivate(self) -> None:
"""Called when the plugin is disabled or unloaded. Release any
resources you acquired in activate() — timers, open connections,
subscriptions you made directly (bus subscriptions you made through
a granted service are the service owner's responsibility to clean up).
"""activate/deactivate are the entire lifecycle contract. There is no __init__ argument injection — PluginManager.load() instantiates your class with no constructor arguments, so do any one-time setup in activate, not __init__.
Until PLUG-030's marketplace lands, there are two ways a plugin reaches PluginManager:
-
First-party pre-loaded (how VSTarget ships):
PluginManager.initialize_preloaded()directly imports and callsself.load(YourPluginClass). This is how Galileo bundles a plugin with the application itself — appropriate for plugins the project maintainer ships, not third-party ones. -
Manual registration (today's path for an out-of-tree plugin): import your plugin class and call
plugin_manager.load(MyPlugin)yourself, e.g. from a startup script or a thin loader you maintain.PluginManagermakes no assumption about how your class reached it — only that it subclassesPluginBase.
from galileo.plugins import PluginManager
mgr = PluginManager()
mgr.load(MyPlugin) # instantiates, calls activate(), registers UI panel if any
mgr.is_loaded("MyPlugin") # True
mgr.disable("MyPlugin") # deactivates without unloading — get_ui_panels() now returns []
mgr.enable("MyPlugin")
mgr.unload("MyPlugin") # calls deactivate(), drops the instancePluginManager.load() wraps instantiation and activate() in a try/except. If your plugin raises during activation, the exception is logged, your plugin is marked faulted (mgr.is_faulted("MyPlugin")), and the rest of the application keeps running. A faulted plugin is not retried automatically — fix the bug and reload. Don't rely on this as a substitute for your own error handling inside activate(); it exists so your bug can't take down someone else's session.
Galileo's current plugin API version is _CURRENT_API_VERSION in galileo/plugins/__init__.py (currently "1"). If your plugin's declared api_version doesn't match, load() issues a PluginApiVersionWarning but still loads the plugin — this is a compatibility warning, not a hard gate, since the API has not yet had a breaking revision to actually gate against. Treat a mismatch warning in your own testing as "verify nothing changed under you," not as something to silently ignore.
Subclass galileo.core.devices.DeviceBackend and implement its abstract surface — the same base class galileo.adapters.indi and galileo.adapters.alpaca implement:
from galileo.core.devices import DeviceBackend, DeviceCategory
from galileo.core.capabilities import DeviceCapabilities
class MyCloudSensorBackend(DeviceBackend):
backend = "my_cloud_sensor" # a short identifier for this backend
device_type = DeviceCategory.SAFETY_MONITOR.value
async def connect(self) -> None: ...
async def disconnect(self) -> None: ...
@property
def is_connected(self) -> bool: ...
def get_capabilities(self) -> DeviceCapabilities:
return DeviceCapabilities()
def get_properties(self) -> dict:
return {}Then, in activate(), register it against the category it serves through PluginContext:
def activate(self, ctx: PluginContext) -> None:
ctx.register_device_backend(DeviceCategory.SAFETY_MONITOR, MyCloudSensorBackend)This appends your class to DeviceBackend.registered_backends[DeviceCategory.SAFETY_MONITOR] — the same registry the device-connection UI scans when building its "pick a backend" list for that category. From the safety module's point of view, your backend is indistinguishable from a built-in INDI or Alpaca adapter; this is what the Software Requirements Specification means by ARCH-070 ("the device-abstraction layer shall be the sole integration point plugins use to register new device backends").
The clearest real case for this extension point, per the Software Design Description §4.16/§4.20, is a Tier 2 safety signal — a software/ML-computed safety classification (e.g. all-sky-camera cloud detection) with no single physical sensor behind it, exposed as a standard Safety Monitor device so galileo.safety can't tell it apart from a physical one.
Only implement the four DeviceBackend abstract methods plus whatever category-specific surface your device category's controller actually calls (e.g. a Safety Monitor's is_safe()/equivalent) — see the existing INDI/Alpaca adapter for your category in galileo/adapters/ for the exact surface its *Controller counterpart drives.
A session block is any class with an async execute(context) method. context is the running session's SessionContext (device handles and service factories for the active Pier).
from dataclasses import dataclass
@dataclass
class WaitForCloudClearBlock:
label: str = "Wait for Clear Sky"
timeout_seconds: float = 3600.0
async def execute(self, context) -> None:
...Register it in activate():
def activate(self, ctx: PluginContext) -> None:
ctx.register_instruction_type(WaitForCloudClearBlock)This adds your class to galileo.session_exec.BlockRegistry.instance(). The session executor runs any block it has no built-in handler for through its own execute(context). Two things to know:
-
Name collisions are first-registration-wins.
BlockRegistry.find(name)matches by class name and returns the first registration — a plugin cannot shadow a built-in block by reusing its name. Pick a distinctive class name. - Plugin blocks do not yet appear in the Sessions palette. The palette is a fixed list today, so a registered block can be run but not yet dragged into a session from the UI.
There is no separate condition/trigger base class any more: the old galileo.sequencer package (with BaseInstruction/BaseCondition/BaseTrigger) was retired.
Set panel_label (and optionally panel_level) as class attributes — no separate registration call is needed; PluginManager.load() reads them directly:
class MyPlugin(PluginBase):
name = "MyPlugin"
version = "1.0.0"
api_version = "1"
panel_level = "primary" # top-level tab, peer to Imaging/Focus/Guiding/...
panel_label = "My Plugin" # the tab/section's visible label
def activate(self, ctx: PluginContext) -> None:
pass
def deactivate(self) -> None:
passpanel_level is your plugin's own declaration of where its panel goes:
panel_level |
Where it appears |
|---|---|
"science" |
An item in the Science section's menu ("primary" and "secondary" are older spellings of the same place and still work). VSTarget uses this. |
"equipment:<category>" |
A panel on one Equipment device page, e.g. "equipment:switch" for Equipment > Switches. The Kasa Switch, Generic Relay and SwitchBot plugins use this. |
"top" |
Its own icon in the left sidebar. Override panel_icon_painter() to return a draw(painter, rect) callable that paints the icon with the pen it is given (so it follows the theme), or leave it for the generic plugin icon. AllSkyCam uses this. |
Leave panel_label as the empty string (the PluginBase default) if your plugin registers no UI at all — a device-backend-only or instruction-only plugin, for instance.
Disabling a plugin (mgr.disable("MyPlugin")) must leave it fully inert per PLUG-060: get_ui_panels("MyPlugin") returns [] while disabled, even though the plugin is still loaded. Don't hold a reference to your own panel widget as "still live" after deactivation — the UI shell won't ask for it again until you're re-enabled.
The widget itself comes from your plugin's build_page(), which Galileo calls when it builds the screen; if it raises, Galileo shows a placeholder and logs the error rather than failing to start.
If your device is an INDI power box whose driver does not follow INDI's standard power interface, you don't need your own panel or INDI code: describe how its properties map and Galileo's Switches page does the rest (PLUG-210). Build a SwitchProfile (from galileo.core.switches) and register it from activate:
from galileo.core.switches import ProfileChannel, ProfileSensor, SwitchProfile
PROFILE = SwitchProfile(
name="My Power Box",
device_names=("My Power Box",), # the INDI device name(s) it may report
signature=frozenset({("USB_HUB", "switch"), ("MONITOR", "number")}), # (property, kind) pairs that must all exist
channels=(
ProfileChannel(id="usb", label="USB hub", group="USB", switch=("USB_HUB", "INDI_ENABLED")),
ProfileChannel(id="heater", label="Dew heater", group="Dew heaters", kind="dew",
number=("HEATER_PWM", "DUTY"), native_max=255, on_via_duty=True, optional=True),
ProfileChannel(id="always", label="12 V always on", group="DC", display_only=True, always_on=True),
),
sensors=(ProfileSensor(id="volts", label="Input voltage", unit="V", ref=("MONITOR", "VOLTAGE")),),
)
class MyPlugin(PluginBase):
def activate(self, ctx):
ctx.register_switch_profile(PROFILE) # returns False, and logs why, if the profile is malformedA device is matched to a profile by the properties it offers, not by its name — two drivers can report the same name — so choose a signature from properties the driver always defines once connected, not ones that come and go with a mode. Dew duty is shown as 0–100 % whatever the driver's own scale (native_max). Properties you don't map still appear under Other. A disabled plugin's profiles are not offered. The WandererBox plugin is a complete example, and it has no other code.
Set dock_label and implement build_dock_widget() to offer a pane the user can dock to, or float from, the Galileo window. It starts closed unless dock_initially_visible() returns True. Open or close it from your own code with ctx.set_dock_visible(True/False); Galileo calls on_dock_visibility_changed(visible) when the user opens or closes it (for example with its close button), so you can remember the choice. Closing the whole application is not reported as the user closing your pane.
Set options_label and implement build_options_page() to get your own item after Plugins in the Options menu, the right place for your plugin's settings (PLUG-170). Read and write them with ctx.settings(). If the page fails to build, Galileo shows a placeholder. Its inline help comes from your plugin's plugin.<name>.md help file.
Set dashboard_label and implement build_dashboard_widget() to offer a view for the Dashboard, such as an animation or a live image (PLUG-180). Galileo adds a Publish on Dashboard box under your Options page (your plugin must therefore also offer one) and remembers the choice in your plugin's settings; the view is built once, when the box is ticked and the plugin is enabled, and shown above the Pier timelines in whatever height they leave free. Let the widget scale to fit, and stop any timers while it is hidden. A view that raises while it is built is skipped.
A disabled plugin must be inert (PLUG-060). Implement on_enabled_changed(enabled) to stop and restart timers, threads and network activity when the user toggles the plugin in Options > Plugins.
Galileo has an in-app help system (hover text, F1, the ? button on each screen). To give your panel help, put Markdown files in a help/ folder next to your plugin's entry module (so it ships in your plugin ZIP). Galileo registers that folder when the plugin loads. Name each file for your screen id — a panel in the Science menu is science.<your plugin's name>.md:
# My Plugin
What this screen is for.
## Exposure
The first paragraph is also the hover text for the control labelled "Exposure".Each ## heading documents one control and is matched by the control's visible text: a form-row label, a button's text, a caption beside the field or a table column header. For a control with no usable text (an icon button or a plot), set widget.setProperty("helpKey", "my key") and use that as the heading. Controls shared with Galileo's own screens (Connect, Save, Driver…) fall back to Galileo's shared help automatically.
PluginContext is deliberately narrow (Software Design Description §6.3): it exposes only what you were explicitly granted, not the whole domain core.
def activate(self, ctx: PluginContext) -> None:
scheduler = ctx.get_service("scheduler") # raises ServiceAccessDenied if not granted
scheduler.submit_job(...)get_service(name) raises galileo.plugins.ServiceAccessDenied for anything not in the granted_services dict the context was built with. For first-party pre-loaded plugins, the Software Design Description names a SchedulerJobSubmitter handle as the intended scheduler grant (what VSTarget's planning module uses to submit a target/plan directly to galileo.scheduler's job queue, VST-090) — but note that today's PluginContext.create_context() (what PluginManager.load() actually calls) always passes granted_services=None, so no service is currently granted to any plugin at load time; the grant mechanism itself works (see tests/test_plug.py::test_tc_plug_080_...), but nothing in the current loader wires a real scheduler handle through it yet. If your plugin needs a granted service today, you'll need your own loader that calls PluginManager.create_context(granted_services={...}) directly rather than relying on initialize_preloaded()/default load().
Two things need no grant:
-
ctx.settings()— your plugin's configuration, stored in Galileo's database under the namespaceplugin.<your plugin's name>(get,set,update,all). Use this, notQSettingsor a config file of your own; Galileo keeps all configuration in its database. Reads fall back to your default and writes never raise if the database is unavailable. -
ctx.site_location()— the selected Observatory's location as anObservingLocation(latitude, longitude, elevation, timezone), orNoneif none is selected or it has no coordinates. Handy withgalileo.planning.visibility.sun_altitude_deg.
ctx.register_device_backend(...) and ctx.register_instruction_type(...) (used in §3/§4 above) are also methods on PluginContext — they don't need a grant, since registering against a port interface is the extension-point surface itself, not a core service call.
AllSkyCam is the best example of a self-contained UI plugin: a top-level section with its own icon, a dock pane, database-backed settings, the Observatory location, background network I/O off the UI thread, and its own in-app help. Kasa Switch and Generic Relay show the minimum (one device backend plus an Equipment panel). VSTarget, below, shows the widest surface.
The VSTarget plugin (galileo/plugins/vstarget/) is the concrete, working demonstration of this entire framework — read its code alongside this guide if an example would help:
| What it demonstrates | Where |
|---|---|
Pre-loaded plugin registration, independent enable/disable (PLUG-060) |
galileo.plugins.PluginManager.initialize_preloaded() loads VSTPlugin and VSTAnalysisPlugin as two separate, independently-toggleable plugins |
Primary-level UI panel insertion (PLUG-070) |
VSTPlugin.panel_level = "primary", panel_label = "Variable Stars" — a peer tab to the built-in Sky Atlas/Targets section, not nested under it |
PluginContext service callback (PLUG-080) |
The planning module's AAVSO target/plan submission goes through a granted SchedulerJobSubmitter-style handle rather than importing galileo.scheduler directly |
| A plugin reusing core domain logic without duplicating it | The analysis module calls core's existing galileo.platesolve (not its own bundled ASTAP integration) and reuses galileo.planning.sky_atlas's visibility computation for its observable-only filter |
| A plugin's own dependency choices coexisting with core's |
photutils (aperture photometry) alongside core's SEP-everywhere policy — a deliberate, documented exception, not an inconsistency to "fix" |
VSTarget's own requirements/design/traceability live in their own parallel document chain — docs/plugins/vstarget/ (PSD, SRS, SDD, RTM) — structurally mirroring core's own chain but scoped to the plugin, consuming core requirements (PLUG-* and others) by reference rather than restating them. If you're building a plugin substantial enough to warrant its own requirements doc, that's the pattern to copy.
-
No sandboxing. A plugin runs in-process with full application privileges — this framework provides fault isolation (a crash in
activate()/deactivate()is caught and logged), not memory or security sandboxing. Don't treat "it's a plugin" as a security boundary. -
No import of adapter or UI internals. A plugin may depend only on the device port interfaces (
galileo.core.devices), the session block interface (galileo.session_exec), andPluginContext. Importinggalileo.adapters.indi/galileo.adapters.alpacaor reaching intogalileo.ui.*internals directly defeats the same module-boundary rule core code is held to. -
No event-bus bypass. Cross-module communication goes through
galileo.bus.get_bus()(EventBus.subscribe/publish), the same as core modules — don't call into unrelated domain-core modules directly just because you're a plugin and the usual import-boundary lint rule doesn't apply to you contractually (it isn't enforced against plugin code the way it's enforced against core, but violating it defeats the fault-isolation guarantee the rest of this framework is built around). - Licensing. Galileo is GPL-3.0-or-later. Because plugins load in-process (not out-of-process/sandboxed), a plugin is very likely a "combined work" under GPL-3.0 and needs a GPL-compatible license to be distributed alongside Galileo. This is a documented consequence of the in-process loading design, not a policy that might loosen later without an architecture change.
-
Updates happen in the running app. Installing a newer version unloads the old one first —
deactivate()is called, its modules leavesys.modules— then imports the new one, so don't keep state in module globals that must survive an update, and stop your threads and timers indeactivate(). If the new version fails to load, the old one is restored. Panels placed on an Equipment device page (panel_level = "equipment:<cat>") appear after the next start; everything else (sidebar, Science, Options, dock panes) updates live.
- Subclass
PluginBase; setname,version,api_version. - Implement
activate(ctx)/deactivate(). - In
activate(), register whatever extension points you need:ctx.register_device_backend(...),ctx.register_instruction_type(...), and/or setpanel_level/panel_labelas class attributes. - If you need a granted core service, build your own
PluginContextviaPluginManager.create_context(granted_services={...})rather than relying on the default loader — nothing is granted by default yet. - Test with a real
PluginManager: load, verify registration took effect against the real registry (DeviceBackend.registered_backends,InstructionRegistry.instance(),UiRegistry), disable, verify inertness, unload. - If your plugin is substantial, write its own requirements/design chain mirroring
docs/plugins/vstarget/rather than asking core'sdocs/SRS.md/SDD.mdto describe it.
- Appendix B1. Science — Variable Stars — the user-facing guide to VSTarget, the plugin this guide uses as its reference implementation.
-
Design documents —
docs/SDD.md§4.20 (galileo.plugins) and §6.3 (Plugin API Surface) are the authoritative architecture reference this guide summarizes. - VSTarget plugin documents — the parallel PSD/SRS/SDD/RTM chain for the reference plugin.