Skip to main content

Crate astarte_message_hub

Crate astarte_message_hub 

Source
Expand description

§Astarte Message Hub

Crates.io docs.rs CI codecov LICENSE

A central service that runs on (Linux) devices for collecting and delivering messages from N apps using 1 MQTT connection to Astarte.

§Documentation

§Requirements

  • protobuf >= 3.15
  • Rust version >= 1.78.0

§Configuration

The Astarte Message Hub is configured through the user’s config directory $HOME/.config/message-hub/, searching for a config file config.toml or config.d/*.toml. Otherwise system wide /etc/message-hub/ directory will be used .

In alternative, you can specify the path to the configuration file with the -c/--config or --config-dir cli options, or passing the options via CLI and ENV directly.

The format for the configuration file is the following:

##
# Required fields
#
realm = "<REALM>"
# Required to communicate with Astarte.
pairing_url = "<PAIRING_URL>"
# Used to register a device and obtain a `credentials_secret`
pairing_token = "[PAIRING_TOKEN]"
# Credential secret, if not provided the `pairing_token` is required
credentials_secret = "[CREDENTIALS_SECRET]"
# Device id, if not provided it will be retrieved from `io.edgehog.Device` dbus-service
device_id = "[DEVICE_ID]"
# Path to store persistent data
store_directory = "[STORE_DIRECTORY]"

##
# Optional fields
#
# Directory containing the JSON interfaces
interfaces_directory = "[INTERFACES_DIRECTORY]"

##
# Other fields, with defaults
#
# Address the gRPC connection will bind to
grpc_socket_host = "127.0.0.1"
grpc_socket_port = 50051

[astarte]
# Ignore SSL errors
ignore_ssl = false

It’s recommended to specify the store directory since the message-hub will require persistence for some data.

If one is not specified the user’s data directory will be used instead. On linux this will follow the XDG specification and use $HOME/.local/share/message-hub while on Windows C:\Users\$USER\AppData\Roaming.

An example configuration file can be found in the examples direction.

§Configuration priority

The Message Hub will first load the default configuration files in the system and user directory, in this order. Then it will sort and merge all the drop-in configuration from the system, user, and store directory (if configured), so the values in a file named 10-config.toml will be overwritten by one named 40-config.toml.

After all the configuration files, the custom configuration file (specified with the -c or --config flag) and other CLI and ENV arguments will take be read.

§Configuration in docker

The Message Hub is also distributed as a docker image available in the ghcr. Using the image you can quickly test out and connect nodes to the message hub. Remember to expose the grpc port (the default is 50051) if you need to accept external connections. You can use docker-compose or run it directly:

Using an already registered device id:

docker run -e MSGHUB_REALM=realm \
  -e MSGHUB_DEVICE_ID=s6USRuvRSv6Te7S2dVVh3Q \
  -e MSGHUB_PAIRING_URL=https://api.eu1.astarte.cloud/pairing \
  -e MSGHUB_CREDENTIALS_SECRET=your_secret \
  -p 50051 ghcr.io/lucaato/astarte-message-hub:snapshot

Replace the environment values with the appropriate ones for your device.

Or by using a pairing token:

docker run -e MSGHUB_REALM=realm \
  -e MSGHUB_DEVICE_ID=s6USRuvRSv6Te7S2dVVh3Q \
  -e MSGHUB_PAIRING_URL=https://api.eu1.astarte.cloud/pairing \
  -e MSGHUB_PAIRING_TOKEN=your_pairing_token \
  -p 50051 ghcr.io/lucaato/astarte-message-hub:snapshot

Replace the environment values with the appropriate ones for your device.

§Override the configuration file

You can override the configuration file options by passing arguments to the command line or exporting the corresponding environment variables. Run the massage hub with --help to see all the options.

§Example

Have a look at the examples for an usage example showing how to send and receive data.

Modules§

astarte
Connection with astarte for the Message Hub
cache
Permits the caching of the Device Introspection
config
Configuration for the Message Hub.
error
Errors for the message hub.
store
Manages the store directory.

Structs§

AstarteMessageHub
Main struct for the Astarte message hub.