Skip to main content
Version: scarthgap_2-x

Edgehog Astarte Interfaces

This page describes the purpose, structure, and usage of the edgehog-astarte-interfaces component within the Clea Cloud IoT architecture.

What are Astarte Interfaces?​

Astarte interfaces are JSON schema definitions that describe the data exchanged between devices and the Astarte backend. They define the structure, types, and direction (device-to-cloud or cloud-to-device) of each data stream or property.

In the context of Edgehog and Clea Cloud, these interfaces enable standardized communication for telemetry, device management, OTA updates, and more.

Purpose of edgehog-astarte-interfaces​

  • Centralized Definitions:
    Provides a set of curated Astarte interface files used by both the device runtime and the backend.
  • Versioning:
    Ensures that all devices and services use compatible interface versions.
  • Integration:
    The Yocto recipe installs these interface files into the device root filesystem, making them available to the Edgehog Device Runtime and other components.

Typical Contents​

The edgehog-astarte-interfaces package includes JSON files such as:

  • org.edgehog.DeviceInfo.json
  • org.edgehog.Telemetry.json
  • org.edgehog.OTARequest.json
  • org.edgehog.OTAStatus.json
  • org.edgehog.NetworkStatus.json
  • ...and others as needed for device management and telemetry.

Each file defines one interface, specifying:

  • Interface name and version
  • Type (datastream/property)
  • Ownership (device/server)
  • Mappings (paths, types, reliability, retention, etc.)

Example: Device Info Interface​

{
  "interface_name": "org.edgehog.DeviceInfo",
  "version_major": 1,
  "version_minor": 0,
  "type": "properties",
  "ownership": "device",
  "mappings": [
    {
      "endpoint": "/hardware_id",
      "type": "string",
      "description": "Unique hardware identifier"
    },
    {
      "endpoint": "/model",
      "type": "string",
      "description": "Device model"
    }
  ]
}

How Interfaces Are Used​

  • On the Device:
    The Edgehog Device Runtime loads these interface definitions to know what data to publish and how to interpret incoming commands.
  • On the Backend:
    The Astarte backend uses the same interface files to validate and process data from devices.
  • During Development:
    Developers can extend or modify interfaces to support new features, but must ensure version compatibility.

Yocto Integration​

The Yocto recipe edgehog-astarte-interfaces_x.x.x.bbis responsible for:

  • Installing the JSON interface files to a standard location (e.g., /usr/share/astarte/interfaces/).
  • Ensuring the correct version is included in the device image.
  • Making the interfaces available to other recipes and services.

Updating or Adding Interfaces​

  1. Edit or add JSON files in the source repository.
  2. Update the Yocto recipe if new files are added or versions change.
  3. Rebuild the image to deploy updated interfaces to devices.

References​