Documentation pour le client eMQTT5

Utilisation des propriétés avec le client

Comme cette bibliothèque est orientée vers une utilisation embarquée, un grand soin a été apporté pour éviter l'utilisation du tas (heap) et minimiser la taille du code.

Paquet à destination du courtier

Afin d'atteindre ces objectifs, la classe Properties est une liste chaînée où chaque noeud stocke un drapeau indiquant s'il a été alloué sur la pile (par défaut) ou sur le tas.

Lorsque la liste chaînée est détruite, chaque noeud se suicide (se delete s'il était alloué sur le tas) ou enchaîne la demande de destruction au noeud suivant.

L'analyse de la liste chaînée se fait de manière récursive, mais cela ne devrait pas poser de problème puisque le nombre de propriétés possibles pour chaque paquet est faible.

L'ajout de propriétés se fait de cette manière :

    Property<uint32> maxProp(PacketSizeMax, recvBufferSize) ;

    if (!packet.props.getProperty(PacketSizeMax))
        packet.props.append(&maxProp) ; // C'est possible avec une propriété sur la pile tant que la durée de vie de l'objet dépasse celle du paquet

Réception des paquets du courtier

Lors de la réception d'un paquet, le code ne fait jamais de copie, donc la sérialisation à partir des propriétés se fait directement à partir du tampon reçu.

Dans ce cas, vous aurez affaire à la classe PropertiesView et plus particulièrement à sa méthode getProperty :

bool getProperty(VisitorVariant & visitor, PropertyType & type, uint32 & offset) const

En général, vous créez une instance de type VisitorVariant, une instance de type PropertyType et un offset (utilisé en lors de la visite pour se positionner sur la prochaine propriété), puis vous appelez getProperty. Cette méthode permet de remplir chaque instance avec le visiteur et le type appropriés. L'offset est augmenté jusqu'à la position suivante de la propriété dans le tampon observé (reçu).

C'est ensuite à vous de vérifier quelle propriété vous intéresse, et d'extraire la valeur de la propriété visitée comme ceci :

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

Interface MessageReceived

L'interface "MessageReceived" qui doit être surchargée :

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

Si cette fonction est activée dans la configuration de la bibliothèque et que vous utilisez une authentification avancée pour votre client, elle sera appelée lors de la connexion au courtier, avec un challenge à relever. Vous appellerez alors la méthode MQTTv5::auth pour soumettre votre réponse.

MQTTv5(...)

Signature

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

Certificat de courtier

Il n'est généralement pas possible de stocker une chaîne complète d'autorités de certification dans un système intégré. Et même si cela était possible, la mise à jour et la maintenance d'une telle bibliothèque seraient assez pénibles. C'est pourquoi le client propose de stocker directement le certificat du courtier attendu et de ne le valider que par rapport à celui-ci.

L'utilisation de DER pour stocker un certificat réduit la taille binaire flash requise de votre certificat d'environ 33 % (par rapport au format textuel X509 ordinaire).

Si vous n'avez pas de certificat codé PEM, utilisez cette commande pour enregistrer le certificat du serveur de courtage dans un fichier .PEM

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

Si vous avez un certificat codé PEM, utilisez ce code pour le convertir au format DER (33% plus petit)

$ 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);

Authentification

L'authentification dans MQTT v3.1.1 était principalement basée soit sur l'identifiant du client, soit sur le nom d'utilisateur/mot de passe, un peu comme le faisait HTTP/1.0. Dans MQTT v5.0, il est maintenant possible d'avoir une authentification à plusieurs étapes avec un protocole spécifique par courtier/par client. L'authentification nécessite un nouveau type de paquet de contrôle, et, à ce titre, vous pouvez utiliser la méthode d'authentification du client pour construire ce paquet.

Le processus habituel d'authentification est le suivant :

1. Client => CONNECT avec quelques propriétés d'authentification attachées => Serveur
2. Serveur => AUTH avec quelques défis/méthodes/données => Client
3. Client => AUTH avec quelques réponses/données => Serveur
4. Serveur => CONNACK => Client

Pour la première étape, vous devrez ajouter autant de propriétés que nécessaire (voir la section Propriétés ci-dessous pour savoir comment faire) lors de votre premier appel à connectTo .

Lorsque le serveur répondra (à l'étape 2), votre instance de rappel sera appelée avec la méthode d'authentification et les données déjà analysées pour vous.

Vous utiliserez ensuite la méthode d'authentification à l'étape 3 pour terminer le défi, la méthode revient avec un succès (étape 4) ou un échec.

Veuillez noter qu'aucun des éléments ci-dessus n'est requis pour l'identification du client habituel ou la connexion par nom d'utilisateur / mot de passe.

Si cette option est activée dans la configuration de la bibliothèque, vous pourrez préparer le paquet AUTH à envoyer au courtier en réponse à un défi d'authentification via la méthode auth :

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)

Vous pouvez appeler cette méthode autant de fois que vous avez de sujets à abonner, ou vous pouvez utiliser l'autre overload subscribe avec une liste chaînée de sujets à s'abonner. Après l'appel de cette méthode, MessageReceived::messageReceived callback sera appelé à la réception d'un message.

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 n'a aucune notion de fil ou de tâche. C'est à vous d'appeler la boucle d'événement à intervalles réguliers. L'implémentation sous-jacente se rabat généralement sur les fonctions "select", "epoll" ou "kqueue", de sorte qu'il est possible de l'appeler en boucle sans aucun délai. Le callback MessageReceived::messageReceived sera appelé dans cette boucle et toute gestion de la qualité de service sera également effectuée dans cette boucle.

disconnect(...)

Signature

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

Il n'est pas nécessaire de se déconnecter du courtier dans le protocole MQTT puisqu'il y a des timeouts. Cependant, vous pouvez indiquer au courtier le motif de votre déconnexion grâce à cette méthode. Après avoir appelé cette méthode, vous devrez appeler connectTo à nouveau pour communiquer avec le courtier.

setDefaultTimeout(...)

Signature

void setDefaultTimeout(const uint32 timeoutMs)

Par défaut, lorsque le client n'est pas configuré en mode LowLatency, l'eventLoop se bloque pendant une durée configurable, en attendant qu'un paquet soit reçu ou qu'un autre soit envoyé. Ceci est utile pour limiter l'utilisation du CPU puisque pendant cette attente, le timeslice de la tâche est abandonnée pour d'autres travaux sur le CPU. Cependant, si vous avez besoin d'effectuer d'autres travaux dans la même tâche que la boucle d'événement, cela signifie que vous verrez une pause de la durée configurée entre chaque travail.

Lorsque le client est configuré avec LowLatency, l'eventLoop vérifie instantanément s'il y a de l'activité sur la socket, et si aucune activité n'est détectée, elle quitte l'eventLoop immédiatement, sans bloquer. Si vous n'avez pas d'autre travail à effectuer, cela accaparera le CPU à 100% et augmentera la consommation d'énergie du système. Cependant, si vous avez du travail à effectuer, et que ce travail s'auto-bloque (par exemple, en attendant une interruption ou un timer), vous pouvez l'utiliser en toute sécurité.