Configurer le connecteur User-MQTT

User MQTT permet une connexion fiable et à long terme entre la plateforme Centiloc et votre système de données.

Il utilise l’authentification mutuelle X509 et nécessite également un nom d’utilisateur et un mot de passe spécifiques pour se connecter.

Votre TenantID

L’adresse e-mail de l’équipe de support : support@centiloc.com

Obtenez plus de détails et de paramètres dans la section détaillée

1. Générez vos secrets X509

Afin de sécuriser et d’authentifier votre connexion, votre client MQTT doit fournir un certificat X509 autorisé par Centiloc. Pour ce faire, vous devrez générer une paire de clés et une demande de signature de certificat avec certains paramètres obligatoires.

Vous trouverez ci-dessous une séquence sur la façon de procéder, en utilisant openssl, dans un terminal.

La connexion MQTT est autorisée tant que votre abonnement est actif.

Le certificat est valable 1 an. N’oubliez donc pas de le renouveler avant son expiration.

1.1. Générez votre paire de clés

openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem

Seules les courbes elliptiques sont acceptées avec une taille d’au moins 256 bits.

🔖 Ce fichier private-key.pem est utilisé dans votre connexion au broker User-MQTT. Conservez-le en toute sécurité.

1.2. Générez une demande de signature de certificat

openssl req -new -key private-key.pem -out certificate-request.csr>

Certaines questions vous seront posées. Peu de champs sont obligatoires :

Organization Name : Le nom de votre entreprise, même en cas de délégation d’accès aux données.
Common Name : tenantID, qui dépend du topic auquel vous prévoyez de vous abonner.
Email Address : où envoyer des informations sur le cycle de vie de votre certificat (annonce d’expiration…).

Exemple de questions répondues

Country Name (2 letter code) []:FR
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:Centiloc
Organizational Unit Name (eg, section) []:
Common Name (eg, fully qualified host name) []:centiloc
Email Address []:myaddress@example.com 

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:

1.3. Demandez la signature du certificat

Envoyez le fichier certificate-request.csr à l’équipe de support Centiloc.

L’équipe de support répondra dans un délai d’un jour ouvrable, en vous fournissant votre 🔖 certificat final requis pour la connexion MQTT.

2. Obtenez le certificat de confiance

Afin de vérifier l’identité du broker MQTT, veuillez utiliser le certificat ci-dessous :

Centiloc Public CA Certificate

3. Obtenez vos informations d’identification

L’équipe de support répondra à votre demande ci-dessus avec un certificat valide.

De plus, vous recevrez un nom d’utilisateur et un mot de passe dédiés à cette seule connexion User-MQTT.

À ce stade, vous devez avoir :

🔖 le fichier private-key.pem que vous avez généré
🔖 le fichier tls-cert.pem fourni par Centiloc
le nom d’utilisateur et le mot de passe fournis par Centiloc
Votre tenantID. Il sera utilisé pour préfixer votre MQTT clientID.
ca-cert.pem collecté au point 2

4. Connectez-vous à User-MQTT

Vous trouverez ci-dessous un exemple de connexion à User-MQTT en python :

## Nous utilisons le package paho bien connu
import paho.mqtt.client as mqtt

mqtt_client = mqtt.Client(
    client_id=tenantID+"anything",
    clean_session=True,
    protocol=mqtt.MQTTv311,
    transport="tcp")

ca_filepath=some_path + "ca-cert.pem"
tlscert_filepath=some_path + "tls-cert.pem"
privkey_filepath=some_path + "private-key.pem"

mqtt_client.tls_set(
        ca_filepath,
        certfile=tlscert_filepath,
        keyfile=privkey_filepath,
        tls_version=ssl.PROTOCOL_TLSv1_2)

mqtt_client.username_pw_set("username", "password")

try:
    ret = mqtt_client.connect("mqtt-client.centiloc.com", 8883, keepalive=60)
    if ret != mqtt.MQTT_ERR_SUCCESS:
        raise Exception('Failed to connect to broker.')
except Exception as e:
        raise Exception('Cannot connect to broker.')

5. Abonnez-vous à votre topic

Vous pouvez maintenant vous abonner à centiloc/<tenantID>.

mqtt_client.subscribe(f"centiloc/{tenantID}", qos=1) # pour les messages protobuf sur l'événement de mouvement
mqtt_client.subscribe(f"centiloc/{tenantID}/json/item/v1/update", qos=1) # pour les messages json sur l'événement de mouvement
mqtt_client.subscribe(f"centiloc/{tenantID}/proto/board/v1/update", qos=1) # pour les messages proto sur le changement d'état du plateau
mqtt_client.subscribe(f"centiloc/{tenantID}/json/board/v1/update", qos=1) # pour les messages json sur le changement d'état du plateau

QoS=1 est un bon compromis entre qualité et performance. Nous le conseillons.

La technologie de sérialisation par défaut utilisée était protobuf, pour l’homogénéité avec les autres API et pour promouvoir l’adoption de cette technologie, petite et performante.

Mais le mqtt-client ouvre la voie à la technologie no-code pour exploiter les données Centiloc. Ces technologies ne supportent pas toutes les technologies trop récentes. C’est pourquoi nous ouvrons une voie vers les technologies de compatibilité avec la messagerie JSON.

Nous vous encourageons toujours à utiliser protobuf qui reste notre techno leader. Choisissez votre technologie, mais il n’est pas nécessaire de consommer les deux messages car ils sont des doublons directs.

La convention de topic protobuf diffère du topic json en raison de l’implémentation héritée. D’autres changements dans protobuf peuvent introduire une mise à niveau sémantique des topics.

6. Décodez les messages

Les événements collectés auprès des plateaux et qualifiés par la plateforme de données sont ensuite publiés sur votre topic.

Vous pouvez les décoder en désérialisant la section API.