Crea la Tua Prima App

Questa guida illustra il tipico flusso di lavoro per costruire un’app IronFlock che raccoglie dati dai dispositivi edge e li visualizza su dashboard in tempo reale. Al termine avrai un modello dati, la logica edge, un form di configurazione per l’utente e grafici live — tutto collegato attraverso il database del progetto.

1. Progetta il Modello Dati

Inizia nel file .ironflock/data-template.yml. Pensa a due categorie di tabelle:

• Tabelle entità — tracciano lo stato corrente degli oggetti (dispositivi, macchine, connessioni). Le righe vengono aggiunte ad ogni modifica; maintainLatestFlagFor dichiara quali colonne identificano un’entità, in modo che la riga più recente di ogni entità possa essere riletta su richiesta.
• Tabelle time-series — raccolgono misurazioni nel tempo (letture sensori, metriche). Ogni riga è un nuovo punto dati con un timestamp.

data:
  tables:
    # Entity table: one row per device, latest state always queryable
    - 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
 
    # Entity table: user-configured Modbus servers
    - 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
 
    # Time-series table: periodic readings from connected hardware
    - tablename: readings
      columns:
        - id: tsp
          dataType: timestamp
        - id: server_id
          dataType: string
        - id: metric
          dataType: string
        - id: value
          dataType: numeric

2. Configura un Ambiente di Test

Per testare la tua app hai bisogno di un ambiente di sviluppo in un progetto con almeno un dispositivo online:

1. Fai clic su Develop nella pagina di dettaglio dell’app per aprire il Cloud IDE.

2. Scegli un dispositivo online da qualsiasi progetto a cui hai accesso.

3. Fai clic su Create Backend nel pannello laterale per creare un ambiente di sviluppo nel database di quel progetto.

Questo crea le tabelle definite nel tuo data-template.yml nel database del progetto. Puoi ispezionarle nella vista Fleet Database del progetto.

Il Cloud IDE ti offre un ambiente VS Code completo con file explorer, editor, terminale e il pannello Edge Development per build e distribuzione sul dispositivo.

3. Scrivi il Codice Edge

Il tuo container Docker gira sul dispositivo e usa l’IronFlock SDK per interagire con il database del progetto.

Registra il dispositivo all’avvio

Quando il componente edge si avvia, aggiungi una riga alla tabella entità devices in modo che la dashboard sappia che il dispositivo è online:

import asyncio
from ironflock import IronFlock
 
async def main():
    # Register this device as online
    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
    })
 
    # ... rest of your logic
 
flock = IronFlock(mainFunc=main)
flock.run()

import { IronFlock } from "ironflock";
 
const flock = new IronFlock();
await flock.start();
 
// Register this device as online
await flock.appendToTable("devices", [{
    device_key: process.env.DEVICE_KEY,
    tsp: new Date().toISOString(),
    status: "online",
    device_name: process.env.DEVICE_NAME,
    deleted: false
}]);

Poiché devices usa maintainLatestFlagFor: ['device_key'], la riga di stato precedente per questo dispositivo viene automaticamente superata. I widget con il filtro latest attivo mostrano sempre lo stato corrente.

Reagisci alla configurazione utente

Gli utenti possono aggiungere server Modbus tramite un form sulla dashboard (vedi step 4). Il codice edge si iscrive alla tabella modbus_servers e agisce sulle nuove voci:

async def main():
    # ... device registration ...
 
    # Read existing Modbus servers
    existing = await flock.getHistory("modbus_servers", {
        "limit": 1000,
        "filterAnd": [
            # "latest": True returns only the newest row per server_id
            {"latest": True},
            {"column": "deleted", "operator": "IS", "value": None}
        ]
    })
    for server in existing:
        create_modbus_connection(server)
 
    # React to new servers in real time
    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)

// Read existing Modbus servers
const existing = await flock.getHistory("modbus_servers", {
    limit: 1000,
    filterAnd: [
        // latest: true returns only the newest row per server_id
        { latest: true },
        { column: "deleted", operator: "IS", value: null }
    ]
});
existing.forEach(server => createModbusConnection(server));
 
// React to new servers in real time
await flock.subscribeToTable("modbus_servers", (...args) => {
    const server = args[0];
    if (server.deleted) {
        deleteModbusConnection(server.server_id);
    } else {
        createModbusConnection(server);
    }
});

Raccogli dati time-series

Una volta stabilita una connessione Modbus, esegui un polling periodico e scrivi le letture nella tabella 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. Costruisci la Dashboard

Apri il Board Editor e aggiungi widget che si collegano alle tabelle del tuo Data Backend.

Mostra lo stato dei dispositivi

Aggiungi un widget Table collegato alla tabella devices. Attiva l’interruttore latest nelle impostazioni del filtro del widget in modo che mostri sempre lo stato corrente di ogni dispositivo. La tabella si aggiorna automaticamente quando un dispositivo va online o offline.

Permetti agli utenti di configurare i server Modbus

Aggiungi un widget Form collegato alla tabella modbus_servers. Configura i campi per host e port. Quando un utente compila il form e lo invia, una nuova riga viene inserita automaticamente nella tabella modbus_servers — nessun codice backend necessario per gestire l’invio del form.

Il tuo codice edge riceve la nuova riga tramite subscribeToTable (vedi step 3) e stabilisce la connessione Modbus.

Visualizza dati time-series

Aggiungi un widget Line Chart collegato alla tabella readings. Mappa tsp sull’asse X e value sull’asse Y. Il grafico si aggiorna in tempo reale man mano che arrivano nuove letture dai dispositivi — senza polling o aggiornamenti manuali.

Come Si Incastra Tutto

┌─────────────────────────────────────────────────────────┐
│  Dashboard                                               │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ Tabella  │  │ Form            │  │ Grafico Lineare │  │
│  │ devices  │  │ modbus_servers  │  │ readings       │  │
│  └────┬─────┘  └──────┬───────┘  └────────┬──────────┘  │
│       │               │                   │             │
└───────┼───────────────┼───────────────────┼─────────────┘
        │               │                   │
   ┌────▼───────────────▼───────────────────▼────┐
   │           Database del Progetto                  │
   │  devices  │  modbus_servers  │  readings    │
   └────▲───────────────▲───────────────────▲────┘
        │               │                   │
   ┌────┴───────────────┴───────────────────┴────┐
   │           Codice Edge (sul dispositivo)             │
   │  registra dispositivo → legge config → polling dati  │
   └─────────────────────────────────────────────┘

Il database del progetto è l’unica fonte di verità. Il codice edge scrive su di esso, la dashboard lo legge in tempo reale e le azioni degli utenti tramite i form vi riscrivono. Il tuo codice edge può iscriversi a queste modifiche per chiudere il ciclo — nessun endpoint API personalizzato necessario.

Suggerimenti

• Inizia con le tabelle entità. Fai funzionare la registrazione del dispositivo e una tabella di stato prima di aggiungere la raccolta time-series.
• Usa maintainLatestFlagFor su qualsiasi tabella in cui devi interrogare lo stato corrente. Ti permette di appendere la cronologia e rileggere l’ultima riga di ogni entità — con l’interruttore latest su un widget, oppure {"latest": true} in un filtro dell’SDK — senza codice aggiuntivo.
• Aggiungi una colonna deleted alle tabelle entità che gli utenti gestiscono tramite form, così i record possono essere soft-deleted preservando la cronologia.
• Usa appendToTable per le scritture che necessitano di conferma (es. registrazione iniziale del dispositivo). Usa publishToTable per la telemetria ad alta frequenza dove il fire-and-forget è accettabile.
• Mantieni semplici le tabelle time-series. Un timestamp, un identificatore della sorgente e i valori misurati. Usa le tabelle di trasformazione per l’aggregazione.

Prossimi Passi

Se il tuo hardware espone una HMI web o un’interfaccia di configurazione, puoi incorporarla direttamente nella tua dashboard IronFlock usando il widget Embed e i tunnel del dispositivo. Vedi Incorporare HMI Esterni per i dettagli.