clearRequestHeaders()
Supprime tous les en-têtes HTTP ajoutés précédemment.
addRequestHeader(key:byte[], value:byte[])
Ajoute un en-tête HTTP aux requêtes suivantes.
Par exemple,:
addRequestHeader("Content-Type", "application/json")
addRequestHeader("Longueur du contenu", strLen(body))
addRequestHeader("Autorisation", "Bearer " + apiKey)
getMQTTData()->byte[1024]
Dès que la fonction hasMQTTMessage() a constaté qu’un message MQTT a été reçu, cette fonction permet de lire les données reçues.
if hasMQTTMessage():
data = getMQTTData()
Limitations: - Un maximum de 1024 octets peut être lu. Les données plus longues sont ajoutées à un nouveau message sans topic.
getMQTTTopic()->byte[48]
Dès que la fonction hasMQTTMessage() a constaté qu’un message MQTT a été reçu, cette fonction permet de lire le topic reçu.
if hasMQTTMessage():
topic = getMQTTTopic()
hasMQTTMessage()->bool
Renvoie true si un message MQTT a été reçu.
Les données reçues peuvent ensuite être lues avec les fonctions suivantes:
getMQTTTopic()
getMQTTData()
unsubscribeMQTT(topic:byte[])->int
Pour cette fonction, la carte doit être connectée à Internet et à un courtier MQTT.
Déconnecte le topic précédemment abonné.
La fonction renvoie un msgId en cas de succès ou -1 en cas d’erreur.
subscribeMQTT(topic:byte[])->int
Pour cette fonction, la carte doit être connectée à Internet et à un courtier MQTT.
S’abonner au topic défini afin de pouvoir recevoir les messages publiés.
La fonction renvoie un msgId en cas de succès ou -1 en cas d’erreur.
Les messages reçus peuvent ensuite être lus à l’aide des fonctions suivantes:
hasMQTTMessage()
getMQTTTopic()
getMQTTData()
exemple:
uri = "mqtt://broker.hivemq.com"
username = ""
mot de passe = ""
if connectMQTT(uri, username, password):
subscribeMQTT("myTopic")
def onDraw():
if hasMQTTMessage():
print(getMQTTTopic())
print(getMQTTData())
delay(100)
publishMQTT(topic:byte[], data:byte[])->int
Pour cette fonction, la carte doit être connectée à Internet et à un courtier MQTT.
Publie un message (data) sous le topic défini.
La fonction renvoie un msgId en cas de succès, 0 si QoS = 0 ou -1 en cas d’erreur.
Exemple de fonction:
uri = "mqtt://broker.hivemq.com"
username = ""
mot de passe = ""
if connectMQTT(uri, username, password):
publishMQTT("myTopic", "myData")
disconnectMQTT()
Pour cette fonction, la carte doit être connectée à Internet et à un courtier MQTT.
Déconnecte d’un courtier MQTT.
connectMQTT(uri:byte[], username:byte[], password:byte[])->bool
Pour cette fonction, la carte doit être connectée à Internet.
Connecte l’Oxocard à un courtier MQTT. La fonction renvoie true si la connexion a réussi.
Le nom d’utilisateur et le mot de passe peuvent être vides si aucune authentification n’est requise.
Exemple:
# Courtier MQTT public (non sécurisé): https://www.mqtt-dashboard.com/
uri = "mqtt://broker.hivemq.com"
username = ""
mot de passe = ""
# # Personal MQTT broker (secure): https://console.hivemq.cloud
# uri = "mqtts://abc.s2.eu.hivemq.cloud:8883"
# username = "monNomUtilisateur"
# mot de passe = "myPassword123"
subscribeTopic = "myTopic"
publishTopic = "myTopic"
publishData = "chaîne de données myData"
title = "MQTT MSG"
drawText(120-textWidth(title)/2, 5, title)
update()
if connectMQTT(uri, nom d'utilisateur, mot de passe):
subscribeMQTT(subscribeTopic)
else:
drawText(10, 55, "connect failed !")
update()
def onDraw():
if hasMQTTMessage():
clear()
textFont(FONT_ROBOTO_32)
drawText(120-textWidth(title)/2, 5, title)
topic = getMQTTTopic()
textFont(FONT_ROBOTO_32)
drawText(10, 55, "topic:")
textFont(FONT_ROBOTO_24)
drawText(20, 95, topic)
data = getMQTTData()
textFont(FONT_ROBOTO_32)
drawText(10, 150, "data:")
textFont(FONT_ROBOTO_24)
drawText(20, 190, données)
update()
buttonByte = getButton()
if buttonByte > 0:
publishMQTT(publishTopic, publishData)
if buttonByte == 4:
if returnToMenu():
return
while getButton(): delay(10)
delay(100)
Notez: Le protocole doit être défini au début de l’URI: “mqtt://…” ou “mqtts://…”. Si nécessaire, un port peut être ajouté à l’hôte (“…:8883”).
selectCertificate(path:byte[])
Cette fonction permet de sélectionner un certificat personnel (.pem) dans le système de fichiers de l’Oxocard.
Ceci n’est nécessaire que si le certificat n’a pas pu être demandé automatiquement et déposé dans le dossier “certs” de l’Oxocard.
Exemple:
selectCertificate("certs/nanopy-io.pem")
Attention ! Le propre certificat (.pem) doit être déposé au préalable dans le système de fichiers de l’Oxocard, par exemple via File Browser.
MQTT est l’abréviation de “Message Queuing Telemetry Transport”. Le protocole se compose de règles qui définissent la manière dont les appareils IoT peuvent publier et s’abonner à des données via Internet. Le protocole relie les appareils à l’aide du modèle (Pub/Sub). L’émetteur (publisher) et le récepteur (subscriber) communiquent via des “topics” et sont découplés l’un de l’autre. La connexion entre eux est gérée par un serveur MQTT (“broker”).
Dans l’exemple ci-dessous, l’Oxocard souscrit et publie sur le même topic et peut ainsi recevoir ses propres messages (via le broker MQTT).
Le serveur public gratuit de HiveMQ est utilisé comme broker.
Exemple de fonctionnement:
# Courtier MQTT public (non sécurisé): https://www.mqtt-dashboard.com/
uri = "mqtt://broker.hivemq.com"
username = ""
mot de passe = ""
subscribeTopic = "myTopic"
publishTopic = "myTopic"
publishData = "chaîne de données myData".
title = "MQTT MSG"
drawText(120-textWidth(title)/2, 5, title)
update()
if connectMQTT(uri, nom d'utilisateur, mot de passe):
subscribeMQTT(subscribeTopic)
else:
drawText(10, 55, "connect failed !")
update()
def onDraw():
if hasMQTTMessage():
clear()
textFont(FONT_ROBOTO_32)
drawText(120-textWidth(title)/2, 5, title)
topic = getMQTTTopic()
textFont(FONT_ROBOTO_32)
drawText(10, 55, "topic:")
textFont(FONT_ROBOTO_24)
drawText(20, 95, topic)
data = getMQTTData()
textFont(FONT_ROBOTO_32)
drawText(10, 150, "data:")
textFont(FONT_ROBOTO_24)
drawText(20, 190, données)
update()
buttonByte = getButton()
if buttonByte > 0:
publishMQTT(publishTopic, publishData)
if buttonByte == 4:
if returnToMenu():
return
while getButton(): delay(10)
delay(100)
Le protocole de transfert hypertexte (HTTP) a été développé pour permettre la communication entre les clients et les serveurs.
HTTP Secure (HTTPS) est la version sécurisée du protocole HTTP.
Oxocard prend en charge les deux méthodes HTTP les plus fréquemment utilisées: GET et POST.
Exemple de GET:
# Request and display IP
url = "http://httpbin.org/ip"
if (getRequest(url)):
origin = readRequestJSON("origin")
drawText(10, 10, origin)
else:
drawText(10, 10, "error")
update()
Exemple de POST:
# Post simple JSON
url = "https://httpbin.org/post"
body = "{\"field1\":\"value1\" }"
print("sending POST request...")
if (postRequest(url, body)):
print("ok")
else:
print("erreur")
Si l’Oxocard est connectée à Internet, elle peut communiquer avec le monde à l’aide des fonctions de réseau.
Pour le moment, elle supporte les requêtes simples HTTP/HTTPS et MQTT/MQTTS.
Le certificat de serveur nécessaire pour les protocoles sécurisés (https & mqtts) est d’abord vérifié dans le CA store interne, puis recherché dans le système de fichiers de l’Oxocard dans le dossier “certs”. S’il n’est pas disponible, il est demandé au serveur cible via notre serveur (openssl). Il est également possible d’ajouter soi-même un certificat et d’y faire référence avec la fonction selectCertificate().
postRequest(url:byte[], body:byte[])->bool
Pour cette fonction, la carte doit être connectée à Internet.
Envoie une requête POST à l’URL définie.
La fonction renvoie true si la requête a réussi (200 OK).
Les éventuelles réponses du serveur peuvent ensuite être lues à l’aide des fonctions suivantes:
readRequestLength()
readRequest(offset)
readRequestJSON(jsonPath)
exemple:
# Toggle Shelly relay
url = "http://192.168.42.146/relay/0"
body = "turn=toggle"
def onDraw():
if getButton():
postRequest(url, body)
while(getButton()): delay(50)
delay(50)
readRequestJSON(jsonPath:byte[])->byte[128]
Renvoie le contenu d’une réponse JSON sous forme de texte (max. 128 octets) de la requête préalablement demandée avec getRequest().
La clé à lire peut être définie avec jsonPath.
Les objets JSON imbriqués peuvent également être sélectionnés avec ‘.’ ou ‘/’.
Exemple1:
url = "http://api.nanopy.io/v1/utc"
getRequest(url) # {"utc":1667912328}
drawText(10, 10, readRequestJSON("utc"))
update()
Exemple2:
# {
# "myObj": {
# "mySubObj": {
# "myArray": [
# {"myKey":111},
# {"myKey":222},
# {"myKey":333}
# ],
# }
# }
# }
readRequestJSON("myObj.mySubObj.myArray.0.myKey") # "111"
readRequestJSON("myObj/mySubObj/myArray/2/myKey") # "333"
Remarque:
readRequestJSON() renvoie toujours une chaîne de caractères (byte[]).
Avec les fonctions stringTo…(), le résultat peut ensuite être converti dans le type de données approprié.
readRequest(offset:int)->byte[128]
Renvoie le texte (max. 128 octets) de la requête précédemment demandée avec getRequest().
Avec offset, on peut définir la position de départ, qui détermine à partir de quel point la réponse doit être lue.
Cela permet de lire des réponses plus longues en plusieurs étapes.
Exemple:
url = "http://api.nanopy.io/v1/hello_world"
getRequest(url)
drawText(10, 10, readRequest(0))
drawText(10, 50, readRequest(6))
update()
Remarque:
Si un serveur personnel est utilisé et que l’on souhaite renvoyer du texte brut, il est impératif de définir également la ‘longueur du contenu’ dans l’en-tête.
readRequestLength()->int
Renvoie la longueur (en octets) de la requête précédemment demandée avec getRequest().
getRequest(url:byte[])->bool
Pour cette fonction, la carte doit être connectée à Internet.
Envoie une requête GET à l’URL définie.
La fonction renvoie true si la requête a abouti (200 OK).
Les données demandées peuvent ensuite être lues à l’aide des fonctions suivantes:
readRequestLength()
readRequest(offset)
readRequestJSON(jsonPath)
Exemple:
url = "http://api.nanopy.io/v1/utc"
if (getRequest(url)):
utc = readRequestJSON("utc")
drawText(10, 10, stringToInt(utc))
else:
drawText(10, 10, "error")
update()
Limitations: - Un maximum de 32k octets peut être demandé. Les réponses plus longues sont coupées