Authoring 1: Scaffold & register

What you'll build: example.counter — a widget that counts the days since a date, here DAY 2346 in icy cyan.

A plugin is a small Python package that adds widgets (and more) to led-ticker without changing core. Over these four pages you’ll build one — example.counter, a deliberately tiny widget that shows the number of days since a date (no data, no async; real plugins like the pool widget fetch live data and render richer screens) — then survey everything else you can contribute.

A plugin is just a module that exposes a register(api) function. led-ticker calls it once at startup and hands you an api object; you call methods on it to register your contributions.

Prerequisites

You’ll work inside a led-ticker checkout:

Clone it and run make dev — this creates a local .venv/ (nothing installed globally) and puts the led-ticker command on its PATH.
Your plugins live in config/plugins/, next to config/config.toml.
To run led-ticker plugins (below): with that venv active, run led-ticker plugins directly; under Docker, run docker compose exec led-ticker led-ticker plugins.

The smallest plugin that loads

Create a file for your plugin. A plugin can be a single .py file or a package directory:
```
example/
  __init__.py
```
Add a register(api) that does nothing yet:
example/__init__.py
```
def register(api):
    pass
```

Put the file under your config’s plugins directory (default config/plugins/):

config/plugins/example/__init__.py

The plugin’s namespace is its file/dir name — here, example.

Ship it as an installable package declaring a led_ticker.plugins entry point (covered in Package & install):

[project.entry-points."led_ticker.plugins"]
example = "example:register"

The entry-point name (example) is the namespace.

Verify it loads

Run:

led-ticker plugins

Your example namespace should appear in the list (with no contributions yet).

Namespaces

Everything a plugin registers is namespaced by <plugin>.<name>, so plugins never collide with core or each other. The widget you build next, registered as counter, becomes example.counter in config — type = "example.counter".