Repository navigation
API
Home · Flow actions · Widgets
Chronograph exposes an app API to list, start, inspect, pause, resume and stop stopwatches, timers and transitions. Calls address a chronograph by its type and name. A timer and stopwatch can have the same name without being the same chronograph.
- Calling from HomeyScript
- Calling from another Homey app
- App API reference
- Start request
- Pause, resume and stop
- Response fields
- Realtime events
Breaking change: individual app API endpoints now use names instead of IDs. Generic individual endpoints also require a type. Update existing HomeyScript and other integrations; the old ID-based paths no longer work.
The app ID is nl.fellownet.chronograph. The app API is not public:
callers must use Homey's authorized API mechanisms. Keep credentials and
tokens private. Homey Cloud does not support apps exposing a Web API; see
Homey's Web API documentation.
Install HomeyScript and use its HomeyAPI app object. Methods take an options object and return promises. The response is already parsed:
const app = await Homey.apps.getApp({ id: 'nl.fellownet.chronograph' });
const timers = await app.get({ path: '/timers/' });
console.log(timers);Start a previously configured timer and then pause it:
const app = await Homey.apps.getApp({ id: 'nl.fellownet.chronograph' });
const name = 'Kitchen fan';
await app.post({
path: '/timers/',
body: { name, time: 10, unit: 'minutes' }
});
await app.put({
path: '/timers/' + encodeURIComponent(name),
body: { running: false }
});This fails if the timer is already active. Add replace: true to the start
body only when you intend to reset it. Resume with { running: true }, or
stop it with:
const app = await Homey.apps.getApp({ id: 'nl.fellownet.chronograph' });
await app.delete({ path: '/timers/' + encodeURIComponent('Kitchen fan') });The HomeyAPI app object supports get({ path }), put({ path, body }),
post({ path, body }), delete({ path }), and
call({ method, path, body }). See the
HomeyAPI app reference.
Old apiGet and apiDelete examples are obsolete.
Declare homey:app:nl.fellownet.chronograph in the calling app's manifest.
The Homey Apps SDK client uses a path string, unlike HomeyScript's HomeyAPI
options object:
const api = this.homey.api.getApiApp('nl.fellownet.chronograph');
if (!await api.getInstalled()) throw new Error('Chronograph is not installed');
const timers = await api.get('/timers/');
this.log(timers);The SDK client also provides post(path, body), put(path, body), and
delete(path). See Homey's Web API guide
for permissions and client details.
Use the exact configured name, including case, and URL-encode it when it
appears in a path: encodeURIComponent(name). Wildcards are not supported by
these endpoints. Collections contain active instances, including paused ones;
finished and stopped instances are removed.
| Method | Path | Operation |
|---|---|---|
GET |
/stopwatches/ |
List active stopwatches. |
POST |
/stopwatches/ |
Start a configured stopwatch. |
GET |
/stopwatches/:name |
Get an active stopwatch. |
PUT |
/stopwatches/:name |
Pause or resume an active stopwatch. |
DELETE |
/stopwatches/:name |
Stop an active stopwatch. |
GET |
/timers/ |
List active timers. |
POST |
/timers/ |
Start a configured timer. |
GET |
/timers/:name |
Get an active timer. |
PUT |
/timers/:name |
Pause or resume an active timer. |
DELETE |
/timers/:name |
Stop an active timer. |
GET |
/transitions/ |
List active transitions. |
POST |
/transitions/ |
Start a configured transition. |
GET |
/transitions/:name |
Get an active transition. |
PUT |
/transitions/:name |
Pause or resume an active transition. |
DELETE |
/transitions/:name |
Stop an active transition. |
GET |
/chronographs/ |
List all active instances. |
GET |
/chronographs/:type/:name |
Get an active instance. |
PUT |
/chronographs/:type/:name |
Pause or resume an active instance. |
DELETE |
/chronographs/:type/:name |
Stop an active instance. |
GET |
/allchronographs/ |
List configured names grouped by type. |
For generic paths :type is stopwatch, timer, or transition (singular,
lowercase). GET /allchronographs/ returns an object of name arrays, not
active states; keys reflect the app's configuration. Names can come from saved
Flow cards or saved start values. Configure a name in an enabled, saved Flow
before starting it through the API. A configured name is not necessarily active.
POST returns the started chronograph object. A start uses the same lifecycle
and Flow triggers as a Flow start and saves the values used by widget defaults.
| Field | Applies to | Meaning |
|---|---|---|
name |
All | Required, exact configured name; it must not be blank or contain *. |
replace |
All | Optional boolean; defaults to false. Set true to replace an active or paused instance. |
time |
Timer, transition | Required number or supported Math expression. Timer duration must be positive; transition duration must be non-negative. |
unit |
Timer, transition | Required: milliseconds, seconds, minutes, hours, or days. |
from, to
|
Transition | Required numeric start and end values. |
steps |
Transition | Required integer of at least 2. Short transitions may use fewer effective steps. |
Example stopwatch request: { "name": "Workout" }.
Example transition request:
{ "name": "Living room dim", "time": 5, "unit": "minutes", "from": 0, "to": 1, "steps": 10, "replace": false }Start rejects unknown names, invalid parameters and existing instances unless
replace is true. A failed validation does not replace the active instance.
A transition produces values; use a step-trigger Flow
to apply them to a device.
Send { "running": false } to pause or { "running": true } to resume.
running must be a boolean. The response is the updated chronograph object.
DELETE stops the instance and returns true. An operation on a missing or
finished instance fails; a timer can finish between a list and a later call,
so handle errors.
An active or newly started object contains name, data, duration,
targetDuration, and running. data.type identifies the type. Transition
data includes from, to, and effective steps; saved flowValues may be
present. Durations are in milliseconds: duration is elapsed time, and
timer/transition remaining time is targetDuration - duration. Stopwatches
have no target; a non-finite target may be represented as null in JSON.
Running values are snapshots and continue to change after the response.
The chronograph_event lifecycle event and periodic chronograph_event_multi
updates omit data.flowValues. When saved Flow/API start values actually
change, chronograph_flow_values_changed sends type, name, and
flowValues. Widget starts do not change these saved values.
In a lifecycle event, removed means the active instance has ended. It can
mean it was stopped explicitly, or that a timer or transition finished
naturally; it does not mean the configured chronograph was deleted.
Support development - If Chronograph is useful to you, you can support its
continued development through GitHub Sponsors,
Patreon,
PayPal, or
bunq.
Thank you!