Skip to main content
Version: Next

Real Estate Core Edge Messaging Format

note

You are currently looking at a work in progress version of the Relynk API documentation. Consider the underlying APIs and messaging formats as stable, but we strive to make the documentation as developer friendly as possible. If you feel anything is missing please reach out to hello@relynk.io, any feedback would be much appreciated.

Real Estate Core Edge Messaging Format

The Real Estate Core (RealEstateCore) Edge Messaging Format provides a standardized messaging format between systems, facilitating standardized communication. This format supports compact, legible JSON messages that are versatile across different implementations of RealEstateCore, encompassing both sensor data (Observations) and command or setpoint instructions (Actuations).

Overview​

RealEstateCore Edge Messages are designed to be both lightweight and powerful, allowing for the inclusion of multiple message types within a single JSON message. These messages can comprise Observations, Actuation-related messages, and meta-telemetry such as Exceptions.

Key Concepts​

  • Observations: Sensor values generated by devices, reflecting the current state or measurement from the sensor.
  • Actuations: Commands or setpoints sent back to the system, allowing for control or adjustment of device operations.
  • Actuation Responses: Acknowledgements from devices indicating the receipt and processing of actuation commands.
  • Exceptions: Error or status messages indicating any issues encountered during the operation of the device or the execution of commands.

Sender and Receiver​

  • Sender: The device or system sending the observations to the Receiver.
  • Receiver: The device or system receiving the observations from the Sender, and potentially sending actuations.

JSON Schema​

The message format is defined using the JSON Schema standard (see json-schema.org), ensuring that messages are structured and validated according to a specified schema. The schema for Edge Messages is available at Real Estate Core official Github repository: Edge Message Schema

Message Structure​

Each Edge Message includes the following key components:

  • format: Specifies the version of RealEstateCore being used, ensuring compatibility across different versions.
  • deviceId: The unique identifier for the device sending or receiving the message. This identifier is not only used to define a device, but in server to server communication it will also be used to identify the server.
  • observations: (Sender-to-Receiver) An array of Observation objects, each containing sensor data and associated metadata.
  • actuationCommands: (Receiver-to-Sender) Commands sent to devices for operational control.
  • actuationResponses: (Sender-to-Receiver) Responses from devices acknowledging the receipt and processing of actuation commands.
  • exceptions: (Sender-to-Receiver) Error or status messages indicating any issues encountered during the operation of the device or the execution of commands.
caution

Relynk only supports the RealEstateCore Edge Messaging Format version 3.3.

Examples​

Below are examples of the Edge Message format for both sender-to-receiver and receiver-to-cloud communication.

Sender to Receiver Format​

In the below example, the Sender is sending an Observation and an Actuation Response to the Receiver. The "sensorId" represents the Point that is the source of the observation, and the "actuatorId" represents the Point that is the source of the actuation response.

tip

To get a complete list of the available quantity kinds in Relynk, check out this page: Quantity Kinds

{
  "format": "rec3.3",
  "deviceId": "64b65a99-a53c-47f5-b959-1c7a641d82d8",
  "observations": [
    {
      "observationTime": "2019-05-27T20:07:44Z",
      "value": 16.1,
      "quantityKind": "https://w3id.org/rec/core/Temperature",
      "sensorId": "e0d5120b-90f1-48d6-a47f-f8ccd7727b04"
    }
  ],
  "actuationResponses": [
    {
      "actuatorId": "a49feda7-2bc3-4793-b87f-8ec0c3909f9b",
      "actuationCommandId": "e1d504ed-e086-5eaa-9563-9894159872ab",
      "responseCode": "success",
      "actuationResponseTime": "2019-05-27T20:07:54Z"
    }
  ],
  "exceptions": [
    {
      "exceptionTime": "2019-05-27T20:08:14Z",
      "origin": "actuator",
      "id": "a49feda7-2bc3-4793-b87f-8ec0c3909f9b",
      "exception": "Unexpected failure",
      "retry": 1
    }
  ]
}

Receiver to Sender Format​

In the below example, the Receiver is sending an Actuation Command to the Sender. The "actuatorId" represents the Point that is the target of the actuation command.

tip

The Receiver will specify the guid part of the actuationCommandId, and the Sender when returning a response will return the same "actuationCommandId" as the Receiver sent.

{
  "format": "rec3.3",
  "deviceId": "64b65a99-a53c-47f5-b959-1c7a641d82d8",
  "actuationCommands": [
    {
      "actuationCommandTime": "2019-05-27T20:07:48Z",
      "actuationCommandId": "e1d504ed-e086-5eaa-9563-9894159872ab",
      "actuatorId": "a49feda7-2bc3-4793-b87f-8ec0c3909f9b",
      "valueString": "Open"
    }
  ]
}