/

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

Twin Schema

Keywords on this page
WordMeaningExample
CrateA Rust library other Rust code builds againsttwin-schema
Registrationdigital-twin telling telemetry that a building exists, and telemetry answering“b1 is ready”
UploadOne request to register a building, tracked until ready or failedhandle b1
Wi-Fi tickWhat one building’s routers saw at one moment3 routers, 2 phones
Token16 hex characters that stand for one phone in one tick, made at random on site7f3c9a01b2d4e6f8
BurstA phone’s scan for networks, heard by one or more routersheard at −58 and −71 dBm
dBmSignal strength. Closer to 0 is louder−40 loud, −90 faint
DotOne estimated person, drawn on the 3D modelLobby, floor 0
TopicA Kafka name that messages are stored onwifi-observations
ChannelA Redis name that messages are published ontwin:devices:b1
FixtureA JSON file of example messages every language must agree onschemas/fixtures/devices.json

Rust crate at schemas/twin-schema. It holds every shape digital-twin exchanges with another service, and the topic and channel names they travel on.

Depends only on serde and serde_json. Tests also use jsonschema.


What is inside

ShapeTravels onWritten byRead by
RegistrationRequestKafka building-registration-requesteddigital-twintelemetry
RegistrationCompletedKafka building-registration-completedtelemetrydigital-twin
WifiObservationsHTTP POST /telemetry/observations, then Kafka wifi-observationsap-collector (Python)telemetry, digital-twin
Devices, DeviceRedis twin:devices:{buildingId}digital-twinsocket, browser
EstimatedOccupancyKafka estimated-occupancydigital-twintelemetry
NameValue
BUILDING_REGISTRATION_REQUESTED_TOPICbuilding-registration-requested
BUILDING_REGISTRATION_COMPLETED_TOPICbuilding-registration-completed
STATUS_READY, STATUS_FAILEDready, failed
WIFI_OBSERVATIONS_TOPICwifi-observations
ESTIMATED_OCCUPANCY_TOPICestimated-occupancy
DEVICES_CHANNEL_PREFIXtwin:devices:
DEVICES_CHANNEL_PATTERNtwin:devices:*

Each service re-exports the topic names from its own adapters/topics.rs. The text of a topic name is written once, here.

flowchart LR
    Tw["digital-twin"] == "RegistrationRequest" ==> T["telemetry"]
    T == "RegistrationCompleted" ==> Tw
    C["ap-collector"] -- "WifiObservations, signed" --> T
    T == "WifiObservations, same bytes" ==> Tw
    Tw == "EstimatedOccupancy" ==> T
    Tw -- "Devices" --> S["socket"]
    S -- "event devices" --> B["browser"]

Thin: HTTP or Redis. Thick: Kafka.


1. Registration

Shapes

{"buildingId":"b1","name":"HQ","rooms":[{"id":"r1","name":"Lobby"},{"id":"r2","name":"Lab"}]}
{"buildingId":"b1","status":"failed","error":"name: must be a non-empty string."}
RegistrationRequest fieldRule
buildingIdOptional in the type, left out when empty. digital-twin always sends it; telemetry drops a message without it
nameEmpty when missing, so telemetry’s own check gives the error text, not serde
maxTemperatureOptional. digital-twin never sends it. telemetry still reads it and, when present, stores a building temperature limit
roomsRead by usable_rooms, below
RegistrationCompleted fieldRule
buildingIdRequired
statusPlain text, not a closed list
errorLeft out when empty

The handshake, call by call

sequenceDiagram
    autonumber
    participant W as digital-twin<br/>Provisioning::provision
    participant P as digital-twin<br/>KafkaEventProducer
    participant K as Kafka
    participant TC as telemetry<br/>kafka_consumer.rs
    participant R as telemetry<br/>Registration
    participant TK as telemetry<br/>KafkaEvents
    participant DC as digital-twin<br/>kafka_consumer.rs
    W->>P: publish_building_registration_request(building)
    P->>P: build RegistrationRequest, blank room names become the room id
    P->>K: building-registration-requested, key b1
    K->>TC: message, group building-registrations
    TC->>TC: read buildingId from the JSON
    TC->>R: register_from_event(b1, payload)
    R->>R: register: deserialize RegistrationRequest, check name and NUL
    R->>R: upsert building and rooms, then maxTemperature limit if present
    R->>TK: publish_completed(b1, outcome)
    TK->>K: building-registration-completed, key b1
    K->>DC: message, group building-registrations-completed
    DC->>DC: handle_payload: parse RegistrationCompleted
    DC->>W: Provisioning::resolve(b1, failure())

Data at each step

Example: building b1 named HQ, rooms r1 Lobby and r2 with a blank name.

StepData
2{"buildingId":"b1","name":"HQ","rooms":[{"id":"r1","name":"Lobby"},{"id":"r2","name":"r2"}]}
7RegistrationRequest, max_temperature None, 2 rooms
81 building row, 2 room rows in telemetry’s database. No limit written
10{"buildingId":"b1","status":"ready"}
13failure() gives None
14the upload b1 becomes ready

Reading rooms leniently

usable_rooms reads rooms as a list of plain JSON values and keeps what it can:

flowchart TD
    E["next entry"] --> I{"has id, a text, not empty?"}
    I -- no --> Drop["drop the entry"]
    I -- yes --> N{"has name, a text, not empty?"}
    N -- yes --> Keep["room id, name"]
    N -- no --> KeepId["room id, name = id"]

Example. [{"name":"ghost"}, {"id":""}, "r0", {"id":"r1"}] gives one room: r1, named r1.

Why: a room with no id cannot be stored or found again. Failing the whole building for one such room would refuse a building for a room nobody can use anyway.

Reading the answer

failure() turns the answer into “done” or a reason:

flowchart TD
    S{"status is ready?"} -- yes --> None["None: upload ready"]
    S -- no --> E{"error present?"}
    E -- yes --> Err["reason = error"]
    E -- no --> St["reason = status text"]

Example. {"buildingId":"b1","status":"exploded"} reads as a failure with reason exploded.

Why status is text and not an enum: an unknown value would then fail to parse. A message that fails to parse is logged and skipped, so the upload would stay pending for ever. As text, anything that is not ready fails the upload, with a reason.

Who decides failed

telemetry answers failed only when the request itself is wrong: no name, a NUL character, a maxTemperature that is not a number. A database error in telemetry is not answered: the message is read again later. Answering failed would make digital-twin delete the building.


2. The Wi-Fi tick

Shape

{"buildingId":"bldg-3f2b4c5d","tick":1761300000000,
 "answered":["e6f7…","f708…","0819…"],
 "connected":[{"token":"7f3c9a01b2d4e6f8","router":"e6f7…","signal":-61},
              {"token":"c2d4e6f8091a2b3c","router":"f708…","signal":-70},
              {"token":"c2d4e6f8091a2b3c","router":"0819…","signal":-72}],
 "bursts":[{"token":"a91e0c3d5f7b2846","started":1761299998412,
            "heard":{"e6f7…":-58,"f708…":-71,"0819…":-80}}]}

Router ids are UUIDs, cut here.

FieldMeaning
buildingIdThe building whose key signed the tick
tickWhen the collector took the snapshot, ms since 1970
answeredRouters that replied. A router missing here failed: its phones are unknown, not gone
connectedOne row per router listing a phone. One token on two rows is one phone heard twice
burstsScans heard: token, start time in ms, and each router’s loudest signal. Always present, empty when scanning is off
devicesPerPersonOptional. Phones per person for this site; without it, no people estimate

No MAC address and no coordinates ever: tokens are random per tick, positions belong to digital-twin.

The rules, in two places

Checked byRule
serde, deny_unknown_fieldsNo extra field anywhere. A mac beside a token fails
problems()buildingId not empty
problems()Each router in answered once, not empty
problems()devicesPerPerson, when present, finite and above 0
problems()At most 2000 connected rows (MAX_CONNECTED), 2000 bursts (MAX_BURSTS)
problems()Token: exactly 16 characters, 0–9 and a–f
problems()Signal from −127 (MIN_SIGNAL) to 0 dBm, router not empty
problems()A burst heard by 1 to 6 routers (MAX_HEARD)

problems() returns one message per broken rule, empty when the tick is sound. The limits keep a tick of UUID router ids under telemetry’s 1 MiB body limit.

Why no extra fields: telemetry forwards the received bytes to Kafka. An unchecked field would travel with them.

A tick end to end

sequenceDiagram
    autonumber
    participant C as ap-collector
    participant O as telemetry<br/>Observations::accept
    participant I as telemetry<br/>Ingest::accept
    participant K as Kafka
    participant WC as digital-twin<br/>wifi_consumer.rs
    participant Tr as digital-twin<br/>Tracking::observe
    C->>O: POST /telemetry/observations, signed body
    O->>O: from_slice into WifiObservations, unknown field refused
    O->>O: problems(), any? then 400, nothing published
    O->>O: room_readings: each phone once, in its loudest router's room
    O->>I: accept(b, totalDeviceCount readings)
    O->>K: publish_observations: same bytes, key buildingId
    K->>WC: newest offset only, auto-commit
    WC->>WC: handle_payload: from_slice again
    WC->>Tr: observe(tick, now)
    Tr->>Tr: problems() again, then age and order checks

digital-twin runs problems() again: it does not take the broker’s word for it.

Example, step 4. Phone c2d4… is on two routers at −70 and −72 dBm. It counts once, in the room of the −70 router. Phone 7f3c… counts in its router’s room. Result: 2 phones, in up to 2 rooms.


3. Devices for the browser

Shape

{"buildingId":"bldg-3f2b4c5d","tick":1761300000000,"devices":[
  {"floor":0,"room":"room-lobby","x":4.25,"y":0.0,"z":6.5,"radius":2.1,"connected":true},
  {"floor":1,"room":"room-office","x":12.75,"y":3.5,"z":3.25,"radius":5.4,"connected":false}]}
FieldMeaning
buildingIdMust match the channel’s building
tickThe snapshot these dots come from
devicesEvery dot of this tick. Always present; an empty list clears the building
floorFloor index, lowest first
roomRoom id
x, y, zPosition in model metres. y is the floor’s height
radiusOne spread of the position, metres
connectedfalse for someone passing who never joined the Wi-Fi

Device has deny_unknown_fields: no token, MAC or id can ride on a dot.

Channel names

FunctionGives
devices_channel("b1")twin:devices:b1
building_of_devices_channel("twin:devices:site:b1")Some("site:b1")
building_of_devices_channel("twin:devices:")None: no building
building_of_devices_channel("notifications")None: not a devices channel

Dots end to end

sequenceDiagram
    autonumber
    participant Tr as digital-twin<br/>Tracking::observe
    participant F as digital-twin<br/>RedisDevicesFeed
    participant R as Redis
    participant S as socket<br/>core/relay.rs
    participant B as Browser
    Tr->>F: publish(Devices)
    F->>F: message: devices_channel(buildingId), serde_json text
    F->>R: PUBLISH twin:devices:b1, gives up after 2 s
    R->>S: message on pattern twin:devices:*
    S->>S: get_devices_delivery_plan(channel, text)
    S->>S: building_of_devices_channel, parse Devices, buildingId equal?
    S->>B: emit devices to room building:b1

At step 6 socket skips the message when the channel names no building, the body is not a Devices, or the two building ids differ.


4. Room counts for telemetry

{"buildingId":"bldg-3f2b4c5d","tick":1761300000000,"rooms":{"room-lobby":3,"room-office":0}}
RuleWhy
One message per accepted tick, only when at least one router answeredNo answer would record an empty building that is not empty
Every room on a floor with a placed router, zeros includeddigital-twin can place no one on a floor with no router
Connected dots onlyA passing dot is placed too rarely to count
Counts only, deny_unknown_fieldsNo position can ride along
Topic keyed by buildingId, kept 1 h, created by digital-twinAn hour of history survives a telemetry restart

telemetry stores each room as an estimatedOccupancy reading at the tick’s time (kernel/occupancy.rs). It never touches totalDeviceCount, which is telemetry’s own count.

Example. The message above becomes two readings at 1761300000000: room-lobby 3, room-office 0.


What stays out of this crate

Building, Room, Coordinates, Dimensions stay in digital-twin/src/domain/. No other Rust service parses them: the ownership lookup GET /domain/{building} answers a plain list of domain names.

The full building is read by agent (Python) and the frontend (TypeScript). A fixture holds them in line:

LanguageTest
Rustdigital-twin/tests/building_conformance.rs: parses schemas/fixtures/building.json into the real Building, writes it back, compares
Pythonagent/tests/unit/test_building_conformance.py: runs the same file through the projections the twin tools give the model
Schematwin-schema/tests/building_schema.rs: the fixture against schemas/json/building.schema.json

Tests

WhereChecks
src/lib.rscamelCase names; current producer output parses; room dropped or named by id; missing name and rooms are empty; non-number maxTemperature fails; ready has no error; failed carries it; unknown status is a failure; channel round trip for b1 and site:b1; other channels give None
tests/wifi_observations_conformance.rsEvery fixture tick round-trips; every rejected one fails serde or problems()
tests/devices_conformance.rs, tests/estimated_occupancy_conformance.rsSame, for dots and room counts
tests/*_schema.rsFixture against its JSON schema, accepted and rejected cases
digital-twin redis_devices.rsEvery devices fixture goes out on its building’s channel as pinned
socket core/relay.rsEvery devices case routed, every rejection skipped
ap-collector tests/test_observations_contract.pyThe Python builder matches the Wi-Fi fixture

Rejected Wi-Fi cases in the fixture: a MAC as token, a MAC beside the token, coordinates on a burst, a positive signal, a burst no router heard, a burst heard by seven routers, a start in seconds, no answered, devicesPerPerson 0, a router answering twice.

mise exec -- cargo test --manifest-path schemas/twin-schema/Cargo.toml