Introduction

LoRaWAN est un réseau radio longue portée pouvant atteindre plusieurs kilomètres en extérieur.

Les objets LoRa MaDomotic fonctionnent sur des réseaux privés ou opérés tels que « The Things Network », « Objenious », etc …

Les trames LoRa sont des octets représentant des commandes et arguments, ou états et valeurs.

Lors de l’envoi et de la réception de ces octets, ils sont convertis ou doivent être convertis sous forme de chaines hexadécimale.

La longueur d’une trame est dépendante de la qualité du signal radio LoRa, de 26 à 80 octets, voire plus si la qualité du signal est excellente.

Tous les objets LoRa MaDomotic identifient leurs trames par 2 octets bien précis et commencent toujours par 0x00 0x07 en hexadécimal, soit la chaine de caractères « 0007 ».

Une trame LoRa pour envoyer un ordre du backend vers l’objet se nomme DOWNLINK, et de l’objet vers le backend se nomme UPLINK.

Les commandes DOWNLINK sont des actions sur le LAM et sont classées de façon mnémotechnique en fonction du nombre d’octets en paramètres.
Exemples :

• Les commandes sans argument iront de 0x00 à 0x0F
• Les commandes avec 1 octet en argument iront de 0x10 à 0x1F
• Les commandes avec 2 octets en argument iront de 0x20 à 0x2F
• Etc …

Les commandes UPLINK spécifiques au LAM vont de 0xE0 à 0xEF.

D’autres commandes génériques à tous les objets LoRa MaDomotic dites de « service / système / configuration » vont de 0xF0 à 0xFF et sont aussi bien pour des DOWNLINK que UPLINK.

Caractéristiques LoRa du LAM

Carte HelTec AutoMation, Wireless Stick Lite (Panda Board).
868 MHz Europe, toutes fréquences ou partie.
Classe C, communications bidirectionnelles non programmées (le LAM est alimenté en permanence en 5 Volts 1.2 Ampères minimum).
OTAA, Over The Air.
ADR, Adaptative Data Rate paramétrable, full, bi canal ou mono canal.
Trames non confirmées par le protocole LoRaWAN, toutefois chaque Downlink est confirmé à l’identique par un Uplink.
Le Port 1 est utilisé pour les Downlink et Uplink.

Le DevEUI et AppEUI figurent sur l’étiquette au dos du dispositif ainsi que dans l’interface HTML.
L’AppKey se trouve dans l’interface HTML.
Le DevEUI est unique à chaque dispositif.
L’AppEUI et l’AppKey sont valables pour tous les dispositifs de la même famille d’objets.

Configuration des paramètres LoRa

« Channel frequency 1 et 2 », « All / None » par défaut active toutes les bandes d’émission et de réception Europe.
Si le dispositif doit envoyer des trames via une Gateway LoRa bi canal ou mono canal, vous devez sélectionner les fréquences concernées de 867.1 à 868.5 MHz par canal.
« Serial Number » et « License » sont des informations pour l’utilisation interne à LoRa.
« DevEUI », « AppEUI » et « AppKey » sont les clés LoRa à paramétrer sur le backend LoRa.
« Duty Cycle » correspond à la trame de vie cyclique en minutes.
« JOIN counter » nombre de tentative de JOIN avec le backend, une tentative toutes les 30 secondes environ.
Pour le dernier downlink reçu, valeur de RSII, SNR et Data Rate.

Signification du Data Rate :

Synoptique des commandes LoRa du LAM

La longueur d’une trame n’est pas figée et les commandes sont cumulatives.
Il est donc tout à fait possible en une trame d’envoyer plusieurs commandes, si la qualité du signal radio le permet, mais il est conseillé de respecter l’ordre suivant dans les commandes (*) :

(*) Chaque commande est suivie du nombre d’octets entre parenthèses.

Pour clarifier les exemples qui suivent, les commandes sont séparées par des espaces.
Pour un bon fonctionnement, les espaces doivent être supprimés.

Commandes Downlink sans paramètre

OFF = 0x00
Eteint les leds, arrête définitivement l’animation en cours et supprime les couleurs fixées.
Exemple : « 0007 00 », envoie la commande OFF.

ON = 0x01
Allume les leds en fixe avec la dernière couleur et dernière luminosité.
Exemple : « 0007 01 », envoie la commande ON.

STOP = 0x02
Arrête l’animation en cours et éteint les leds.
Exemple : « 0007 02 », envoie la commande STOP.

PAUSE = 0x03
Suspend l’animation en cours sans éteindre les leds.
Exemple : « 0007 03 », envoie la commande PAUSE.

RESTART = 0x04
Reprend l’animation qui était en PAUSE ou en STOP.
Exemple : « 0007 04 », envoie la commande RESTART.

WHEEL = 0x05
Animation roue (même couleur sur toutes les leds).
Exemple : « 000 705 », envoie la commande WHEEL.

STROBE = 0x06
Animation flash (même couleur sur toutes les leds).
Exemple : « 0007 06 », envoie la commande STROBE.

FADE = 0x07
Animation progressive fondue in/out (même couleur sur toutes les leds).
Exemple : « 0007 07 », envoie la commande FADE.

FADEIN = 0x08
Allumage progressif puis les leds restent ON.
Exemple : « 0007 08 », envoie la commande FADEIN.

FADEOUT = 0x09
Extinction dégressive puis les leds passent à STOP.
Exemple : « 0007 09 », envoie la commande FADEOUT.

RANDOM = 0x0A
Animation aléatoire des couleurs (la commande COLOR sera ignorée).
Exemple : « 0007 0A », envoie la commande RANDOM.

ROUNDTRIP = 0x0B
Autre animation roue (même couleur sur toutes les leds).
Exemple : « 0007 0B », envoie la commande ROUNDTRIP.

Commandes Downlink suivies d’1 octet

BRIGHT = 0x10
Luminosité pour toutes les leds suivie de 0x00 à 0xFF (défaut 0x1F).
Exemple : « 0007 01 10FF », envoie la commande ON suivi de la commande BRIGHT au maximum.

FIRST_LED = 0x12
Première led pour la translation, de 0 à nombre de leds-1 (0x00 à 0xFF).
Exemple : « 0007 1203 », envoie la commande pour définir la première led logique, donc la led physique 3 devient la led logique 0, vous pouvez ainsi orienter le voyant comme bon vous semble.

LED = 0x13
Pour identifier une led précise suivi du son numéro de 0x00 à nombre de leds-1 ou 0xFF pour toutes les leds.
Nota 1 : cette commande n’est valable que ON, OFF, FADEIN et FADEOUT.
Nota 2 : pour spécifier une couleur précise, la commande COLOR doit précéder celle-ci.
Exemple : « 0007 01 30FF0000 1305 », envoie la commande ON avec la couleur rouge sur la led 5.

Commandes Downlink suivies de 2 octets

SPEED = 0x20
Vitesse de l’animation sur toutes les leds en 100^ième de seconde, 0x0000 à 0xFFFF (de 0 à 655cs, défaut 5cs)
Nota 1 : cas particulier de la commande FADE, la valeur est exprimée en ms (de 0 à 6550ms, défaut 3ms).
Nota 2 : cette commande est ignorée avec les animations FADEIN et FADEOUT.
Exemples :
« 0007 06 200005 », envoie l’animation STROBE à une vitesse de 5cs.
« 0007 07 200003 », envoie l’animation FADE à une vitesse de 3ms.

DELAY = 0x21
Durée de l’animation en seconde, 0x0000 à 0xFFFF (de 0 à 65535s, défaut 0 permanent).
Nota 1 : passé cette durée, la commande STOP est automatiquement exécutée.
Nota 2 : avec la commande de l’animation FADEIN, les leds resteront fixes pendant cette durée, puis exécution de la commande FADEOUT.
Exemples :
« 0007 01 210010 », fait un ON pendant 10 secondes puis un STOP.
« 0007 08 210010 », fait un FADEIN, ON pendant 10 secondes, puis un FADEOUT.

LEDS = 0x23
Pour borner une série de leds précises suivie leurs numéros de 0x00 à nombre de leds-1.
Nota 1 : cette commande n’est valable que ON, OFF, FADEIN et FADEOUT.
Nota 2 : pour spécifier une couleur précise, la commande COLOR doit précéder celle-ci.
Exemple : « 0007 01 3000FF00 230104 », envoie la commande ON avec la couleur verte sur les leds de 1 à 4.

Commande Downlink suivie de 3 octets

COLOR = 0x30
Couleur composée de 3 octets RVB 0x00 à 0xFF chacun.
Exemples :
« 0007 01 30FF0000 », envoie un ON en rouge sur toutes les leds.
« 0007 05 3000FF00 », envoie l’animation WHEEL en vert sur toutes les leds.
« 0007 06 300000FF », envoie l’animation STROBE en bleu sur toutes les leds.
« 0007 01 30FF0000 1105 », envoie la commande ON avec la couleur rouge sur la led 5.

Commande Uplink spécifique à l’option Switch du LAM

SWITCH = 0xE
Commande envoyée lors d’une ou plusieurs pressions sur l’interrupteur tactile, suivi de l’état du bouton sur 1 octet, longueur totale de la trame 4 octets.
Exemples :
« 0007 0E0A » pour un appui long.
« 0007 0E0B » pour une pression brève.
« 0007 0E0C » pour 2 pressions brèves.
« 0007 0E0D » pour 3 pressions brèves.
« 0007 0E0E » pour 4 pressions brèves.

Commandes Downlink / Uplink dites de service / système / configuration

TEST = 0xF1 (Downlink)
Envoie une animation de tests des leds pour chaque couleur primaire et en blanc pendant 20 secondes.
Exemple : « 0007 F1 »

REBOOT = 0xFD (Downlink)
Envoie une commande de REBOOT au dispositif, il a lieu 30 secondes après réception de la commande.
Exemple : « 0007 FD »

DUTY_CYCLE = 0xFE (Downlink)
Pour définir la périodicité de réception du message de vie suivi de 2 octets, de 1 à 65535 minutes, soit environ 45 jours maximum.
Exemples :
« 0007 FE000A », pour recevoir un message de vie toutes les 10mn.
« 0007 FE00B4 », pour un message de vie toutes les 3 heures.
« 0007 FE05A0 », pour un message de vie toutes les 24 heures.

HEARTBEAT = 0xFF (Uplink – message de vie cyclique fonction du DUTY_CYCLE)
Commande de réception du message de vie sur 18 octets.
Exemple : « 0007 FF aaaa bbbbbbbb cc rrggbb dd eeee ffff »
commence toujours par « 0007 »,
FF est la trame de vie,
aaaa = DUTY_CYCLE sur 2 octets,
bbbbbbbb = temps écoulé (uptime) depuis le dernier démarrage du dispositif au format timestamp sur 4 octets,
cc = dernière commande/animation sur les leds, 1 octet,
rrggbb = COLOR, dernière couleur active, 1 octet par couleur primaire,
dd = BRIGHT, dernier niveau de luminosité, 1 octet,
eeee = SPEED, dernière vitesse d’animation, 2 octets,
ffff = DELAY, dernier délai d’animation, 2 octets.