User manual

User manual

Broker

The broker is a modified version of HiveMQ Community Edition.

There are two primary ways of running the broker, either cloning the git repo and running the code directly or running as a docker container. The docker image is available at DockerHub with the name tokongs/ffi02-broker. To run simply use the command bellow.

docker run -p 1883:1883 tokongs/ffi02-broker

This spins up the broker and maps port 1883 on the container to the corresponding port on the host machine. To run with a custom configuration you'll have to mount a config file at /opt/hivemq/conf/config.xml. An example of this can be seen in the command bellow.

docker run -p 1883:1883 -v "$(pwd)"/config.xml:/opt/hivemq/conf/config.xml tokongs/ffi02-broker

This assumes there is a file called config.xml in the current working directory.

Topic priorities

When starting the broker it'll load a config file called config.xml from the HIVEMQ_HOME directory. HIVEMQ_HOME is an environment variable specifying where the broker should load config files from. The priorities are specified as an XML object, priorities bellow the root object <hivemq>. Bellow is an example configuration file.

<hivemq>
    <listeners>
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
        </tcp-listener>
    </listeners>
    <persistence>
        <mode>in-memory</mode>
    </persistence>

    <priorities>
        <priority>
            <filter>testtopic/#</filter>
            <priority>100</priority>
            <priority-class>FLASH</priority-class>
        </priority>
    </priorities>
</hivemq>

<filter> is a standard MQTT topic filter and can contain wildcards(#, +). The inner <priority> element is the priority as a number where a higher number means a higher priority. <priority-class> can take on one of the following values, ["FLASH", "IMMEDIATE", "PRIORITY", "ROUTINE"]. Messages in priority class FLASH have a higher priority than IMMEDIATE, which has a higher priority than the class PRIORITY and the lowest priority class is ROUTINE. This means that a message in class routine and with a priority value of 100 has a lower priority than a message in class immediate and with a priority value of 50. Every messages also gets it's priority class encoded in the IP Differentiated Services header. The value is encoded into the 4th and 5th bit. The values corresponding to the classes are shown bellow.

ROUTINE   = 00
PRIORITY  = 01
IMMEDIATE = 10
FLASH     = 11

Refer to the HiveMQ Community Edition documentation to see more configuration options related to MQTT and operation of the broker.

Client library

The Client library is a modified version of the HiveMQ MQTT Client. Our version can be used in the same way as the normal HiveMQ MQTT Client, but we have added some additional features.

Topic priories

When creating the client with the client builder you can specify a priority class(Flash, Immediate, Priority or Routine) to apply to a specific topic or topic filter. An example of how to do this is shown below in Kotlin code, but the same will work in any JVM based language.

    val client = Mqtt5Client.builder()
        .identifier(UUID.randomUUID().toString())
        .serverHost("broker_hostname")
        .addTopicPriority(TopicPriority(MqttTopicFilter.of("this/will/have/priotity/routine/#"), PriorityClass.ROUTINE))
        .addTopicPriority(TopicPriority(MqttTopicFilter.of("testtopic/#"), PriorityClass.PRIORITY))
        .addTopicPriority(TopicPriority(MqttTopicFilter.of("hello/world/1"), PriorityClass.IMMEDIATE))
        .addTopicPriority(TopicPriority(MqttTopicFilter.of("flash/#"), PriorityClass.FLASH))
        .buildBlocking()

Test app

The test app is a CLI which uses the client library for communicating with a broker. The broker may be our broker, or another standard MQTT broker. The easiest way to run the application is by pulling the docker image. An example of this is docker run tokongs/ffi02-test-app. Running the application like this without any arguments will output a list of valid commands. To gain more information about each command you can use the -h/--help flag, like so docker run tokongs/ffi-test-app publish -h.

Connectivity

By default the application will try to connect to an MQTT broker running on localhost on the standard port. This will be unreachable without some configuration of the docker container. By setting docker to use the host network mode the application can connect to the host's loopback address. docker run --network="host" test-app publish -t test hei. This command will send a message with the payload hei to the topic test to a broker running on port 1883 on the host machine.

Another way to use the application is to provide it with an address to a remote broker using the -b/--broker-address flag.