MyQttSatellite -- MQTT client node to bridge message to commands

#1

Table of contents

1. What is MyQttSatellite?
2. What does MyQttSatellite do?
3. MyQttSatellite License
4. Are you going to OpenSource MyQttSatellite?
5. How to install MyQttSatellite?
6. MyQttSatellite Upgrade
7. Mapping commands
8. How to generate response commands
9. Change running user for MyQttSatellite service
10. MyQttSatellite Support

1. What is MyQttSatellite?

Is a client side service daemon that acts as a client to a MQTT broker waiting to receive messages that are translated into commands that are executed in order.
It has a highly concurrent design using #Akka and #Scala but it makes sure messages are processed in order.

It is designed for long-term running, with keep-alive and connection supervision functions so it is always available. It operates with low memory consumption (150MB) in a stable way.

2. What does MyQttSatellite do?

Essentially, it helps to bridge a node running MyQttSatellite with a #MQTT Hub/Broker so it can receive message commands to implement operations and optionally reply with content that is sent to sender-configured topics.

Use cases are:

  • Send node status (temp, disk status, sensor measurements)

  • Provide access to mission critical or sensitive nodes that have sensitive resources that can be exposed by a MQTT API

  • Provide MQTT message termination, traslating them into commands that optionally generate output that can be sent to sender-configured-topics.

3. MyQttSatellite License

MyQttSatellite is FreeWare. You can:

  1. Use it without any cost, any limit.
  2. You can redistribute
  3. It is provided as is, without any expressed or implied warranty
  4. You are not required to make any attribution.

4. Are you going to OpenSource MyQttSatellite?

Yes. It should be very soon.

5. How to install MyQttSatellite?

  1. Make sure you have java installed. MyQttSatellite requires java. Run the following to check if you have java installed. If it is not the case, check OS provider manual to deploy latest java 8 version:

    > java -version

  2. Download MyQttSatellite:

    > cd /usr/src
    > wget --no-check-certificate https://www.aspl.es/downloads/myqtt-satellite/myqtt-satellite-all-0.2.43.zip

  3. Install with:

    > unzip myqtt-satellite-all-0.2.43.zip
    > ./deploy.sh
    > ./install.sh # ONLY first time myqtt-satellite is installed

  4. Now get into your MyQttHub account and create one or two #MQTT devices to connect to the platform. You can use a single #MQTT device to publish and receive or have two #MQTT devices, one for publishing and one for message reception.

  5. With these MQTT devices created, open your configuration file: /etc/MyQttSatellite/conf/application.conf

    1. Configure host to point to node02.myqtthub.com

    2. Configure reader section to setup reader account.

    # reader configuration to receive messages
    reader {
    enabled = true
    client-id = “clientid”
    username = “username”
    password = “apassword”
    }

    1. Do the same with publisher section. If you are not expecting to publish, disable by setting enabled=false.

    # separate user to publish responses or information

    publisher {
    enabled = true
    client-id = “publisher.clientid”
    username = “publisher.username”
    password = “klasdflkj”
    }

  1. Now configure SMTP settings so you can get notifications about messages executed, inside mail.settings section.

  2. Restart service:

    > systemctl restart myqtt-satellite.service

    After that, check logs by running the following to see if it is working without errors:

    > tail -f /var/log/syslog /var/log/myqtt-satellite.log

6. MyQttSatellite Upgrade

Assuming you already have a working MyQttSatellite, just download new release as usual, unpack, deploy and restart. Here is how:

  1. Download MyQttSatellite as usual:

    > cd /usr/src
    > wget --no-check-certificate https://www.aspl.es/downloads/myqtt-satellite/myqtt-satellite-all-NEW-VERSION.zip

  2. Deploy upgraded version with:

    > unzip myqtt-satellite-all-NEW-VERSION.zip
    > ./deploy.sh

  3. Restart service:

    > systemctl restart myqtt-satellite.service

7. Mapping commands

Inside configuration file /etc/MyQttSatellite/conf/application.conf you will find the following section that explains how to map MQTT messages to commands:

# Command mapper : defines how subscriptions are mapped to commands
# Syntax:
#    <subscription>  ->   <command>
#
# Inside <commnad> can be configured any command that uses:
#
#   - <messageFile> : file where message body was received
#   - <topic> : topic for message received
#   - <qos> : message received QoS
#
command-mapper = [
    "pas/events/# -> myqtt_myqtt_worker.py --file <messageFile>"
]

The idea is very straightforward: a preference string list where each item maps a subscription MQTT filter to a command that can use <messageFile>, <qos> and/or <topic> to produce a final complete command that will be executed, in order, by MyQttSatellite.

We mean “in order” because if several messages are received, they are handled concurrently but execution in a blocking-serial manner.

Default example describes a single command that maps: pas/events/# to command myqtt_myqtt_worker.py --file <mesageFile>.

That is, any MQTT message received matching with topic filter pas/events/# will run that command.

Remember that after configuring any mapping, you have to restart MyQttSatellite.

8. How to generate response commands

In case you need to run a query service (request-reply), make your command to generate an output with the following format:

X-Publish-Reply-To-Topic: <topic>

<message content>

That is, MIME format, where we generate X-Publish-Reply-To-Topic header along with content.
This will be detected by MyQttSatellite creating a PUBLISH message to the provided topic using commands’ output.

9. Change running user for MyQttSatellite service

By default, during installation, it is created a low-privilege user for this service: myqttsatellite

This user is secure and it is the most recommended option if you are integrating MyQttSatellite with APIs, libraries, ports or
SQL databases access.

In case you want to change service running user for MyQttSatellite because it needs higher of different permissions, you only have to edit file:

/etc/systemd/system/myqtt-satellite.service

Then update the following variables to declare running user required:

User=myqttsatellite
Group=myqttsatellite

Security considerations:
This configuration can be used, even, to setup root as running user. In such case, make sure it is really needed as well as take caution about what is run by command mapping.

After applying changes, restart with:

>> /etc/init.d/myqtt-satellite restart

10. MyQttSatellite Support

Bug reports, problems and help needed, please use this forum: open a topic explaining your case.

MyQttHub EN -- Start here