Integrar lectores RFID en un mapa de interiores: guía paso a paso

La RFID lleva años siendo una herramienta de trabajo en tiendas y almacenes, y aun así la mayoría de los equipos la siguen leyendo como un registro de eventos que no para de desplazarse o como una cuadrícula de contadores. Ninguno de los dos te dice qué arco del muelle se quedó en silencio ni si los lectores de las escaleras mecánicas de la planta 2 están leyendo algo. Esta guía coloca cada lector sobre el plano. Sigue una instalación de demostración real de Spatial Map, así que puedes reproducir cada captura.

El ejemplo es Retail Mart Store, una tienda de tres plantas (Ground, Level 1, Level 2) en el espacio de trabajo de demostración Production Corp. Tiene 85 lectores fijos: 66 en puertas y arcos entre departamentos, 9 en las puertas de los ascensores, 9 en los extremos de las escaleras mecánicas y 1 en la escalera. Cada lector es un marcador en el mapa con el nombre del lector, por ejemplo «RFID-G-02 · Office ↔ Receiving / Loading Docks». Una sola tabla, Retail Mart · RFID Reader Reads, guarda una fila por lector.

Retail Mart Store en el editor: marcadores de lectores en arcos, ascensores y escaleras mecánicas

Los lectores UHF fijos entregan sus lecturas a través de un middleware de borde: la propia interfaz LLRP del lector o el SDK del fabricante ejecutándose en un pequeño equipo a su lado. Ese middleware lee etiquetas de maravilla, pero no tiene nada útil que decirle a un mapa. Por eso añades una pieza pequeña en medio: un relé que controlas tú. Escucha al middleware, agrega las lecturas por lector y, cada pocos segundos, escribe el resultado en una tabla de Spatial Map mediante la API de escritura de la tabla. El mapa y el informe leen de esa tabla.

¿Por qué agregar en lugar de reenviar cada lectura? Un arco con mucho tráfico ve cientos de lecturas por minuto, muchas de ellas la misma etiqueta vista por dos antenas. Un mapa no puede mostrar eso de forma útil, y la API de tablas tiene un límite por clave. Una fila por lector —lecturas de hoy, de la última hora, etiquetas únicas, entradas y salidas, la última etiqueta y SKU, y un estado— es justo lo que guarda la tabla de la demo y lo que quiere ver un jefe de turno. Si lo que necesitas es la posición de cada etiqueta, el mismo patrón funciona con una fila por etiqueta en su último lector; mira seguimiento de activos en interiores en tiempo real.

1. 1
   Crea la tabla

   Ve a Tables → Create new table, ponle nombre (la demo usa «Retail Mart · RFID Reader Reads») y elige RFID tag como tipo. Las columnas estándar que propone son solo un punto de partida: renómbralas, cambia su tipo o elimínalas para que coincidan con lo que enviará tu relé.

2. 2
   Diseña una fila por lector

   Añade un campo de texto `reader_id` marcado como Required y Unique, y después `reader_name`, `floor`, `reader_type`, `status`, los contadores enteros (`reads_today`, `reads_last_hour`, `unique_tags_today`, `in_count_today`, `out_count_today`, `alerts_today`), `last_read_at` como fecha y hora, `last_tag_epc`, `last_sku`, `last_direction`, `rssi_dbm`, `firmware` y `elevation_m`. Cada escritura se valida contra este esquema.

3. 3
   Crea una clave

   En la pestaña API & access de la tabla, escribe un nombre de clave y pulsa Create key. La clave empieza por `sgv_tbl_` y solo se muestra una vez, así que guárdala directamente en los secretos del relé. Una clave solo puede escribir en esta tabla; da a cada relé su propia clave para poder revocar una sin romper las demás. Pueden crear claves los roles Owner y Admin.

4. 4
   Copia la URL base

   La misma pestaña lista los 12 endpoints con ejemplos curl listos para copiar. En producción la base es `https://app.spatialmap.io/api/v1/public/tables`; la clave decide en qué tabla escribes, por eso no hay id de tabla en la ruta.

Create new table: elige un tipo y da forma a los campos

El relé son unas pocas decenas de líneas en el lenguaje que prefiera tu equipo. Suscríbete a los eventos de lectura del middleware (informes LLRP o el callback del SDK), mantén un pequeño contador en memoria por lector y, con un temporizador —cada 5 a 10 segundos es más que suficiente—, envía en una sola llamada por lotes todos los lectores que hayan cambiado. Usa el id del lector como `entityKey`, para que cada llamada actualice la fila existente en lugar de añadir una nueva.

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` y `POST /rows/bulk` hacen upsert: el payload que envías pasa a ser el estado completo de la fila, así que envía siempre la fila entera. Para cambiar un solo campo —por ejemplo, marcar un lector como Offline cuando deja de dar señales de vida— usa `PATCH`, que fusiona los cambios con el payload guardado.

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: en la pestaña API & access de la tabla, indica la URL del middleware, un intervalo (30 segundos como mínimo en el formulario), el campo clave de fila, la ruta JSON de los elementos, las cabeceras necesarias y el mapeo de campos, y pulsa Start polling. Un proceso en el servidor lo ejecuta más o menos una vez por minuto, aunque nadie tenga un mapa abierto. Cada consulta lee hasta 1.000 filas de una respuesta de hasta 10 MB.
• Upload file: para tiendas que solo exportan recuentos diarios. Añade un archivo CSV, Excel, JSON o GeoJSON en Integrations → Add integration → Upload file y usa Re-import con la exportación del día siguiente.

Los pasos del mapa y del informe son los mismos llegue como llegue el dato. La referencia de la API está en Tables, y tienes un ejemplo completo en Push rows with the table write API.

Cada lector necesita un marcador en su posición real: en una puerta, junto a la puerta de un ascensor, arriba o abajo de una escalera mecánica. Colócalos con la herramienta Marker en la planta correcta y da a cada marcador exactamente el nombre que tu relé escribe en `reader_name`. Ese nombre es la clave de unión del siguiente paso, así que cópialo en vez de teclearlo. En una tienda de varias plantas, construye primero las plantas, los ascensores y las escaleras mecánicas: Multi-floor store with escalators and lifts recorre la misma distribución de Retail Mart.

Un marcador seleccionado: su nombre es lo que empareja el enlace de datos

Abre la instalación en el editor y pulsa Data links y luego New data link (también desde el menú Data → Manage data links). El enlace de la demo se llama RFID reader activity. Esta es su configuración, sección por sección:

1. 1
   Data source

   La tabla Retail Mart · RFID Reader Reads.

2. 2
   Display mode

   Pulsing zone activity: un anillo animado con un contador en cada marcador de lector. El contador muestra `reads_last_hour`, elegido como campo de etiqueta en Connect fields.

3. 3
   Attach to shapes

   Apunta a los marcadores y empareja por Attribute join: el campo `reader_name` de la fila frente al nombre del marcador.

4. 4
   Floor scope

   From record, con `floor` como campo del que leer la planta. La tabla guarda texto («Ground», «Level 1», «Level 2»), así que cada valor se asigna a una de las plantas de la instalación: los lectores de Level 2 solo pulsan en Level 2.

5. 5
   Style rules

   Tres reglas sobre `status`: Active en violeta, Idle en gris y Offline en rojo. Las reglas se evalúan de arriba abajo y gana la primera que coincide.

6. 6
   Map tooltip

   Se activa al pasar el ratón y muestra id del lector, tipo, planta, estado, contadores, última lectura, último EPC, último SKU, sentido, señal y firmware; un clic abre el panel de detalle.

Which floors?: From record, Specific floors o All floors

Cada opción se explica en Source and render mode y Style and rules.

Guarda el enlace y abre la instalación en Preview o mediante un enlace compartido. Cada marcador de lector pulsa ahora con su recuento de la última hora y el color de su estado. Cuando el relé escribe, el servidor avisa a los mapas abiertos y estos recargan esa capa al momento, con una actualización cada 30 segundos como red de seguridad. Pasa el ratón por un lector para ver el tooltip; haz clic para ver el registro completo y su historial.

Retail Mart Store en Preview: lectores coloreados por estado

Para quien no trabaja en el editor, la demo incluye también un informe de mapa completo, Retail Mart · RFID Live Map. La lista de lectores está a la izquierda, el mapa vivo de la tienda en el centro y las cifras flotan encima: KPI de filas, lecturas totales de hoy, lecturas de la última hora y etiquetas únicas de hoy, un donut By status y un gráfico de barras Reads today by floor. Los filtros Floor, Status y Search lo acotan todo a la vez: elige Offline y tendrás la lista de mantenimiento de la mañana. Consulta Full-map reports.

Retail Mart · RFID Live Map: el informe de mapa completo

“Envía al mapa estado, no eventos: una fila por lector, actualizada cada pocos segundos, es algo que un jefe de turno entiende de un vistazo.”

La demo sugiere algunas ampliaciones naturales. Añade una regla de estilo sobre `alerts_today` (el campo «Exit alerts today») para que destaquen los arcos con alertas de salida: cambia un color en el mapa y en el informe, no envía ninguna notificación. Combina el estado de los lectores con el stock de los estantes y los sensores de cadena de frío en las mismas plantas, como en la solución para retail, o céntrate en salidas y arcos con la solución antirrobo. Para activos que se mueven en lugar de lectores fijos, lee seguimiento de activos en interiores en tiempo real.