Skip to main content

Services

As explained in the architecture section, Connhex Edge is composed of multiple services. We can divide these into two types: built-in and custom services.

Built-in services​

There are two built-in services:

  • control: responsible for receiving commands from Connhex Cloud
  • bridge: responsible for sending data to Connhex Cloud

Both services communicate with Connhex Cloud through a unified connection handler: communication is configured and secured here, with message persistence being managed at this level too.

What follows is a brief description of the workflow for both services, assuming the connection protocol used is MQTT.

Bridge service​

When a message is published to a BUS subject1, the bridge service will:

  • convert it to an MQTT message
  • map the BUS subject to a specific MQTT topic, according to the policy specified here
  • send the message to Connhex Cloud via MQTTs, automatically handling the retention of the message in cases of network or power loss through the unified connection handler

Control service​

When a message is delivered through MQTT, the control service will:

  • extract its payload
  • map the MQTT topic to the specific BUS subject, according to the policy specified here
  • publish the message to the BUS

Custom services​

Connhex Edge enables a better way of writing firmware for your IoT applications: custom services.

Custom services are, like the name suggests, application-specific: they handle all the logic that allows the Edge to perform its intended purposes. See here for a primer on how to write a custom service or here for some examples.

Shared message BUS​

The shared message BUS consists of a pub-sub message queue: services use this to communicate with each-other and Connhex Cloud. It implements a one-to-many publish-subscribe pattern where a publisher sends a message on a specific subject and any active subscriber listening on that subject receives the message.

Decoupling

You can use the shared message bus to perform the same behavior irrespective of where an action was triggered.

Suppose that pressing a button on a web UI, on a machine's HMI or on a physical button should lead to the same behavior: it's only necessary for the custom service responsible for handling the local button press to emit the same event coming from the control service on the BUS!

The BUS supports two message queues:

Custom services can interact with it by using the selected message queue APIs2.

Choosing between NATS and Redis

By default, Connhex Edge includes a message bus based on NATS. However, the two are quite similar for this use case: feel free to choose what suits you best!

Monitoring services: heartbeat messages​

Heartbeat messages are used by the Connhex Edge agent to understand whether a service is healthy or not. It periodically3 checks if all services have published a heartbeat message to a specific BUS subject (i.e. heartbeat.<service-name>.service). If not, the service is marked as down.

The status of each service running on the Edge can be retrived remotely using Connhex Control:

Connhex Control: Connhex Edge services status

Mappings​

Mappings specify the relationship between BUS subjects and MQTT topics.

Examples are using NATS

The following examples assume NATS is used as message queue. If you use Redis, simply change nats_topic to redis_topic.

NATS subjects to MQTT topics mapping​

The mapping between NATS subjects and MQTT topics is specified in the auto-generated agent.toml file (specifically in the routes file section). The default configuration is this:

...
[[routes]]
  mqtt_topic = "events"
  nats_topic = "events.>"
  qos = 0
  workers = 1
...

In this case, all messages published to the NATS subject named events will be automatically sent to Connhex through the channels/<channel-id>/messages/events MQTT topic.

MQTT subtopic

Note the .> in the NATS topic configuration. This is used to turn the latter part of the NATS subject into an MQTT subtopic: for example, if you're using the Connhex Message Policy, sending pushing data on a events.params subject means receiving the same data in Connhex Cloud on channels/<channel-id>/messages/events/params.

MQTT topics to NATS subjects mapping​

When a MQTT message is sent from Connhex Cloud to an Edge, it is automatically converted to a NATS message and then published on a specific subject.

If you're targeting a specific custom service running on your Edge, the MQTT topic used by Connhex Cloud will be channels/<channel-id>/messages/services/<service-name>. On the Edge, this will be delivered to the NATS subject commands/<service-name>.

Footnotes​

  1. Subjects are equivalent to topics: the two terms are used interchangeably here. ↩

  2. Check out the NATS or Redis official documentation for more information and available clients. ↩

  3. By default, every 10 seconds. ↩