How your system connects
For a technology partner with equipment or a platform of its own, what connects to Klorad today, what the work is, and how we prove the connection.
This page is for the engineer at a technology partner who has to answer one question first: can our system be shown as a twin, and what does it take. The three guides it points to are written for a developer with a licence; this one is written for the decision before the licence.
What connects today
Klorad reads your system through an ObservationSource on the server. @klorad/protocols
ships three:
| Your system offers | Klorad uses | Guide |
|---|---|---|
| An MQTT broker (gateways, PLCs, sensors) | mqttConnection: subscribes to your topics, publishes an authorised command back | Connect MQTT devices |
| Pushes to a URL you configure (alarms, events) | webhookSource: a receiver for signed, timestamped pushes that answers 202 or refuses | Receive webhooks |
| A REST endpoint you can read on an interval | restSource: fetches, validates, routes to shadows | Connect a polling API |
Every reading carries the time your system observed it, not the time Klorad received it, and
every payload is validated at the boundary before it reaches the scene. Your system keeps its
devices and its certified functions; Klorad holds a Digital Shadow of each (one way, timestamped)
or a Digital Twin (two way, commands only through an authorised Action). The model is in
Physical correspondence. mqttConnection hands each payload to your
parse function as bytes; it does not decode Sparkplug B for you.
A system that offers none of the three (a proprietary SDK, a database, a file drop) connects
through a source of its own: one object with an id and a start method, described in
Integration. In an app built on the SDK, your developers write it. In
Klorad One, a new kind of connection is a module. Need a module we do not have? We build it and
maintain it. Ask for a module.
What the work is
- Name the entities. The device or asset names your system uses are the names the twin binds to. There is no mapping table in between.
- Write the parser. One function that takes your payload and returns readings, with a schema that refuses what it does not expect.
- Place the objects. Each device becomes a Scene Object with a position on the site and a
bindingto its entity, taken from your as built drawings or a device list. - Decide the commands. For a twin, which commands exist and who may send them. Everything else stays read only.
A proof of connection
We prove the connection on a sample of your own data: a recording of your broker, a batch of your webhooks or a few pages of your API, replayed into a scene with your objects on it, with the readings arriving in order and each object following them. The proof needs no access to your production systems.
To start, send the kind of system, the interface it offers and a sample through the contact form.
Something wrong or unclear? Tell us.