Aller au contenu

Kit de démarrage

De Wiki Alseno

Kit de démarrage

Cinq exemples de code pour se lancer. Ils sont neufs, courts, génériques et commentés en français : ils s'inspirent de ce qui a marché pour nous (et des pièges évités), mais n'en sont pas des copies. Chaque valeur à remplacer est notée entre chevrons : <DEV_EUI>, <APP_KEY>, <URL_API>, <CLE_A_CHOISIR>.

Licence proposée pour ces exemples : MIT (utilisation, copie et modification libres, sans garantie) — en attente de confirmation par Alseno Tech.

Vérification. Le croquis Arduino a été compilé avec arduino-cli pour une carte ATmega328P 3,3 V / 8 MHz avec la bibliothèque MCCI LMIC 6.1.0 (région EU868) : environ 76 % de flash et 77 % de mémoire vive. Les scripts Python ont été vérifiés par python -m py_compile puis exécutés sur des données fictives ; le récepteur de webhook a été testé avec un message TTN fictif (authentification, enregistrement, doublon). Le formateur JavaScript a été vérifié par node --check et exécuté sur des trames fictives. Aucun de ces essais n'a utilisé de vrai appareil : à vous de tester sur le vôtre.

Exemple Rôle Langage
a le capteur : mesure et envoi OTAA Arduino (C++)
b décode la trame dans TTN JavaScript
c reçoit les mesures et les stocke Python + SQLite
d convertit la valeur brute en pourcentage Python
e dit s'il faut arroser Python

Les cinq exemples forment une chaîne : (a) émet une trame de 7 octets sur le port 10, (b) la décode dans TTN, (c) la reçoit et la range en base, (d) donne le pourcentage, (e) en tire un conseil. Voir Chaîne de données.

a. Capteur de sol LoRaWAN (Arduino)

Mesure toutes les 10 minutes, envoie 7 octets. Utilise la bibliothèque « MCCI LoRaWAN LMIC library » (pas l'ancienne). À régler avant de compiler : région EU868, clés, broches (voir Capteur de sol).

/*
 * Capteur d'humidité du sol LoRaWAN — exemple de démarrage (Alseno Tech, licence MIT).
 *
 * Carte visée : ATmega328P 3,3 V / 8 MHz + module RFM95 (SX1276) en 868 MHz.
 * Bibliothèque : « MCCI LoRaWAN LMIC library » (PAS l'ancienne IBM LMIC).
 * Région       : EU868 (Sénégal, Europe, Afrique de l'Ouest).
 *
 * PIÈGE : la bibliothèque MCCI est livrée réglée sur la région US915. Éditez
 *   <bibliothèques Arduino>/MCCI_LoRaWAN_LMIC_library/project_config/lmic_project_config.h :
 *   activez « #define CFG_eu868 1 » et désactivez « CFG_us915 ». Sinon le capteur émet sur
 *   des fréquences illégales ici, et aucune passerelle EU868 ne l'entend.
 * Compilation (testée) : carte « Arduino Pro ou Pro Mini, ATmega328P 3,3 V 8 MHz », avec
 *   -DDISABLE_PING -DDISABLE_BEACONS pour que le croquis tienne dans les 32 Ko (≈ 76 % utilisés).
 *
 * Principe : toutes les INTERVALLE_S secondes on alimente la sonde, on lit
 * la valeur brute (ADC), on mesure la tension d'alimentation, puis on envoie
 * 7 octets sur le port 10. Le formateur TTN du wiki décode ce format.
 *
 * Format de la trame (7 octets) :
 *   octet 0     : 0xA1  (identifiant de format, permet au décodeur de reconnaître la trame)
 *   octets 1-2  : valeur brute de la sonde, entier non signé, poids fort d'abord
 *   octets 3-4  : température en centièmes de °C, entier signé (0x8000 = absente)
 *   octets 5-6  : tension d'alimentation en millivolts, poids fort d'abord
 */
#include <lmic.h>
#include <hal/hal.h>
#include <SPI.h>

// ---------------------------------------------------------------------------
// 1) CLÉS — À REMPLACER par celles de VOTRE appareil (console TTN).
//    ATTENTION à l'ordre des octets, première cause d'échec du « join » :
//      - DevEUI et JoinEUI (AppEUI) : ordre INVERSE de la console (poids faible d'abord) ;
//      - AppKey                      : même ordre que la console (poids fort d'abord).
//    Ne publiez jamais ce fichier une fois les vraies clés écrites dedans.
// ---------------------------------------------------------------------------
static const u1_t PROGMEM DEVEUI[8]  = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };  // <DEV_EUI> inversé
static const u1_t PROGMEM APPEUI[8]  = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };  // <JOIN_EUI> inversé
static const u1_t PROGMEM APPKEY[16] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                                         0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };  // <APP_KEY>

void os_getDevEui(u1_t *buf) { memcpy_P(buf, DEVEUI, 8); }
void os_getArtEui(u1_t *buf) { memcpy_P(buf, APPEUI, 8); }
void os_getDevKey(u1_t *buf) { memcpy_P(buf, APPKEY, 16); }

// ---------------------------------------------------------------------------
// 2) Branchements — À ADAPTER à votre carte.
// ---------------------------------------------------------------------------
const lmic_pinmap lmic_pins = {
  .nss  = 10,
  .rxtx = LMIC_UNUSED_PIN,
  .rst  = 9,
  .dio  = { 2, 6, 7 },        // DIO0, DIO1, DIO2 : LMIC a besoin de DIO0 ET de DIO1 réellement câblés
};

const uint8_t  PIN_SONDE      = A2;   // sortie analogique de la sonde capacitive
const uint8_t  PIN_ALIM_SONDE = 5;    // commande de l'alimentation de la sonde (économise le courant)
const uint32_t INTERVALLE_S   = 600;  // 10 min ; les limites légales (1 % de temps d'antenne) vous laissent bien plus
const uint8_t  PORT_APPLI     = 10;   // doit correspondre au formateur TTN

static osjob_t jobEnvoi;
static uint8_t trame[7];

// Mesure la tension d'alimentation (mV) en comparant la référence interne 1,1 V à Vcc.
static uint16_t lireVccMv() {
  ADMUX = _BV(REFS0) | _BV(MUX3) | _BV(MUX2) | _BV(MUX1);
  delay(2);                               // laisse la référence se stabiliser
  ADCSRA |= _BV(ADSC);
  while (bit_is_set(ADCSRA, ADSC)) {}
  return (uint16_t)(1125300UL / ADC);
}

// Lit la sonde : moyenne de 8 mesures pour lisser le bruit.
static uint16_t lireSonde() {
  digitalWrite(PIN_ALIM_SONDE, HIGH);
  delay(100);                             // temps de stabilisation de la sonde
  uint32_t somme = 0;
  for (uint8_t i = 0; i < 8; i++) { somme += analogRead(PIN_SONDE); delay(5); }
  digitalWrite(PIN_ALIM_SONDE, LOW);
  return (uint16_t)(somme / 8);
}

static void construireTrame() {
  uint16_t brut = lireSonde();
  uint16_t vcc  = lireVccMv();
  int16_t  temp = (int16_t)0x8000;        // pas de capteur de température dans cet exemple
  trame[0] = 0xA1;
  trame[1] = brut >> 8;  trame[2] = brut & 0xFF;
  trame[3] = ((uint16_t)temp) >> 8;  trame[4] = ((uint16_t)temp) & 0xFF;
  trame[5] = vcc >> 8;   trame[6] = vcc & 0xFF;
}

static void envoyer(osjob_t *job) {
  // Si une émission est encore en cours, on ne fait rien : la prochaine sera replanifiée par onEvent().
  if (LMIC.opmode & OP_TXRXPEND) {
    Serial.println(F("emission deja en cours"));
    return;
  }
  construireTrame();                      // les mesures se font AVANT la mise en file...
  LMIC_setTxData2(PORT_APPLI, trame, sizeof(trame), 0);
  Serial.println(F("trame en file"));     // ...et surtout aucun delay() après : il fausserait les fenêtres de réception
}

void onEvent(ev_t ev) {
  switch (ev) {
    case EV_JOINING:
      Serial.println(F("join en cours"));
      break;
    case EV_JOINED:
      Serial.println(F("join OK"));
      LMIC_setLinkCheckMode(0);           // inutile pour un capteur fixe, économise des échanges
      break;
    case EV_JOIN_FAILED:
      Serial.println(F("join echoue : verifier l'ordre des octets des cles et la portee"));
      break;
    case EV_TXCOMPLETE:
      Serial.println(F("emission terminee"));
      // Toujours replanifier ici : si on oublie, le capteur s'arrête en silence.
      os_setTimedCallback(&jobEnvoi, os_getTime() + sec2osticks(INTERVALLE_S), envoyer);
      break;
    default:
      break;
  }
}

void setup() {
  Serial.begin(115200);
  pinMode(PIN_ALIM_SONDE, OUTPUT);
  digitalWrite(PIN_ALIM_SONDE, LOW);

  os_init();
  LMIC_reset();
  // L'horloge de l'ATmega à 8 MHz dérive : sans cette tolérance de 2 %, les fenêtres de
  // réception s'ouvrent à côté et la réponse au « join » est manquée.
  LMIC_setClockError(MAX_CLOCK_ERROR * 2 / 100);
  LMIC_setAdrMode(1);                     // capteur fixe : le réseau peut ajuster le facteur d'étalement
  LMIC_setDrTxpow(DR_SF7, 14);            // 14 dBm = plafond EU868 pour les canaux par défaut

  envoyer(&jobEnvoi);                     // lance le « join » puis la première trame
}

void loop() {
  os_runloop_once();                      // moteur LMIC : à appeler le plus souvent possible, sans delay()
}

b. Formateur de charge utile TTN

Ne décode que le port et le format du croquis (a) ; renvoie une erreur sinon. À coller dans la console TTN, ou mieux : sur l'appareil seul.

// Formateur de charge utile TTN (montante) — exemple de démarrage (Alseno Tech, licence MIT).
// À coller dans : console TTN > Application > Payload formatters > Uplink > JavaScript.
//
// PIÈGE : un formateur défini au niveau de l'APPLICATION s'applique à TOUS les appareils
// de cette application (capteurs, mouchards de couverture, tests...). Un appareil qui n'a
// rien à voir recevrait des « mesures » inventées. Deux protections ci-dessous :
//   1. on ne décode que le port PORT_SOL ;
//   2. on exige l'octet d'identification 0xA1 et la bonne longueur ; sinon on répond par une erreur,
//      jamais par des valeurs plausibles.
// Mieux encore : définissez le formateur sur l'appareil lui-même (onglet Payload formatters
// de l'appareil), il ne touche alors que celui-là.

var PORT_SOL = 10;
var ID_FORMAT = 0xA1;
var LONGUEUR = 7;

// Calibration de VOTRE sonde (voir la page « Capteur de sol ») : valeur brute dans l'air / dans l'eau.
var BRUT_SEC = 870;      // sonde à l'air libre : 0 %
var BRUT_HUMIDE = 560;   // sonde dans l'eau : 100 %  (une sonde capacitive donne MOINS quand c'est plus humide)

function decodeUplink(input) {
  var b = input.bytes;

  if (input.fPort !== PORT_SOL) {
    return { errors: ["port " + input.fPort + " non géré par ce formateur"] };
  }
  if (b.length !== LONGUEUR || b[0] !== ID_FORMAT) {
    return { errors: ["trame inconnue (longueur " + b.length + ")"] };
  }

  var brut = (b[1] << 8) | b[2];
  var tempBrute = (b[3] << 8) | b[4];
  if (tempBrute & 0x8000) tempBrute -= 0x10000;      // entier signé sur 16 bits
  var vccMv = (b[5] << 8) | b[6];

  // Conversion brut -> pourcentage, bornée entre 0 et 100.
  var pct = 100 * (BRUT_SEC - brut) / (BRUT_SEC - BRUT_HUMIDE);
  pct = Math.max(0, Math.min(100, Math.round(pct)));

  var data = { sol_brut: brut, sol_pct: pct, batterie_mv: vccMv };
  if (tempBrute !== -32768) data.temperature_c = tempBrute / 100;   // 0x8000 = « pas de mesure »
  return { data: data };
}

c. Récepteur de webhook TTN

Reçoit les messages de TTN, vérifie la clé, déduplique, range les mesures dans SQLite. Une seule dépendance (Flask).

#!/usr/bin/env python3
"""Récepteur minimal de webhook TTN : stocke les mesures dans SQLite.

Exemple de démarrage (Alseno Tech, licence MIT). Une seule dépendance : Flask.

    pip install flask
    export CLE_INGESTION="<CLE_A_CHOISIR>"      # longue chaîne aléatoire, à vous
    python recepteur_webhook.py

Dans la console TTN : Integrations > Webhooks > Custom webhook
    URL de base : https://<URL_API>      chemin montant : /ttn
    En-tête     : X-Ingest-Key = <CLE_A_CHOISIR>
(Exposez le service derrière HTTPS : proxy inverse, tunnel...)

Choix de conception, tirés de l'expérience :
  * on répond TOUJOURS 200 aux charges inattendues ou déjà vues : un webhook qui reçoit
    des erreurs réessaie, puis TTN finit par le désactiver. Seules l'authentification
    (401) et une vraie panne (500) échouent ;
  * on garde la charge d'origine (colonne brut) : un décodeur peut être faux, et sans le
    brut on ne peut rien rejouer ;
  * un doublon (même appareil, même compteur de trame, même heure) est ignoré proprement.
"""
import hmac
import json
import os
import sqlite3

from flask import Flask, jsonify, request

BASE = os.environ.get("BASE_SQLITE", "mesures.db")
CLE = os.environ.get("CLE_INGESTION", "")

app = Flask(__name__)


def ouvrir_base():
    """Ouvre la base et crée les tables au premier appel (mode WAL : lecture pendant l'écriture)."""
    cnx = sqlite3.connect(BASE)
    cnx.execute("PRAGMA journal_mode=WAL")
    cnx.executescript("""
        CREATE TABLE IF NOT EXISTS receptions (
            id INTEGER PRIMARY KEY,
            appareil TEXT NOT NULL,
            recu_le TEXT NOT NULL,
            compteur INTEGER,
            rssi REAL, snr REAL,
            brut TEXT NOT NULL,
            UNIQUE (appareil, compteur, recu_le)
        );
        CREATE TABLE IF NOT EXISTS mesures (
            reception_id INTEGER NOT NULL REFERENCES receptions(id),
            grandeur TEXT NOT NULL,
            valeur REAL NOT NULL
        );
        CREATE INDEX IF NOT EXISTS idx_mesures ON mesures (grandeur, reception_id);
    """)
    return cnx


def cle_valide():
    """Compare la clé reçue à la clé attendue, en temps constant."""
    recue = request.headers.get("X-Ingest-Key", "")
    return bool(CLE) and hmac.compare_digest(recue, CLE)


@app.post("/ttn")
def recevoir():
    if not cle_valide():
        return jsonify(erreur="non autorise"), 401

    msg = request.get_json(silent=True) or {}
    montante = msg.get("uplink_message")
    if not montante:                       # événement qui n'est pas une mesure (join, etc.)
        return jsonify(ok=True, ignore="pas une mesure")

    appareil = msg.get("end_device_ids", {}).get("device_id", "inconnu")
    decode = montante.get("decoded_payload") or {}
    # On ne retient que les valeurs numériques : un champ texte inattendu ne casse rien.
    mesures = {k: float(v) for k, v in decode.items()
               if isinstance(v, (int, float)) and not isinstance(v, bool)}
    if not mesures:
        return jsonify(ok=True, ignore="rien a stocker")

    meta = (montante.get("rx_metadata") or [{}])[0]   # première passerelle ayant entendu la trame
    cnx = ouvrir_base()
    try:
        with cnx:                          # une transaction : tout ou rien
            cur = cnx.execute(
                "INSERT OR IGNORE INTO receptions (appareil, recu_le, compteur, rssi, snr, brut) "
                "VALUES (?, ?, ?, ?, ?, ?)",
                (appareil, msg.get("received_at", ""), montante.get("f_cnt"),
                 meta.get("rssi"), meta.get("snr"), json.dumps(msg)))
            if cur.rowcount == 0:          # doublon : déjà enregistré
                return jsonify(ok=True, ignore="doublon")
            cnx.executemany(
                "INSERT INTO mesures (reception_id, grandeur, valeur) VALUES (?, ?, ?)",
                [(cur.lastrowid, g, v) for g, v in mesures.items()])
    finally:
        cnx.close()
    return jsonify(ok=True, stocke=len(mesures))


if __name__ == "__main__":
    app.run(host="127.0.0.1", port=8600)    # derrière un proxy HTTPS, jamais exposé tel quel

d. Calibration sec / mouillé

Calcule les deux repères à partir de vos relevés, puis convertit une valeur brute en pourcentage.

#!/usr/bin/env python3
"""Calibration sec / mouillé d'une sonde d'humidité du sol et conversion ADC -> %.

Exemple de démarrage (Alseno Tech, licence MIT). Aucune dépendance.

Méthode : relevez 20 à 30 valeurs brutes (dans le moniteur série ou la console TTN),
une par ligne dans un fichier texte, dans deux situations :
  - sonde SÈCHE (à l'air libre, ou dans le sol le plus sec que vous aurez) ;
  - sonde MOUILLÉE (plongée dans l'eau jusqu'à la ligne de repère, ou sol saturé).

    python calibration_sonde.py enregistrer sec     < releves_sec.txt
    python calibration_sonde.py enregistrer mouille < releves_eau.txt
    python calibration_sonde.py convertir 640

Une sonde capacitive donne une valeur PLUS BASSE quand le sol est plus humide : le script
s'en accommode (il travaille avec l'écart entre les deux repères, quel que soit le sens).
Chaque sonde est différente : calibrez-les une par une.
"""
import json
import statistics
import sys

FICHIER = "calibration.json"


def lire_releves(flux):
    """Lit des nombres, un par ligne, en ignorant les lignes vides ou non numériques."""
    valeurs = []
    for ligne in flux:
        try:
            valeurs.append(float(ligne.strip()))
        except ValueError:
            continue
    return valeurs


def charger():
    try:
        with open(FICHIER, encoding="utf-8") as f:
            return json.load(f)
    except FileNotFoundError:
        return {}


def enregistrer(repere, valeurs):
    """Stocke la médiane (insensible aux mesures aberrantes) et la dispersion."""
    if len(valeurs) < 5:
        sys.exit("Il faut au moins 5 relevés (idéalement 20 à 30).")
    cal = charger()
    cal[repere] = {"mediane": statistics.median(valeurs),
                   "ecart_type": round(statistics.pstdev(valeurs), 2),
                   "nombre": len(valeurs)}
    with open(FICHIER, "w", encoding="utf-8") as f:
        json.dump(cal, f, indent=2)
    print(repere, "=", cal[repere])


def convertir(brut):
    """Valeur brute -> pourcentage d'humidité (0 = repère sec, 100 = repère mouillé), borné."""
    cal = charger()
    if "sec" not in cal or "mouille" not in cal:
        sys.exit("Enregistrez d'abord les deux repères : sec puis mouille.")
    sec, mouille = cal["sec"]["mediane"], cal["mouille"]["mediane"]
    if abs(sec - mouille) < 20:
        sys.exit("Repères trop proches : sonde défaillante ou mauvais essai.")
    pct = 100.0 * (brut - sec) / (mouille - sec)
    return max(0.0, min(100.0, pct))


if __name__ == "__main__":
    if len(sys.argv) == 3 and sys.argv[1] == "enregistrer" and sys.argv[2] in ("sec", "mouille"):
        enregistrer(sys.argv[2], lire_releves(sys.stdin))
    elif len(sys.argv) == 3 and sys.argv[1] == "convertir":
        print("%.0f %%" % convertir(float(sys.argv[2])))
    else:
        sys.exit(__doc__)

e. Règle de conseil d'arrosage

Un seuil et une tendance. Point de départ à ajuster par plante et par sol, avant un modèle appris (voir Agriculture de précision).

#!/usr/bin/env python3
"""Conseil d'arrosage v1 : un seuil et une tendance. Point de départ d'un modèle plus fin.

Exemple de démarrage (Alseno Tech, licence MIT). Aucune dépendance.

Idée : on n'arrose pas seulement parce que le sol est sec, on regarde aussi
  - s'il vient d'être mouillé (pluie, arrosage) : la tendance est à la hausse -> on attend ;
  - s'il s'assèche vite : on prévient plus tôt.
Les seuils dépendent de la plante et du sol : ce sont des valeurs de départ à ajuster.
"""
from datetime import datetime, timedelta

SEUIL_ARROSER = 30.0      # % d'humidité en dessous duquel on conseille d'arroser
SEUIL_ATTENTION = 40.0    # en dessous, on surveille de près
HAUSSE_PLUIE = 5.0        # hausse (points de %) en 2 h qui signale un arrosage ou une pluie récente
FENETRE_H = 3             # durée sur laquelle on mesure la tendance


def pente_par_heure(releves, maintenant):
    """Pente moyenne (points de % par heure) sur FENETRE_H heures, par régression linéaire simple.

    releves : liste de (datetime, pourcentage). Renvoie None s'il y a trop peu de points."""
    debut = maintenant - timedelta(hours=FENETRE_H)
    pts = [((t - debut).total_seconds() / 3600.0, v) for t, v in releves if t >= debut]
    if len(pts) < 4:
        return None
    n = len(pts)
    mx = sum(x for x, _ in pts) / n
    my = sum(y for _, y in pts) / n
    var = sum((x - mx) ** 2 for x, _ in pts)
    if var == 0:
        return None
    return sum((x - mx) * (y - my) for x, y in pts) / var


def conseil(releves, maintenant=None):
    """Renvoie (action, raison) avec action dans 'arroser', 'surveiller', 'attendre', 'donnees_insuffisantes'."""
    maintenant = maintenant or datetime.now()
    if not releves:
        return "donnees_insuffisantes", "aucune mesure"
    releves = sorted(releves)
    dernier_t, dernier = releves[-1]
    if maintenant - dernier_t > timedelta(hours=2):
        return "donnees_insuffisantes", "derniere mesure trop ancienne (capteur muet ?)"

    pente = pente_par_heure(releves, maintenant)
    deux_h = [v for t, v in releves if t >= maintenant - timedelta(hours=2)]
    if deux_h and dernier - min(deux_h) >= HAUSSE_PLUIE:
        return "attendre", "humidite en hausse : pluie ou arrosage recent"

    if dernier < SEUIL_ARROSER:
        return "arroser", "sol sec (%.0f %% < %.0f %%)" % (dernier, SEUIL_ARROSER)
    if dernier < SEUIL_ATTENTION and pente is not None and pente < -1.0:
        return "arroser", "sol en train de secher vite (%.1f points/h)" % pente
    if dernier < SEUIL_ATTENTION:
        return "surveiller", "sol assez sec (%.0f %%)" % dernier
    return "attendre", "humidite suffisante (%.0f %%)" % dernier


if __name__ == "__main__":
    # Démonstration avec des mesures fictives : le sol sèche de 45 % à 32 % en 3 heures.
    maintenant = datetime(2026, 1, 1, 12, 0)
    exemple = [(maintenant - timedelta(minutes=15 * k), 32 + 13 * (k / 12.0)) for k in range(13)]
    print(conseil(exemple, maintenant))

Pour aller plus loin

  • Ajouter un capteur de température au croquis et à la trame (le champ existe déjà).
  • Faire dormir le microcontrôleur entre deux mesures si vous êtes sur piles.
  • Brancher le conseil (e) sur les mesures de la base du récepteur (c).
  • Commander une vanne : voir Matériel et coûts.

Licence

Exemples proposés sous licence MIT, © Alseno Tech (sous réserve de confirmation).