Intégrer des lecteurs RFID à une carte d’intérieur : le guide pas à pas

La RFID est un outil de travail éprouvé dans les magasins et les entrepôts, et pourtant la plupart des équipes la lisent encore comme un journal d’événements qui défile ou une grille de compteurs. Aucun des deux ne vous dit quel portique de quai s’est tu, ni si les lecteurs des escalators du niveau 2 voient quoi que ce soit. Ce guide place chaque lecteur sur le plan. Il s’appuie sur une vraie installation de démonstration dans Spatial Map : chaque capture ci-dessous est reproductible.

L’exemple est Retail Mart Store, un magasin sur trois niveaux (Ground, Level 1, Level 2) dans l’espace de travail de démonstration Production Corp. Il compte 85 lecteurs fixes : 66 aux portes et portiques entre rayons, 9 aux portes d’ascenseur, 9 aux extrémités des escalators et 1 dans l’escalier. Chaque lecteur est un marqueur sur la carte, nommé d’après le lecteur — par exemple « RFID-G-02 · Office ↔ Receiving / Loading Docks ». Une seule table, Retail Mart · RFID Reader Reads, contient une ligne par lecteur.

Retail Mart Store dans l’éditeur — marqueurs de lecteurs aux portiques, ascenseurs et escalators

Les lecteurs UHF fixes remontent leurs lectures via un middleware de périphérie : l’interface LLRP du lecteur lui-même, ou le SDK du fabricant qui tourne sur un petit boîtier à côté. Ce middleware lit très bien les tags, mais n’a rien d’utile à dire à une carte. Vous ajoutez donc une petite pièce entre les deux : un relais qui vous appartient. Il écoute le middleware, agrège les lectures par lecteur et, toutes les quelques secondes, écrit le résultat dans une table Spatial Map grâce à l’API d’écriture de la table. La carte et le rapport lisent cette table.

Pourquoi agréger plutôt que transmettre chaque lecture ? Un portique fréquenté voit des centaines de lectures par minute, dont beaucoup sont le même tag vu par deux antennes. Une carte ne peut pas montrer cela utilement, et l’API de table est limitée par clé. Une ligne par lecteur — lectures du jour, de la dernière heure, tags uniques, entrées et sorties, dernier tag et SKU, et un statut — c’est exactement ce que contient la table de la démo, et ce qu’un chef d’équipe veut voir. S’il vous faut plutôt la position de chaque tag, le même schéma fonctionne avec une ligne par tag à son dernier lecteur ; voir suivi d’actifs en intérieur en temps réel.

1. 1
   Créer la table

   Allez dans Tables → Create new table, nommez-la (la démo utilise « Retail Mart · RFID Reader Reads ») et choisissez le type RFID tag. Les colonnes standard proposées ne sont qu’un point de départ : renommez-les, changez leur type ou supprimez-les pour coller à ce que votre relais enverra.

2. 2
   Une ligne par lecteur

   Ajoutez un champ texte `reader_id` coché Required et Unique, puis `reader_name`, `floor`, `reader_type`, `status`, les compteurs entiers (`reads_today`, `reads_last_hour`, `unique_tags_today`, `in_count_today`, `out_count_today`, `alerts_today`), `last_read_at` en date-heure, `last_tag_epc`, `last_sku`, `last_direction`, `rssi_dbm`, `firmware` et `elevation_m`. Chaque écriture est validée par rapport à ce schéma.

3. 3
   Créer une clé

   Dans l’onglet API & access de la table, saisissez un nom de clé et cliquez sur Create key. La clé commence par `sgv_tbl_` et ne s’affiche qu’une fois : rangez-la aussitôt dans les secrets du relais. Une clé n’écrit que dans cette table ; donnez à chaque relais sa propre clé pour pouvoir en révoquer une sans casser les autres. Les rôles Owner et Admin peuvent créer des clés.

4. 4
   Copier l’URL de base

   Le même onglet liste les 12 endpoints avec des exemples curl à copier. En production, la base est `https://app.spatialmap.io/api/v1/public/tables` ; c’est la clé qui détermine la table, il n’y a donc pas d’identifiant de table dans le chemin.

Create new table — choisir un type, puis façonner les champs

Le relais tient en quelques dizaines de lignes, dans le langage que votre équipe préfère. Abonnez-vous aux événements de lecture du middleware (rapports LLRP ou callback du SDK), tenez un petit compteur en mémoire par lecteur et, sur minuterie — toutes les 5 à 10 secondes suffit largement —, envoyez en un seul appel groupé tous les lecteurs qui ont changé. Utilisez l’identifiant du lecteur comme `entityKey`, pour que chaque appel mette à jour la ligne existante au lieu d’en ajouter une.

curl -X POST https://app.spatialmap.io/api/v1/public/tables/rows/bulk \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "entityKey": "RFID-G-02",
        "payload": {
          "reader_id": "RFID-G-02",
          "reader_name": "RFID-G-02 · Office ↔ Receiving / Loading Docks",
          "floor": "Ground",
          "reader_type": "Gate",
          "status": "Active",
          "reads_today": 590,
          "reads_last_hour": 56,
          "unique_tags_today": 288,
          "in_count_today": 294,
          "out_count_today": 296,
          "last_read_at": "2026-10-08T09:25:12Z",
          "last_tag_epc": "E2801121130DB42AB66C7A7B",
          "last_sku": "SKU-339201 Frozen Peas 1kg",
          "last_direction": "Out",
          "alerts_today": 2,
          "elevation_m": 2.4
        }
      },
      {
        "entityKey": "RFID-L1-15",
        "payload": {
          "reader_id": "RFID-L1-15",
          "reader_name": "RFID-L1-15 · Escalator 2 top · L1",
          "floor": "Level 1",
          "reader_type": "Escalator",
          "status": "Idle",
          "reads_today": 525,
          "reads_last_hour": 29,
          "unique_tags_today": 220,
          "in_count_today": 261,
          "out_count_today": 264,
          "last_read_at": "2026-10-08T09:25:49Z",
          "last_tag_epc": "E280115AC002CF6117A1B75B",
          "last_sku": "SKU-509112 LED TV 55in",
          "last_direction": "Out",
          "alerts_today": 0,
          "elevation_m": 6.067
        }
      }
    ]
  }'

`POST /rows` et `POST /rows/bulk` font un upsert : le payload envoyé devient l’état complet de la ligne, envoyez donc toujours la ligne entière. Pour modifier un seul champ — par exemple passer un lecteur en Offline quand il ne donne plus signe de vie — utilisez `PATCH`, qui fusionne avec le payload enregistré.

curl -X PATCH https://app.spatialmap.io/api/v1/public/tables/rows/RFID-G-01 \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"Offline"}'

• Pull from a REST API — dans l’onglet API & access de la table, renseignez l’URL du middleware, un intervalle (30 secondes minimum dans le formulaire), le champ de clé de ligne, le chemin JSON des éléments, les en-têtes éventuels et le mappage des champs, puis cliquez sur Start polling. Un processus côté serveur l’exécute environ une fois par minute, même si personne n’a de carte ouverte. Chaque interrogation lit jusqu’à 1 000 lignes dans une réponse de 10 Mo maximum.
• Upload file — pour les magasins qui n’exportent que des compteurs quotidiens. Ajoutez un fichier CSV, Excel, JSON ou GeoJSON via Integrations → Add integration → Upload file, puis utilisez Re-import pour l’export du lendemain.

Les étapes carte et rapport ci-dessous sont identiques quelle que soit la voie d’entrée. La référence de l’API est dans Tables, et un exemple complet se trouve dans Push rows with the table write API.

Chaque lecteur a besoin d’un marqueur à sa position réelle : sur une porte, à côté d’une porte d’ascenseur, en haut ou en bas d’un escalator. Placez-les avec l’outil Marker au bon étage et donnez à chaque marqueur exactement le nom que votre relais écrit dans `reader_name`. Ce nom sert de clé de jointure à l’étape suivante : copiez-le plutôt que de le retaper. Dans un magasin à plusieurs niveaux, construisez d’abord les étages, les ascenseurs et les escalators — Multi-floor store with escalators and lifts reprend la même implantation Retail Mart.

Un marqueur sélectionné — son nom est ce que le lien de données apparie

Ouvrez le site dans l’éditeur, cliquez sur Data links puis New data link (accessible aussi via le menu Data → Manage data links). Le lien de la démo s’appelle RFID reader activity. Voici ses réglages, section par section :

1. 1
   Data source

   La table Retail Mart · RFID Reader Reads.

2. 2
   Display mode

   Pulsing zone activity — un anneau animé avec un badge de compteur sur chaque marqueur de lecteur. Le badge affiche `reads_last_hour`, choisi comme champ d’étiquette dans Connect fields.

3. 3
   Attach to shapes

   Ciblez les marqueurs et appariez par Attribute join : le champ `reader_name` de la ligne face au nom du marqueur.

4. 4
   Floor scope

   From record, avec `floor` comme champ où lire l’étage. La table stocke du texte (« Ground », « Level 1 », « Level 2 ») : chaque valeur est donc associée à un étage du site, et les lecteurs de Level 2 ne pulsent qu’au Level 2.

5. 5
   Style rules

   Trois règles sur `status` : Active en violet, Idle en gris, Offline en rouge. Les règles sont évaluées de haut en bas et la première qui correspond l’emporte.

6. 6
   Map tooltip

   Déclenchement au survol, avec identifiant, type, étage, statut, compteurs, dernière lecture, dernier EPC, dernier SKU, sens, signal et firmware ; un clic ouvre le panneau de détail.

Which floors? — From record, Specific floors ou All floors

Chaque option est détaillée dans Source and render mode et Style and rules.

Enregistrez le lien et ouvrez le site en Preview ou via un lien de partage. Chaque marqueur de lecteur pulse désormais avec son compteur de la dernière heure, coloré selon son statut. Quand le relais écrit, le serveur prévient les cartes ouvertes, qui rechargent ce calque aussitôt, avec un rafraîchissement toutes les 30 secondes en filet de sécurité. Survolez un lecteur pour l’infobulle ; cliquez pour l’enregistrement complet et son historique.

Retail Mart Store en Preview — lecteurs colorés par statut

Pour ceux qui ne vivent pas dans l’éditeur, la démo propose aussi un rapport plein écran cartographique, Retail Mart · RFID Live Map. La liste des lecteurs est à gauche, la carte du magasin en direct au centre, et les chiffres flottent par-dessus : KPI du nombre de lignes, des lectures du jour, des lectures de la dernière heure et des tags uniques du jour, un anneau By status et un histogramme Reads today by floor. Les filtres Floor, Status et Search affinent tout d’un coup — choisissez Offline et vous avez la liste de maintenance du matin. Voir Full-map reports.

Retail Mart · RFID Live Map — le rapport plein écran cartographique

“Envoyez à la carte un état, pas des événements : une ligne par lecteur, rafraîchie toutes les quelques secondes, se lit d’un coup d’œil par un chef d’équipe.”

La démo suggère quelques prolongements naturels. Ajoutez une règle de style sur `alerts_today` (le champ « Exit alerts today ») pour faire ressortir les portiques ayant des alertes de sortie — cela change une couleur sur la carte et dans le rapport, sans envoyer de notification. Combinez l’état des lecteurs avec le stock en rayon et les capteurs de chaîne du froid sur les mêmes niveaux, comme dans la solution retail, ou concentrez-vous sur les sorties et portiques avec la solution antivol. Pour des actifs mobiles plutôt que des lecteurs fixes, lisez suivi d’actifs en intérieur en temps réel.