Crea tu primera app

Esta guía recorre el flujo de trabajo típico para construir una app de IronFlock que recopila datos de dispositivos edge y los muestra en dashboards en tiempo real. Al final tendrás un modelo de datos, lógica edge, un formulario de configuración para usuarios y gráficos en vivo — todo conectado a través de la base de datos del proyecto.

1. Diseña el modelo de datos

Comienza en el archivo .ironflock/data-template.yml. Piensa en dos categorías de tablas:

• Tablas de entidad — rastrean el estado actual de las cosas (dispositivos, máquinas, conexiones). Las filas se añaden con cada cambio; maintainLatestFlagFor declara qué columnas identifican una entidad, de modo que la fila más reciente de cada entidad puede leerse cuando se necesite.
• Tablas de series temporales — recopilan mediciones a lo largo del tiempo (lecturas de sensores, métricas). Cada fila es un nuevo punto de datos con marca de tiempo.

data:
  tables:
    # Tabla de entidad: una fila por dispositivo, estado actual siempre consultable
    - tablename: devices
      maintainLatestFlagFor: ['device_key']
      columns:
        - id: tsp
          dataType: timestamp
        - id: device_key
          dataType: string
        - id: status
          dataType: string
        - id: device_name
          dataType: string
        - id: deleted
          dataType: boolean
 
    # Tabla de entidad: servidores Modbus configurados por el usuario
    - tablename: modbus_servers
      maintainLatestFlagFor: ['server_id']
      columns:
        - id: tsp
          dataType: timestamp
        - id: server_id
          dataType: string
        - id: host
          dataType: string
        - id: port
          dataType: numeric
        - id: deleted
          dataType: boolean
 
    # Tabla de series temporales: lecturas periódicas del hardware conectado
    - tablename: readings
      columns:
        - id: tsp
          dataType: timestamp
        - id: server_id
          dataType: string
        - id: metric
          dataType: string
        - id: value
          dataType: numeric

2. Configura un entorno de pruebas

Para probar tu app necesitas un entorno de desarrollo en un proyecto con al menos un dispositivo en línea:

1. Haz clic en Develop en la página de detalle de la app para abrir el Cloud IDE.

2. Selecciona un dispositivo en línea de cualquier proyecto al que tengas acceso.

3. Haz clic en Create Backend en el panel lateral para crear un entorno de desarrollo en la base de datos del proyecto.

Esto crea las tablas definidas en tu data-template.yml dentro de la base de datos del proyecto. Puedes inspeccionarlas en la vista Fleet Database del proyecto.

El Cloud IDE te ofrece un entorno VS Code completo con explorador de archivos, editor, terminal y el panel Edge Development para compilar y desplegar en tu dispositivo.

3. Escribe el código edge

Tu contenedor Docker se ejecuta en el dispositivo y usa el SDK de IronFlock para interactuar con la base de datos del proyecto.

Registrar el dispositivo al iniciar

Cuando el componente edge arranca, añade una fila a la tabla de entidad devices para que el dashboard sepa que el dispositivo está en línea:

import asyncio
from ironflock import IronFlock
 
async def main():
    # Registrar este dispositivo como en línea
    await flock.append_to_table("devices", {
        "device_key": os.environ.get('DEVICE_KEY'),
        "tsp": now,
        "status": "online",
        "device_name": os.environ.get('DEVICE_NAME'),
        "deleted": False
    })
 
    # ... resto de la lógica
 
flock = IronFlock(mainFunc=main)
flock.run()

import { IronFlock } from "ironflock";
 
const flock = new IronFlock();
await flock.start();
 
// Registrar este dispositivo como en línea
await flock.appendToTable("devices", [{
    device_key: process.env.DEVICE_KEY,
    tsp: new Date().toISOString(),
    status: "online",
    device_name: process.env.DEVICE_NAME,
    deleted: false
}]);

Como devices usa maintainLatestFlagFor: ['device_key'], la fila de estado anterior de este dispositivo se reemplaza automáticamente. Los widgets que tienen activado el filtro latest siempre muestran el estado actual.

Reaccionar a la configuración del usuario

Los usuarios pueden añadir servidores Modbus a través de un formulario en el board (ver paso 4). Tu código edge se suscribe a la tabla modbus_servers y actúa ante nuevas entradas:

async def main():
    # ... registro del dispositivo ...
 
    # Leer servidores Modbus existentes
    existing = await flock.getHistory("modbus_servers", {
        "limit": 1000,
        "filterAnd": [
            # "latest": True devuelve solo la fila más reciente por server_id
            {"latest": True},
            {"column": "deleted", "operator": "IS", "value": None}
        ]
    })
    for server in existing:
        create_modbus_connection(server)
 
    # Reaccionar a nuevos servidores en tiempo real
    def on_server_change(*args, **kwargs):
        server = args[0] if args else kwargs
        if server.get("deleted"):
            delete_modbus_connection(server["server_id"])
        else:
            create_modbus_connection(server)
 
    await flock.subscribe_to_table("modbus_servers", on_server_change)

// Leer servidores Modbus existentes
const existing = await flock.getHistory("modbus_servers", {
    limit: 1000,
    filterAnd: [
        // latest: true devuelve solo la fila más reciente por server_id
        { latest: true },
        { column: "deleted", operator: "IS", value: null }
    ]
});
existing.forEach(server => createModbusConnection(server));
 
// Reaccionar a nuevos servidores en tiempo real
await flock.subscribeToTable("modbus_servers", (...args) => {
    const server = args[0];
    if (server.deleted) {
        deleteModbusConnection(server.server_id);
    } else {
        createModbusConnection(server);
    }
});

Recopilar datos de series temporales

Una vez establecida una conexión Modbus, consulta periódicamente y escribe las lecturas en la tabla readings:

async def modbus_poll_loop(server_id, client):
    while True:
        values = client.read_registers()
        for metric, value in values.items():
            await flock.publish_to_table("readings", {
                "server_id": server_id,
                "metric": metric,
                "value": value
            })
        await asyncio.sleep(5)

async function modbusPollingLoop(serverId, client) {
    setInterval(async () => {
        const values = client.readRegisters();
        for (const [metric, value] of Object.entries(values)) {
            await flock.publishToTable("readings", [{
                server_id: serverId,
                metric,
                value
            }]);
        }
    }, 5000);
}

4. Construye el board

Abre el Board Editor y añade widgets conectados a las tablas de tu Data Backend.

Mostrar el estado de los dispositivos

Añade un widget Table conectado a la tabla devices. Activa el interruptor latest en los ajustes de filtro del widget para que siempre muestre el estado actual de cada dispositivo. La tabla se actualiza automáticamente cuando un dispositivo se conecta o desconecta.

Permitir a los usuarios configurar servidores Modbus

Añade un widget Form conectado a la tabla modbus_servers. Configura campos para host y port. Cuando un usuario completa el formulario y lo envía, se inserta automáticamente una nueva fila en la tabla modbus_servers — no se necesita código backend para manejar el envío del formulario.

Tu código edge detecta la nueva fila vía subscribeToTable (ver paso 3) y establece la conexión Modbus.

Visualizar datos de series temporales

Añade un widget Line Chart conectado a la tabla readings. Asigna tsp al eje X y value al eje Y. El gráfico se actualiza en tiempo real conforme llegan nuevas lecturas de los dispositivos — sin polling ni actualización manual.

Cómo encaja todo

┌─────────────────────────────────────────────────────────┐
│  Board (Dashboard)                                      │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ Table    │  │ Form            │  │ Line Chart        │  │
│  │ devices  │  │ modbus_servers  │  │ readings          │  │
│  └────┬─────┘  └──────┬───────┘  └────────┬──────────┘  │
│       │               │                   │              │
└───────┼───────────────┼───────────────────┼──────────────┘
        │               │                   │
   ┌────▼───────────────▼───────────────────▼────┐
   │           Base de datos del proyecto          │
   │  devices  │  modbus_servers  │  readings     │
   └────▲───────────────▲───────────────────▲────┘
        │               │                   │
   ┌────┴───────────────┴───────────────────┴────┐
   │           Código edge (en el dispositivo)     │
   │  registrar dispositivo → leer config → datos  │
   └──────────────────────────────────────────────┘

La base de datos del proyecto es la única fuente de verdad. El código edge escribe en ella, el board lee en tiempo real, y las acciones del usuario a través de formularios escriben de vuelta. Tu código edge puede suscribirse a esos cambios para cerrar el ciclo — sin necesidad de endpoints API personalizados.

Consejos

• Comienza con tablas de entidad. Haz que el registro de dispositivos y una tabla de estado funcionen antes de añadir recopilación de series temporales.
• Usa maintainLatestFlagFor en cualquier tabla donde necesites consultar el estado actual. Te permite añadir historial y volver a leer la fila más reciente de cada entidad — con el interruptor latest en un widget, o {"latest": true} en un filtro del SDK — sin código adicional.
• Añade una columna deleted a las tablas de entidad que los usuarios gestionan a través de formularios, para que los registros puedan eliminarse de forma lógica preservando el historial.
• Usa appendToTable para escrituras que necesiten confirmación (ej: registro inicial del dispositivo). Usa publishToTable para telemetría de alta frecuencia donde fire-and-forget es aceptable.
• Mantén las tablas de series temporales simples. Una marca de tiempo, un identificador de la fuente y los valores medidos. Usa tablas transform para agregaciones.

Próximos pasos

Si tu hardware expone una HMI web o interfaz de configuración, puedes integrarla directamente en tu board de IronFlock usando el widget Embed y los túneles de dispositivo. Consulta Integrar HMIs externas para más detalles.