TECHRIB IOT CLOUD · CENTRAL PARA DESENVOLVEDORES

Do código ESP-IDF ao componente no aplicativo

Aprenda a estruturar seu próprio firmware, declarar componentes compatíveis com o contrato TechRib V2, implementar estados e comandos e entender o pareamento por QR Code e Bluetooth. Exemplos públicos e independentes, sem distribuir o firmware proprietário.

Iniciar tutorial Explorar 64 tipos Ver pareamento

Base técnica: contrato TechRib V2 2.0.0 · ESP-IDF 5.x · referências de firmware e aplicativo de outubro de 2026. Exemplos são didáticos; integração completa exige autorização e homologação.

01 · VISÃO GERAL

Entenda as camadas da integração

Uma placa compatível executa um firmware ESP-IDF que controla seu próprio hardware e anuncia somente os componentes existentes. A TechRib Cloud valida a identidade, recebe o inventário e os estados, e expõe os controles autorizados ao app Flutter e ao dashboard.

Dispositivo ESP32Firmware, GPIO, sensores, MQTT/TLS, BLE e identidade

↕

TechRib IoT CloudAutorização, catálogo V2, estados, comandos

↕

App e dashboardCards gerados por tipo, estado e permissões

Contrato não é driver: um tipo como energy_meter está definido no catálogo, mas seu firmware precisa implementar a aquisição física e validar as medições. O catálogo impede comandos não declarados; o backend também deve autorizá-los.

02 · AMBIENTE

Crie um projeto ESP-IDF do zero

Instale o ESP-IDF 5.x e a extensão oficial no VS Code. Escolha o alvo compatível com seu chip e inicie com um projeto vazio. Compile primeiro sem acionamento físico.

ESTRUTURA

meu_dispositivo/
├── CMakeLists.txt
├── main/
│   ├── CMakeLists.txt
│   ├── app_main.c
│   ├── board_profile.c     # Tipos e identificadores do hardware
│   ├── board_profile.h
│   └── cloud_bridge.c      # Integração MQTT/TLS autorizada
└── sdkconfig.defaults

TERMINAL

# Terminal ESP-IDF configurado (ESP32 clássico)
idf.py set-target esp32
idf.py menuconfig
idf.py build
# Para ESP32-S3, use set-target esp32s3 em um projeto adequado.

Para estudar a construção do perfil, comece com IDs estáveis (luz_sala, rgb_sala, temperatura_1). O driver deve registrar estado inicial conhecido e reagir somente a comandos declarados. Identidade autorizada, certificados, BLE/QR e registro no servidor não surgem automaticamente de um projeto vazio.

// Modelo didático: declaração própria, sem integrar ainda ao broker.
typedef struct {
    const char *id;
    const char *type;
    const char *name;
} my_component_t;

static const my_component_t components[] = {
    {"luz_sala", "switch", "Luz da sala"},
    {"rgb_sala", "light_rgb", "Fita RGB"},
    {"temp_1", "temperature", "Temperatura"}
};
// Próxima fase: criar manifesto, drivers, validações e transporte.

03 · PRIMEIRO ACESSO

Pareamento por QR Code e Bluetooth: experiência TechRib

O fluxo de experiência segue boas práticas de provisionamento BLE, como as explicadas na documentação ESP RainMaker, porém o formato do QR e a ativação são específicos da TechRib. Um QR do RainMaker não é aceito como QR TechRib.

Prepare a conta: a empresa e o usuário precisam ter acesso autorizado à plataforma.
Coloque a placa em modo de pareamento: o firmware anuncia BLE com o nome previsto para a família ESP32.
Abra a inclusão de dispositivos no app: habilite Bluetooth e as permissões solicitadas pelo Android.
Escaneie o QR oficial da TechRib: o aplicativo valida o protocolo, o host de ativação, a identidade BLE e o PoP.
Escolha a rede Wi-Fi e forneça a senha no aplicativo: a sessão BLE com Security 1 transporta o provisionamento; a rede precisa ser compatível com o chip.
Aguarde a conexão e a aprovação: o dispositivo se apresenta à nuvem, a solicitação é validada e o app acompanha o estado de ativação.
Confira os componentes: após manifesto e estados válidos, os cards podem aparecer no dashboard e no aplicativo.

Formato ilustrativo de QR V2

O app atual aceita o protocolo techrib-pairing-v2 com transport: ble e security: 1. A URL de ativação usa HTTPS no domínio administrativo e um código temporário emitido legitimamente pelo servidor; o exemplo abaixo contém um marcador fictício que não ativa nenhum dispositivo.

JSON (DIDÁTICO — NÃO UTILIZAR PARA ATIVAÇÃO)

{
  "ver": "v2",
  "name": "TechRibESP32S3DEMO",
  "pop": "0123456789abcdef",
  "transport": "ble",
  "security": 1,
  "techrib": {
    "protocol": "techrib-pairing-v2",
    "activation_url": "https://admin.iot.techrib.com.br/ativar?c=00000000000000000000000000000000",
    "ble_active": true,
    "board_family": "esp32-s3"
  }
}

A verificação do servidor é indispensável: conhecer o QR não confere acesso automaticamente. O exemplo não substitui a emissão de identidade e de código pela infraestrutura TechRib. Em placas já provisionadas pode existir apenas a URL de ativação, conforme o fluxo autorizado.

04 · PROTOCOLO

Os tópicos MQTT e o envelope TechRib V2

O firmware universal do pacote utiliza techrib.capabilities, versão 2.0.0. Os tópicos seguem o identificador legítimo do dispositivo, e a comunicação remota usa MQTT com TLS e credenciais provisionadas.

MQTT

techrib/devices/SEU_DEVICE_ID/telemetry      # manifesto
techrib/devices/SEU_DEVICE_ID/state          # estado real
techrib/devices/SEU_DEVICE_ID/event          # ACK e eventos
techrib/devices/SEU_DEVICE_ID/availability   # disponibilidade
techrib/devices/SEU_DEVICE_ID/command        # comandos de entrada

Os exemplos usam identificadores fictícios. Mensagens V2 são envelopes com contract, version, message_id, device_id, kind, timestamp e payload. Algumas mensagens também exigem component_id ou correlation_id.

05 · INVENTÁRIO

Como o aplicativo descobre os componentes

Cada item do manifesto possui ID estável, tipo presente no catálogo, nome, transporte e somente os comandos realmente suportados. A identidade do componente não deve mudar entre reinicializações.

JSON

{
  "contract": "techrib.capabilities",
  "version": "2.0.0",
  "message_id": "manifest_demo_001",
  "device_id": "ESP32_DEMO_01",
  "kind": "manifest",
  "timestamp": "2026-10-30T18:00:00Z",
  "payload": {
    "contract": "techrib.capabilities",
    "version": "2.0.0",
    "device_id": "ESP32_DEMO_01",
    "hardware": {"model": "ESP32 demo", "firmware_version": "1.0.0"},
    "components": [
      {"id":"luz_sala","type":"switch","name":"Luz da sala",
       "transport":"local","commands":["set_power"]},
      {"id":"rgb_sala","type":"light_rgb","name":"RGB sala",
       "transport":"local","commands":["set_power","set_rgb","set_brightness"]},
      {"id":"temp_1","type":"temperature","name":"Temperatura",
       "transport":"wired","commands":[]}
    ]
  }
}

O backend confere o manifesto contra o catálogo V2 e as permissões. Componentes repetidos precisam ter IDs distintos, por exemplo rgb_sala e rgb_quarto; o mesmo vale para sensores.

06 · TELEMETRIA

Publicação de estados e leitura dos sensores

O estado representa o que foi observado ou confirmado pelo dispositivo, não uma previsão da interface. Relatórios devem usar campos e unidades definidos no catálogo.

JSON

{
  "contract": "techrib.capabilities",
  "version": "2.0.0",
  "message_id": "state_temp_001",
  "device_id": "ESP32_DEMO_01",
  "kind": "state",
  "component_id": "temp_1",
  "timestamp": "2026-10-30T18:00:10Z",
  "payload": {"state": {"temperature_c": 24.6}, "quality": "valid"}
}

Repita o padrão para outros componentes, trocando component_id e campos de state. Quando um comando altera uma saída, publique o estado resultante com correlation_id quando disponível.

07 · CONTROLE

Validar, executar, confirmar

O backend pode enviar um comando somente se o tipo e o manifesto o permitirem. O firmware precisa verificar o destino, a data, o message_id, a ação e os argumentos; rejeitar mensagens antigas ou duplicadas; e manter a proteção local independente da internet.

JSON

{
  "contract": "techrib.capabilities",
  "version": "2.0.0",
  "message_id": "cmd_000001",
  "device_id": "ESP32_DEMO_01",
  "kind": "command",
  "component_id": "luz_sala",
  "timestamp": "2026-10-30T18:00:00Z",
  "payload": {"command": "set_power", "args": {"power": true}}
}

A confirmação do firmware usa kind: ack, status accepted, executed ou failed, e correlação com o message_id do comando. ACK aceito não significa que a saída foi acionada.

JSON

{
  "contract": "techrib.capabilities",
  "version": "2.0.0",
  "message_id": "ack_000001",
  "device_id": "ESP32_DEMO_01",
  "kind": "ack",
  "component_id": "luz_sala",
  "correlation_id": "cmd_000001",
  "status": "executed",
  "timestamp": "2026-10-30T18:00:01Z",
  "payload": {}
}

08 · SAÍDAS

Interruptores, relés lógicos e pulsadores

Para uma saída simples, declare switch com comando set_power e estado power. O firmware genérico da TechRib permite perfis de saída configuráveis e modos de atuação; a escolha do GPIO depende da placa e deve ser validada separadamente.

FRAGMENTOS JSON

{"id":"luz_1","type":"switch","name":"Luz 1",
 "transport":"local","commands":["set_power","toggle"]}
// Estado após confirmação
{"power":true,"actuation_mode":"latch","pulse_duration_ms":500}
// Exemplo de payload de comando
{"command":"set_power","args":{"power":true}}

Para acionamento por tempo, o catálogo oferece relay_pulse com comando pulse e argumento duration_ms. Em switch, modos latch, toggle e pulse só devem ser anunciados se implementados.

FRAGMENTOS JSON

{"id":"campainha_1","type":"relay_pulse","name":"Pulso 1",
 "transport":"local","commands":["pulse"]}
{"command":"pulse","args":{"duration_ms":500}}

09 · COR E ILUMINAÇÃO

RGB: canais independentes, cor e brilho

O firmware universal enviado contém perfis nativos para até dois conjuntos RGB convencionais independentes, sujeitos à disponibilidade real de recursos PWM/GPIO. Cada RGB precisa ter um ID próprio; na nuvem, é um componente light_rgb, não três switches separados.

FRAGMENTOS JSON

{"id":"rgb_sala","type":"light_rgb","name":"RGB sala",
 "transport":"local",
 "commands":["set_power","set_rgb","set_brightness"]}
// Estado compatível com o contrato
{"power":true,"r":255,"g":80,"b":12,"brightness":70}
// Comandos separados
{"command":"set_rgb","args":{"r":255,"g":80,"b":12}}
{"command":"set_brightness","args":{"brightness":70}}

Os valores r/g/b vão de 0 a 255; brightness vai de 0 a 100. O app Flutter agrupa light_rgb na família RGB, usa o ícone padrão de paleta e pode abrir controles dedicados de cor e brilho. Para RGBW, CCT ou LED endereçável, consulte o respectivo contrato: não presuma driver pronto.

LÓGICA DIDÁTICA

// Estrutura de lógica independente de fabricante (pseudocódigo)
if (comando == SET_RGB && args_validos) {
    rgb_sala.r = r; rgb_sala.g = g; rgb_sala.b = b;
    aplicar_pwm_normalizado(rgb_sala);  // implementar no hardware
    publicar_estado_confirmado("rgb_sala");
}

10 · ENTRADAS E MEDIÇÕES

Temperatura, umidade, LDR, presença e portas

O firmware de referência demonstra DHT11, leitura analógica, presença e porta. Para cada sensor físico, crie IDs separados e publique somente campos válidos. Uma leitura de ADC bruta de LDR não equivale a lux sem calibração.

FRAGMENTOS ILUSTRATIVOS

{"id":"temp_1","type":"temperature","name":"Temperatura","commands":[]}
{"state":{"temperature_c":24.6},"quality":"valid"}

{"id":"umid_1","type":"humidity","name":"Umidade","commands":[]}
{"state":{"humidity_pct":58.0},"quality":"valid"}

{"id":"ldr_1","type":"analog_input","name":"LDR (ADC bruto)","commands":[]}
{"state":{"value":2350},"quality":"valid"}

{"id":"presenca_1","type":"presence","name":"Presença","commands":[]}
{"state":{"detected":false},"quality":"valid"}

{"id":"porta_1","type":"door_sensor","name":"Porta","commands":[]}
{"state":{"open":false},"quality":"valid"}

Uma única amostra DHT pode alimentar dois componentes, temperatura e umidade, mas são dois IDs e dois estados. Em vários sensores iguais, o índice deve ser estável e a atribuição de pinos não pode conflitar com RGB, saídas ou recursos internos da placa. Falha de leitura exige estado inválido/ausente — não publique medição fictícia.

11 · MOVIMENTO

Persianas: abrir, fechar e parar

Para persianas simples, declare um cover com três comandos: open, close e stop. Internamente, o firmware de referência modela duas direções e tem lógica de intertravamento; no app aparece um único controle de persiana.

FRAGMENTOS JSON

{"id":"persiana_sala","type":"cover","name":"Persiana da sala",
 "commands":["open","close","stop"]}
{"state":{"status":"stopped","direction":"stopped"},"quality":"valid"}
{"command":"open","args":{}}
{"command":"stop","args":{}}

O estado cover suporta status e direction. cover_position é outro tipo, com position de 0 a 100, e exige medição ou estimação validada da posição: não anuncie percentual se não o possui.

12 · RS485

Gateway Modbus RTU: módulos, endereços e limites

O Gateway ESP32 Modbus é um firmware dedicado, diferente do firmware universal de GPIO. Nos arquivos recebidos ele inicia desabilitado por padrão. O código implementa o enquadramento Modbus RTU para ler coils (FC01), ler entradas discretas (FC02) e escrever coil individual (FC05), sujeito ao mapeamento real do fabricante.

CONFIGURAÇÃO LÓGICA

# Exemplo ilustrativo do campo de módulos no menuconfig
# endereço, tipo R (relé) ou I (entrada), canais, offset zero-based, ID
1,R,16,0,rele01;2,I,16,0,entradas01

# Associações locais opcionais — primeiro canal de entrada ao de relé
entradas01:1=rele01:1:toggle

Esse exemplo descreve dois módulos e 32 IDs lógicos: rele01_01 até rele01_16 e entradas01_01 até entradas01_16. A configuração do Laravel apresentada no painel Modbus é atualmente de planejamento: não configura um Gateway em produção automaticamente nem cria cards de hardware real.

Módulo R

16 relés · endereço 1 · FC01 para leitura · FC05 para comando · representar como saída/interruptor se houver estado real publicado.

Módulo I

16 entradas discretas · endereço 2 · FC02 para leitura · criar componentes de entrada conforme o tipo e estado efetivamente suportados.

Todos os equipamentos no mesmo barramento exigem endereços Modbus válidos e distintos. A tabela Modbus dos fabricantes pode usar offsets diferentes e suportar funções distintas; confirme no manual de cada equipamento. Parâmetros como taxa e paridade precisam coincidir.

13 · APLICATIVO

Como o tipo do firmware determina o card e o ícone

O Flutter obtém do Laravel o type e, quando configurado, o campo icon. Primeiro utiliza um ícone personalizado reconhecido; caso contrário, escolhe um padrão por tipo ou família. O mesmo tipo pode exibir aparência diferente conforme tema, permissões e configurações do usuário.

Tipos do manifesto	Componente visual padrão (Flutter)	Card/controle esperado
`switch`, `outlet`	Alternância / toggle	Ligar e desligar, se `set_power` declarado
`light_rgb`, `light_rgbw`, `light_addressable`	Paleta	Cor, brilho e estado conforme comandos
`temperature`, `temperature_probe`	Termômetro	Leitura de temperatura
`humidity`, `humidity_controller`	Gota	Umidade
`presence`, `motion`	Sensor	Indicador de presença
`door_sensor`, `window_sensor`	Porta	Aberta/fechada
`cover`, `cover_position`	Persiana	Subir, descer, parar ou posição, conforme tipo
`motor`, `vfd`	Motor	Controle do motor
`energy_meter`, `power`, `voltage`, `current`	Raio/energia	Medidas elétricas
`rf_433_`, `lora_`	Antena	Telemetria e controles autorizados
Demais medições	Monitor/sensor	Leitura conforme `state_schema`

O app também oferece escolhas de ícones: lightbulb (iluminação), activity (sensor), motor, droplets, antenna, zap e thermometer. Um ícone escolhido pelo usuário não altera o driver físico.

14 · REFERÊNCIA

Os 64 tipos definidos no catálogo oficial

Selecione qualquer item para consultar os campos válidos, os comandos definidos e exemplos de declaração e estado. Todos os exemplos abaixo são sintéticos, derivados do catálogo V2 anexado, sem prometer suporte físico a todos os sensores. Em um firmware real, registre apenas os tipos que efetivamente implementou.

Buscar tipo, categoria, campo ou comando

64 tipos de contrato

01switchacionamento · toggle+

Campos de estado: power, actuation_mode, pulse_duration_ms
Comandos de catálogo: set_power, toggle, pulse, set_mode

JSON · EXEMPLO DIDÁTICO

{
  "component": {
    "id": "switch_1",
    "type": "switch",
    "name": "Exemplo switch",
    "commands": [
      "set_power"
    ]
  },
  "state": {
    "state": {
      "power": false,
      "actuation_mode": "latch",
      "pulse_duration_ms": 50
    },
    "quality": "valid"
  },
  "command": {
    "command": "set_power",
    "args": {
      "power": false
    }
  }
}