/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Telemetry

Keywords on this page
WordMeaningExample
ReadingOne value from one sensor at one moment24.5 °C in room 2
TickEverything one building reports at one moment40 readings in one batch
MetricA kind of readingtemperature, peopleCount
PluginOne metric’s own rules, in one placeThe temperature plugin
MicrokernelA small core that knows no metric, plus plugins that add themLike a phone and its apps
LimitThe value a metric must stay withinOver 28 °C is a breach
CollectorA small box in the building that reads its Wi-Fi routersOne per site
HMACA signature that proves the sender holds the building’s keySent with every batch

Realises the Telemetry Ingestion domain. Rust, PostgreSQL with TimescaleDB. Code-level page: Telemetry Service.

The door for every sensor reading. It checks, stores and hands on, and tells when a limit is broken.


Who talks to it

flowchart LR
    S["Sensors, collector"] -- "signed batches" --> T["telemetry"]
    C["client"] -- "history, limits" --> T
    T -. "every tick" .-> D["dashboard"]
    T == "breaches" ==> N["notification"]
    T -- "commands" --> Dev["Devices"]

Thin: a request. Thick: Kafka. Dotted: Redis.

With digital-twin it trades in both directions:

DirectionWhatHow
From digital-twinNew building and its roomsKafka
From digital-twinRoom counts from Wi-FiKafka
From digital-twinRoom limits after an editRequest
To digital-twin“Registration done”Kafka
To digital-twinWi-Fi ticksKafka
To digital-twin“Who owns this building?”Request

Two directions of change

Two things change often, and for different reasons. Each has its own pattern.

What changesExamplePattern
Kinds of metricA new CO₂ sensorMicrokernel: one new plugin
Technology around itAnother database or brokerPorts and adapters: one new adapter
flowchart LR
    subgraph In["Driving adapters"]
        H["HTTP"]
        K["Kafka in"]
    end
    subgraph Kernel["Kernel: knows no metric"]
        UC["Use cases"]
        REG["Plugin registry"]
        P["Ports"]
    end
    subgraph Plugins
        T1["temperature"]
        T2["peopleCount"]
        T3["airQuality"]
        T4["deviceCount"]
    end
    subgraph Out["Driven adapters"]
        PG["PostgreSQL"]
        R["Redis"]
        KP["Kafka out"]
        TW["digital-twin lookup"]
        DV["Device commands"]
    end
    H --> UC
    K --> UC
    UC --> REG
    REG --> T1 & T2 & T3 & T4
    UC --> P
    P -.-> PG & R & KP & TW & DV

A batch comes in

sequenceDiagram
    participant S as Sensor gateway
    participant T as telemetry
    participant DB as PostgreSQL
    participant R as Redis
    participant K as Kafka
    S->>T: one batch, signed
    Note over T: signature, then every reading
    T->>DB: store
    T-->>S: 202
    T->>R: the tick, on telemetry:raw
    Note over T: any value over its limit?
    T->>K: one message per breach
RuleWhy
One bad reading refuses the whole batchThe sender knows exactly what was kept: all or nothing
At most 500 readingsOne batch cannot hold the service up
Store before publishingNobody sees a reading that cannot be queried yet
Publishing never fails the batchThe reading is already safe; a broker hiccup is only logged
Breaches are queued, not awaitedA Kafka outage cannot slow down sensors

Example. A batch holds 40 readings. Reading 17 has no room. The batch is refused, and none of the 40 is stored.


Limits

Example. The building limit for temperature is 28 °C. Room 2, a server room, has its own: 24 °C. A reading of 25 °C breaches in room 2 only.


Wi-Fi ticks

  1. The collector sends a signed tick: which router hears which phone.
  2. telemetry refuses unknown fields, so a raw phone address cannot get in.
  3. It counts phones per router room, each phone once, at its loudest router.
  4. It hands the tick on to digital-twin, which estimates positions.
  5. digital-twin sends room counts back, stored as readings like any other.

Choices

ChoiceWhy
One plugin per metricA new sensor kind touches one place
A port for every technologyThe kernel is tested with fakes, no database
Ask digital-twin who owns a buildingNo copy of someone else’s data to keep in step; a failed lookup denies
Device commands in its own wordsDevice URLs and fields live in one adapter only. See Sensor Actions

Storage and retention: Telemetry Storage.


Gaps