Developer guide

Write a Speculum plugin in one thin JAR

A standalone, independently buildable reference module for the Speculum smart-mirror dashboard. No app rebuild, no source checkout of the mirror — drop a JAR in plugins/ and it appears on screen.

Start here Download the JAR Source on GitHub

What this is

Speculum loads external modules from JARs at runtime. This repository is the smallest complete example of one: a Gradle project with a single module that renders a greeting, a refresh counter and the last notification it received, placed at top_center.

It exercises the whole plugin surface, so you can copy it and delete what you do not need:

Runtime discovery

A ModuleFactory declared in META-INF/services, found by the JDK ServiceLoader — no registration in the host app.

Lifecycle

start(), a periodic refresh(), stop(), plus the notification bus and a Compose Content().

Typed settings

settingsSchema() tells the admin console what options exist, so they render as real controls instead of raw text rows.

Thin JAR

compileOnly against mirror-api and Compose: the built JAR holds only your classes, around 11 KB.

How the host finds it

You build a JAR and put it in the Speculum install's plugins/ folder.
On startup the app scans plugins/*.jar and loads each one in a URLClassLoader whose parent is the app, so Compose and mirror-api come from the host.
It asks the JDK ServiceLoader for every org.speculum.core.ModuleFactory on that classloader.
Each factory contributes defaultConfig(), so the module is placed and configured without anyone editing config.json.

Why compileOnly: the API and Compose are provided by the host at runtime through the parent classloader. Bundling them would bloat the JAR and risk loading two copies of the same classes.

Where to go next

Page	What it covers
Quickstart	Run the prebuilt JAR, or build from source and deploy it into a mirror.
Module Anatomy	Every file in the project and what the host does with it.
Settings Schema	Declaring options so the admin console renders typed controls.
mirror-api Reference	The full published API: `MirrorModule`, `ModuleConfig`, `Region`, `SettingSpec`.