Crie Seu Primeiro App

Este guia apresenta o fluxo de trabalho típico para construir um app IronFlock que coleta dados de dispositivos de borda e os exibe em dashboards em tempo real. Ao final, você terá um modelo de dados, lógica de borda, um formulário de configuração para usuários e gráficos ao vivo — tudo conectado através do banco de dados do projeto.

1. Projete o Modelo de Dados

Comece no arquivo .ironflock/data-template.yml. Pense em duas categorias de tabelas:

• Tabelas de entidade — rastreiam o estado atual das coisas (dispositivos, máquinas, conexões). Linhas são adicionadas a cada mudança; maintainLatestFlagFor declara quais colunas identificam uma entidade, para que a linha mais recente de cada entidade possa ser lida quando necessário.
• Tabelas de séries temporais — coletam medições ao longo do tempo (leituras de sensores, métricas). Cada linha é um novo ponto de dados com timestamp.

data:
  tables:
    # Tabela de entidade: uma linha por dispositivo, estado atual sempre consultável
    - 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
 
    # Tabela de entidade: servidores Modbus configurados pelo usuário
    - 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
 
    # Tabela de séries temporais: leituras periódicas do hardware conectado
    - tablename: readings
      columns:
        - id: tsp
          dataType: timestamp
        - id: server_id
          dataType: string
        - id: metric
          dataType: string
        - id: value
          dataType: numeric

2. Configure um Ambiente de Teste

Para testar seu app, você precisa de um ambiente de desenvolvimento em um projeto com pelo menos um dispositivo online:

1. Clique em Develop na página de detalhes do app para abrir o Cloud IDE.

2. Escolha um dispositivo online de qualquer projeto ao qual você tenha acesso.

3. Clique em Create Backend no painel lateral para criar um ambiente de desenvolvimento no banco de dados do projeto.

Isso cria as tabelas definidas no seu data-template.yml dentro do banco de dados do projeto. Você pode inspecioná-las na visualização Fleet Database do projeto.

O Cloud IDE oferece um ambiente VS Code completo com explorador de arquivos, editor, terminal e o painel Edge Development para compilar e implantar no seu dispositivo.

3. Escreva o Código de Borda

Seu contêiner Docker roda no dispositivo e usa o SDK do IronFlock para interagir com o banco de dados do projeto.

Registre o dispositivo na inicialização

Quando o componente de borda inicia, adicione uma linha à tabela de entidade devices para que o dashboard saiba que o dispositivo está online:

import asyncio
from ironflock import IronFlock
 
async def main():
    # Registrar este dispositivo como 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
    })
 
    # ... resto da lógica
 
flock = IronFlock(mainFunc=main)
flock.run()

import { IronFlock } from "ironflock";
 
const flock = new IronFlock();
await flock.start();
 
// Registrar este dispositivo como 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
}]);

Como devices usa maintainLatestFlagFor: ['device_key'], a linha de status anterior deste dispositivo é automaticamente substituída. Widgets com o filtro latest ativado sempre mostram o estado atual.

Reaja à configuração do usuário

Usuários podem adicionar servidores Modbus através de um formulário no board (veja passo 4). Seu código de borda se inscreve na tabela modbus_servers e age sobre novas entradas:

async def main():
    # ... registro do dispositivo ...
 
    # Ler servidores Modbus existentes
    existing = await flock.getHistory("modbus_servers", {
        "limit": 1000,
        "filterAnd": [
            # "latest": True retorna apenas a linha mais recente de cada server_id
            {"latest": True},
            {"column": "deleted", "operator": "IS", "value": None}
        ]
    })
    for server in existing:
        create_modbus_connection(server)
 
    # Reagir a novos servidores em tempo 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)

// Ler servidores Modbus existentes
const existing = await flock.getHistory("modbus_servers", {
    limit: 1000,
    filterAnd: [
        // latest: true retorna apenas a linha mais recente de cada server_id
        { latest: true },
        { column: "deleted", operator: "IS", value: null }
    ]
});
existing.forEach(server => createModbusConnection(server));
 
// Reagir a novos servidores em tempo real
await flock.subscribeToTable("modbus_servers", (...args) => {
    const server = args[0];
    if (server.deleted) {
        deleteModbusConnection(server.server_id);
    } else {
        createModbusConnection(server);
    }
});

Colete dados de séries temporais

Uma vez estabelecida uma conexão Modbus, consulte periodicamente e grave as leituras na tabela 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. Construa o Board

Abra o Board Editor e adicione widgets conectados às tabelas do seu Data Backend.

Mostre o status dos dispositivos

Adicione um widget Table conectado à tabela devices. Ative o interruptor latest nas configurações de filtro do widget para que ele sempre mostre o estado atual de cada dispositivo. A tabela atualiza automaticamente quando um dispositivo fica online ou offline.

Permita que usuários configurem servidores Modbus

Adicione um widget Form conectado à tabela modbus_servers. Configure campos para host e port. Quando um usuário preenche o formulário e envia, uma nova linha é inserida automaticamente na tabela modbus_servers — sem necessidade de código backend para processar o envio do formulário.

Seu código de borda detecta a nova linha via subscribeToTable (veja passo 3) e estabelece a conexão Modbus.

Visualize dados de séries temporais

Adicione um widget Line Chart conectado à tabela readings. Mapeie tsp para o eixo X e value para o eixo Y. O gráfico atualiza em tempo real conforme novas leituras chegam dos dispositivos — sem polling ou atualização manual.

Como Tudo se Encaixa

┌─────────────────────────────────────────────────────────┐
│  Board (Dashboard)                                      │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ Table    │  │ Form            │  │ Line Chart        │  │
│  │ devices  │  │ modbus_servers  │  │ readings          │  │
│  └────┬─────┘  └──────┬───────┘  └────────┬──────────┘  │
│       │               │                   │              │
└───────┼───────────────┼───────────────────┼──────────────┘
        │               │                   │
   ┌────▼───────────────▼───────────────────▼────┐
   │           Banco de Dados do Projeto           │
   │  devices  │  modbus_servers  │  readings     │
   └────▲───────────────▲───────────────────▲────┘
        │               │                   │
   ┌────┴───────────────┴───────────────────┴────┐
   │           Código de Borda (no dispositivo)    │
   │  registrar dispositivo → ler config → dados   │
   └──────────────────────────────────────────────┘

O banco de dados do projeto é a única fonte da verdade. O código de borda escreve nele, o board lê em tempo real, e ações do usuário via formulários escrevem de volta. Seu código de borda pode se inscrever nessas mudanças para fechar o ciclo — sem necessidade de endpoints de API personalizados.

Dicas

• Comece com tabelas de entidade. Faça o registro de dispositivos e uma tabela de status funcionarem antes de adicionar coleta de séries temporais.
• Use maintainLatestFlagFor em qualquer tabela onde você precise consultar o estado atual. Permite adicionar histórico e ler de volta a linha mais recente de cada entidade — com o interruptor latest em um widget, ou {"latest": true} em um filtro do SDK — sem código extra.
• Adicione uma coluna deleted a tabelas de entidade que usuários gerenciam via formulários, para que registros possam ser excluídos logicamente preservando o histórico.
• Use appendToTable para escritas que precisam de confirmação (ex: registro inicial do dispositivo). Use publishToTable para telemetria de alta frequência onde fire-and-forget é aceitável.
• Mantenha tabelas de séries temporais simples. Um timestamp, um identificador da fonte e os valores medidos. Use tabelas transform para agregações.

Próximos Passos

Se seu hardware expõe uma HMI web ou interface de configuração, você pode incorporá-la diretamente no seu board IronFlock usando o widget Embed e túneis de dispositivo. Veja Incorporando HMIs Externas para detalhes.