Documentation for eMQTT5 client

Using Properties with the client

Since this library is oriented for embedded usage, a great care was taken for avoiding heap usage and minimizing code size.

Packet in destination of the broker

In order to acheive theses goals, the Properties class is a chained list where each node stores a flag telling if it was allocated on the stack (default) or on the heap.

When the chained list is destructed, each node will either suicide(delete itself if heap allocated) or just chain the destruction request to the next node.

Parsing the chained list is done recursively, but this shouldn't be an issue since the number of possible properties for each packet is small.

Appending properties is done like this:

    Property<uint32> maxProp(PacketSizeMax, recvBufferSize);

    if (!packet.props.getProperty(PacketSizeMax))
        packet.props.append(&maxProp); // That's possible with a stack property as long as the lifetime of the object outlive the packet

Receiving packets from the broker

When receiving a packet, the code never does any copy, so serialization from Properties is done directly from the received buffer.

In that case, you'll be dealing with PropertiesView class and more specifically with its getProperty method:

bool getProperty(VisitorVariant & visitor) const

Typically, you'll create a VisitorVariant instance then call getProperty. This method will fill each instance with the appropriate visitor and type.

It's then up to you to check which property you are interested in, and extract the visited property value like this:

    VisitorVariant visitor;
    while (packet.props.getProperty(visitor))
    {
        switch (visitor.propertyType())
        {
            case PacketSizeMax:
            {
                auto pod = visitor.as< LittleEndianPODVisitor<uint32> >();
                maxPacketSize = pod->getValue();
                break;
            }
   [...]

When you extract the value from the visitor, you have to specify the type you expect for the given property. In eMQTT5, the possible property type are implementing the standard:

MessageReceived interface

MessageReceived interface that must be implemented:

struct MessageReceived
{
    // This is called upon published message reception.
    virtual void messageReceived(const DynamicStringView & topic, 
                                 const DynamicBinDataView & payload, 
                                 const uint16 packetIdentifier, const PropertiesView & properties) = 0;
    // This is usually called upon creation to know what it the maximum packet size you'll support.
    // By default, MQTT allows up to 256MB control packets. 
    // On embedded system, this is very unlikely to be supported. 
    // This implementation does not support streaming so a buffer is created on the heap with this size  
    // upon client construction to store the received control packet. 
    virtual uint32 maxPacketSize() const; // Default to 2048 bytes

    // An authentication packet was received. 
    virtual void authReceived(const ReasonCodes reasonCode, const DynamicStringView & authMethod, const DynamicBinDataView & authData, const PropertiesView & properties) { } // Optionnal: Depends on library configuration
};

MessageReceived::messageReceived

MessageReceived::authReceived

If enabled in the library configuration, and you are using advanced authentication for your client, this will be called while connecting to the broker with some challenge to succeed. You'll then call MQTTv5::auth method to submit your answer.

MQTTv5(...)

Signature

MQTTv5(const char * clientID, 
       MessageReceived * callback, 
       const DynamicBinDataView * brokerCert = 0)

Broker certificate

It's not usually possible to store a complete certificate authority chain in an embedded system. And even if it were possible, updating and maintaining such a library would be quite painful. That's why it's possible to store the expected broker's certificate directly and validate against it only.

Using DER for storing a certificate reduce the flash binary size requirement of your certificate by ~33% (compared to plain X509 textual format).

If you don't have a PEM encoded certificate, use this command to save the broker server's certificate to a .PEM file

$ echo | openssl s_client -servername your.server.com -connect your.server.com:8883 2>/dev/null | openssl x509 > cert.pem

If you have a PEM encoded certificate, use this code to convert it to (33% smaller) DER format

$ openssl x509 -in cert.pem -outform der -out cert.der

connectTo(...)

Signature

ErrorType connectTo(
     // Broker configuration
     const char * serverHost, 
     const uint16 port, 
     bool useTLS = false,

     // Session configuration
     const uint16 keepAliveTimeInSec = 300,                                      
     const bool cleanStart = true,

     // Credentials
     const char * userName = nullptr, 
     const DynamicBinDataView * password = nullptr,

     // Last will message
     WillMessage * willMessage = nullptr, 
     const QoSDelivery willQoS = QoSDelivery::AtMostOne, 
     const bool willRetain = false,

     // Additional properties
     Properties * properties = nullptr);

Authentication

Authentication in MQTT v3.1.1 was mainly either client identifier based or username/password based, a bit like HTTP/1.0 did. In MQTT v5.0, it's now possible to also have multiple step authentication with per-broker/per-client specific protocol. Authentication requires a new control packet type, and, as such, you can use auth method of the client to build this packet.

The usual process with authentication is the following:

1. Client => CONNECT with some authentication properties attached => Server
2. Server => AUTH with some challenge/method/data => Client
3. Client => AUTH with some answer/data => Server
4. Server => CONNACK => Client

For the first step, you'll need to append as many properties as required (see the Properties section below for how to do that) in your first call to connectTo .

When the server answers (in step 2), your callback instance will be called with the authentication method and data already parsed for you.

You'll then use the auth method in step 3 to complete the challenge, the method either returns with a success (step 4) or a failure.

Please notice that none of the above is required for usual client identifier or username / password connection.

If enabled in the libary configuration, you'll be able to prepare AUTH packet to send to the broker in reply to a authentication challenge via the auth method:

auth(...)

Signature

ErrorType auth(const ReasonCodes reasonCode, 
               const DynamicStringView & authMethod, 
               const DynamicBinDataView & authData, 
               Properties * properties = nullptr)

subscribe(...)

Signature

ErrorType subscribe(
    const char * topic, 
    const RetainHandling retainHandling = RetainHandling::GetRetainedMessageForNewSubscriptionOnly, 
    const bool withAutoFeedBack = false, 
    const QoSDelivery maxAcceptedQoS = QoSDelivery::ExactlyOne, 
    const bool retainAsPublished = true, 
    Properties * properties = nullptr)

You can call this method as many times as you have topics to subscribe for, or you can use the other subscribe overload with a chained list of topics to subscribe to. When this method returns successfully, MessageReceived::messageReceived callback will be called upon receiving a message.

unsubscribe(...)

Signature

ErrorType unsubscribe(UnsubscribeTopic & topic, 
    Properties * properties = nullptr)

When this method returns successfully, MessageReceived::messageReceived callback won't be called upon receiving a message on the specified topics. Please notice that's it's required to run the event loop after calling this method to fetch the unsubscribe's result if you are interested in that (which are accessible with getUnsubscribeResult()) method.

It's not necessary to unsubscribe when disconnecting from the broker, so this method is usually non built since a typical application will connect, subscribe then (optionally) publish and disconnect.

publish(...)

Signature

ErrorType publish(
    const char * topic, 
    const uint8 * payload, 
    const uint32 payloadLength, 
    const bool retain = false, 
    const QoSDelivery QoS = QoSDelivery::AtMostOne, 
    const uint16 packetIdentifier = 0, 
    Properties * properties = nullptr)

eventLoop()

Signature

ErrorType eventLoop()

MQTTv5 has no notion of thread or task. It's up to you to call the event loop at regular interval. The underlying implementation usually fallback to either select or epoll or kqueue so it's safe to call this in a loop with no delay whatsoever. The MessageReceived::messageReceived callback will be called in this loop and any Quality Of Service management will be also performed in this loop.

disconnect(...)

Signature

ErrorType disconnect(const ReasonCodes code, Properties * properties = nullptr)

It's not required to disconnect from the broker in MQTT since there are keep alive and session timeouts. Yet, you can tell the broker for your disconnection reason with such method. After calling this method, you'll have to connectTo again to communicate with the broker.

setDefaultTimeout(...)

Signature

void setDefaultTimeout(const uint32 timeoutMs)

By default, when the client isn't configured with LowLatency mode, the eventLoop will block for the some configurable duration, waiting for a packet to be received or some packet to be sent. This is useful to limit the CPU usage since during this wait, the task's timeslice is relinquished for other work on the CPU. However, if you need to perform some other work in the same task as the event loop, this means that you'll see a pauses of the configured timeout between each work.

When built with LowLatency, the eventLoop instantly checks if there is activity on the socket, and if no activity is detected, exits the eventLoop immediately, without blocking. If you have no other work to perform, this will hog the CPU to 100% usage and increase the power consumption of the system. However, if you do have work to perform, and this work throttles itself (for example, by waiting for an interrupt or a timer), this is safe to use.