Message transferring among devices with Local Hub Service

Statement

  • The operating system as mentioned in this document is Ubuntu 18.04.
  • The MQTT client toolkit as mentioned in this document is MQTTBox.

NOTE:Darwin can install Baetyl by using Baetyl source code. Please see How to build image from source code.

Different from Device connect to Baetyl with Hub service, if you want to transfer MQTT messages among multiple MQTT clients, you need to configure the connect information, topic permission, and router rules. More detailed configuration of Hub service, please refer to Hub service configuration.

This document uses the TCP connection method as an example to test the message routing and forwarding capabilities of the Hub service.

Workflow

  • Step 1: Install Baetyl and its example configuration, more details please refer to How-to-quick-install-Baetyl
  • Step 2: Modify the configuration according to the usage requirements, and then execute sudo systemctl start baetyl to start the Baetyl in Docker container mode, or execute sudo systemctl restart baetyl to restart the Baetyl. Then execute the command sudo systemctl status baetyl to check whether baetyl is running.
  • Step 3:MQTTBox connect to Hub Service by TCP connection method, more detailed contents please refer to Device connect to Baetyl with Hub service.
    • If connect successfully, then subscribe the MQTT topic due to the configuration of Hub Service.
    • If connect unsuccessfully, then retry Step 3 operation until it connect successfully.
  • Step 4:Check the publishing and receiving messages via MQTTBox.

Message Routing Test

The Baetyl application configuration is replaced with the following configuration:

# /usr/local/var/db/baetyl/application.yml
version: V2
services:
  - name: hub
    image: 'hub.baidubce.com/baetyl/baetyl-hub'
    replica: 1
    ports:
      - '1883:1883'
    mounts:
      - name: localhub-conf
        path: etc/baetyl
        readonly: true
      - name: localhub_data
        path: var/db/baetyl/data
      - name: log-V1
        path: var/log/baetyl
volumes:
  - name: localhub-conf
    path: var/db/baetyl/localhub-conf/V1
  - name: log-V1
    path: var/db/baetyl/log
  - name: localhub_data
    path: var/db/baetyl/localhub_data

The Baetyl Hub service configuration is replaced with the following configuration:

# /usr/local/var/db/baetyl/localhub-conf/service.yml
listen:
  - tcp://0.0.0.0:1883
principals:
  - username: 'test'
    password: 'hahaha'
    permissions:
      - action: 'pub'
        permit: ['#']
      - action: 'sub'
        permit: ['#']
subscriptions:
  - source:
      topic: 't'
    target:
      topic: 't/topic'
logger:
  path: var/log/baetyl/service.log
  level: 'debug'

As configured above, message routing rules depends on the subscriptions configuration item, which means that messages published to the topic t will be forwarded to all devices(users, or mqtt clients) that subscribe the topic t/topic.

NOTE: In the above configuration, the permitted topics which are configured in permit item support the + and # wildcards configuration. More detailed contents of + and # wildcards will be explained as follows.

# wildcard

For MQTT protocol, the number sign(# U+0023) is a wildcard character that matches any number of levels within a topic. The multi-level wildcard represents the parent and any number of child levels. The multi-level wildcard character MUST be specified either on its own or following a topic level separator(/ U+002F). In either case it MUST be the last character specified in the topic.

For example, the configuration of permit item of sub action is sport/tennis/player1/#, it would receive messages published using these topic names:

  • sport/tennis/player1
  • sport/tennis/player1/ranking
  • sport/tennis/player1/score/wimbledon

Besides, topic sport/# also matches the singular sport, since # includes the parent level.

For Baetyl, if the topic # is configured in the permit item list(whether pub action or sub action), there is no need to configure any other topics. And the specified account(depends on username/password) will have permission to all legal topics of MQTT protocol.

+ wildcard

As described in the MQTT protocol, the plus sign(+ U+002B) is a wildcard character that matches only one topic level. The single-level wildcard can be used at any level in the topic, including first and last levels. Where it is used it MUST occupy an entire level of the topic. It can be used at more than one level in the topic and can be used in conjunction with the multi-level wildcard.

For example, topic sport/tennis/+ matches sport/tennis/player1 and sport/tennis/player2, but not sport/tennis/player1/ranking. Also, because the single-level wildcard matches only a single level, sport/+ does not match sport but it does match sport/.

For Baetyl, if the topic + is configured in the permit item list(whether pub action or sub action), the specified account(depends on username/password) will have permission to all single-level legal topics of MQTT protocol.

NOTE: For MQTT protocol, wildcard ONLY can be used in Topic Filter(sub action), and MUST NOT be used in Topic Name(pub action). But in the design of Baetyl, in order to enhance the flexibility of the topic permissions configuration, wildcard configured in permit item(whether in pub action or sub action) is valid, as long as the topic of the published or subscribed meets the requirements of MQTT protocol is ok. In particular, wildcards ( # and + ) policies are recommended for developers who need to configure a large number of publish and subscribe topics in the principals configuration.

Message Transfer Test Among Devices

The message transferring and routing workflow among devices are as follows:

../_images/trans-flow.pngMessage transfer test among devices

Specifically, as shown in the above figure, client1, client2, and client3 respectively establish a connection to Baetyl with Hub Service, client1 has the permission to publish messages to the topic t, and client2 and client3 respectively have the permission to subscribe topic t and t/topic.

Once the connection to Baetyl for the above three clients with Hub Service is established, as the configuration of the above three clients, client2 and client3 will respectively get the message from client1 published to the topic t to Hub Service.

In particular, client1, client2, and client3 can be combined into one client, and the new client will have the permission to publish messages to the topic t, with permissions to subscribe messages to the topic t and t/topic. Here, using MQTTBox as the new client, click the Add subscriber button to subscribe the topic t and t/topic.

Then clicks the Publish button to publish message with the payload This is a new message. and with the topic t to Hub service, you will find this message is received by MQTTBox with the subscribed topics t and t/topic. More detailed contents are as below.

../_images/mqttbox-tcp-trans-message-success.pngMQTTBox received message successfully

In summary, the message forwarding and routing test between devices based on Hub service is completed through MQTTBox.