SDK do IronFlock

O SDK do IronFlock permite que suas aplicações de borda interajam com a plataforma IronFlock. Ele cuida da autenticação automaticamente quando executado em um dispositivo registrado e fornece funções para publicar dados, consultar histórico, chamar procedimentos remotos entre dispositivos e atualizar os metadados do dispositivo.

Instalação

pip install ironflock

npm install ironflock

Início Rápido

import asyncio
from ironflock import IronFlock
 
async def main():
    while True:
        await ironflock.publish_to_table("sensordata", {
            "temperature": 22.5,
            "humidity": 60
        })
        await asyncio.sleep(5)
 
ironflock = IronFlock(mainFunc=main)
ironflock.run()

import { IronFlock } from "ironflock";
 
const ironflock = new IronFlock();
await ironflock.start();
 
setInterval(async () => {
    await ironflock.publishToTable("sensordata", [{
        temperature: 22.5,
        humidity: 60
    }]);
}, 5000);

Quando usado dentro de um contêiner de aplicação do IronFlock, o SDK lê as credenciais de conexão do ambiente automaticamente — nenhuma configuração manual é necessária.

Opções do Construtor

ironflock = IronFlock(
    mainFunc=main,           # async function to run after connecting
    serial_number="abc123"   # override device serial (optional)
)

const ironflock = new IronFlock({
    serialNumber: "abc123",    // device serial (env: DEVICE_SERIAL_NUMBER)
    deviceKey: "dev-key-1",    // device key (env: DEVICE_KEY)
    appName: "MyApp",          // app name (env: APP_NAME)
    swarmKey: 10,              // project key (env: SWARM_KEY)
    appKey: 20,                // app key (env: APP_KEY)
    env: "PROD",               // "DEV" or "PROD" (env: ENV)
});

Publicando Dados

publishToTable / publish_to_table

Publica um registro de dados em uma tabela da frota. O nome da tabela deve corresponder a uma tabela definida no data-template.yml da sua aplicação. O SDK roteia automaticamente os dados para o banco de dados correto do projeto.

await ironflock.publish_to_table("sensordata", {
    "temperature": 22.5,
    "humidity": 60,
    "device_id": "sensor-001"
})

await ironflock.publishToTable("sensordata", [{
    temperature: 22.5,
    humidity: 60,
    device_id: "sensor-001"
}]);

appendToTable / append_to_table

Acrescenta dados a uma tabela da frota usando uma chamada de procedimento remoto em vez de pub/sub. Use isto quando você precisar de confirmação de que os dados foram persistidos.

result = await ironflock.append_to_table("sensordata", {
    "temperature": 22.5,
    "humidity": 60
})

const result = await ironflock.appendToTable("sensordata", [{
    temperature: 22.5,
    humidity: 60
}]);

publishRowsToTable / publish_rows_to_table

Publica várias linhas em uma única mensagem (inserção em lote) em uma tabela da frota. A plataforma insere todo o lote atomicamente (tudo ou nada) em uma única operação. Use isto para dados de alta frequência, onde uma ida e volta por linha seria custosa demais. Assim como publishToTable, isto é fire-and-forget — a confirmação atesta a entrega ao roteador, não a inserção no banco de dados.

await ironflock.publish_rows_to_table("sensordata", [
    {"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
    {"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
])

await ironflock.publishRowsToTable("sensordata", [
    { tsp: "2024-01-15T10:30:00.000Z", temperature: 22.5 },
    { tsp: "2024-01-15T10:30:01.000Z", temperature: 22.7 },
]);

O segundo argumento é uma lista não vazia de objetos de linha a inserir.

appendRowsToTable / append_rows_to_table

Acrescenta várias linhas em uma única chamada de procedimento remoto (inserção em lote) a uma tabela da frota. A plataforma insere todo o lote atomicamente (tudo ou nada): se qualquer linha for inválida, todo o lote é rejeitado e nada é persistido. Prefira isto a publishRowsToTable / publish_rows_to_table quando você precisar do resultado da inserção.

result = await ironflock.append_rows_to_table("sensordata", [
    {"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
    {"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
])
# result -> {"success": True, "count": 2}

const result = await ironflock.appendRowsToTable("sensordata", [
    { tsp: "2024-01-15T10:30:00.000Z", temperature: 22.5 },
    { tsp: "2024-01-15T10:30:01.000Z", temperature: 22.7 },
]);
// result -> { success: true, count: 2 }

reportError / report_error

Reporta um erro da aplicação na tabela error-logs da sua frota. Isto é um invólucro de conveniência sobre publishToTable / appendToTable: ele carimba a linha com source: "app", um nível de severidade level e um timestamp, e então a escreve como qualquer linha de tabela normal. O erro chega na mesma tabela error-logs que os erros de sistema do fleetdb usam (marcados com source: "system"), de modo que ele pode ser consultado com getHistory, transmitido com subscribeToTable / subscribe_to_table, usado em board-templates e entregue em tempo real em transformed.error-logs — sem disparar o toast de erro de sistema da plataforma.

# Fire-and-forget (default): publishes to the error-logs table
await ironflock.report_error("Sensor read timed out", level="warn")
 
# Pass an exception to capture its traceback (falls back to the message)
try:
    risky_operation()
except Exception as err:
    await ironflock.report_error(err)
 
# Use the append RPC when you want to await the insert outcome
await ironflock.report_error("Calibration failed", level="error", append=True)

// Fire-and-forget (default): publishes to the error-logs table
await ironflock.reportError("Sensor read timed out", { level: "warn" });
 
// Pass an Error to capture its stack (falls back to the message)
try {
    riskyOperation();
} catch (err) {
    await ironflock.reportError(err);
}
 
// Use the append RPC when you want to await the insert outcome
await ironflock.reportError("Calibration failed", { level: "error", append: true });

Parâmetros:

Em Python as opções são argumentos nomeados (report_error(error, level=..., append=..., tsp=...)); em JavaScript elas são passadas via um objeto de opções (reportError(error, { level, append, tsp })).

publish

Publica uma mensagem em qualquer tópico WAMP. Use isto para mensagens ou eventos personalizados que não correspondem a uma tabela do banco de dados.

await ironflock.publish("com.myapp.alerts", {
    "level": "warning",
    "message": "Temperature threshold exceeded"
})

await ironflock.publish("com.myapp.alerts", [{
    level: "warning",
    message: "Temperature threshold exceeded"
}]);

Consultando Dados Históricos

getHistory

Recupera dados históricos de uma tabela da frota. Suporta filtragem, intervalos de tempo e paginação.

# Simple query
data = await ironflock.getHistory("sensordata", {"limit": 100})
 
# Query with time range and filters
data = await ironflock.getHistory("sensordata", {
    "limit": 500,
    "offset": 0,
    "timeRange": {
        "start": "2026-01-01T00:00:00Z",
        "end": "2026-03-01T00:00:00Z"
    },
    "filterAnd": [
        {"column": "temperature", "operator": ">", "value": 20},
        {"column": "humidity", "operator": "<=", "value": 80}
    ]
})
 
# Current value(s) only: the "latest" marker returns the newest row per entity
current = await ironflock.getHistory("sensordata", {
    "limit": 100,
    "filterAnd": [{"latest": True}]
})

// Simple query
const data = await ironflock.getHistory("sensordata", { limit: 100 });
 
// Query with time range and filters
const data = await ironflock.getHistory("sensordata", {
    limit: 500,
    offset: 0,
    timeRange: {
        start: "2026-01-01T00:00:00Z",
        end: "2026-03-01T00:00:00Z",
    },
    filterAnd: [
        { column: "temperature", operator: ">", value: 20 },
        { column: "humidity", operator: "<=", value: 80 },
    ],
});
 
// Current value(s) only: the `latest` marker returns the newest row per entity
const current = await ironflock.getHistory("sensordata", {
    limit: 100,
    filterAnd: [{ latest: true }],
});

Parâmetros da consulta:

Operadores de filtro: =, !=, >, <, >=, <=, LIKE, ILIKE, IN, NOT IN, IS, IS NOT

Cada filtro é um objeto com as chaves column, operator e value.

Lendo os valores atuais. Uma entrada {"latest": true} em filterAnd não é uma condição de filtro, e sim uma troca de modo: o backend de dados retorna apenas a linha mais recente de cada entidade, derivada em SQL a partir da chave de entidade que a tabela declara com maintainLatestFlagFor. Uma tabela sem chave de entidade retorna a sua única linha mais recente.

As demais condições se combinam com o marcador como você esperaria: condições sobre colunas da chave de entidade restringem quais entidades são retornadas, enquanto todas as outras condições e o timeRange são aplicados às linhas mais recentes resultantes. Assim, combinar {"latest": true} com um filtro de deleted oculta as entidades excluídas em vez de fazer a linha anterior delas reaparecer.

Versões anteriores do IronFlock armazenavam uma coluna física latest_flag. Ela não existe mais — um filtro legado latest_flag = true continua sendo aceito e tratado como o marcador, mas código novo deve usar {"latest": true}. O marcador latest não está disponível em getSeriesHistory.

getSeriesHistory / get_series_history

Recupera dados de séries temporais reduzidos (down-sampled) de uma tabela de frota: colunas numéricas agregadas em intervalos de tempo (por exemplo, médias por hora). Ideal para gráficos que abrangem longos intervalos de tempo. Disponível para tabelas (não para transforms).

series = await ironflock.get_series_history("sensordata", {
    "metrics": ["temperature", "humidity"],
    "method": "AVG",
    "limit": 500,
    "timeRange": ["2026-01-01T00:00:00Z", "2026-03-01T00:00:00Z"],
    "groupBy": ["device_id"]
})

const series = await ironflock.getSeriesHistory("sensordata", {
    metrics: ["temperature", "humidity"],
    method: "AVG",
    limit: 500,
    timeRange: ["2026-01-01T00:00:00Z", "2026-03-01T00:00:00Z"],
    groupBy: ["device_id"],
});

Parâmetros da consulta:

Inscrevendo-se em Dados

subscribeToTable / subscribe_to_table

Inscreve-se em atualizações em tempo real de uma tabela da frota. O handler é chamado sempre que novos dados são publicados na tabela. As linhas escritas pelo caminho de inserção em lote (publishRowsToTable / appendRowsToTable) são entregues ao seu handler uma de cada vez, de modo que o código do handler permanece o mesmo independentemente de como os dados foram escritos.

def on_sensor_data(*args, **kwargs):
    print("New reading:", args, kwargs)
 
await ironflock.subscribe_to_table("sensordata", on_sensor_data)

function onSensorData(...args) {
    console.log("New reading:", args);
}
 
await ironflock.subscribeToTable("sensordata", onSensorData);

subscribe

Inscreve-se em qualquer tópico WAMP para mensagens personalizadas em tempo real.

def on_alert(*args, **kwargs):
    print("Alert received:", args, kwargs)
 
await ironflock.subscribe("com.myapp.alerts", on_alert)

function onAlert(...args) {
    console.log("Alert received:", args);
}
 
await ironflock.subscribe("com.myapp.alerts", onAlert);

Acesso a Dados Entre Apps

Leia os dados de frota de outro app de dentro do seu próprio app, no mesmo projeto. O app provedor deve declarar o seu app na seção consumes: do seu data-template.yml, e o usuário do projeto deve conceder o acesso. O acesso é somente leitura: você pode consultar o histórico e se inscrever em tempo real nas linhas das tabelas e transforms que o provedor compartilha, mas não pode escrever nelas. As conexões com apps consumidos são armazenadas em cache por app e fechadas automaticamente quando a sua instância para.

Se o seu app possuir a concessão curinga (consumes: [{ app: "*" }]), você pode descobrir e abrir provedores dinamicamente com listConsumableApps / list_consumable_apps e connectToAllApps / connect_to_all_apps (abaixo).

connectToApp / connect_to_app

Abre uma conexão somente leitura ao backend de dados de outro app e retorna um handle. O handle expõe getHistory / get_history, subscribeToTable / subscribe_to_table e getSeriesHistory / get_series_history (apenas tabelas) — as mesmas consultas e inscrições que você usa nas suas próprias tabelas — além de close e dos catálogos compartilhados tables / transforms.

# Open a read-only handle on another app's data backend
weather = await ironflock.connect_to_app("weather-app")
 
# Inspect what the provider shares
print([t["tablename"] for t in weather.tables])
 
# Query history and subscribe, just like your own tables
rows = await weather.get_history("forecasts", {"limit": 100})
 
def on_forecast(*args, **kwargs):
    print("New forecast:", args)
 
await weather.subscribe_to_table("forecasts", on_forecast)

// Open a read-only handle on another app's data backend
const weather = await ironflock.connectToApp("weather-app");
 
// Inspect what the provider shares
console.log(weather.tables.map((t) => t.tablename));
 
// Query history and subscribe, just like your own tables
const rows = await weather.getHistory("forecasts", { limit: 100 });
 
await weather.subscribeToTable("forecasts", (...args) => {
    console.log("New forecast:", args);
});

Parâmetros:

Se o acesso for negado ou usado incorretamente, um CrossAppAccessError é levantado (Python) / lançado (JavaScript) com um campo code: NO_GRANT, PROVIDER_NOT_INSTALLED, UNKNOWN_APP, PRIVATE_TABLE ou NOT_AUTHORIZED.

Em Python, stage e on_error são argumentos nomeados; em JavaScript eles são passados via um objeto de opções (connectToApp(appName, { stage, onError })).

listConsumableApps / list_consumable_apps

Lista todos os provedores não privados do projeto — a primitiva de descoberta para apps que possuem a concessão de consumo curinga (consumes: [{ app: "*" }] no seu data-template.yml, concedida pelo usuário do projeto). Realiza uma única chamada e não abre nenhuma conexão: renderize os catálogos retornados em um seletor, então chame connectToApp / connect_to_app para os que você deseja — ou connectToAllApps / connect_to_all_apps para abrir todos de uma vez.

Nota: Declare a concessão no data-template.yml do seu app, e coloque o * entre aspas — um * sem aspas é um alias YAML e não será interpretado:

consumes:
  - app: "*"

providers = await ironflock.list_consumable_apps()
 
for p in providers:
    print(p["app"], list(p["stages"].keys()))  # e.g. "weather-app" ["dev", "prod"]

const providers = await ironflock.listConsumableApps();
 
for (const p of providers) {
    console.log(p.app, Object.keys(p.stages)); // e.g. "weather-app" ["dev", "prod"]
}

Cada entrada descreve um provedor:

Levanta (Python) / lança (JavaScript) um CrossAppAccessError com code: NO_GRANT se o seu app não possuir a concessão curinga.

connectToAllApps / connect_to_all_apps

Abre handles somente leitura para todos os provedores não privados do projeto em uma única chamada (apenas consumidores curinga). Enumera os provedores via listConsumableApps / list_consumable_apps e abre cada um, ignorando qualquer um sem um backend de dados para o stage solicitado. Cada handle é armazenado em cache sob a mesma chave que connectToApp / connect_to_app, de modo que uma chamada posterior a connectToApp(name) retorna o handle já aquecido. Os handles retornados são fechados em conjunto quando a sua instância para.

apps = await ironflock.connect_to_all_apps(
    on_error=lambda err: print("Provider skipped:", err)
)
 
for app in apps:
    rows = await app.get_history(app.tables[0]["tablename"], {"limit": 10})
    print(app.app, rows)

const apps = await ironflock.connectToAllApps({
    onError: (err) => console.warn("Provider skipped:", err),
});
 
for (const app of apps) {
    const rows = await app.getHistory(app.tables[0]?.tablename, { limit: 10 });
    console.log(app.app, rows);
}

Parâmetros:

Retorna os handles de provedor abertos com sucesso (o mesmo tipo de handle que connectToApp / connect_to_app). Levanta (Python) / lança (JavaScript) um CrossAppAccessError com code: NO_GRANT se o seu app não possuir a concessão curinga.

Em Python, stage, on_error e continue_on_error são argumentos nomeados; em JavaScript eles são passados via um objeto de opções (connectToAllApps({ stage, onError, continueOnError })).

Armazenamento Gerenciado de Arquivos

Todo backend de dados de app recebe um armazenamento de objetos privado ao lado das suas tabelas, acessível através da propriedade files. Use-o para imagens, PDFs, frames de câmera, blobs de firmware — qualquer coisa que não pertença a uma linha de tabela. Nenhuma configuração é necessária: um app sem uma seção files: no seu data template ainda recebe um namespace chamado default.

A ideia central é que armazenar um objeto lhe devolve uma URL permanente que você pode escrever diretamente em uma coluna de tabela, de modo que um widget de dashboard consiga renderizá-la sem nenhum trabalho adicional:

# Store an object and get a permanent URL back in the same call
info = await ironflock.files.put("part-1.jpg", jpeg_bytes, content_type="image/jpeg")
 
# The URL is safe to store in a table column — a dashboard widget can then
# render <img src="{{photo_url}}"> without any extra round trip
await ironflock.publish_to_table("inspections", part_id="1", photo_url=info.url)
 
# Read it back
data = await ironflock.files.get("part-1.jpg")
 
# Walk every object under a prefix (pages are fetched for you)
async for obj in ironflock.files.iter(prefix="2026/"):
    print(obj.key, obj.size)

// Store an object and get a permanent URL back in the same call
const info = await ironflock.files.put("part-1.jpg", jpegBytes, {
    contentType: "image/jpeg",
});
 
// The URL is safe to store in a table column — a dashboard widget can then
// render <img src="{{photo_url}}"> without any extra round trip
await ironflock.publishToTable("inspections", [{ part_id: "1", photo_url: info.url }]);
 
// Read it back
const data = await ironflock.files.get("part-1.jpg");
 
// Walk every object under a prefix (pages are fetched for you)
for await (const obj of ironflock.files.iterate({ prefix: "2026/" })) {
    console.log(obj.key, obj.size);
}

Essa URL nunca expira, mas ela não é um link público: ela permanece legível apenas para um solicitante autenticado que possua acesso READ neste backend de dados, e um proxy de autenticação reverifica isso a cada requisição. Por isso, ela é segura para armazenar no banco de dados.

Namespaces

Um namespace é um prefixo de chave que carrega política — retenção, regras de compartilhamento, tipos de conteúdo permitidos. Ele não é um bucket separado; todo namespace de um app vive dentro da única área de armazenamento daquele app. Declare um apenas quando um conjunto de objetos precisar de regras diferentes; caso contrário, permaneça em default e organize os seus objetos com caminhos de chave como 2026/03/part-1.jpg.

Declare namespaces adicionais no data-template.yml:

files:
  # Storage budget the app suggests for itself. The project user can change it,
  # and their setting is the one that gets enforced.
  quotaBytes: 5368709120
  namespaces:
    - name: frames
      description: Raw camera frames, one JPEG per inspected part.
      contentTypes: ["image/jpeg"]
      maxObjectBytes: 20971520
      retention: { deleteAfter: 30 days }

Note que o orçamento é declarado uma única vez para o app inteiro, e não por namespace. Um namespace é apenas um prefixo de chave dentro da única área de armazenamento do app, então não há nada contra o que um orçamento por prefixo pudesse ser imposto. maxObjectBytes é por namespace — ele limita um único objeto, não um total.

Todos os métodos abaixo aceitam o namespace como um argumento opcional e usam default como padrão.

Armazenando e lendo objetos

# Bytes in, bytes out
info = await ironflock.files.put("reports/march.pdf", pdf_bytes, content_type="application/pdf")
data = await ironflock.files.get("reports/march.pdf")
 
# Or straight from/to a local file — these stream on the large-object path,
# so a multi-gigabyte file never has to fit in memory
await ironflock.files.put_file("firmware/v2.bin", "/data/build/v2.bin")
await ironflock.files.get_to_file("firmware/v2.bin", "/tmp/v2.bin")

// Bytes in, bytes out — put/get work on Uint8Array in both Node and the browser
const info = await ironflock.files.put("reports/march.pdf", pdfBytes, {
    contentType: "application/pdf",
});
const data = await ironflock.files.get("reports/march.pdf");

O JavaScript não possui helpers de caminho de arquivo porque o pacote entrega um único build tanto para o Node quanto para o navegador — leia e escreva os arquivos locais você mesmo com fs.

put aceita: content_type / contentType (o tipo MIME; o namespace pode restringir quais são permitidos) e namespace. Em Python estes são argumentos nomeados; em JavaScript eles vão em um objeto de opções.

Listando e inspecionando

Os objetos são descritos pelos mesmos campos em ambos os SDKs, no estilo de nomenclatura de cada linguagem: namespace, key, size, etag, content_type / contentType, last_modified / lastModified, checksum_sha256 / checksumSha256 e url.

Uso de armazenamento e cota

usage responde a partir do object store em uma única chamada, então os totais são exatos em vez de somados pelo SDK:

u = await ironflock.files.usage()
print(u.size_bytes, u.object_count, u.quota_bytes, u.free_bytes)
 
# Break the total down per namespace (costs one listing per namespace)
detailed = await ironflock.files.usage(detail=True)
print(detailed.per_namespace)   # {"default": 1048576, "frames": 73400320}

const u = await ironflock.files.usage();
console.log(u.sizeBytes, u.objectCount, u.quotaBytes, u.freeBytes);
 
// Break the total down per namespace (costs one listing per namespace)
const detailed = await ironflock.files.usage({ detail: true });
console.log(detailed.perNamespace);   // { default: 1048576, frames: 73400320 }

O detalhamento por namespace vem desligado por padrão porque o store não consegue respondê-lo diretamente: ele contabiliza por área de armazenamento, e um namespace é apenas um prefixo, então o SDK precisa listar cada namespace para somar os tamanhos. Peça-o quando você quiser, não em um caminho crítico de desempenho.

Duas cotas diferentes aparecem, e vale a pena mantê-las separadas. catalog() reporta as duas:

Elas divergem sempre que um usuário aumentou ou diminuiu o orçamento do app, e é por isso que o valor imposto é lido do store em vez do template — reimplantar o app não pode redefinir silenciosamente a escolha de um usuário. Uma UI pode mostrar ambos (“o app sugere X, você definiu Y”). A imposição sempre usa o primeiro.

Compartilhando objetos

Existem dois tipos de link, e a diferença importa:

share_url / shareUrl é uma capacidade ao portador (bearer): entregue-o a uma pessoa que precise de acesso temporário, e não o armazene no banco de dados. Use url para qualquer coisa que um dashboard renderize.

url retorna None / undefined onde a implantação não possui uma borda HTTP (por exemplo, um appliance em HTTP puro) — esse é o sinal para recorrer a get. Passar o etag de um objeto como argumento version permite que os navegadores armazenem a resposta em cache de forma imutável.

upload_url / uploadUrl gera uma URL expirável que aceita um upload direto, retornando url, method, headers e expires_in / expiresIn. Envie exatamente os headers que ela retorna, ou a assinatura não será verificada.

Objetos grandes

O SDK escolhe o transporte pelo tamanho, automaticamente — não há nada para configurar:

O limite exato é reportado pelo servidor em tempo de execução como inline_max_bytes / inlineMaxBytes em catalog(), de modo que ele pode ser elevado sem um novo release do SDK.

Dois tetos permanecem, e ambos reportam TOO_LARGE com um motivo que nomeia qual deles você atingiu:

• 5 GiB — o limite de upload único do armazenamento de objetos. O upload multipart ainda não foi implementado.
• O limite inline, onde não há endpoint direto — um appliance isolado (air-gapped) não consegue transferir um objeto grande de forma alguma. Nenhuma nova tentativa nem chunk menor vai ajudar, e a mensagem diz isso.

O caminho direto exige que o dispositivo alcance o host do armazenamento de objetos, não apenas o roteador. Duas falhas comuns em campo recebem os seus próprios códigos em vez de parecerem problemas de autorização: PRESIGN_UNREACHABLE (um proxy que permite apenas o roteador) e CLOCK_SKEW (o armazenamento de objetos rejeita requisições com mais de 15 minutos de defasagem — verifique o NTP no dispositivo).

Erros de armazenamento de arquivos

Toda operação de arquivo levanta (Python) / lança (JavaScript) um FileStoreError que carrega um code estável e um reason legível por humanos. Ramifique pelo code, nunca pelo reason.

from ironflock.filestore import FileStoreError
 
try:
    await ironflock.files.put("huge.bin", payload)
except FileStoreError as e:
    if e.code == "QUOTA_EXCEEDED":
        print("Filestore is full:", e.reason)
    else:
        raise

import { FileStoreError } from "ironflock";
 
try {
    await ironflock.files.put("huge.bin", payload);
} catch (e) {
    if (e instanceof FileStoreError && e.code === "QUOTA_EXCEEDED") {
        console.error("Filestore is full:", e.reason);
    } else {
        throw e;
    }
}

Um servidor mais novo pode introduzir códigos que este release do SDK não conhece. Eles são repassados como code em vez de serem colapsados, portanto trate um valor não reconhecido como uma falha genérica.

Em Python, FileStoreError é importado de ironflock.filestore; em JavaScript ele é exportado a partir da raiz do pacote (import { FileStoreError } from "ironflock").

Comunicação Entre Dispositivos

registerDeviceFunction / register_device_function

Registra um procedimento que outros dispositivos no mesmo projeto podem chamar. O SDK automaticamente atribui um namespace ao procedimento para o dispositivo atual.

def add(a, b):
    return a + b
 
await ironflock.register_device_function("com.myapp.add", add)

function add(args) {
    return args[0] + args[1];
}
 
await ironflock.registerDeviceFunction("com.myapp.add", add);

callDeviceFunction / call_device_function

Chama um procedimento registrado por outro dispositivo. O SDK monta o tópico WAMP completo automaticamente usando a chave do dispositivo de destino.

result = await ironflock.call_device_function(
    42,                        # target device key
    "com.myapp.add",           # procedure name
    args=[3, 5]                # arguments
)
print(result)  # 8

const result = await ironflock.callDeviceFunction(
    42,                        // target device key
    "com.myapp.add",           // procedure name
    [3, 5]                     // arguments
);
console.log(result);  // 8

call

Chama um procedimento remoto usando um URI WAMP completo. Use isto para chamadas diretas quando você conhece o tópico exato.

result = await ironflock.call("some.full.wamp.topic", args=[42])

const result = await ironflock.call("some.full.wamp.topic", [42]);

Metadados do Dispositivo

setDeviceLocation / set_device_location

Atualiza a localização GPS do dispositivo na plataforma. As alterações são refletidas em tempo real nos mapas do IronFlock.

await ironflock.set_device_location(long=8.6821, lat=50.1109)

await ironflock.setDeviceLocation(8.6821, 50.1109);

O histórico de localização não é armazenado. Para rastrear a localização ao longo do tempo, crie uma tabela dedicada e use publish_to_table / publishToTable.

getRemoteAccessUrlForPort

Retorna a URL pública de acesso remoto para uma determinada porta no dispositivo.

url = ironflock.getRemoteAccessUrlForPort(8080)
# "https://<device_key>-<app_name>-8080.app.ironflock.com"

const url = ironflock.getRemoteAccessUrlForPort(8080);
// "https://<device_key>-<app_name>-8080.app.ironflock.com"

Propriedades de Conexão e Ciclo de Vida

Tratamento de Erros

Todo método do SDK falha de forma explícita: diante de argumentos inválidos, de uma conexão perdida ou de uma rejeição da plataforma, ele levanta uma exceção (Python) ou rejeita (JavaScript) com uma mensagem que nomeia a operação, o tópico e o motivo. Nada é silenciosamente engolido, portanto envolva em um bloco try as chamadas que você deseja que sobrevivam.

try:
    rows = await ironflock.getHistory("sensordata", {"limit": 100})
except ValueError as e:
    # Invalid parameters — e.g. limit out of range, or a malformed filter
    print(f"Bad query: {e}")
except RuntimeError as e:
    # Not connected, table not in the data-template, or the platform rejected the call
    print(f"Query failed: {e}")

import { WampError } from "ironflock";
 
try {
    const rows = await ironflock.getHistory("sensordata", { limit: 100 });
} catch (e) {
    if (e instanceof WampError) {
        // Rejected by the platform — e.error holds the WAMP error URI
        console.error(`Query rejected: ${e.error}`, e.args);
    } else {
        // Invalid parameters, or no connection
        console.error(`Query failed: ${e.message}`);
    }
}

Em JavaScript, as falhas provenientes da plataforma são instâncias de WampError — uma subclasse normal de Error que adicionalmente carrega o URI de erro WAMP em error e a carga do erro em args / kwargs. Todo o restante (parâmetros inválidos, ausência de conexão) é um Error comum.

Migrando: versões mais antigas do SDK registravam uma mensagem e retornavam None / null quando uma chamada falhava. Agora elas levantam o erro, de modo que código no formato if result is None: não detecta mais as falhas — use try / except (ou try / catch).

Uso no Navegador (apenas JavaScript)

O SDK em JavaScript funciona em navegadores modernos. Como os navegadores não possuem variáveis de ambiente, passe toda a configuração pelo construtor:

import { IronFlock } from "ironflock";
 
const ironflock = new IronFlock({
    serialNumber: "device-serial-from-server",
    deviceKey: "my-device-key",
    appName: "MyWebApp",
    swarmKey: 10,
    appKey: 20,
    env: "PROD",
});
 
await ironflock.start();
await ironflock.publishToTable("sensordata", [{ temperature: 22 }]);

Use IronFlock.fromServer() para buscar a configuração do seu backend em vez de embutir as credenciais no código:

const ironflock = await IronFlock.fromServer("/api/ironflock-config");
await ironflock.start();

O endpoint do seu backend deve retornar um objeto JSON com as opções de conexão (serialNumber, deviceKey, appName, swarmKey, appKey, env).

Registrando Funções para Agentes de IA

O SDK pode registrar funções que podem ser chamadas por agentes de IA. Registre um procedimento e referencie o seu tópico no seu ai-template.yml:

def get_sensor_reading(sensor_id):
    """Returns the latest reading from a sensor."""
    reading = read_from_hardware(sensor_id)
    return {
        "sensor_id": sensor_id,
        "temperature": reading.temp,
        "humidity": reading.hum,
        "timestamp": reading.ts
    }
 
await ironflock.register_device_function("sensors.get_latest", get_sensor_reading)

function getSensorReading(args, kwargs) {
    const sensorId = kwargs.sensor_id;
    const reading = readFromHardware(sensorId);
    return {
        sensor_id: sensorId,
        temperature: reading.temp,
        humidity: reading.hum,
        timestamp: reading.ts,
    };
}
 
await ironflock.registerDeviceFunction("sensors.get_latest", getSensorReading);

O agente de IA pode então chamar esta função quando um usuário fizer uma pergunta que exija dados de sensor ao vivo.

Para conectar o tópico WAMP registrado a um agente de IA, referencie-o no .ironflock/ai-template.yml da sua aplicação:

sensor_agent:
    tool_description: |
        Delegate to this agent when the user asks about sensor readings,
        live device data, or current environmental conditions.
 
    system_prompt: |
        You are a sensor data specialist. Use get_current to retrieve
        the latest reading from any sensor. Always include the unit in
        your response.
 
    main: true
    max_context_tokens: 30000
    max_iterations: 5
 
    tools:
        get_current:
            description: Returns the latest reading from a sensor.
            topic: sensors.get_latest
            parameters:
                sensor_id:
                    type: string
                    description: The sensor identifier to query.
                    required: true

O valor de topic (sensors.get_latest) deve corresponder ao nome passado para register_device_function / registerDeviceFunction no seu código de borda. O IronFlock roteia automaticamente a chamada para o dispositivo onde a função está registrada.

Para a referência completa do ai-template.yml, consulte Definindo Agentes e Ferramentas.

Variáveis de Ambiente

Estas variáveis são definidas automaticamente pelo runtime do IronFlock dentro dos contêineres de aplicação:

import os
 
device_name = os.environ.get("DEVICE_NAME")
serial = os.environ.get("DEVICE_SERIAL_NUMBER")
project_key = os.environ.get("SWARM_KEY")

const deviceName = process.env.DEVICE_NAME;
const serial = process.env.DEVICE_SERIAL_NUMBER;
const projectKey = process.env.SWARM_KEY;