Headless background service for the Grovekit IoT stack. Connects to an MQTT broker via the Homie MQTT convention and durably persists all device state changes, property value updates, log messages, and alerts into TimescaleDB.
Part of the
grovekit/grovekitmonorepo. See the root README for setup and deployment instructions.
- Homie auto-discovery — automatically discovers all devices, nodes, and
properties advertising themselves on the
homie/MQTT topic prefix. - Device state tracking — records every device lifecycle state transition
(
init,ready,sleeping,lost,disconnected) to the database. - Device info ingestion — parses and stores the full Homie device
description (nodes, properties, datatypes, units, settable/retained flags)
whenever a device publishes its
$description. - Typed datapoint ingestion — routes each incoming property value and
property target update to the correct typed time-series table
(
float,integer,boolean,string,enum,json) based on the property's declared Homie datatype. - Batch ingestion — datapoints are accumulated in in-memory batches and flushed to the database in bulk, reducing per-message round-trip overhead.
- Device log ingestion — stores log messages published by devices via the
Homie
$logextension. - Alert ingestion — tracks open and closed device alerts published via the
Homie
$alertextension, maintaining per-device open and total alert counts. - LRU caching — frequently-accessed feed and device records are cached in memory (60 s TTL, up to 10 000 entries each) to avoid redundant database lookups on hot MQTT topics.
- Automatic database migration — applies any pending TimescaleDB migrations at startup before subscribing to the broker.
Scribe is configured entirely through environment variables.
| Variable | Default | Description |
|---|---|---|
GK_LOG_LEVEL |
info |
Log verbosity: trace, debug, info, warn, or error |
GK_HOMIE_PREFIX |
homie |
Homie device prefixes for device autodiscovery, separated by commas |
GK_DB_HOSTNAME |
localhost |
TimescaleDB hostname |
GK_DB_PORT |
5432 |
TimescaleDB port |
GK_DB_DATABASE |
grovekit |
Database name |
GK_DB_USERNAME |
(none) | Database username |
GK_DB_PASSWORD |
(none) | Database password |
GK_BROKER_HOSTNAME |
localhost |
MQTT broker hostname |
GK_BROKER_PORT |
1883 |
MQTT broker port |
GK_BROKER_PROTOCOL |
3 |
MQTT protocol version (3 or 5) |
GK_BROKER_CLIENTID |
(none) | MQTT client ID (auto-generated if omitted) |
GK_BROKER_USERNAME |
(none) | MQTT broker username |
GK_BROKER_PASSWORD |
(none) | MQTT broker password |
See the root README for the full Docker Compose deployment. Scribe starts automatically after TimescaleDB is available and Control has completed the database migrations.
| Package | Role |
|---|---|
| @grovekit/homie-client | Homie MQTT client — auto-discovery, device/property event callbacks |
| @grovekit/database | Data-access layer — device upserts, feed lookups, datapoint inserts, alert management |
| @grovekit/utils | Shared utilities — config, logging, BatchWorker |
| @grovekit/homie-core | Homie type definitions and topic utilities |
| lru-cache | In-memory caching of feed and device records |
| debug | Scoped debug logging |