Skip to main content
Version: scarthgap_2-x

Astarte Message Hub

Astarte Message Hub is a D-Bus service that enables Astarte device SDK functionality to be shared across multiple services on the same device. This guide is aimed at developers who want to understand, build, and integrate the Astarte Message Hub into their IoT projects.

Overview​

The Message Hub acts as a local broker between device services and the Astarte backend. It exposes a D-Bus interface that allows client applications to send and receive Astarte data without each implementing the Astarte Device SDK.

Key Components​

  • Message Hub Daemon (astarte-message-hub): Core service managing D-Bus interfaces and device communication.
  • D-Bus API: Exposes org.astarte-platform.MessageHub namespace with support for signals, interfaces, and introspection.
  • Client Libraries: Optional bindings for client apps to use the message hub (e.g., Rust or Python).

Getting Started​

Prerequisites​

  • Astarte instance set up with a registered device.
  • MQTT broker endpoint (typically part of Astarte).
  • Linux system with D-Bus and systemd support.
  • Rust (for building from source).

Clone the Repository​

git clone https://github.com/astarte-platform/astarte-message-hub.git
cd astarte-message-hub

Build​

cargo build --release

Install and Run​

You can run the binary directly:

target/release/astarte-message-hub --config /etc/astarte-message-hub/config.toml

Or install as a systemd service:

sudo cp target/release/astarte-message-hub /usr/local/bin/
sudo cp contrib/astarte-message-hub.service /etc/systemd/system/
sudo systemctl enable astarte-message-hub
sudo systemctl start astarte-message-hub

Configuration​

The hub uses a TOML configuration file typically located at /etc/astarte-message-hub/config.toml.

Example Configuration​

[connection]
device_id = "device-id@example.realm"
credentials_secret = "secret"
pairing_url = "https://api.astarte.example.com/pairing"
realm = "example"

[logging]
level = "info"

Fields:

  • device_id: Full Astarte device ID.
  • credentials_secret: Token for authentication.
  • pairing_url: URL to the pairing API.
  • realm: Astarte realm name.
  • level: Logging verbosity.

D-Bus API Overview​

  • Send Datastream:
org.astarte-platform.MessageHub.SendDatastream(interface_name, path, value)
  • Send Property:
org.astarte-platform.MessageHub.SendProperty(interface_name, path, value)

  • Receive Signals: Use D-Bus signals to receive changes for properties and datastreams.

  • Introspection Support:

org.freedesktop.DBus.Introspectable.Introspect()

See docs/dbus-api.md for full details.

Integration Example (Python)​

Using pydbus to publish a value:

from pydbus import SystemBus
bus = SystemBus()
msg_hub = bus.get("org.astarte-platform.MessageHub", "/org/astarte_platform/MessageHub")
msg_hub.SendDatastream("com.example.MyInterface", "/sensor/temp", 23.5)

Receiving updates:

def on_signal(iface, path, value):
    print(f"Update from {iface} {path}: {value}")
msg_hub.onSignalReceived = on_signal

Development Tips​

  • Format code with cargo fmt
  • Lint using cargo clippy
  • Run tests:
cargo test
  • Use dbus-send or d-feet to test D-Bus interfaces interactively.

References​