Status global: 📝 em construção Última atualização: 2026-05-14 Responsável: Rodrigo Belli Idioma: português (PT-BR) Objetivo: permitir a reprodução completa de uma Yara Box do zero, do projeto à instalação técnica em campo

Como usar este manual

O manual é dividido em 10 capítulos temáticos (visão → eletrônica → mecânica → elétrica → firmware → cloud → montagem → testes → instalação → operação) e 3 apêndices (BOM, esquemáticos, calibração bruta).

Cada capítulo declara no topo:

• Status: 📝 rascunho · 🚧 bloqueado · ✅ pronto
• Audiência
• Última atualização (ISO YYYY-MM-DD)
• TOC interno

Bloqueadores externos aparecem em blocos:

🚧 BLOQUEADO — aguardando <o quê> de <quem> TODO ao destravar: <ação concreta>

Convenções de notação:

• Refs cruzadas: [Cap N — Título](NN_xxx.md)
• Refs a código (firmware): link permanente GitHub agua-camelo-cs/YB-<repo>/blob/main/<path>#L<linha> (repos privados — acesso restrito à organização)
• Refs a materiais Embrapii: caminho relativo (../Macroentregas_Embrapii/...)
• Diagramas: Mermaid inline para fluxos/arquitetura; PNG/JPG em imagens/<NN_capitulo>/ para fotos e renders

Índice

Linha do tempo de versões

Bloqueadores externos abertos

Glossário rápido

Créditos

Desenvolvimento original (EMBRAPII PIFF-2412.0051):

• PICG / Instituto Federal Fluminense — Polo de Inovação, Campos dos Goytacazes
  • Coordenador do projeto: Vitor Rangel da Silva
  • Pesquisadores: Eduardo Atem de Carvalho, William da Silva Vianna
  • Estudantes: Marllon Batista da Conceição, Valmir Monteiro Júnior, Matheus Vieira dos Santos, João Vitor Bernardo Moreira da Silva, Marcos Sabino Magro Sales de Oliveira
• Água Camelo / Wara Tech
  • Responsável: Rodrigo Belli

Financiamento: EMBRAPII — Empresa Brasileira de Pesquisa e Inovação Industrial

Documento-fonte

Handoff original: HANDOFF_Manual_Mestre_Yara_Box.md

Status: ✅ pronto Última atualização: 2026-05-14 Responsável: Rodrigo Belli Tempo de leitura estimado: 15 minutos

Sumário

• 1. O que é a Yara Box
• 2. Audiência e estrutura deste manual
• 3. Três inovações centrais
  • 3.1. Cloração inteligente proporcional à vazão
  • 3.2. Rastreabilidade e telemetria IoT
  • 3.3. Unidade integrada plug-and-play
• 4. Arquitetura macro (5 camadas)
• 5. Drivers de produto (custo por litro vs autonomia)
• 6. Conformidade regulatória
• 7. Linha do tempo do desenvolvimento (Embrapii)
• 8. Ecossistema de propriedade intelectual
• 9. Como navegar pelo restante do manual

1. O que é a Yara Box

A Yara Box é uma unidade portátil e autônoma de tratamento de água para consumo humano, instrumentada com IoT. Em uma única caixa de até 25 kg e dimensões de 80×40×40 cm, integra:

• Filtração em 4 estágios (grade → disco 130 μm → microfiltração 0,2 μm → ultrafiltração 0,01 μm)
• Cloração ativa proporcional à vazão, controlada por uma bomba peristáltica com motor de passo
• Telemetria remota via Wi-Fi e GSM, com publicação MQTT em ThingsBoard
• Operação híbrida — alimentada por até cinco fontes diferentes de energia (rede AC, 12 VDC direto, gerador, painéis solares ou bomba manual), com bateria 18650 para autonomia de até 72 horas sem energia externa
• Capacidade de até 300 L/h (parametrizável até 600 L/h)

A Yara Box foi desenvolvida no âmbito do projeto EMBRAPII PIFF-2412.0051 ("Desenvolvimento de uma Unidade Portátil Instrumentada com Tecnologia IoT para o Tratamento de Água para Consumo Humano"), em parceria entre o Polo de Inovação do IFFluminense (PICG) e a Água Camelo, com financiamento da EMBRAPII.

A unidade é projetada para atender comunidades em áreas rurais, remotas, emergenciais ou com infraestrutura elétrica precária, e atende à Portaria GM/MS Nº 888/2021 (norma brasileira de potabilidade) — em particular o intervalo de 0,2–2 mg/L de cloro residual livre, ver §6.

2. Audiência e estrutura deste manual

Este manual destina-se a um profissional com formação técnica, mesmo sem conhecimento prévio do projeto. O objetivo é permitir que essa pessoa reproduza uma Yara Box do zero — projete e fabrique as PCBs, montagem mecânica/hidráulica, instale o firmware, suba o backend e calibre a unidade — usando apenas este manual, os repositórios de código vinculados e a BOM consolidada.

O conteúdo está organizado em 10 capítulos temáticos (este, mais 9) e 3 apêndices (BOM, esquemáticos, calibração bruta). Cada capítulo declara no topo seu status (📝 rascunho, 🚧 bloqueado, ✅ pronto), audiência específica e data ISO da última atualização.

Os capítulos podem ser lidos de forma linear (ordem natural: visão → eletrônica → mecânica → ... → operação) ou consultados como referência por tópico. Refs cruzadas linkam capítulos relacionados.

Documentos-fonte usados na construção deste manual (referência permanente):

• Três Macroentregas do projeto EMBRAPII PIFF-2412.0051 (Manual de configuração, Manual do desenvolvedor, Projeto do sistema, etc.)
• Repositórios agua-camelo-cs/YB-* no GitHub (mirrors privados dos repos originais do GitLab PICG)
• Resposta complementar do PICG de 14/05/2026 (procedimentos de calibração, P&ID formal, 2D cotado das chapas PEAD)
• Backup operacional da unidade Yara Box 001 em produção (/11-Confidencial/YaraBox_001_Backup_Config.md)
• Sessão de infraestrutura de 14/05/2026 (migração do backend de iot.picg.iff.edu.br para yarabox.aguacamelo.com.br)

3. Três inovações centrais

A Yara Box combina filtração + cloração + telemetria + autonomia energética em uma única unidade transportável. Três diferenciais sustentam essa proposta:

3.1. Cloração inteligente proporcional à vazão

A bomba peristáltica dosadora, acionada por motor de passo (via driver A4988), doseia hipoclorito de sódio (4%) em tempo real com base na vazão instantânea de água tratada. A cada ciclo de leitura do sensor de vazão Hall (FE300), o microcontrolador calcula o número de passos do motor pela fórmula:

D = (C × Q) / E

Onde:

• D — passos do motor a executar no ciclo
• C — concentração-alvo de cloro residual (mg/L), configurável
• Q — vazão instantânea medida (L/min)
• E — eficiência volumétrica da bomba dosadora (mL/passo, calibrável)

Parâmetros configuráveis ficam em data/config.json (ver Cap 5 — Firmware):

• Dosagem-alvo: 5–50 μL/L (dose_hipoclorito_ug-L)
• Calibração da dosadora: ~0,333 mL/passo padrão; 0,32078445 mL/passo medido em laboratório PICG e em uso na unidade 001 (ver Apêndice C)
• Calibração da vazão: 0,253526896 mL/pulso na unidade 001

Diferencial competitivo: mantém concentração de cloro residual aproximadamente constante mesmo com flutuações de pressão e vazão — comportamento superior a sistemas Venturi (dosagem dependente de pressão diferencial) ou a sistemas de dosagem por tempo fixo.

Pegadinha histórica documentada: no Ensaio 1 da Fundenor (03/03/2026), o cloro residual ficou em 0,1 mg/L (fora do padrão 0,2–5,0). Causa raiz: o cálculo usava concentração de hipoclorito de 12% quando o produto real era 4%. Após a correção do parâmetro (concentracao_hipoclorito_porcentagem: 4), o cloro subiu para 0,8 mg/L (dentro do padrão) no Ensaio 2 (11/03/2026). Detalhes em Cap 8 §6.

3.2. Rastreabilidade e telemetria IoT

A Yara Box transmite telemetria via MQTT para uma instância de ThingsBoard Community Edition, hospedada em VPS própria da Água Camelo (yarabox.aguacamelo.com.br). Dois canais redundantes:

• Wi-Fi quando há rede local disponível
• GSM/3G/4G via módulo SIM7080G (com GPS embutido) — consumo de apenas ~5 μA em sleep

Dados publicados a cada 30 segundos (publicação parcial) e a cada 10 minutos (publicação completa):

• Pressão em até 4 pontos do circuito hidráulico (PT100, PT101, PT102, PT103)
• Vazão instantânea e acumulada
• Nível do reservatório de hipoclorito (LSL200, LSLL200)
• Tensão de alimentação e tensão de bateria
• Volume total tratado e volume desde a última manutenção
• Geolocalização (GPS), quando disponível
• Estado da máquina (Tratamento / Idle / Lavagem / Calibração / Teste)

Alertas automáticos: dosagem fora da faixa, baixo cloro, pressão anormal, nível crítico de hipoclorito, tensão crítica de bateria.

Manutenção preditiva por volume tratado desde a última intervenção (lavagem 10 mil L, limpeza 50 mil L, troca de filtro 100 mil L ou 365 dias, recalibração 100 mil L) — configurável via config.json (ver Cap 10 — Operação & Manutenção).

3.3. Unidade integrada plug-and-play

Mecânica modular construída em perfis de alumínio estruturais (ALU-01 a ALU-04) com fechamentos em chapas de PEAD (polietileno de alta densidade) — sete chapas distintas com geometrias cotadas, ver Cap 3 §2.2 e Apêndice A.

Dimensões alvo: 80×40×40 cm, até 25 kg, com quatro rodízios para deslocamento. Modelo 3D completo em STEP files no repositório YB-projeto-mecanico-hidraulico. Renderização e revisão de débitos técnicos do CAD em Macroentregas_Embrapii/Macroentrega_3/revisao_3D_claude/.

Energia híbrida via PCB Seletora v1.1.1 (chaveamento entre 5 fontes — ver Cap 4 — Elétrico) e bateria 18650 em arranjo 3S3P (11,1 V nominal, 6,48 Ah, autonomia ~72 h sem bombeamento).

4. Arquitetura macro (5 camadas)

Olhando do macro pro micro, a Yara Box organiza-se em cinco camadas funcionais:

Cada camada é detalhada em capítulo próprio:

Dentro da Camada 4 (Firmware), a organização interna do código segue arquitetura clássica em camadas (Aplicação → Lógica → Serviços → HAL → Hardware), com processamento dual-core distribuído via FreeRTOS — núcleo 0 cuida de sensoriamento e comunicação externa, núcleo 1 cuida de UI local e acionamento do motor de passo. Detalhe completo em Cap 5 §4.

5. Drivers de produto

A evolução do produto é orientada por dois drivers mensuráveis, não por fases temporais. Toda decisão de engenharia (componente, firmware, mecânica, software) precisa puxar pelo menos um deles.

Driver A — Custo por litro entregue (R$/L)

• Por que importa: define margem unitária, viabiliza preço competitivo, abre o mercado de pasto (24× maior em volume que confinamento, mas com poder aquisitivo menor).
• Métrica: R$ por m³ de água tratada entregue ao bebedouro.
• Baseline atual: ~R$ 1,87/m³ (COGS R$ 728/Box/mês ÷ 12.960 L/dia × 30 dias).
• Alavancas: BOM (R$ 8K protótipo → R$ 4K escala), vazão (540 L/h → mais nas próximas gerações), vida útil dos filtros UF, eficiência de cloração, manutenção preditiva, self-cleaning.

Driver B — Autonomia (operação sem humano)

• Por que importa: reduz necessidade de equipe operacional, permite escalar volume sem inflar headcount, viabiliza operação em locais sem energia/sinal estáveis (pasto, áreas isoladas).
• Métrica: tempo médio entre intervenções humanas; % de eventos resolvidos sem intervenção.
• Baseline atual: ESP32 com 14 estados, buffer 72 h offline, failsafe mecânico, manutenção física mensal.
• Alavancas: patentes P1/P2/P3 (ver §8), manutenção preditiva, detecção de anomalia em tempo real, conectividade redundante (Wi-Fi → GSM → LoRa → satélite), self-cleaning de filtros.

Régua de decisão: antes de qualquer mudança de produto, perguntar (1) quanto reduz R$/L? (2) quanto aumenta autonomia? Se a resposta a ambas é "nada", a mudança é cosmética e fica adiada.

6. Conformidade regulatória

A Yara Box é projetada para atender à Portaria GM/MS Nº 888/2021 do Ministério da Saúde brasileiro, que estabelece os procedimentos de controle e vigilância da qualidade da água para consumo humano e seu padrão de potabilidade.

Parâmetros monitorados em campo (telemetria):

• Vazão instantânea (controle proporcional da cloração)
• Pressão em pontos críticos do circuito
• Nível do reservatório de hipoclorito (controle de continuidade da desinfecção)
• Tensão de alimentação (continuidade operacional)

Parâmetros validados em ensaios laboratoriais (Fundenor, Campos dos Goytacazes — RJ):

Detalhes completos em Cap 8 §6 e fonte primária Macroentregas_Embrapii/Macroentrega_3/Testes/consolidado-ensaios.md.

Gargalo identificado nos ensaios: o filtro de microfiltração (MF, 0,2 μm, cartucho descartável) saturou após ~400–450 L com água de 140 NTU — autonomia comercialmente inviável. Substituição em avaliação com filtro tipo "Camelo" (carcaça inox, lavável, retrolavável). Resultado do teste de substituição em Cap 8 §6.3.

7. Linha do tempo do desenvolvimento (Embrapii)

O projeto EMBRAPII PIFF-2412.0051 foi estruturado em três macroentregas:

Macroentrega 1 — aceita

• Detalhamento dos parâmetros principais, conceituais e tecnológicos
• Projeto preliminar mecânico, eletro-eletrônico e software
• Relação de aquisição de itens comerciais e tecnológicos
• Critérios de aceitação definidos

Macroentrega 2 — aceita em 03/11/2025

• Desenvolvimento eletro-eletrônico e de software (projeto atualizado com adoção do módulo JNG-E da Eneltec na PCB Core, após reunião de 27/03/2025 — decisão estratégica para viabilizar suporte pós-projeto pela Água Camelo)
• Testes preliminares dos subsistemas (PCB Seletora de Alimentação fabricada, testada e validada via JLCPCB)
• Montagem preliminar do protótipo (estrutura com painel, sistema hidráulico visível)
• Visita técnica em 24/10/2025 (fotos do protótipo montado disponíveis em Macroentregas_Embrapii/Macroentrega_2/Fotos da Visita 24out25/)

Macroentrega 3 — em andamento (atual)

• Ensaios laboratoriais Fundenor (eficácia bacteriológica >99% comprovada, problema de cálculo de cloro resolvido)
• Eletrônica nova validada (4 painéis solares funcionais, GPS validado em ambiente aberto)
• Gargalo do filtro de microfiltração identificado e em avaliação de substituição
• Resposta complementar do PICG em 14/05/2026 com procedimentos formais de calibração (pressão, vazão, dosadora), fluxograma P&ID com tags ISA-5.1 e 2D cotado das 7 chapas PEAD

Em paralelo — infraestrutura própria

Em 14/05/2026, a Água Camelo concluiu a migração do backend de iot.picg.iff.edu.br (PICG) para yarabox.aguacamelo.com.br (VPS Vultr SP própria, ThingsBoard CE 4.2.1, Docker Compose, Nginx + Let's Encrypt). Documentação completa em Cap 6 — Backend & Cloud.

8. Ecossistema de propriedade intelectual

A Yara Box é base de um ecossistema de IP sustentado por três patentes de software já depositadas no INPI em 18/03/2026 (titularidade 100% Rodrigo Machado Belli) e uma patente de hardware em preparação (titularidade compartilhada 50/50 entre IFFluminense e Água Camelo):

Importante: as três patentes descrevem roteamento de fluido entre filtros DENTRO de uma única unidade Yara Box — não orquestração de múltiplas unidades em rede. Princípio: entra água com perfil X, sistema identifica, roteia pelos filtros necessários, output bate parâmetros desejados.

Total: 52 reivindicações de software depositadas.

9. Como navegar pelo restante do manual

Próximas leituras sugeridas conforme objetivo:

Fontes deste capítulo

• Arquitetura_Yara_Box/Visao_Tecnica_Wara_Box.md (consolidação técnica)
• Arquitetura_Yara_Box/arquitetura_produto.md (drivers A/B e régua de decisão de produto)
• Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/modulo-basico/ARCHITECTURE.md (arquitetura em 4 camadas do firmware)
• Macroentregas_Embrapii/.../picg-resposta-2026-05-14/Fluxogramas.docx (créditos da equipe PICG)
• Macroentregas_Embrapii/Macroentrega_3/Testes/consolidado-ensaios.md (resultados Fundenor)
• 11-Confidencial/YaraBox_001_Backup_Config.md (parâmetros operacionais reais)

Status: ✅ pronto Última atualização: 2026-05-14 Audiência: engenheiro eletrônico (KiCad, ESP32, datasheets) Tempo de leitura estimado: 20 minutos

Sumário

• 1. Visão geral das placas
• 2. PCB Principal-DevKit-ESP32S3 (prototipagem)
• 3. PCB Joker — Core final com módulo JNG-E
  • 3.1. Visão geral e o porquê do JNG-E
  • 3.2. Sub-esquemáticos (9 sheets KiCad)
  • 3.3. Mapeamento de pinos
• 4. PCB Seletora de Alimentação v1.1.1
  • 4.1. Função
  • 4.2. Sub-esquemáticos
  • 4.3. Componentes-chave e conectores
• 5. PCB DAQ Shield (Datalogger para Arduino Nano)
• 6. Como fabricar (Gerbers, BOM JLCPCB)
• 7. Validações e testes preliminares (ME2)

1. Visão geral das placas

A eletrônica da Yara Box é composta por três PCBs próprias (mais uma PCB auxiliar de instrumentação):

Todos os projetos KiCad estão clonados localmente em:

Macroentregas_Embrapii/Macroentrega_3/fontes códigos  e projetos/
├── modulo-basico-pcb-principal-devkit-esp32s3-main/
├── modulo-basico-pcb-principal-joker-main/
├── modulo-basico-pcb-seletor-de-alimentacao-main/
└── (DAQ shield em `YB-dataloggerpcb` apenas no GitHub)

A relação entre as PCBs no sistema é:

Para detalhes do projeto elétrico geral (fiação fora das PCBs, hierarquia de fontes, bateria), ver Cap 4 — Elétrico.

2. PCB Principal-DevKit-ESP32S3 (prototipagem)

Repositório: YB-modulo-basico-pcb-principal-devkit-esp32s3 (privado)

Versão de prototipagem desenhada antes da decisão pelo módulo JNG-E. Usa o módulo ESP32-S3-WROOM diretamente no formato DevKit (o board é o mesmo esp32-s3-devkitc-1 da Espressif). Função: permitir desenvolvimento e validação do firmware enquanto a PCB Joker (Core final com JNG-E) está sendo finalizada.

Quando usar: desenvolvimento em bancada, debug com gravação USB, antes de migrar para o Joker em produção. Quando não usar: unidades de produção — usar o Joker.

3. PCB Joker — Core final com módulo JNG-E

Repositório: YB-modulo-basico-pcb-principal-joker (privado) Repo local: Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/modulo-basico-pcb-principal-joker-main/

3.1. Visão geral e o porquê do JNG-E

A PCB Joker é a placa principal final da Yara Box e centraliza:

• O MCU (módulo JNG-E da Eneltec, com ESP32-S3-WROOM)
• O módulo de comunicação celular SIM7080G (GSM/3G/4G + GPS, consumo em sleep ~5 μA)
• Interfaces I²C para sensores analógicos (ADS1115) e I/O digital (PCF8574)
• Drivers de motor de passo (A4988) para a bomba dosadora
• Drivers de válvula (IRLZ44N)
• Conectores para sensores de pressão, vazão, nível, e display SH1107

Por que JNG-E? Reunião técnica de 27/03/2025 decidiu migrar do ESP32-S3 direto (projeto próprio do PICG) para o módulo JNG-E da Eneltec. Razão: garantir suporte e manutenibilidade pós-projeto pela Água Camelo (a Eneltec é um fornecedor brasileiro estabelecido, com BSP testado e suporte técnico contínuo). Trade-off aceito: BOM unitário ligeiramente maior, em troca de viabilidade operacional de longo prazo.

3.2. Sub-esquemáticos (9 sheets KiCad)

A PCB Joker está organizada em uma sheet principal (modulo-basico-pcb-principal-joker.kicad_sch) com 8 sub-sheets dedicadas:

3.3. Mapeamento de pinos

Resumo dos pinos do ESP32-S3 usados (detalhamento em Cap 5 §15):

Endereços I²C:

• ADS1115 #1 — 0x48 (PT100-103)
• ADS1115 #2 — 0x49 (canais de expansão futuros)
• PCF8574 #1 — 0x20 (relés/válvulas/LEDs principais)
• PCF8574 #2 — 0x24 (expansão de I/O)
• SH1107 (display) — 0x3C

3.4. Artefatos prontos no repositório

Em Macroentregas_Embrapii/.../modulo-basico-pcb-principal-joker-main/Documentos/:

Documentos/
├── bom/                       ← BOM da PCB Joker
├── datasheet/                 ← Datasheets dos componentes principais
├── esquematico.pdf            ← Esquemático completo em PDF (referência rápida)
├── layout.pdf                 ← Layout da PCB em PDF
└── mod_eneltec/               ← Documentação do módulo JNG-E

Também em IMGs/: imagens da arquitetura do sistema, do circuito LED-BUZZER, e dos módulos PCF8574, ADS1115 e do sensor capacitivo.

PDFs e artefatos completos referenciados em Apêndice B §1.

4. PCB Seletora de Alimentação v1.1.1

Repositório: YB-modulo-basico-pcb-seletor-de-alimentacao (privado) Repo local: Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/modulo-basico-pcb-seletor-de-alimentacao-main/ Status: ✅ fabricada via JLCPCB, testada e validada (ME2 aceita em 03/11/2025)

4.1. Função

Placa dedicada ao chaveamento automático entre 5 fontes de energia (ver Cap 4 para a lógica de hierarquia A→E). Implementa:

• Retificação e filtragem das entradas AC/DC
• Controle MPPT solar (CN3722)
• Regulação Buck (XL4015) e Boost (XL6019) de tensão
• Seleção da fonte ativa via 3 relés CMA51H (12 V, 15–20 A) controlados pela lógica interna
• Saída separada para bomba elétrica (12 V/20 A) e lógica de controle (sinal para PCB Core via conector J2)
• Chave ON/OFF geral

Princípio crítico: separa fisicamente a alimentação da bomba da alimentação lógica. Isto permite manter telemetria viva (PCB Core + bateria) mesmo quando não há energia disponível para bombeamento.

4.2. Sub-esquemáticos

A PCB Seletora tem uma sheet principal + 3 sub-sheets:

4.3. Componentes-chave e conectores

Componentes principais (BOM completa no repo):

Conectores de entrada/saída:

4.4. Bibliotecas KiCad customizadas

libsSeletor/ contém modelos 3D para os componentes principais (CN3722, XL4015, XL6019, CMA51H). Permite visualizar a placa em 3D para validação mecânica antes da fabricação.

4.5. Artefatos prontos

Em Macroentregas_Embrapii/.../modulo-basico-pcb-seletor-de-alimentacao-main/documentos/:

documentos/
├── ESQUEMATICO.pdf            ← esquemático em PDF
├── layout.pdf                 ← layout final
├── BOM/                       ← BOM completa para JLCPCB
├── Gerbers/                   ← arquivos de produção Gerber
├── positions/                 ← arquivos de posicionamento de componentes (pick-and-place)
└── netlist/                   ← netlist do projeto

Pronto para fabricação via JLCPCB. Custo unitário em volume baixo (~10 placas): da ordem de R$ 30–60/placa SMT-assembly inclusive.

5. PCB DAQ Shield (Datalogger para Arduino Nano)

Repositório: YB-dataloggerpcb (privado)

Shield de aquisição de dados projetado em KiCad para instrumentação de testes em bancada e campo. Montada sobre Arduino Nano ATmega328 (não vai no produto final).

5.1. Características do hardware

• Isolação óptica via optoacopladores LTV-817 (entradas digitais/analógicas)
• MOSFET SI4483ADY para chaveamento de cargas
• Reguladores de tensão L78xx (fixos) e LM317 (ajustável)
• Proteção ESD com TVS LESD5D5 nas entradas
• Conectores industriais: 7 pinos e 3 pinos (pitch 9,5 mm); 2 pinos (pitch 5 mm, potência)

5.2. Variantes de firmware do Datalogger

Existem dois firmwares para a mesma PCB DAQ (selecionáveis na hora de gravar o Arduino):

Variante A — JSON Serial

Comunica via serial 115200 baud em formato request/response:

• Cliente envia "readAll" → Arduino responde JSON com leituras de A0, D2/D3 (counters + frequência), D4 (estado lógico)
• Aceita comando PWM para o pino 9 (0–255)
• Cálculo de frequência a cada 10 s com debounce

Repositório: YB-datalogger (privado).

Variante B — Modbus RTU

Mesma PCB DAQ, firmware diferente. Protocolo Modbus RTU Slave (ID=1, 115200 baud, 8N1):

• Input Registers (FC 04): IREG 0–5 (A0–A5), IREG 6 (estado D4–D7 compactado), IREG 7/8 (counter+freq D2), IREG 9/10 (counter+freq D3)
• Holding Register (FC 06): HREG 0 (saída PWM pino 9, 0–255)
• Funções Modbus suportadas: FC 01, 02, 03, 04, 05, 06, 0F, 10
• Watchdog de 4 s habilitado (auto-reset em hang)
• Limites: MAX_REGS=32, MAX_FRAME=128

Vantagens da variante Modbus: protocolo industrial padrão, compatível com CLPs e supervisórios, lê 6 canais analógicos (vs. 1 na JSON), watchdog para robustez.

Repositório: YB-datalogger-modbus (privado).

5.3. Dashboard Node-RED

Dashboard local separado do ThingsBoard, para visualização e logging em bancada. Roda em PC conectado ao Arduino via serial (/dev/ttyUSB0, 9600 baud).

Funcionalidades:

• Gauge de vazão instantânea (L/h): frequência × 1.759 × 60 / 1000
• 4 gauges de pressão estática (PT100–PT103) com calibração linear a × raw + b
• Pressão diferencial em 3 filtros (PT100−PT101, PT101−PT102, PT102−PT103)
• Slider PWM (0–255) com gauge de duty cycle
• Logging CSV automático em /home/<user>/.node-red/dados/datalogger.csv com colunas: cont, vazaoInst, vazaoTotal, pwm, potencia, pt100–pt103, pdfiltro1–3
• Gráfico histórico de pressão (line chart)

Constantes de calibração no Node-RED (referência cruzada com Cap 8):

6. Como fabricar (Gerbers, BOM JLCPCB)

Para fabricar uma cópia da Yara Box, o fluxo recomendado é:

6.1. PCB Seletora (mais simples — pronta)

1. Baixar o repo YB-modulo-basico-pcb-seletor-de-alimentacao.
2. Em documentos/Gerbers/, zipar os arquivos.
3. No painel da JLCPCB: novo pedido → upload do zip → escolher SMT-assembly (opcional, recomendado).
4. Subir a BOM e o arquivo de posicionamento (positions/).
5. Confirmar componentes não fabricados (rotular como "Skip" — alguns são THT).
6. Encomendar (R$ 30–60/placa em quantidades pequenas).

6.2. PCB Joker

1. Abrir o projeto em KiCad 8.x.
2. Verificar ERC/DRC (Electrical Rules Check / Design Rules Check).
3. Gerar Gerbers e arquivos de posicionamento via PCBNew → Plot.
4. Submeter na JLCPCB.
5. Atenção: o módulo JNG-E não é fabricado pela JLCPCB — comprar separadamente da Eneltec e montar manualmente, ou via fabricante local que aceite componente fornecido pelo cliente.

6.3. PCB Principal-DevKit-ESP32S3

Igual à Joker, mas SEM o JNG-E (usa o módulo ESP32-S3-WROOM diretamente). Mais simples para fabricar em pequena escala.

6.4. PCB DAQ (opcional)

Só necessária para instrumentação de bancada. Submeter Gerbers do YB-dataloggerpcb.

7. Validações e testes preliminares (ME2)

A Macroentrega 2 (aceita em 03/11/2025) incluiu testes preliminares dos subsistemas eletrônicos:

Documentação de testes preliminares: Macroentregas_Embrapii/Macroentrega_2/3.3 Testes preliminares dos subsistemas/Testes preliminares dos subsistemas.docx.

Fontes deste capítulo

• Repositórios locais em Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/:
  • modulo-basico-pcb-principal-joker-main/ (sheets KiCad + esquemático/layout PDFs + datasheets + IMGs)
  • modulo-basico-pcb-seletor-de-alimentacao-main/ (BOM completa, Gerbers, positions, ESQUEMATICO.pdf)
  • modulo-basico-pcb-principal-devkit-esp32s3-main/
• Repositórios GitHub (mirrors privados): agua-camelo-cs/YB-modulo-basico-pcb-*
• Macroentregas_Embrapii/Macroentrega_2/Relatório da PCB Seletor de Alimentação.pdf
• Macroentregas_Embrapii/Macroentrega_2/3.3 Testes preliminares dos subsistemas/
• Macroentregas_Embrapii/Macroentrega_3/5.1 .../Projeto do sistema.docx
• Arquitetura_Yara_Box/Visao_Tecnica_Wara_Box.md §3.2

Esquemáticos completos e datasheets: ver Apêndice B.

Status: ✅ pronto Última atualização: 2026-05-14 Audiência: engenheiro mecânico/hidráulico (sem conhecimento prévio do projeto) Tempo de leitura estimado: 20 minutos

Sumário

• 1. Visão geral do gabinete
• 2. Estrutura mecânica
  • 2.1. Perfis de alumínio
  • 2.2. Chapas PEAD (7 chapas cotadas)
  • 2.3. Acessórios
• 3. Sistema hidráulico (4 estágios + cloração)
• 4. P&ID formal (tags ISA-5.1)
  • 4.1. Diagrama
  • 4.2. Tabela completa de tags
  • 4.3. Loops de controle
• 5. Linhas de retrolavagem e drenos
• 6. Capacidade e dimensões
• 7. Modelo 3D (STEP files)
• 8. Débito técnico do CAD (estado em maio/2026)

1. Visão geral do gabinete

A Yara Box é montada em um gabinete modular de até 80 × 40 × 40 cm e até 25 kg de peso total. A estrutura usa perfis de alumínio para o esqueleto e chapas de PEAD (polietileno de alta densidade) para os fechamentos. Quatro rodízios na base permitem deslocamento manual; uma alça superior facilita o transporte de curtas distâncias.

Princípio mecânico: modularidade + manutenibilidade em campo. A tampa lateral é abrível para acesso direto ao sistema hidráulico, à bateria 18650 e às PCBs. Sensores são posicionados em pontos específicos do circuito para acesso visual e troca rápida.

2. Estrutura mecânica

2.1. Perfis de alumínio

Quatro tipos de perfis estruturais conformam o esqueleto:

Junções com cantoneiras (CANT-01) e parafusos M5/M6 conforme padrão de perfis 30×30 mm ou 40×40 mm (a especificação exata está na BOM consolidada — ver Apêndice A).

2.2. Chapas PEAD (7 chapas cotadas)

Os fechamentos do gabinete usam 7 chapas distintas de PEAD, todas com 5 mm de espessura. Os 2D cotados em formato ABNT foram entregues pelo PICG em 12/05/2026 (autor: Marllon Batista) e estão prontos para envio a fornecedores de corte:

PDFs em formato técnico ABNT, escala apropriada para fabricação por corte CNC ou roteamento. Material padrão: PEAD branco ou natural, 5 mm, classificado para uso em contato com água potável.

2.3. Acessórios

Detalhamento e quantidades exatas na BOM consolidada — ver Apêndice A.

3. Sistema hidráulico (4 estágios + cloração)

O fluxo segue captação → 4 estágios de filtração → cloração proporcional → saída:

Cada estágio em detalhe:

3.1. Filtro 0 — Pré-captação (grade)

Grade ou pré-filtro grosseiro para reter partículas grandes (folhas, detritos, areia grossa) que possam danificar a bomba elétrica. Sem media filtrante substituível — limpeza por enxágue.

3.2. Filtro 1 — Disco 130 μm

Filtro de disco para remoção de partículas grandes, sedimentos e detritos antes dos filtros de membrana. Pressão máxima de trabalho: 0,79 MPa (≈115 psi).

Catálogo do fornecedor sugerido: ver Macroentregas_Embrapii/.../picg-resposta-2026-05-14/Fluxogramas.docx (link interno do PICG).

3.3. Filtro 2 — Microfiltração 0,2 μm

Membrana de polipropileno 0,2 μm, capacidade de até 300 L/h, pressão de trabalho 0,1–0,4 MPa.

⚠️ Gargalo identificado nos ensaios Fundenor (ME3): o cartucho descartável atual (não lavável, não plissado) satura após ~400–450 L com água de 140 NTU. Inviabilidade comercial em fontes de alta turbidez. Avaliação em curso de filtro alternativo tipo "Camelo" (carcaça inox, lavável, retrolavável) como substituto. Detalhes em Cap 8 §6 e em Macroentregas_Embrapii/Macroentrega_3/Testes/consolidado-ensaios.md.

3.4. Filtro 3A / 3B — Ultrafiltração 0,01 μm (dois em paralelo)

Membranas tubulares/capilares de 0,01 μm, dois cartuchos em paralelo (3A e 3B) com chaveamento por solenóides S1 e S2 para permitir retrolavagem alternada. Capacidade: até 300 L/h cada, pressão de trabalho 0,1–0,4 MPa.

O modelo 3D atual inclui 2 filtros UF físicos (decisão confirmada por Rodrigo em 07/05/2026 — modelo 3D está correto; BOM precisava ser atualizada para qty 2).

3.5. Cloração — Bomba peristáltica + misturador estático

A bomba dosadora peristáltica (Bomba D) injeta hipoclorito de sódio 4% do reservatório TQ Cloro (1,5–2 L) na linha após os filtros UF. O misturador estático (MIX) garante homogeneização sem partes móveis adicionais.

Cálculo da dosagem (referência cruzada com Cap 5 §10):

velocidade_passo = calibracao_bomba_dosadora × vazao_minuto × dose_hipoclorito

Concentração-alvo configurável (5–50 μg/L); dose default 4000 μg/L.

Capacidade do reservatório: ~36.000 L tratados por recarga de hipoclorito (com dosagem default).

4. P&ID formal (tags ISA-5.1)

A nomenclatura segue ISA-5.1 (Standard for Instrumentation Symbols and Identification). O fluxograma técnico completo está em Macroentregas_Embrapii/.../picg-resposta-2026-05-14/Fluxogramas.docx (PICG, 14/05/2026).

4.1. Diagrama

4.2. Tabela completa de tags

Convenção de pinos:

• GPIO XX — pinos diretos do ESP32-S3
• APx — pinos do PCF8574 expansor 1 (I²C @ 0x20) — atuadores (LEDs, buzzer, solenóides)
• BPx — pinos do PCF8574 expansor 2 (I²C @ 0x24) — entradas (chaves, botoeiras, nível)

Esses pinos são detalhados em Cap 5 §15.

4.3. Loops de controle

Três loops automáticos são implementados pelo firmware (sem PID — controle on/off ou proporcional simples):

Loop FIQC300 — Cloração proporcional à vazão:

FE300 (vazão) → MCU (estado Tratamento) → Bomba D (motor passo proporcional)

Calculado a cada ciclo de 250 ms no Núcleo 1 do ESP32. Detalhes em Cap 5 §10.

Loop PAHH100 — Intertravamento por sobrepressão:

PT100 ou PT101 > limiar muito_alto (40 psi) → MCU → desliga Bomba E

Limiar configurável em config.pressao_bomba.estado_muito_alto.

Loop LALL200 — Intertravamento por falta de desinfetante:

LSLL200 (nível crítico) → MCU → desliga Bomba E (bombeamento manual continua permitido)

5. Linhas de retrolavagem e drenos

O sistema inclui linhas de retrolavagem automática dos filtros UF (3A e 3B), comandadas pelo estado EstadoControlarLavagem do firmware (Cap 5 §6):

Sequência típica:

1. Solenóides S1 e S2 abrem por 30 segundos (inversão de fluxo nos filtros)
2. Bomba E aciona por 60 segundos (vazão reversa para remover particulado)
3. Solenóides fecham, sistema retorna ao Idle

Recomendação automática de lavagem por volume tratado: cada 10.000 L (parâmetro volume_recomendado_nova_lavagem_filtro no config.json). Limpeza completa cada 50.000 L; troca cada 100.000 L ou 365 dias.

Dreno: saída inferior do gabinete para descarte do efluente de retrolavagem (água com particulado retido).

6. Capacidade e dimensões

Detalhes regulatórios (Portaria GM/MS Nº 888/2021) em Cap 1 §6.

7. Modelo 3D (STEP files)

Repositório: YB-projeto-mecanico-hidraulico (privado) Repo local: Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/projeto-mecanico-hidraulico-main/

Modelo CAD principal em Fusion 360 (Autodesk). Idioma: PT-BR. Padrão de cotagem: ABNT.

8. Débito técnico do CAD

A revisão técnica do modelo 3D vs BOM realizada em 07/05/2026 (Macroentregas_Embrapii/Macroentrega_3/revisao_3D_claude/Revisao_Projeto_e_Plano_Fusion.md) identificou inconsistências entre modelo 3D e BOM/projeto que precisam ser resolvidas antes da produção em volume:

Princípio diretor (definido por Rodrigo, 07/05/2026):

O modelo 3D deve ser espelho fiel do protótipo real — mesmas peças, mesmas dimensões gerais exatas. Diferenças entre modelo e real são bugs a corrigir.

Detalhes da auditoria completa em Macroentregas_Embrapii/Macroentrega_3/revisao_3D_claude/Revisao_Projeto_e_Plano_Fusion.md. As correções são tracked no backlog 00-Backlog/tasks.md (item "Refazer 3D no Fusion").

Fontes deste capítulo

• Macroentregas_Embrapii/Macroentrega_3/5.1 Transferência da tecnologia ao cliente/picg-resposta-2026-05-14/Fluxogramas.docx (P&ID formal + tabela de tags ISA-5.1 + parâmetros do sistema embarcado)
• Macroentregas_Embrapii/Macroentrega_3/5.1 Transferência da tecnologia ao cliente/picg-resposta-2026-05-14/Desenhos 2D cotados das Chapas/ (7 PDFs ABNT cotados, Marllon Batista, 12/05/2026)
• Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/projeto-mecanico-hidraulico-main/ (STEP files)
• Macroentregas_Embrapii/Macroentrega_3/revisao_3D_claude/Revisao_Projeto_e_Plano_Fusion.md (auditoria cross-check BOM ↔ 3D)
• Macroentregas_Embrapii/Macroentrega_3/5.1 .../Projeto do sistema.docx (especificações originais)
• Arquitetura_Yara_Box/Visao_Tecnica_Wara_Box.md §3.1 (sistema hidráulico)
• Macroentregas_Embrapii/Macroentrega_3/Testes/consolidado-ensaios.md (gargalo do filtro MF)

BOM consolidada com quantidades: ver Apêndice A. P&ID original em PDF: ver Apêndice B.

Status: ✅ pronto Última atualização: 2026-05-14 Audiência: engenheiro elétrico/eletrônico

Sumário

• 1. Visão geral (sistema híbrido de 5 fontes)
• 2. Hierarquia de prioridade A → E
• 3. Detalhe de cada fonte
• 4. Chaveamento automático via PCB Seletora
• 5. Bateria 18650 (3S3P)
• 6. Separação alimentação bomba vs alimentação lógica
• 7. Limiares de tensão configuráveis
• 8. Consumo estimado e balanço energético
• 9. Esquema elétrico geral (projeto-eletrico)
• 10. Sub-esquemáticos do projeto elétrico

1. Visão geral (sistema híbrido de 5 fontes)

A Yara Box é projetada para operar em locais com infraestrutura elétrica precária ou ausente. Para isso, suporta cinco fontes diferentes de energia com chaveamento automático sem interrupção do processamento. Permite, por exemplo, alimentar a unidade simultaneamente a partir da rede AC do cliente e do banco solar, com a bateria como tampão para o caso de queda das duas.

Característica fundamental: separa fisicamente a alimentação da bomba elétrica da alimentação lógica (PCB Core + bateria). Quando não há energia disponível para bombeamento, a telemetria continua funcionando — o sistema relata a falha em vez de simplesmente apagar.

2. Hierarquia de prioridade A → E

A PCB Seletora seleciona automaticamente a fonte ativa conforme ordem de prioridade decrescente:

A lógica de seleção é:

1. Se A está disponível → A
2. Senão, se B ou C disponível → B/C
3. Senão, se D fornece energia suficiente → D
4. Em paralelo: bateria (P6) cobre transições e atua como tampão de até 72 h para a eletrônica (sem bombeamento) — ver §5
5. Em todos os casos: E (bombeamento manual via bomba pistão 300 L/min) está sempre disponível como fallback mecânico — independente de eletrônica

3. Detalhe de cada fonte

3.1. Fonte A — Rede AC 110/220V

• Entrada via P1 da Seletora (AC retificada internamente)
• Requer fonte chaveada externa AC → 12 VDC / 20 A (ex: Mean Well S-250-12 ou equivalente)
• Prioridade máxima: sempre que disponível, é a fonte primária
• Recomendado para instalações fixas em locais com rede confiável

3.2. Fonte B — Entrada 12 VDC direta

• Entrada via P2 da Seletora
• Mínimo 5 A (para alimentar bomba elétrica de 8 L/min com folga)
• Use casos:
  • Banco de baterias externo (12 V)
  • Painel solar com controlador externo já fornecendo 12 V regulado
  • Adaptador de veículo (12 V do alternador)

3.3. Fonte C — Gerador 12 VDC

• Geradores portáteis a combustível com saída 12 VDC
• Pode entrar via P2 (se já regulado) ou P1 (se via inversor AC + fonte chaveada)
• Recomendado para instalações temporárias ou emergenciais

3.4. Fonte D — Painel solar + MPPT (CN3722)

• Entradas via P3 e P4 (até 2 painéis solares 18–22 V)
• O CN3722 na Seletora faz Maximum Power Point Tracking automaticamente
• 4 painéis solares funcionais validados em ME3 (ver consolidado-ensaios.md)
• Recomendado para instalações off-grid em áreas com boa insolação

3.5. Fonte E — Bomba/geração manual

• Bomba pistão 300 L/min com baixa pressão
• Independente da eletrônica: funciona mesmo com Yara Box desligada
• Backup absoluto — garante acesso à água tratada (sem cloração ativa nem telemetria) em situação de falha total

4. Chaveamento automático via PCB Seletora

A PCB Seletora de Alimentação v1.1.1 implementa o chaveamento sem interrupção do processamento via 3 relés CMA51H (12 V, 15–20 A). Detalhes da placa em Cap 2 §4.

Lógica: os relés são acionados pelo bloco SELETOR_DE_FONTE.kicad_sch, que monitora a presença de tensão em cada entrada e prioriza conforme §2.

Características elétricas:

• Capacidade do relé: 15–20 A (suficiente para bomba elétrica 12 V/8 L/min em pico de carga)
• Tensão de bobina: 12 V
• Tipo: SPDT (1 contato normal aberto + 1 contato normal fechado)
• Isolamento: garante que tensões de diferentes fontes não se misturem

5. Bateria 18650 (3S3P)

Configuração: 9 células 18650 Li-ion, arranjo 3 bancos × 3 em série:

• 3 células em série por banco → 11,1 V nominal (3 × 3,7 V)
• 3 bancos em paralelo → 6,48 Ah total (3 × 2,16 Ah típico por célula)
• Energia total: ~72 Wh

Conector: P6 na PCB Seletora.

Autonomia:

• Apenas eletrônica (PCB Core + display + comunicação MQTT) → até ~72 h
• Eletrônica + bombeamento (bomba elétrica em duty cycle típico de operação) → da ordem de horas, conforme uso
• Recarga: automática quando a fonte A/B/C/D está ativa e a tensão de bateria está abaixo do limite normal

BMS (Battery Management System): recomendado mas não obrigatório — o controle de proteção mínima é feito pelo firmware via leitura tensao_bateria (ver §7). Para produção em volume, integrar BMS dedicado para proteção contra over-discharge, balanceamento entre células e proteção térmica.

6. Separação alimentação bomba vs alimentação lógica

A PCB Seletora tem duas saídas independentes:

Razão da separação: garantir que a telemetria continua mesmo sem energia para bombear. Cenários típicos:

• Painéis solares fornecem energia suficiente apenas para a eletrônica (luz fraca) → o sistema continua telemetrando, reporta vazão zero, e o operador remoto sabe que não houve tratamento
• Bateria cai abaixo do limite para acionar bomba → bomba desliga, mas eletrônica continua até esgotar a bateria; o evento é registrado e publicado

Isso é diferente de muitos sistemas IoT industriais que perdem comunicação ao mesmo tempo que a função principal — design crítico para áreas remotas onde manutenção é cara.

7. Limiares de tensão configuráveis

Os limiares ficam em data/config.json (ver Cap 5 §5) e podem ser ajustados via AP mode ou OTA sem reflashar o firmware:

Tensão de alimentação (P1/P2/P3/P4 chegando ao Core via J2)

"tensao_alimentacao": {
    "estado_normal":       12.4,   // V
    "estado_baixo":        10.0,   // V — começa a alertar
    "estado_muito_baixo":   8.0    // V — corta acionamentos
}

Tensão de bateria (P6)

"tensao_bateria": {
    "estado_normal":       12.3,   // V
    "estado_baixo":        10.5,   // V — alerta no display + telemetria
    "estado_muito_baixo":  10.0    // V — modo de proteção (desliga bomba)
}

Calibração das leituras

As leituras de tensão passam pelo ADS1115 (I²C @ 0x48) através de um divisor de tensão, e o firmware aplica regressão linear y = a · x + b. Coeficientes reais da unidade 001 (ver Apêndice C §5):

Procedimento de calibração em Cap 8 §5.

8. Consumo estimado e balanço energético

Consumo estimado total da Yara Box (todos subsistemas operando, com fator térmico de 30% aplicado):

Implicações para autonomia da bateria 6,48 Ah / 11,1 V (72 Wh):

• Apenas eletrônica: 72 Wh ÷ 2,4 W = 30 horas teóricas (na prática, ~72 h com sleep dinâmico do SIM7080G e periodicidade de publicação MQTT)
• Com bomba elétrica em duty cycle típico de operação intermitente: bateria não é dimensionada para alimentar a bomba sozinha por períodos longos — a bomba consome 40× mais do que a eletrônica

Recomendação operacional: a bateria serve como tampão para a eletrônica durante quedas momentâneas das fontes A-D. Para operação contínua de bombeamento em locais off-grid, dimensionar o banco solar adequadamente (D) ou prever recarga periódica via fonte A/B.

9. Esquema elétrico geral (projeto-eletrico)

Repositório: YB-projeto-eletrico (privado) Repo local: Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/projeto-eletrico-main/

Esse projeto complementa as PCBs próprias documentando a fiação geral entre PCBs, sensores externos, atuadores, conectores no gabinete e o banco de baterias. Não é uma PCB — é o esquemático em KiCad da instalação elétrica completa da unidade.

Artefatos:

• projeto-eletrico.kicad_sch — sheet principal
• 6 sub-esquemáticos (ver §10)
• projeto-eletrico.kicad_pcb — não é PCB própria, é placeholder para footprint mecânico
• DOCS/ — PDFs consolidados, datasheets de componentes externos

10. Sub-esquemáticos do projeto elétrico

O projeto-eletrico está organizado em 6 sub-sheets:

Cada sub-sheet referencia conectores no gabinete físico e nomeia os fios para facilitar a montagem em campo. Detalhamento do sistema hidráulico que esses atuadores e sensores integram está em Cap 3.

Fontes deste capítulo

• Repositório local: Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/projeto-eletrico-main/
• Repositório GitHub: agua-camelo-cs/YB-projeto-eletrico (privado)
• PCB Seletora (referência cruzada): Cap 2 §4
• Arquitetura_Yara_Box/Visao_Tecnica_Wara_Box.md §3.3 (sistema de energia)
• Macroentregas_Embrapii/Macroentrega_2/Relatório da PCB Seletor de Alimentação.pdf
• Macroentregas_Embrapii/Macroentrega_3/5.1 .../Projeto do sistema.docx
• 11-Confidencial/YaraBox_001_Backup_Config.md (valores reais de calibração de tensão)
• data/config.json do firmware (limiares operacionais)

Esquemáticos PDF e sources KiCad completos: ver Apêndice B §5.

Status: ✅ pronto Última atualização: 2026-05-14 Audiência: engenheiro de firmware embarcado (C++, ESP32, PlatformIO, FreeRTOS, ArduinoJson) Tempo de leitura estimado: 25 minutos

Sumário

• 1. Visão geral do firmware
• 2. Stack e dependências
• 3. Estrutura do projeto (src/, lib/, data/)
• 4. Particionamento de flash (custom_partitions.csv)
• 5. Configuração externa via config.json
• 6. Máquina de estados (14 estados, dual-core)
• 7. Módulos lib/ (15 módulos)
• 8. Padrões de projeto adotados
• 9. Sincronização (FreeRTOS, 8 mutexes, 5 tasks)
• 10. Loop principal de controle (Tratamento)
• 11. Telemetria MQTT (Producer-Consumer)
• 12. Persistência (LittleFS)
• 13. Configuração via AP mode
• 14. OTA Update
• 15. Mapeamento de pinos
• 16. Compilar, gravar e debugar

1. Visão geral do firmware

O firmware roda em um ESP32-S3-DevKitC-1 (dual-core Xtensa LX7 a 240 MHz, 8 MB PSRAM, 16 MB flash QIO). É escrito em C++17 sobre o framework Arduino e construído com PlatformIO.

Versão atual em produção (unidade 001): v2.1.4-alpha (SDK Espressif v4.4.7-dirty).

A organização em alto nível segue arquitetura clássica em quatro camadas:

┌─────────────────────────────────────────────────────────┐
│  Aplicação    → main.cpp (callbacks Arduino + delegação)│
├─────────────────────────────────────────────────────────┤
│  Lógica       → MaquinaEstado (Singleton) + 14 estados  │
├─────────────────────────────────────────────────────────┤
│  Serviços     → display, mqtt, wifi, gsm, filesystem... │
├─────────────────────────────────────────────────────────┤
│  HAL          → ADS1115, PCF8574, SH1107, SIM7080G      │
└─────────────────────────────────────────────────────────┘
                          ▼
                   Hardware ESP32-S3

Nenhuma lógica de negócio mora em main.cpp — ele apenas inicializa o sistema e delega para MaquinaEstado::get_estado_boot()->on_setup(). Todo o comportamento de runtime é dirigido por eventos e transições de estado.

Principal arquivo de referência interna: ARCHITECTURE.md no repositório (~60 KB, 1700+ linhas) — leia este capítulo primeiro, depois consulte o ARCHITECTURE.md quando precisar do nível de detalhe das classes/funções.

2. Stack e dependências

Plataforma

• Framework: Arduino (via PlatformIO)
• Plataforma: espressif32@^6.11.0 (Arduino-ESP32 core)
• Board: esp32-s3-devkitc-1
• Toolchain: platformio/tool-esptoolpy@^2.40900.250804
• Linguagem: C++17 com -fexceptions -frtti
• Filesystem: LittleFS (block 4096, page 256)
• Particionamento: custom (ver §4)
• Memória: QIO + QSPI + PSRAM QIO

Bibliotecas (declared em platformio.ini)

Fonte: platformio.ini.

3. Estrutura do projeto

modulo-basico/
├── platformio.ini             ← config de build/plataforma/libs
├── custom_partitions.csv      ← layout das partições de flash
├── Doxyfile                   ← config Doxygen (geração de docs)
├── README.md                  ← guia local de uso (26 KB)
├── ARCHITECTURE.md            ← arquitetura detalhada (60 KB, 1700+ linhas)
├── src/
│   ├── main.cpp               ← setup() + callbacks Arduino
│   └── main.h
├── lib/                       ← 15 módulos próprios (ver §7)
│   ├── maquina_estado/
│   ├── display/
│   ├── dispositivos_ads/
│   ├── dispositivos_pcf/
│   ├── dosadora/
│   ├── access_point/
│   ├── ota_update/
│   ├── filesystem/
│   ├── global_members/
│   ├── gps/
│   ├── gsm/
│   ├── mqtt/
│   ├── rtos_/
│   ├── SIM7080/
│   ├── wifi/
│   └── (cada um com README.md + src/)
└── data/                      ← uploadado para LittleFS
    ├── config.json            ← configuração runtime (override de fábrica)
    ├── config-padrao-fabrica.json
    ├── leituras.json          ← últimas leituras persistidas
    └── AP/                    ← HTML/CSS/JS do portal de configuração

Cada módulo em lib/<nome>/ é uma biblioteca PlatformIO autocontida, com seu próprio README.md. Detalhes em §7.

4. Particionamento de flash

Layout customizado para suportar OTA (duas partições de aplicação) e LittleFS grande:

nvs,      data, nvs,      0x9000,   0x5000     # 20 KB
otadata,  data, ota,      0xe000,   0x2000     # 8 KB
app0,     app,  ota_0,    0x10000,  0x300000   # 3 MB (firmware ativo)
app1,     app,  ota_1,    0x310000, 0x300000   # 3 MB (OTA buffer)
coredump, data, coredump, 0x610000, 0x20000    # 128 KB (debug crash)
spiffs,   data, spiffs,   0x630000, 0x9D0000   # ~10 MB (LittleFS)

Total: ~16 MB. O processo OTA grava o novo binário em app1, altera otadata para apontar para app1, e reinicia. Em caso de falha de boot, fallback automático para app0.

Fonte: custom_partitions.csv.

5. Configuração externa via config.json

Princípio de design: zero configuração hardcoded. Tudo que pode mudar entre unidades (Wi-Fi, MQTT, calibrações, limiares, intervalos de manutenção) está em data/config.json, gravado em LittleFS.

Schema completo (extraído do data/config.json da unidade 001):

{
  // Conectividade Wi-Fi (modo STA — produção)
  "ssid_wifi": "<rede do cliente>",
  "psk_wifi":  "<senha>",

  // Modo Access Point (configuração local)
  "ssid_ap":     "yarabox_AP",
  "psk_ap":      "",              // aberto
  "dominio_ap":  "yarabox.local",

  // Modo OTA (atualização remota)
  "ssid_ota":    "yarabox_OTA",
  "psk_ota":     "@gu@c@m3l0",
  "dominio_ota": "yarabox-ota.local",

  // Credenciais do portal admin (AP mode)
  "user_conf":   "camelo",
  "pass_conf":   "@gu@c@m3l0",

  // MQTT (ThingsBoard)
  "token_mqtt":  "<access token do device no TB>",
  "server_mqtt": "yarabox.aguacamelo.com.br",   // ver Cap 6

  // GSM (fallback de conectividade)
  "pin_gsm":  "0",
  "user_gsm": "vivo",
  "pass_gsm": "vivo",
  "apn_gsm":  "zap.vivo.com.br",

  // NTP (sincronização de hora)
  "ntp_server": {
    "1": "br.pool.ntp.org",
    "2": "a.st1.ntp.br",
    "3": "pool.ntp.org"
  },
  "ntp_gmt_offset":      -3,        // BRT
  "ntp_daylight_offset": 3600,
  "rtc_sincronizado_ntp":     false,
  "horario_verao_habilitado": false,

  // Limites operacionais
  "limitar_volume_tratado":      false,
  "valor_limite_volume_tratado": 0,
  "pwm_bomba_eletrica":          115,    // duty cycle padrão
  "velocidade_bomba_dosadora":   50,
  "hipoclorito_habilitado":      true,
  "limite_maximo_vazao_hora":    600,    // L/h

  // Calibrações (regressão linear y = a·x + b — ver Cap 8)
  "calibracao_vazao":             0.253526896,
  "calibracao_pt100_a":           0.02909090,
  "calibracao_pt100_b":          -8.79708816,
  "calibracao_pt101_a":           0.04210526,
  "calibracao_pt101_b":         -13.38947261,
  "calibracao_pt102_a":           0,      // não calibrado nesta unidade
  "calibracao_pt102_b":           0,
  "calibracao_pt103_a":           0,
  "calibracao_pt103_b":           0,
  "calibracao_tensao_bateria_a":  0.0043795620,
  "calibracao_tensao_bateria_b": -0.1883211678,
  "calibracao_tensao_bomba_a":    0.0097249061,
  "calibracao_tensao_bomba_b":    0.0,
  "calibracao_bomba_dosadora":    0.32078445,

  // Cloração
  "concentracao_hipoclorito_porcentagem": 4,
  "dose_hipoclorito_ug-L": {
    "valor":          4000,
    "limite_minimo":  200,
    "limite_maximo":  5000
  },

  // Limiares e alarmes (ver Cap 10)
  "nivel_hipoclorito":  { "estado_muito_baixo": 0,   "estado_baixo": 30, "estado_normal": 100 },
  "pressao_bomba":      { "estado_muito_baixo": 5,   "estado_baixo": 10, "estado_alto": 30, "estado_muito_alto": 40 },
  "tensao_alimentacao": { "estado_normal": 12.4, "estado_baixo": 10.0, "estado_muito_baixo": 8.0 },
  "tensao_bateria":     { "estado_normal": 12.3, "estado_baixo": 10.5, "estado_muito_baixo": 10.0 },
  "vazao_litros_hora":  { "estado_muito_baixo": 150, "estado_baixo": 300, "estado_normal": 330, "estado_alto": 600, "estado_muito_alto": 650 },

  // Manutenção preventiva
  "volume_tratado_desde_ultima_lavagem_filtro":    0,
  "volume_tratado_desde_ultima_limpeza_filtro":    0,
  "volume_tratado_desde_ultima_troca_filtro":      0,
  "volume_tratado_desde_ultima_calibracao_vazao":  0,
  "volume_recomendado_nova_lavagem_filtro":        10000,
  "volume_recomendado_nova_limpeza_filtro":        50000,
  "volume_recomendado_nova_troca_filtro":          100000,
  "volume_recomendado_nova_calibracao_vazao":      100000,
  "data_ultima_troca_filtro":                      "01/01/2025",
  "dias_recomendado_nova_troca_filtro":            365
}

Fonte: data/config.json (template) e data/config-padrao-fabrica.json (defaults imutáveis).

Persistência: o módulo filesystem (ver §7) carrega config.json no boot. Se o arquivo está corrompido ou não existe, faz fallback para config-padrao-fabrica.json e copia para config.json no primeiro write. Todas as alterações via menu local ou AP mode reescrevem config.json atomicamente.

Para uma placa nova/resetada: restaurar valores reais a partir do backup operacional documentado em /11-Confidencial/YaraBox_001_Backup_Config.md — procedimento em Apêndice C §8.

6. Máquina de estados (14 estados, dual-core)

O coração lógico do firmware é uma máquina de estados implementada com State Pattern clássico. A interface IEstado é o contrato base:

class IEstado {
public:
    virtual void on_enter() = 0;          // executado uma vez na transição para o estado
    virtual void on_setup() = 0;          // inicialização única (recursos pesados)
    virtual void on_loop()  = 0;          // executado a cada tick da task do núcleo
    virtual void on_exit()  = 0;          // determina o próximo estado
    virtual void on_input(InteracaoUsuario evento) = 0;  // reação a eventos do encoder/botão
};

MaquinaEstado é Singleton e mantém ponteiros para todos os 14 estados (criados via std::unique_ptr no construtor — padrão Factory implícito). Cada estado roda em um dos dois núcleos do ESP32-S3:

Estados do Núcleo 0 (sensoriamento, UI, comunicação externa)

Estados do Núcleo 1 (controle de atuadores)

Por que dual-core?

Isolar os estados de controle de atuadores no Núcleo 1 garante que o ciclo de acionamento do motor de passo e da bomba elétrica não sofra interferência das operações de UI, rede ou persistência executadas no Núcleo 0. Em particular: o pulso do motor de passo da dosadora precisa de timing preciso (ms), e qualquer jitter introduzido por publicação MQTT ou redesenho do display comprometeria a dosagem proporcional.

Diagrama de fluxo

O loop "estável" do Núcleo 0 é Ler → Exibir → Sinalizar → Publicar → Ler (com Input processado antes de cada transição). O Núcleo 1 alterna entre Idle ↔ Tratamento conforme comandos do usuário e proteções automáticas.

Fonte completa (com diagrama ASCII expandido e código de transições): ARCHITECTURE.md §"Diagrama de Estados Completo".

7. Módulos lib/ (15 módulos)

Cada módulo é uma biblioteca PlatformIO autocontida em lib/<nome>/ com src/ próprio e README.md documentando responsabilidade e API.

Convenção de refs: snippets curtos inline no manual + link permanente para cada módulo no GitHub:

• https://github.com/agua-camelo-cs/YB-modulo-basico/tree/main/lib/<nome>/src/

Cada lib/<nome>/README.md é leitura obrigatória ao tocar no módulo correspondente.

8. Padrões de projeto adotados

Trade-offs aceitos (documentados em ARCHITECTURE.md §"Decisões de Design"):

• Singleton/estática dificulta testes unitários (mocking complexo) — aceito por simplicidade
• Repository pattern com flags acopla módulos — aceito por performance
• Média móvel simples (5 amostras) vs Kalman — aceito por baixo custo computacional

9. Sincronização (FreeRTOS)

5 tasks pinadas a núcleos

8 mutexes (em RTOS)

class RTOS {
public:
    static SemaphoreHandle_t xMutex_copia_parametros;   // protege configurações
    static SemaphoreHandle_t xMutex_testes;             // flags de teste manual
    static SemaphoreHandle_t xMutex_controle;           // flags de controle (vazão, bomba, etc.)
    static SemaphoreHandle_t xMutex_conexao;            // estado de rede
    static SemaphoreHandle_t xMutex_serial_gsm;         // UART do modem (write/read exclusivos)
    static SemaphoreHandle_t xMutex_7080_habilitado;    // flag GSM ativo/dormindo
    static SemaphoreHandle_t xMutex_leitura_gps;        // dados de coordenada
    static SemaphoreHandle_t xMutex_publicacao;         // buffer MQTT (Producer-Consumer)
};

Padrão de uso (em GlobalMembers):

void GlobalMembers::set_vazao_l_min(float valor) {
    if (xSemaphoreTake(RTOS::xMutex_controle, INTERVALO_MAXIMO_MUTEX)) {
        vazao_l_min = valor;
        xSemaphoreGive(RTOS::xMutex_controle);
    } else {
        // log de falha (mutex timeout)
    }
}

Watchdog Timer

O WDT é habilitado para todas as tasks. Em loops longos (típicos do GSM, que pode bloquear segundos esperando resposta do modem), o WDT é alimentado entre operações com esp_task_wdt_reset() para evitar reset espúrio. Se o WDT estoura por descuido, o ESP32 reinicia automaticamente — mecanismo de segurança essencial em campo.

void RTOS::loop_SIM7080_nucleo_0() {
    RedeGSM::loop();
    esp_task_wdt_reset();

    ThingsBoardMQTT::manter_conexaoGSM();
    esp_task_wdt_reset();

    GPS::loop();
    esp_task_wdt_reset();
}

10. Loop principal de controle (Tratamento)

EstadoControlarTratamento::on_loop() roda no Núcleo 1 a cada 250 ms. É o coração funcional da Yara Box.

Fluxo

1. Verificar tensão de alimentação. Se abaixo do limiar crítico (tensao_alimentacao.estado_muito_baixo, default 8 V), interrompe o tratamento e transiciona para Idle.
2. Acionar bomba elétrica via ledcWrite(CANAL_BOMBA_ELETRICA, 255) (LEDC PWM em duty fixo — variação de velocidade foi removida por incompatibilidade com o circuito de acionamento atual).
3. Calcular velocidade da dosadora com base na vazão instantânea e na configuração:

   velocidade_passo = calibracao_bomba_dosadora × vazao_minuto × dose_hipoclorito
   

   Onde dose_hipoclorito vem de config.dose_hipoclorito_ug-L.valor (5–50 μg/L, default 4000).
4. Acionar dosadora via Dosadora::set_velocidade(velocidade_passo). O motor de passo é chamado diretamente no loop do Core 1 para garantir pulsos precisos sem interferência de rede.

Cálculo da dosagem (relembrando do Cap 1)

D = (C × Q) / E

• D — passos do motor a executar
• C — dose-alvo (μg/L), vem de config.dose_hipoclorito_ug-L.valor
• Q — vazão instantânea (L/min), vem do sensor FE300
• E — eficiência volumétrica da dosadora (mL/passo), inverso de calibracao_bomba_dosadora

Exemplo numérico com valores da unidade 001 (vazão hipotética 5 L/min, dose 4000 μg/L):

calibracao_bomba_dosadora = 0.32078445
velocidade_passo = 0.32078445 × 5 × 4000 = 6415,69 passos/min ≈ 107 passos/s

Condições de saída

• tratamento_permitido == false → transição para Idle
• limite_volume_atingido → transição para Idle (quando limitar_volume_tratado está ativo)

Proteções automáticas (intertravamentos)

• PAHH100 — pressão alta extrema (PT100/101 > pressao_bomba.estado_muito_alto, default 40 psi) → desliga bomba E
• LALL200 — nível crítico de hipoclorito (LSLL200) → desliga bomba E (bombeamento manual continua permitido)
• Tensão de alimentação crítica (< 8 V) → desliga bomba E e dosadora

Fonte: lib/maquina_estado/src/ — arquivos estado_controlar_tratamento.cpp e similares.

11. Telemetria MQTT (Producer-Consumer)

O fluxo de publicação é desacoplado em 3 etapas:

Etapa 1 — EstadoPublicarDados::on_loop() (publicador)

• Publicação parcial a cada 30 s (apenas valores que mudaram)
• Publicação completa a cada 10 min (todos os ~30 parâmetros)
• Coleta dados de leituras_dispositivos (estrutura ArduinoJson global) → serializa → grava em GlobalMembers::set_json_publicacao(json_string) (protegido por xMutex_publicacao)

Etapa 2 — loop_publicacao_nucleo_0() (consumidor)

void RTOS::loop_publicacao_nucleo_0() {
    String json_buffer = GlobalMembers::get_json_publicacao();
    if (!json_buffer.isEmpty()) {
        ThingsBoardMQTT::publicar_json(json_buffer);
        GlobalMembers::set_json_publicacao("");  // limpa buffer
    }
}

Etapa 3 — ThingsBoardMQTT::publicar_json()

Usa o SDK thingsboard/ThingsBoard@^0.15.0:

tb.sendTelemetryJson(json_payload.c_str());

O transporte (Wi-Fi ou GSM) é selecionado automaticamente pelo módulo mqtt com base em conectividade. Em produção, Wi-Fi é prioritário; GSM serve como fallback.

Payload típico (publicação completa)

{
  "pressao_pt100":         2.5,
  "pressao_pt101":         2.3,
  "pressao_pt102":         null,
  "pressao_pt103":         null,
  "vazao_l_min":           15.7,
  "vazao_media_litros_hora": 942,
  "volume_total_litros":   125430,
  "tensao_alimentacao":    12.6,
  "tensao_bateria":        12.4,
  "nivel_hipoclorito":     100,
  "estado":                "TRATAMENTO",
  "timestamp":             1747260000,
  "lat":                   -22.7470,
  "lon":                   -41.3196
}

Em alta latência (rede 4G ruim, MQTT lento): o Producer continua escrevendo no buffer; o Consumer transmite quando possível. Buffer é sobrescrito, não enfileirado — telemetria mais antiga é descartada em favor da mais recente. Para arquivamento histórico, ver §12.

Detalhes da infra do broker (VPS, Nginx, SSL): Cap 6 — Backend & Cloud.

12. Persistência (LittleFS)

Dois fluxos de escrita:

Fluxo A — config.json (configuração)

Acionado sob demanda quando o usuário salva parâmetros no menu local ou via AP mode:

EstadoMenuUI::salvar_configuracoes()
    ou
EstadoAccessPoint::POST /save_config
        │
        ▼
FileSystem::write("/config.json", json_serializado)
        │
        ▼
LittleFS.open("/config.json", "w") → escreve → fecha

Escrita atômica via rewrite completo — não há append nem mutação parcial. Reduz risco de corrupção.

Fluxo B — leituras.json (histórico local)

Acionado periodicamente a cada 15 min pelo EstadoPublicarDados:

EstadoPublicarDados::on_loop()  (timer 15 min)
        │
        ▼
FileSystem::write("/leituras.json", leituras_serializadas)

Permite reconstituir histórico local em caso de queda de conectividade prolongada.

Leitura no boot

EstadoSequenciaBoot::on_setup() chama FileSystem::read("/config.json"). Se o arquivo está corrompido ou ausente, faz fallback automático para config-padrao-fabrica.json e copia para config.json.

Arquivos típicos no LittleFS

/config.json                        ← configuração runtime (override de fábrica)
/config-padrao-fabrica.json         ← defaults imutáveis
/leituras.json                      ← snapshot periódico das leituras
/AP/index.html                      ← portal de configuração (HTML)
/AP/styles.css
/AP/script.js
/AP/configuracoes.html
/AP/calibracoes.html

13. Configuração via AP mode

Quando ativado (via menu local ou no boot se Wi-Fi STA falha por N tentativas), o firmware sobe uma rede Wi-Fi própria:

Fluxo do usuário

1. Conectar celular/notebook à rede yarabox_AP.
2. Abrir http://yarabox.local (ou http://192.168.4.1).
3. Acesso Restrito — login: usuário camelo, senha @gu@c@m3l0 (defaults; podem ser trocados em config.json).
4. Editar campos (Wi-Fi do cliente, MQTT server, token, calibrações, limiares).
5. Salvar → o firmware reescreve config.json e reinicia.

Stack interna

• Servidor HTTP assíncrono: ESPAsyncWebServer@^3.8.0 (sobre AsyncTCP@^3.4.7)
• Servidor DNS captive: redireciona qualquer domínio para o IP do AP, garantindo que o browser do celular sempre caia no portal
• Autenticação: Basic Auth — credenciais em config.user_conf / config.pass_conf

Fonte: lib/access_point/src/ + arquivos HTML em data/AP/.

14. OTA Update

Atualização remota de firmware via biblioteca ESP2SOTA@^1.0.2. Estado dedicado: EstadoOTAUpdate.

Fluxo

1. Usuário ativa modo OTA via menu local (ou via comando MQTT no futuro).
2. Firmware desconecta Wi-Fi STA, sobe rede yarabox_OTA.
3. Usuário conecta na rede e acessa http://yarabox-ota.local.
4. Upload do arquivo .bin do novo firmware.
5. ESP2SOTA grava em app1, atualiza otadata, reinicia.
6. Em caso de boot falho do app1, fallback automático para app0.

Pré-requisito de segurança: OTA via AP local apenas. Não há OTA via internet pública nesta versão — evita exposição da superfície de ataque (decisão técnica, ver ARCHITECTURE.md §"Decisões").

Fonte: lib/ota_update/src/.

15. Mapeamento de pinos

Endereços I²C:

• ADS1115 #1 — 0x48 (sensores PT100-103 principais)
• ADS1115 #2 — 0x49 (canais de expansão)
• PCF8574 #1 — 0x20 (relés, válvulas, LEDs principais)
• PCF8574 #2 — 0x24 (expansão de saídas/entradas)
• SH1107 (display) — 0x3C

Mapeamento detalhado por sub-circuito está em Cap 2 §3.3 e nos esquemáticos do Apêndice B.

16. Compilar, gravar e debugar

Pré-requisitos

• Sistema: macOS, Linux ou Windows
• PlatformIO Core (CLI) ou extensão PlatformIO IDE no VS Code
• Driver USB-Serial: CP210x ou CH340 (depende da revisão do ESP32-S3-DevKitC-1) — normalmente reconhecido nativamente em macOS e Linux recentes

Clone e setup

gh repo clone agua-camelo-cs/YB-modulo-basico
cd YB-modulo-basico
pio pkg install   # instala todas as libs declaradas em platformio.ini

Build

pio run                              # compila firmware
pio run -t buildfs                   # constrói imagem do LittleFS (data/ → spiffs.bin)

Gravar firmware via USB

pio run -t upload                    # grava firmware
pio run -t uploadfs                  # grava conteúdo de data/ no LittleFS
pio device monitor                   # serial monitor 115200 baud + esp32_exception_decoder

Gravar firmware via OTA (placa já em produção)

1. Ativar OTA mode (via menu local).
2. Conectar à rede yarabox_OTA.
3. Acessar http://yarabox-ota.local no navegador.
4. Upload do .bin em .pio/build/esp32-s3-devkitc-1/firmware.bin.
5. Aguardar reinício automático.

Debug

• esp32_exception_decoder já está habilitado em monitor_filters — qualquer crash resulta em backtrace legível no monitor serial.
• Coredump partition (128 KB) salva dump completo em caso de panic — pode ser extraído via espcoredump.py.
• pio device monitor --filter esp32_exception_decoder força o filtro mesmo fora do contexto do platformio.ini.

Geração de docs

doxygen Doxyfile                     # gera HTML em docs/ a partir dos comentários do código

Fontes deste capítulo

• Repositório de firmware (local): Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/modulo-basico/
  • ARCHITECTURE.md (1700+ linhas — referência primária para detalhes)
  • README.md (26 KB — guia de uso)
  • platformio.ini
  • custom_partitions.csv
  • src/main.cpp, src/main.h
  • lib/<15 módulos>/
  • data/config.json, data/config-padrao-fabrica.json, data/AP/
• Repositório GitHub (mirror privado): agua-camelo-cs/YB-modulo-basico
• Macroentregas_Embrapii/Macroentrega_3/5.1 .../Manual do desenvolvedor.docx
• Macroentregas_Embrapii/Macroentrega_3/5.1 .../manual-do-desenvovedor-módulo-básico.pdf
• Arquitetura_Yara_Box/Visao_Tecnica_Wara_Box.md §3.4
• Backup operacional da unidade 001: /11-Confidencial/YaraBox_001_Backup_Config.md

Status: ✅ pronto Última atualização: 2026-05-14 Audiência: engenheiro DevOps / infra (Linux, Docker, Nginx, DNS, TLS) Tempo de leitura estimado: 30 minutos Pré-requisito: acesso a uma máquina cliente com SSH, terminal, e capacidade de provisionar VPS em algum provedor

Sumário

• 1. Visão geral da arquitetura
• 2. Decisões arquiteturais e o porquê
  • 2.1. Provedor da VPS (Vultr Cloud Compute SP)
  • 2.2. Sistema operacional
  • 2.3. ThingsBoard CE vs PE
  • 2.4. Imagem Docker do ThingsBoard
  • 2.5. Volumes Docker — nomeados, não bind mount
  • 2.6. Mapeamento de portas
  • 2.7. SSH — desabilitar root e senha
  • 2.8. Firewall UFW + fail2ban
  • 2.9. SSL Let's Encrypt automático
  • 2.10. DNS
• 3. Setup passo a passo (comandos reais)
• 4. Setup inicial dentro do ThingsBoard
• 5. Configurar o device para conectar
• 6. Compartilhamento de acesso
• 7. Operação contínua
• 8. Custos recorrentes
• 9. Troubleshooting comum
• 10. Pontos em aberto / próximos passos da infra
• 11. Glossário rápido

1. Visão geral da arquitetura

A Yara Box é um produto IoT que precisa de três camadas de backend em produção:

1. Broker MQTT — para os devices em campo conectarem e publicarem telemetria
2. Plataforma IoT — armazena telemetria, gerencia devices, regras, alarmes, dashboards
3. Web frontend (UI/admin) — para humanos acessarem o sistema via navegador, com HTTPS e autenticação

A solução escolhida usa ThingsBoard Community Edition (CE) como peça central porque resolve as 3 camadas em um único produto open source bem mantido: ele é broker MQTT, plataforma IoT, e tem UI web embutida. O sistema roda em uma VPS Linux controlada pela Água Camelo / Wara Tech, atrás de um Nginx que faz proxy reverso e termina TLS via Let's Encrypt, com DNS apontado pelo registrador do domínio.

┌─────────────────────────────────────────────────────────────────┐
│                  INTERNET                                       │
└─────────────────────────────────────────────────────────────────┘
        │                                       │
        │ HTTPS (443)                          │ MQTT plain (1883)
        │ acesso humano                        │ devices Yara Box
        ▼                                       ▼
┌─────────────────────────────────────────────────────────────────┐
│  VPS Vultr — São Paulo, BR                                      │
│  216.238.100.81 | aguacamelo-tb | Ubuntu 24.04 LTS              │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ UFW (firewall) → portas: 22, 80, 443, 1883, 8883         │   │
│  │ fail2ban → bane SSH brute force                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ Nginx (HTTP/HTTPS) — porta 80→redirect 443→proxy 8080    │   │
│  │   SSL Let's Encrypt (renovação automática via certbot)   │   │
│  └────────────────────────┬─────────────────────────────────┘   │
│                           │                                     │
│                           ▼                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ Docker Compose                                            │   │
│  │   container: thingsboard (imagem tb-postgres:latest)      │   │
│  │     - escuta 127.0.0.1:8080 (HTTP web UI, só localhost)   │   │
│  │     - escuta 0.0.0.0:1883 (MQTT, exposto publicamente)    │   │
│  │     - volumes nomeados: tb-data, tb-logs                  │   │
│  │     - Postgres embutido (banco interno)                   │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

DNS: o subdomínio yarabox.aguacamelo.com.br aponta para o IP fixo da VPS via A record no registrador (GoDaddy no caso atual; qualquer registrador serve).

Em produção (validado em 14/05/2026): https://yarabox.aguacamelo.com.br responde HTTP/1.1 200 OK com nginx 1.24.0 e certificado Let's Encrypt válido. MQTT :1883 recebe telemetria da unidade YB-001 a cada 30 s.

2. Decisões arquiteturais e o porquê

2.1. Provedor da VPS

Escolhido: Vultr Cloud Compute, datacenter São Paulo. Plano: vhf-2c-4gb (High Frequency, 2 vCPU, 4 GB RAM, 128 GB NVMe). Custo: ~$36/mês + ~$5/mês de auto-backup = ~$41/mês total.

Por que não outros:

• Hostinger VPS BR: parecia óbvio pelo "pagamento em real, NF", mas Hostinger não tem datacenter no Brasil para VPS (só compartilhado/cloud hosting comum). Verificar antes de comprar.
• DigitalOcean: sem São Paulo. Latência maior pra IoT (~120 ms vs ~10 ms da VPS SP).
• AWS Lightsail: tem SP, preço parecido. Boa alternativa se for migrar para o ecossistema AWS depois.
• Magalu Cloud: brasileira, datacenter BR, mais nova (menos provada).
• GoDaddy VPS: sem datacenter BR, painel limitado para Linux puro.

Critério decisor: datacenter no Brasil para minimizar latência MQTT (IoT em campo, redes 4G instáveis, packets pesam) + provedor maduro com snapshots/firewall/API.

2.2. Sistema operacional

Escolhido: Ubuntu 24.04 LTS x64. Por que: distribuição mais comum, LTS até 2029, documentação abundante para Docker e systemd.

2.3. ThingsBoard CE vs PE

Escolhido: Community Edition (open source, gratuito). Por que: CE tem todas as features que o MVP precisa (MQTT, REST API, devices, telemetria, dashboards, regras, alarmes, multi-tenant). PE custa $$$/device/mês e oferece extras (white-label, scheduling avançado, integrations enterprise) que não justificam o gasto enquanto há ~1 unidade em operação.

Quando reconsiderar PE: se passar de ~50 devices em produção e/ou precisar white-label fortemente para revender SaaS.

2.4. Imagem Docker do ThingsBoard

Escolhido: thingsboard/tb-postgres:latest (monolítica, Postgres embutido). Por que: simples, um único container roda TB + DB. Backup vira backup do volume.

Quando trocar: quando precisar escalar Postgres separado (com replicação, gerência dedicada), trocar para thingsboard/tb-node (TB stateless) + container Postgres separado + volume dedicado.

2.5. Volumes Docker — nomeados, NÃO bind mount

Pegadinha crítica: se usar bind mount (./tb-data:/data), o usuário interno do container (UID do processo thingsboard) não tem permissão de escrever na pasta do host (que pertence ao UID 1001 do usuário admin). Erro fatal na primeira inicialização:

mkdir: cannot create directory '/data/db': Permission denied

Solução: usar volumes nomeados (tb-data:/data), gerenciados pelo Docker. O Docker resolve a permissão automaticamente.

2.6. Mapeamento de portas

Por que 8080 só em localhost: se exposto publicamente, a interface admin do TB ficaria acessível em HTTP plain (login passa em texto claro). Forçar o tráfego pelo nginx garante TLS obrigatório.

2.7. SSH — desabilitar root e senha

Práticas básicas mas essenciais:

• Cria usuário não-root com sudo (aguacamelo neste caso) e configura NOPASSWD para sudo, já que login só por SSH key.
• Copia a chave SSH do root para o usuário novo antes de desabilitar root.
• Desabilita PermitRootLogin (sem login root direto, mesmo com chave).
• Desabilita PasswordAuthentication (força chave SSH sempre).

⚠️ Pegadinha crítica do sshd no Ubuntu: o sshd lê arquivos drop-in em /etc/ssh/sshd_config.d/ em ordem alfabética, e o primeiro valor encontrado prevalece — não o último. Por isso o arquivo de hardening precisa começar com 00- para ganhar precedência sobre 50-cloud-init.conf (que vem com PasswordAuthentication yes por padrão na Vultr).

2.8. Firewall UFW + fail2ban

UFW define política deny incoming por padrão e libera apenas: 22 (SSH), 80, 443, 1883, 8883. Tudo mais é bloqueado.

fail2ban monitora /var/log/auth.log (SSH) e bane IPs após 5 falhas em 10 minutos por 1 h. Cobertura mínima viável; pode expandir para nginx/MQTT depois.

2.9. SSL Let's Encrypt automático

certbot com plugin nginx faz todo o ciclo:

• Solicita certificado válido para o domínio
• Reescreve /etc/nginx/sites-available/ adicionando bloco server { listen 443 ssl; ... }
• Adiciona redirect HTTP→HTTPS no bloco da porta 80
• Configura certbot.timer no systemd para tentar renovação 2× por dia (renova quando faltam ≤30 dias)

Custo zero. Certificado válido por 90 dias, renovado automaticamente.

2.10. DNS

Escolhido: registrador do domínio mantém o DNS (no caso, GoDaddy). A record yarabox → IP da VPS, TTL 600 s (10 min — adequado para migrações futuras).

Não foi preciso Cloudflare ou DNS de terceiros porque o tráfego é baixo e não há ataque DDoS plausível para justificar proxying.

3. Setup passo a passo (comandos reais)

Os comandos abaixo são reproduzíveis verbatim, testados em 14/05/2026. Substitua <IP> pelo IP público da sua VPS quando aparecer.

3.1. Provisionar VPS (no painel da Vultr)

• Deploy → Cloud Compute → Shared CPU → Intel Regular (ou AMD High Performance)
• Localização: São Paulo
• Imagem: Ubuntu 24.04 LTS x64
• Plano: vhf-2c-4gb (~$36/mo base + ~$4.80 backups = ~$41/mês em SP)
• SSH Key: cadastrar a chave pública (~/.ssh/id_ed25519.pub no Mac local). Antes, gerar a chave se ainda não houver:

  ssh-keygen -t ed25519 -C "rodrigo@waratech" -f ~/.ssh/id_ed25519 -N ""
  cat ~/.ssh/id_ed25519.pub  # copiar e colar no Vultr
  

• Hostname/Label: aguacamelo-tb
• Auto-backups: ✅ Enabled
• IPv6: ✅
• Deploy → aguardar status "Running" (~2–5 min)
• Anotar o IP público (no exemplo histórico: 216.238.100.81)

3.2. Conectar via SSH

No Mac local:

ssh root@<IP>   # primeira vez, confirmar fingerprint com "yes"

Se aparecer "Connection refused", aguardar mais 1 minuto (boot do sshd).

3.3. Hardening — atualizações, timezone e swap

Dentro da VPS:

# Em background protegido (sobrevive a queda de SSH)
nohup bash -c '
apt update && apt upgrade -y
timedatectl set-timezone America/Sao_Paulo

if [ "$(swapon --show | wc -l)" -eq 0 ]; then
  fallocate -l 4G /swapfile
  chmod 600 /swapfile
  mkswap /swapfile
  swapon /swapfile
  echo "/swapfile none swap sw 0 0" >> /etc/fstab
  echo "Swap de 4GB criado"
else
  echo "Swap ja existe"
fi
' > /tmp/setup.log 2>&1 &

# Acompanhar
tail -f /tmp/setup.log

A Vultr já provisiona ~8 GB de swap por padrão. Se já existe, o script só verifica.

Configurar SSH keep-alive no Mac local (evitar conexões caindo durante apt upgrade longo):

cat >> ~/.ssh/config <<'EOF'

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
EOF

3.4. Hardening — usuário não-root

adduser --gecos "" --disabled-password aguacamelo
usermod -aG sudo aguacamelo

mkdir -p /home/aguacamelo/.ssh
cp /root/.ssh/authorized_keys /home/aguacamelo/.ssh/authorized_keys
chown -R aguacamelo:aguacamelo /home/aguacamelo/.ssh
chmod 700 /home/aguacamelo/.ssh
chmod 600 /home/aguacamelo/.ssh/authorized_keys

# sudo sem senha (login só por chave SSH, então senha não é "second factor" útil)
echo 'aguacamelo ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/90-aguacamelo
chmod 440 /etc/sudoers.d/90-aguacamelo

Validar ANTES de fechar SSH como root: em outra janela, ssh aguacamelo@<IP> deve entrar direto, e sudo -n whoami deve retornar root.

3.5. Hardening — SSH (desabilitar root + senha)

Drop-in que ganha precedência alfabética:

cat > /etc/ssh/sshd_config.d/00-hardening.conf <<EOF
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
ChallengeResponseAuthentication no
KbdInteractiveAuthentication no
EOF
chmod 644 /etc/ssh/sshd_config.d/00-hardening.conf

sshd -t && systemctl reload ssh
sshd -T | grep -iE "^permitrootlogin|^passwordauthentication|^pubkeyauthentication"

Teste de fogo:

• ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no root@<IP> → deve falhar com Permission denied (publickey)
• ssh aguacamelo@<IP> → deve entrar normal

3.6. Hardening — UFW + fail2ban

sudo apt install -y ufw fail2ban

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp comment 'HTTP (nginx → ThingsBoard)'
sudo ufw allow 443/tcp comment 'HTTPS (nginx → ThingsBoard)'
sudo ufw allow 1883/tcp comment 'MQTT plain'
sudo ufw allow 8883/tcp comment 'MQTT TLS'
sudo ufw --force enable

sudo tee /etc/fail2ban/jail.local > /dev/null <<EOF
[DEFAULT]
bantime = 1h
findtime = 10m
maxretry = 5

[sshd]
enabled = true
port = ssh
EOF

sudo systemctl enable --now fail2ban
sudo ufw status verbose
sudo fail2ban-client status sshd

3.7. Instalar Docker

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker aguacamelo
sudo systemctl enable --now docker

# Reconectar SSH para o grupo docker valer na sessão
exit
ssh aguacamelo@<IP>

docker run --rm hello-world   # validação

3.8. Subir ThingsBoard via Docker Compose

sudo mkdir -p /opt/thingsboard
sudo chown aguacamelo:aguacamelo /opt/thingsboard
cd /opt/thingsboard

cat > docker-compose.yml <<'EOF'
services:
  thingsboard:
    image: thingsboard/tb-postgres:latest
    container_name: thingsboard
    restart: always
    ports:
      - "127.0.0.1:8080:9090"   # HTTP UI — só localhost (nginx faz proxy)
      - "1883:1883"              # MQTT plain — exposto publicamente
    environment:
      TB_QUEUE_TYPE: in-memory
    volumes:
      - tb-data:/data
      - tb-logs:/var/log/thingsboard

volumes:
  tb-data:
  tb-logs:
EOF

docker compose up -d
docker compose logs -f

Aguardar a linha Started ThingsBoardServerApplication in XX seconds no log (3–5 min na primeira inicialização, porque cria schema do Postgres). Depois Ctrl+C no tail.

3.9. Apontar DNS

No painel do registrador (GoDaddy → DNS → Records):

• Tipo: A
• Nome: yarabox
• Valor: <IP da VPS>
• TTL: 600

Aguardar propagação (10–60 min, em geral muito rápido). Validar:

dig +short yarabox.aguacamelo.com.br
# deve retornar o IP da VPS

3.10. Nginx + SSL Let's Encrypt

sudo apt install -y nginx certbot python3-certbot-nginx

sudo tee /etc/nginx/sites-available/thingsboard > /dev/null <<'EOF'
server {
    listen 80;
    listen [::]:80;
    server_name yarabox.aguacamelo.com.br;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support (TB usa para real-time)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }
}
EOF

sudo ln -sf /etc/nginx/sites-available/thingsboard /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx

# Solicitar cert + ativar HTTPS automático com redirect HTTP→HTTPS
sudo certbot --nginx \
  -d yarabox.aguacamelo.com.br \
  --non-interactive \
  --agree-tos \
  -m rodrigobelli@aguacamelo.com.br \
  --redirect

Validação final:

curl -I https://yarabox.aguacamelo.com.br/   # deve retornar HTTP/1.1 200 ou 3xx
systemctl list-timers | grep certbot         # deve mostrar certbot.timer ativo

4. Setup inicial dentro do ThingsBoard

4.1. Primeiro login (sysadmin)

Abra https://yarabox.aguacamelo.com.br no navegador.

Imediatamente o TB força troca de senha. Crie uma senha forte (24+ chars de password manager) e salve no cofre de credenciais ANTES de submeter (se perder, fica trancado fora do sysadmin sem recovery built-in).

Em seguida, vá em Profile → troque o email do sysadmin para algo institucional (ex: o email do dono da plataforma, não @thingsboard.org). Reduz superfície de ataque.

4.2. Criar Tenant

Como sysadmin: Locatários (Tenants) → + → preencher:

Padrão arquitetural: tenant = empresa operacional. Não usar "Yara Box" como nome de tenant — Yara Box é o produto. Cada cliente que opera Yara Boxes é um tenant separado. Isolamento de dados é design fundamental do TB.

4.3. Criar Tenant Admin

Na linha do tenant → ícone de pessoa (Tenant Administrators) → +:

• Email: do admin operacional (no caso, sócio que vai operar)
• Send activation mail: desmarcar (SMTP ainda não configurado)
• Display activation link: marcar (TB vai te dar URL de ativação na hora)

Copie o link de ativação, abra em uma aba nova, defina senha forte, salve no cofre. Conta agora ativa.

⚠️ Pegadinha: o link de ativação aponta para localhost:8080 se você está acessando via SSH tunnel. Se for repassar para outra pessoa em outra máquina, o link só funciona após o DNS+SSL estarem prontos (assim aponta direto para o domínio real). Boa prática: ativar você mesmo, salvar a senha, repassar email+senha para a pessoa via canal seguro depois.

4.4. Como o sysadmin acessa dashboards do tenant

Sysadmin NÃO vê dashboards diretamente (design do TB — separação plataforma vs operação). Para acessar:

• Locatários → linha do tenant → "Login as Tenant Administrator" (impersonação)
• Interface muda para visão do tenant admin
• Pode criar/editar dashboards, devices, etc.

4.5. Device Profile

Como tenant admin: Profiles → Device profiles → + → Adicionar perfil de dispositivo (NÃO "Importar" — vai dar erro por refs quebradas se importar JSON do TB antigo).

Preencher:

• Name: Perfil <Tipo de Device> (ex: Perfil Água Camelo)
• Profile type / Transport type: Default
• Demais campos: deixar em branco

Você pode adicionar alarms depois (na seção Alarm rules dentro do profile).

⚠️ Por que NÃO importar JSON: profiles do TB antigo carregam defaultRuleChainId apontando para rule chain do servidor antigo (UUID que não existe na instância nova). Erro: "Can't assign non-existent rule chain". Criar manual evita o problema.

4.6. Criar device

Entidades → Dispositivos → + → Adicionar dispositivo:

Após criar, clique no device → aba/seção "Credenciais" → copie o Access Token (string tipo L89lNbR77bcBCf7hSPeT). Esse token é o que o firmware vai usar para autenticar no MQTT.

5. Configurar o device para conectar

A Yara Box lê configurações em runtime do arquivo data/config.json (não hardcoded no firmware — ver Cap 5 §5). Dois caminhos para atualizar:

5.1. Via AP mode (mais simples, requer acesso físico/proximidade)

1. Liga a Yara Box. Ela cria rede Wi-Fi própria yarabox_AP (sem senha).
2. Conecta o celular/notebook nessa rede.
3. Abre http://yarabox.local ou http://192.168.4.1 no navegador.
4. Faz login em "Acesso Restrito": usuário camelo / senha @gu@c@m3l0 (defaults do firmware atual).
5. Edita campos:
   • Servidor MQTT = yarabox.aguacamelo.com.br
   • Token MQTT = o Access Token copiado do TB no §4.6
6. Salvar e reiniciar.

5.2. Via OTA Wi-Fi (avançado, remoto)

A Yara Box também sobe rede OTA (yarabox_OTA, senha no firmware — ver Cap 5 §14). Permite upload de novo config.json sem acesso físico. Procedimento detalhado no manual do desenvolvedor.

5.3. Validar telemetria chegando

No ThingsBoard como tenant admin:

• Dispositivos → clique no device → aba "Última telemetria"
• State deve mudar de Inactive para 🟢 Active em até 30 s após o boot
• Aba Last Telemetry mostra as keys (pressao_pt100, pressao_pt101, vazao_l_min, tensao_alimentacao, tensao_bateria, nivel_hipoclorito, estado, etc.) com timestamps recentes

Detalhes do payload em Cap 5 §11.

6. Compartilhamento de acesso

6.1. Sysadmin (admin total)

Login via email + senha. Salvar credenciais no cofre. Nunca compartilhar.

6.2. Tenant Admin (gerencia o tenant)

Login com email + senha. Pode haver múltiplos por tenant. Cada um com conta própria.

6.3. URL pública read-only (sem login)

Para mandar para funcionários internos ou demos rápidas, o ThingsBoard suporta tornar dashboard + devices "públicos":

1. No device → menu de ações → "Make public"
2. No dashboard → 3 pontinhos → "Make public dashboard"
3. TB gera URL tipo https://<dominio>/dashboard/<UUID>?publicId=<UUID>
4. Qualquer pessoa com a URL vê os dados read-only, sem login

Trade-offs:

Boa prática: usar para demos e prospecção. Para clientes pagantes, criar Customer + Customer User no tenant (acesso com login auditado, permissões granulares).

7. Operação contínua

7.1. Comandos úteis

Reiniciar TB:

cd /opt/thingsboard && docker compose restart

Ver logs em tempo real:

cd /opt/thingsboard && docker compose logs -f

Atualizar TB para nova versão:

cd /opt/thingsboard
docker compose pull
docker compose up -d

Status do sistema:

free -h                                # memória
df -h /                                # disco
systemctl status nginx
systemctl status fail2ban
sudo fail2ban-client status sshd

Renovar SSL manualmente (caso certbot.timer falhe):

sudo certbot renew --dry-run     # teste
sudo certbot renew                # real
sudo systemctl reload nginx

7.2. Backup

Camada 1 — Vultr Auto-Backup ($4.80/mês): snapshot semanal completo da VPS. Restore via painel. Bom para "voltar ao estado de uma semana atrás". Ruim para perda de dados recentes (até 7 dias podem se perder).

Camada 2 — Backup específico do volume tb-data (não configurado ainda, recomendado):

docker run --rm \
  -v thingsboard_tb-data:/data \
  -v "$(pwd)":/backup \
  alpine \
  tar czf /backup/tb-data-$(date +%Y%m%d).tar.gz /data

Pode ser scheduled via cron, mandando para S3/Vultr Object Storage. Permite backup diário granular e restore parcial (só DB).

7.3. Monitoring (não configurado ainda)

Recomendação futura: Prometheus + Grafana lendo métricas de node_exporter, nginx_exporter, cadvisor. Dashboards com uso de CPU/RAM/disco, latência HTTP, MQTT connection count, alertas via Slack/email.

8. Custos recorrentes

Cresce linearmente com:

• Upgrade de plano (mais devices, mais dashboards pesados) → próximo tier ~$48/mês
• Backup externo dedicado (S3/Vultr Object) → ~$5–10/mês conforme volume

9. Troubleshooting comum

10. Pontos em aberto / próximos passos da infra

• MQTT TLS na porta 8883 (atualmente devices usam 1883 plain — tráfego em texto claro). Requer certificado adicional para o broker MQTT e ajuste no firmware (módulo mqtt).
• Backup específico do Postgres com retenção (diário 7d + semanal 4w + mensal 12m) para S3/Vultr Object Storage.
• Monitoring (Prometheus + Grafana + alertas).
• DNS records secundários quando criar mqtt.aguacamelo.com.br ou app.aguacamelo.com.br para separar broker MQTT do painel web.
• Customer Users quando passar a ter clientes pagantes (substitui URL pública para acesso oficial).
• Multi-tenant ativo (hoje só tenant Água Camelo). Adicionar tenants conforme clientes onboardados.
• Frontend próprio consumindo TB API — substitui a UI default do TB pela cara branded da Wara Tech. Projeto separado (ver /01-Produto/Produto_Yara_Box/Dashboard_yara_box/HANDOFF_Dashboard_Wara_Tech.md).

11. Glossário rápido

Fontes deste capítulo

• manual-mestre/fontes/sessao_infra_2026-05-14_destilada.md (fonte primária, 648 linhas — sessão de 14/05/2026 que executou a migração do backend de iot.picg.iff.edu.br para yarabox.aguacamelo.com.br)
• /11-Confidencial/YaraBox_001_Backup_Config.md (parâmetros device-side: MQTT, GSM, NTP)
• /11-Confidencial/Credenciais_Acessos.md (credenciais sysadmin/tenant admin)
• ThingsBoard CE docs: https://thingsboard.io/docs/
• ThingsBoard Docker install: https://thingsboard.io/docs/user-guide/install/docker/
• Vultr Cloud Compute: https://www.vultr.com/products/cloud-compute/
• Let's Encrypt / certbot: https://certbot.eff.org/
• UFW Ubuntu: https://help.ubuntu.com/community/UFW

Referência histórica (substituída pela infra atual): Macroentregas_Embrapii/Macroentrega_3/5.1 Transferência da tecnologia ao cliente/Manual de configuração do VPS.docx (144 pgs, doc do PICG/Embrapii). Não usar como fonte primária — descreve a infra no servidor antigo iot.picg.iff.edu.br, descontinuada em 14/05/2026.

Status: 🚧 bloqueado (parcial) Última atualização: 2026-05-14 Audiência: engenheiro/técnico de bancada (montagem mecânica + hidráulica + eletrônica)

🚧 BLOQUEADO — aguardando sessão presencial com o PICG (item 1 do email Embrapii de 11/05/2026 — não retornado até 14/05/2026)

TODO ao destravar:

• Capturar passo-a-passo formal de montagem (sequência exata, torques, ferramentas)
• Fotos profissionais (ou vídeo) de cada etapa significativa
• Tempo estimado de montagem (hh:mm) com 1 técnico vs 2 técnicos
• Lista de ferramentas necessárias (Allen, torquímetro, alicate de crimpar, etc.)
• Lista de consumíveis (vedação, parafusos, conectores, fios)
• Checklist de inspeção de qualidade pós-montagem

Este capítulo documenta a estrutura conceitual da montagem com base no que JÁ está documentado em ME2, mas o passo-a-passo formal só será autoritativo após a sessão presencial.

Sumário

• 1. Pré-requisitos
• 2. Topologia da montagem em 4 camadas
• 3. Camada 1 — Estrutura (perfis alumínio + chapas PEAD)
• 4. Camada 2 — Sistema hidráulico
• 5. Camada 3 — Sistema eletrônico
• 6. Camada 4 — Sistema elétrico e bateria
• 7. Fechamento do gabinete
• 8. Inspeção final
• 9. Material de apoio disponível (workaround atual)

1. Pré-requisitos

Antes de iniciar a montagem:

1.1. Peças prontas

• PCBs fabricadas e testadas: Joker (Core), Seletora v1.1.1 (ver Cap 2)
• 7 chapas PEAD cortadas conforme PDFs cotados (ver Cap 3 §2.2)
• Perfis de alumínio dimensionados (ALU-01, ALU-02, ALU-03, ALU-04 — ver Apêndice A)
• Filtros Filtro 1 (disco 130 μm), Filtro 2 (MF 0,2 μm), Filtro 3A e 3B (UF 0,01 μm)
• Bombas: Bomba E (elétrica 12V/8L/min), Bomba D (peristáltica dosadora), Bomba manual (pistão)
• Sensores: PT100, PT101 (calibrados); PT102, PT103 (opcional); FE300; LSL200; LSLL200
• Atuadores: Solenóides S1 e S2; LED YL400; buzzer
• Conexões hidráulicas: T-fittings, joelhos, adaptadores, válvula de retenção (FV301)
• Reservatório de hipoclorito (TQ Cloro 1,5–2 L)
• Display SH1107, encoder rotativo, botoeiras HS500/501/502
• Bateria 18650 3S3P carregada
• Firmware gravado na PCB Joker (ver Cap 5 §16)

1.2. Ferramentas (lista preliminar — confirmar com PICG)

• Chave Allen (jogo completo)
• Chave de fenda Phillips e Pozidriv
• Alicate de bico
• Alicate de crimpar (terminais)
• Torquímetro (para parafusos M5/M6 dos perfis)
• Soldador (para conexões elétricas críticas)
• Multímetro
• Computador com PlatformIO para flash e debug

1.3. Área de trabalho

• Bancada limpa, plana, com pelo menos 1×1 m livre
• Tomada elétrica próxima
• Iluminação adequada para inspeção visual

2. Topologia da montagem em 4 camadas

A montagem segue bottom-up, em 4 camadas:

┌─────────────────────────────────────────────────────┐
│  Camada 4: Sistema elétrico + bateria + fechamento  │
├─────────────────────────────────────────────────────┤
│  Camada 3: Sistema eletrônico                       │
│     (PCBs + sensores + display + atuadores)         │
├─────────────────────────────────────────────────────┤
│  Camada 2: Sistema hidráulico                       │
│     (filtros + bombas + conexões + reservatório)    │
├─────────────────────────────────────────────────────┤
│  Camada 1: Estrutura (perfis + chapas PEAD)         │
└─────────────────────────────────────────────────────┘
                       ▲
                     Rodízios

Cada camada deve estar inspecionada e validada antes da próxima ser instalada.

3. Camada 1 — Estrutura (perfis alumínio + chapas PEAD)

3.1. Conceito

Montar o esqueleto em perfis de alumínio, fixar chapas PEAD como fechamentos. As 7 chapas têm posições específicas (ver Cap 3 §2.2).

3.2. Sequência conceitual

1. Posicionar os 6 perfis ALU-01 (680 mm) como esqueleto vertical e horizontal principal.
2. Conectar com cantoneiras (CANT-01) e parafusos M5/M6.
3. Adicionar perfis ALU-02 (300 mm), ALU-03 e ALU-04 (490 mm) conforme projeto.
4. Verificar esquadro com esquadro de marceneiro antes de apertar parafusos finais.
5. Fixar a divisória interna (PEAD-DIV) que separa o compartimento hidráulico do eletrônico.
6. Aplicar os 4 rodízios (SUP-ROD) na base, parafusados.
7. Instalar as 2 dobradiças (DOB-01) na tampa lateral.
8. Instalar tampo superior (TAMPO-01) e alça de transporte (ALC-01).
9. Reservar as 7 chapas PEAD — serão instaladas após Camadas 2 e 3.

🚧 Detalhes pendentes da sessão presencial PICG: torque exato dos parafusos, sequência de aperto, posicionamento exato de cada chapa, tolerâncias dimensionais.

4. Camada 2 — Sistema hidráulico

4.1. Conceito

Montar o circuito hidráulico completo no compartimento inferior, antes de fechar a tampa.

4.2. Sub-camadas

4.2.1. Fixação dos filtros

1. Posicionar Filtro 0 (grade/pré-filtro) na captação.
2. Fixar Filtro 1 (disco) com suporte adequado.
3. Fixar Filtro 2 (MF 0,2 μm) em posição vertical.
4. Fixar Filtros 3A e 3B (UF, em paralelo).

4.2.2. Conexões hidráulicas

Seguir o diagrama do Cap 3 §3:

• Captação → Filtro 0 → válvula de retenção FV301 → Bomba E → Filtro 1 → Filtro 2 → (Filtros 3A e 3B em paralelo) → ponto de mistura MIX → saída
• Reservatório TQ Cloro → Bomba D → ponto de mistura MIX
• Dreno de retrolavagem com solenóides S1/S2

Vedação: fita teflon ou pasta vedante em todas as conexões roscadas. Verificar com pressurização (até 0,5 MPa) antes da Camada 3.

4.2.3. Instalação dos sensores

• PT100, PT101 em pontos críticos do circuito (ver Cap 3 §4.2)
• FE300 (sensor de vazão) em linha após o ponto de mistura MIX
• LSL200 e LSLL200 no reservatório de hipoclorito (TQ Cloro)
• Cabos roteados para o compartimento eletrônico via passa-fios na divisória PEAD-DIV

4.2.4. Instalação das bombas

• Bomba E (elétrica) em suporte rígido para minimizar vibração
• Bomba D (dosadora peristáltica) em suporte dedicado (SUP-BOM-PERI), com mangueira pelos rolos da bomba
• Bomba manual (pistão) montada de modo que possa ser operada externamente sem abrir o gabinete

4.2.5. Reservatório de hipoclorito

Reservatório TQ Cloro (1,5–2 L) em suporte SUP-RES-HIPO, com tampa abrível pelo topo do gabinete para reposição em campo sem desmontagem.

4.3. Validação da Camada 2

Antes de prosseguir para a Camada 3:

• Teste de estanqueidade com água a 0,5 MPa em todos os pontos
• Verificar que Bomba E impulsiona água pelo circuito sem vazamentos
• Verificar que Bomba D injeta volume conhecido (calibração simples — ver Cap 8 §4)

5. Camada 3 — Sistema eletrônico

5.1. Conceito

Montar PCBs, display, encoder, botoeiras e fiação no compartimento eletrônico (acima da divisória PEAD-DIV).

5.2. Sequência

1. Fixar PCB Joker (Core) em suporte na divisória.
2. Fixar PCB Seletora em suporte na divisória (próxima à entrada de fontes externas).
3. Cabear sensores (PT100/101/102/103, FE300, LSL200, LSLL200) à PCB Core via conectores apropriados.
4. Conectar atuadores:
   • Bomba E → saída P7 da Seletora
   • Bomba D → saída controlada pela Joker (driver A4988)
   • Solenóides S1/S2 → saídas da Joker (drivers IRLZ44N)
5. Conectar alimentação: PCB Seletora → PCB Joker via J2.
6. Display SH1107 na frente da tampa principal, conectado ao barramento I²C.
7. Encoder rotativo + push-button (HS503) ao lado do display.
8. Botoeiras HS500/501/502 no painel frontal.
9. LED YL400 e buzzer no painel frontal.
10. Conectar antena GSM externa do SIM7080G (cabo coaxial) — antena deve sair do gabinete para campo aberto.

5.3. Validação da Camada 3

• Ao ligar (provisoriamente, com bateria de bancada), o display mostra logo de boot
• Encoder rotativo navega no menu
• Botoeiras respondem corretamente
• Sensores reportam leituras coerentes no display
• LEDs e buzzer testados via menu Geral → Teste
• Conexão Wi-Fi STA funciona (após configurar via AP mode)

6. Camada 4 — Sistema elétrico e bateria

6.1. Sequência

1. Instalar banco de bateria 18650 3S3P em suporte com BMS (se aplicável).
2. Conectar bateria à PCB Seletora via P6.
3. Instalar conectores externos P1 (AC), P2 (12VDC), P3/P4 (solar), P7 (saída bomba) nas laterais do gabinete.
4. Fixar fusíveis em cada linha de alimentação principal.
5. Cabear seguindo o projeto-eletrico (Cap 4 §10) — todas as conexões nomeadas conforme os sub-esquemáticos.
6. Aterrar o chassi do gabinete (perfis de alumínio) ao GND comum.

6.2. Validação da Camada 4

• Tensão de cada conector externo medida com multímetro
• Sistema liga com cada uma das 5 fontes individualmente (testar A, B, D — solar e gerador testáveis em bancada com fontes simuladas)
• Chaveamento automático entre fontes funciona ao desconectar a fonte primária
• Bateria recarrega quando há fonte externa ativa

7. Fechamento do gabinete

1. Instalar as 7 chapas PEAD conforme posicionamento (Cap 3 §2.2):
   • Chapa Posterior Interna (primeiro, do lado de dentro)
   • Chapa Posterior Externa
   • Chapa Lateral Direita Interna
   • Chapa Grande Lateral Esquerda (com janelas para sensores se houver)
   • Chapa Pequena Lateral Esquerda
   • Chapa Grande Superior e Inferior
   • Chapa Pequena Superior e Inferior
2. Fechar a tampa lateral com as 2 dobradiças (DOB-01) e travamento (ver Manual de Instalação e Operação - Tampa lateral).
3. Instalar manômetro analógico (MANOM-01) no painel frontal — verificar conexão hidráulica.

8. Inspeção final

Antes de enviar a unidade para ensaios ou para o cliente, validar todos os checklists das Camadas 2, 3 e 4 + esta lista final:

• Sem vazamentos sob pressão de 0,5 MPa por 30 minutos
• Bomba E aciona/desliga conforme comandos
• Bomba D doseia volume conhecido em tempo conhecido (validação rápida — sem calibrar)
• Todos os sensores reportam valores plausíveis no display
• Telemetria chega ao ThingsBoard em até 30 s após o boot (verificar na URL https://yarabox.aguacamelo.com.br)
• Calibrações restauradas conforme Apêndice C §8
• Concentração de hipoclorito (config.concentracao_hipoclorito_porcentagem) bate com o produto usado
• Rótulo de identificação afixado no gabinete (número de série, data de fabricação, contato do fabricante)
• Cabos externos protegidos contra umidade (conectores estanques se uso externo)

9. Material de apoio disponível (workaround atual)

Enquanto a sessão presencial com o PICG não acontece, os seguintes materiais cobrem ~50% da documentação de montagem:

9.1. Fotos da visita técnica de 24/10/2025

Em Macroentregas_Embrapii/Macroentrega_2/Fotos da Visita 24out25/:

• protótipo - vista do sistema hidráulico.JPG
• protótipo - teste iniciais com painéis solares.JPG
• protótipo - frontal painel.JPG
• IMG_1906.JPG, IMG_1907.JPG, IMG_1908.JPG, IMG_1910.JPG (vistas adicionais)

9.2. Documento original de montagem preliminar

Macroentregas_Embrapii/Macroentrega_2/3.4 Montagem preliminar do protótipo/Montagem do protótipo.docx

Descreve a montagem inicial do protótipo conforme realizada pelo PICG em ME2 (aceita em 03/11/2025). É a melhor referência atual até a sessão presencial.

9.3. Modelo 3D em STEP

Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/projeto-mecanico-hidraulico-main/

Permite visualizar a montagem completa em 3D para inferir posicionamento de peças (com a ressalva dos débitos técnicos documentados em Cap 3 §8).

9.4. PDFs cotados das chapas PEAD

Macroentregas_Embrapii/Macroentrega_3/5.1 .../picg-resposta-2026-05-14/Desenhos 2D cotados das Chapas/ (7 PDFs ABNT) — permitem fabricar as chapas em qualquer fornecedor de corte.

Fontes deste capítulo

• Macroentregas_Embrapii/Macroentrega_2/3.4 Montagem preliminar do protótipo/Montagem do protótipo.docx
• Macroentregas_Embrapii/Macroentrega_2/Fotos da Visita 24out25/
• Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/projeto-mecanico-hidraulico-main/ (STEP)
• Macroentregas_Embrapii/.../picg-resposta-2026-05-14/Desenhos 2D cotados das Chapas/
• Cap 3 — Mecânico & Hidráulico, Cap 2 — Eletrônica, Cap 4 — Elétrico, Cap 5 — Firmware

Status: ✅ pronto Última atualização: 2026-05-14 Audiência: técnico/engenheiro de bancada (instrumentação, metrologia básica) Tempo de leitura estimado: 25 minutos

Sumário

• 1. Princípio geral — regressão linear via ADS1115
• 2. Calibração dos sensores de pressão (PT100, PT101, PT102, PT103)
  • 2.1. Setup de bancada
  • 2.2. Procedimento de 2 pontos
  • 2.3. Cálculo dos coeficientes
  • 2.4. Exemplo trabalhado (PT101 da unidade 001)
  • 2.5. Aplicação dos coeficientes no firmware
• 3. Calibração do sensor de vazão (FE300)
• 4. Calibração da bomba dosadora
• 5. Calibração de tensões (bateria, bomba)
• 6. Validação bacteriológica e físico-química (ensaios Fundenor)
• 7. Recalibração — quando e como
• 8. Validação após troca de placa ou reset

1. Princípio geral — regressão linear via ADS1115

Todos os sensores analógicos da Yara Box (pressão PT100/101/102/103, tensão da bateria, tensão da bomba) passam pelo conversor ADS1115 (I²C, 16-bit, 4 canais) e usam a mesma equação de conversão:

y = a · x + b

Onde:

• x — valor lido pelo módulo ADS1115 (em mV ou unidade ADC bruta, conforme configuração)
• y — valor estimado da grandeza física (PSI para pressão, V para tensão)
• a — coeficiente angular da reta
• b — coeficiente linear

Os coeficientes ficam em data/config.json do firmware (ver Cap 5 §5) com chaves do tipo calibracao_<sensor>_a e calibracao_<sensor>_b. Podem ser atualizados via AP mode ou OTA sem reflashar o firmware.

Por que regressão linear simples (2 pontos)?

• Os sensores PT100-103 e o divisor de tensão usam sinais inerentemente lineares ao longo de sua faixa de operação.
• 2 pontos bem espaçados na faixa de interesse capturam tanto offset (b) quanto ganho (a).
• Procedimento de bancada simples, reproduzível por técnicos com calibrador básico.
• Caso o sensor mostre não-linearidade significativa no futuro, migrar para polinômio de 2º grau via firmware é um ajuste pontual no módulo dispositivos_ads.

Princípio do ADS1115 documentado pelo PICG:

"Para realizar a calibração da leitura do sinal proveniente do divisor de tensão, primeiramente aplicamos uma tensão na entrada do circuito e verificamos qual o valor foi lido pelo módulo ADS1115. Considerando que a razão entre os valores da tensão na entrada do circuito e o valor lido pelo módulo sempre será constante, podemos utilizar os resultados de duas medições, com valores de entrada distintos, para calcular os coeficientes de uma equação reduzida da reta na forma y = Ax + B."

Fonte: Macroentregas_Embrapii/.../picg-resposta-2026-05-14/procedimento_calibracao_sensor_vazão_bomba_dosadora.pdf (Apêndice A, página 19).

2. Calibração dos sensores de pressão

Procedimento formal entregue pelo PICG em 14/05/2026.

Fonte: Macroentregas_Embrapii/.../picg-resposta-2026-05-14/procedimento_calibracao_sensor_pressao.pdf.

2.1. Setup de bancada

Ar comprimido → Filtro regulador com manômetro → Sensor de pressão (DUT)
                                                ↓
                                                Manômetro de referência ou calibrador certificado

Materiais necessários:

• Fonte de ar comprimido (compressor de bancada com regulagem fina)
• Filtro regulador com manômetro (Festo, SMC ou equivalente)
• Manômetro de referência ou calibrador de pressão certificado (faixa 0–30 PSI mínimo)
• Mangueiras e adaptadores T para conectar simultaneamente o sensor (DUT) e o manômetro de referência
• Multímetro ou notebook para ler o ADS1115 via I²C (ou usar o próprio firmware com debug serial)

Yara Box em modo de leitura: ligar a unidade, garantir que o display mostra leitura da pressão (estados Ler/Exibir ativos). Alternativamente, conectar diretamente o sensor a uma bancada ADS1115 isolada com Arduino/ESP32 de testes.

2.2. Procedimento de 2 pontos

Passo 1: Ajustar a pressão de entrada para 0 PSI (válvula totalmente fechada). Passo 2: Registrar a leitura bruta do ADS1115 — anotar valor x₁. Passo 3: Ajustar a pressão para 20 PSI (faixa cobrindo a operação típica do sensor). Passo 4: Aguardar estabilização (~30 s). Passo 5: Registrar leitura ADS — anotar valor x₂. Passo 6: Calcular a e b conforme §2.3.

Recomendações operacionais:

• Evitar histerese: subir e descer a pressão pelo menos 2 ciclos antes de tomar leituras finais.
• Tomar a média de 3 leituras em cada ponto para reduzir ruído.
• Documentar temperatura ambiente e umidade — sensores capacitivos têm leve deriva com condições ambientais.
• Anotar todos os valores brutos em planilha (ver Apêndice C) para rastreabilidade.

2.3. Cálculo dos coeficientes

Dados dois pontos (x₁, y₁) e (x₂, y₂):

a = (y₂ - y₁) / (x₂ - x₁)
b = y₁ - a · x₁

Em código (pseudocódigo Python ou planilha):

y1, y2 = 0, 20          # PSI conhecidos
x1, x2 = 318, 793       # leituras ADS1115 medidas

a = (y2 - y1) / (x2 - x1)
b = y1 - a * x1

print(f"a = {a:.8f}")
print(f"b = {b:.8f}")
print(f"PSI = {a:.8f} × leitura {b:+.8f}")

2.4. Exemplo trabalhado (PT101 da unidade 001)

Dados reais do procedimento PICG anexados ao PDF:

Cálculo:

a = (20 - 0) / (793 - 318) = 20 / 475 = 0,04210526
b = 0 - 0,04210526 × 318 = -13,38947268

PSI = 0,04210526 × leitura - 13,38947268

✅ Match perfeito com a unidade 001 em produção:

"calibracao_pt101_a": 0.04210526,
"calibracao_pt101_b": -13.38947268

Este é o procedimento exato que originou os coeficientes em uso. Sempre validar contra YaraBox_001_Backup_Config.md em caso de dúvida.

📷 Foto do registro manual (cálculo no caderno do operador): ver Apêndice C §7.

2.5. Aplicação dos coeficientes no firmware

Via AP mode (recomendado em bancada):

1. Conectar à rede yarabox_AP
2. Acessar http://yarabox.local → login camelo / @gu@c@m3l0
3. Em Calibrações → Pressão, atualizar a e b para cada PT.
4. Salvar → firmware reinicia e usa os novos valores.

Via edição direta (avançado — só em bancada, com placa desligada):

1. Conectar via USB.
2. Editar data/config.json manualmente.
3. Gravar LittleFS: pio run -t uploadfs.
4. Reiniciar.

3. Calibração do sensor de vazão (FE300)

Procedimento formal entregue pelo PICG em 14/05/2026.

Fonte: Macroentregas_Embrapii/.../picg-resposta-2026-05-14/procedimento_calibracao_sensor_vazão_bomba_dosadora.pdf (Apêndice A, página 19–20).

3.1. Princípio

O sensor de vazão funciona enviando um pulso sempre que um determinado volume fixo passar por ele. A calibração determina a resolução — qual volume precisa passar pelo sensor para gerar um pulso.

3.2. Setup de bancada

Reservatório de água → Mangueira → FE300 (sensor de vazão DUT) → Becker graduado

Materiais:

• Reservatório elevado ou bomba para fornecer vazão constante
• Mangueira compatível com a entrada do FE300 (1/4" ou conforme especificação)
• Becker graduado com escala adequada (volume típico do teste: 1 L)
• ESP32/Arduino para contar pulsos do FE300 (firmware Yara Box em modo de teste ou bancada isolada)
• Cronômetro (apenas para taxa — não interfere no cálculo da resolução)

3.3. Procedimento

1. Zerar o contador de pulsos no firmware.
2. Posicionar o becker abaixo da saída.
3. Abrir a válvula e deixar a água passar pelo sensor.
4. Quando o becker estiver com volume conhecido (ex: 1000 mL), fechar a válvula.
5. Ler o número de pulsos acumulados no firmware.
6. Anotar par (volume, pulsos).
7. Repetir pelo menos 4 vezes com volumes diferentes (mas conhecidos, lidos no becker).
8. Calcular a resolução média em mL/pulso.

3.4. Tabela de medições (PICG, exemplo de bancada)

3.5. Cálculo para uso no firmware

A unidade 001 está com calibracao_vazao = 0.253526896 no config.json, ligeiramente diferente da média do PDF. Isso é esperado — cada sensor tem variação individual e pode ser recalibrado após instalação.

Importante: o firmware trata o coeficiente como mL/pulso, então o valor de config.calibracao_vazao é diretamente a resolução medida. Para converter para pulsos/L (útil em cálculos externos):

pulsos_por_L = 1000 / calibracao_vazao
              = 1000 / 0.253526896
              ≈ 3944 pulsos/L

3.6. Drift progressivo — observação técnica do PICG

⚠️ Atenção operacional: "a leitura fornecida pelo sensor de vazão tem apresentado uma discrepância progressiva em relação ao volume real de água. Faz-se necessário investigar a correlação entre o desgaste operacional do equipamento e a deriva da calibração, a fim de estabelecer a periodicidade ideal para a recalibração do sensor de vazão."

— procedimento_calibracao_sensor_vazão_bomba_dosadora.pdf, p. 19–20

Implicação: o intervalo padrão atual de recalibração da vazão é 100.000 L (config.volume_recomendado_nova_calibracao_vazao), mas pode ser ajustado em função de evidência empírica acumulada. Plano de recalibração detalhado em Cap 10 §10.

4. Calibração da bomba dosadora

Procedimento formal entregue pelo PICG em 14/05/2026.

Fonte: Macroentregas_Embrapii/.../picg-resposta-2026-05-14/procedimento_calibracao_sensor_vazão_bomba_dosadora.pdf.

4.1. Princípio

A bomba dosadora é movida por um motor de passo (driver A4988), que permite controle preciso do volume dispensado. A quantidade de fluido é proporcional ao número de passos executados.

O objetivo da calibração é encontrar a relação entre passos e volume dispensado em um intervalo conhecido.

4.2. Setup de bancada

Reservatório de água/cloro → Bomba dosadora (DUT) → Proveta graduada

Materiais:

• Reservatório com líquido a dispensar (água destilada ou hipoclorito de teste)
• Proveta graduada (escala adequada, tipicamente 10–50 mL)
• Cronômetro
• Bomba dosadora montada conforme produto final (com driver A4988 + motor de passo)
• ESP32/Arduino para comandar a bomba (firmware Yara Box em modo de teste)

4.3. Procedimento

1. Conectar a bomba ao reservatório e à proveta vazia.
2. Configurar a bomba para operar a velocidade P passos/min por tempo T minutos.
3. Acionar a bomba.
4. Ao terminar T, parar a bomba e medir o volume V (mL) dispensado.
5. Calcular a constante de calibração:

calibração = (P × T) / V

6. Repetir com pelo menos 3 combinações diferentes de P e T para validar consistência.
7. Calcular a média.

4.4. Tabela de medições (PICG, exemplo de bancada)

4.5. Aplicação em runtime

O firmware usa o coeficiente para calcular a velocidade da bomba dosadora em função da vazão instantânea e da dose-alvo de hipoclorito:

velocidade_passo = calibração × vazao_minuto × dose_hipoclorito

Onde:

• calibração — valor médio calibrado (ex: 0,32078446)
• vazao_minuto — vazão instantânea em L/min (do FE300)
• dose_hipoclorito — dose-alvo em mg/L (de config.dose_hipoclorito_ug-L.valor)

Match perfeito com a unidade 001:

"calibracao_bomba_dosadora": 0.32078445

(7 casas decimais batendo com a média do PDF — confirma que este foi o procedimento que originou o coeficiente em uso.)

5. Calibração de tensões (bateria, bomba)

⚠️ Gap pequeno — o procedimento formal do PICG cobre o princípio do ADS1115 mas não traz exemplo numérico específico de calibração de tensões.

5.1. Princípio (extrapolado)

A calibração segue o princípio idêntico ao da pressão (§2), pois ambas as grandezas (tensão e pressão) passam pelo mesmo módulo ADS1115 com divisor de tensão associado:

1. Aplicar uma tensão conhecida V₁ (ex: 0 V curto-circuitando a entrada, ou usando fonte de bancada precisa).
2. Ler a leitura do ADS1115 (x₁).
3. Aplicar uma segunda tensão conhecida V₂ (ex: tensão nominal do banco — 12,6 V para bateria 3S Li-ion totalmente carregada).
4. Ler o ADS1115 (x₂).
5. Calcular a = (V₂ - V₁) / (x₂ - x₁) e b = V₁ - a × x₁.

5.2. Valores reais aplicados na unidade 001

Fontes de bancada recomendadas para a calibração:

• Tensão bateria: banco 3S Li-ion carregado em 12,6 V (medido com multímetro de referência) + curto-circuito em 0 V para o segundo ponto.
• Tensão bomba: fonte de bancada ajustável (ex: 0 V e 14 V) — b = 0 na unidade 001 sugere que o divisor de tensão dela é linear sem offset, característica do circuito de entrada usado.

5.3. TODO

Pedir ao PICG, em follow-up curto, o exemplo numérico das medições brutas (V aplicado vs leitura ADS) para registro completo no Apêndice C.

6. Validação bacteriológica e físico-química (ensaios Fundenor)

Os ensaios laboratoriais validam o sistema completo (filtração + cloração) contra os parâmetros da Portaria GM/MS Nº 888/2021.

Laboratório: Fundenor — Campos dos Goytacazes, RJ. Fonte de água: Rio Paraíba do Sul. Referência completa: Macroentregas_Embrapii/Macroentrega_3/Testes/consolidado-ensaios.md.

6.1. Ensaio 1 — 03/03/2026 (água de alta turbidez, 139 NTU)

6.2. Ensaio 2 — 11/03/2026 (mesma fonte, condições melhores)

6.3. Causa raiz do problema do cloro

Identificada após Ensaio 1: o cálculo de dosagem no firmware usava concentracao_hipoclorito_porcentagem = 12 quando o produto real era 4%.

Correção aplicada: ajustar para concentracao_hipoclorito_porcentagem = 4 no config.json. Cloro subiu de 0,1 para 0,8 mg/L (dentro do padrão).

⚠️ Aprendizado operacional: SEMPRE verificar config.concentracao_hipoclorito_porcentagem contra o produto que está efetivamente sendo usado. Ver Cap 10 §7.3.

6.4. Gargalo identificado: Filtro de Microfiltração (MF 0,2 μm)

O filtro MF (cartucho descartável, não lavável, não plissado) saturou após ~400–450 L com água de 140 NTU. 400 L de autonomia torna o produto inviável comercialmente em fontes de água de alta turbidez.

Plano: substituição por filtro tipo "Camelo" (carcaça inox, lavável, retrolavável). Resultado do teste de substituição (25/03/2026) pendente de incorporação aqui — ver consolidado-ensaios.md para status mais recente.

7. Recalibração — quando e como

7.1. Sensores de pressão (PT100, PT101)

• Intervalo recomendado: a cada 100.000 L tratados ou quando o operador suspeitar de deriva (leitura inconsistente com manômetro analógico físico — MANOM-01 no painel frontal).
• Procedimento: §2 — requer remover o sensor do circuito e levar à bancada.
• Alternativa em campo: calibração de 1 ponto (offset) sem remover — comparar leitura com manômetro de referência conectado em paralelo, ajustar b mantendo a.

7.2. Sensor de vazão

• Intervalo recomendado: a cada 100.000 L (atual) — mas atenção ao drift documentado pelo PICG (§3.6).
• Procedimento: §3.
• Em campo: difícil de fazer com precisão sem becker graduado. Recomendar troca preventiva se o drift exceder ±5% antes do intervalo.

7.3. Bomba dosadora

• Intervalo recomendado: a cada troca de bomba ou anualmente. A bomba peristáltica desgasta a tubulação interna com o tempo.
• Procedimento: §4.
• Validação rápida em campo: verificar visualmente se o cloro residual está dentro de 0,2–2 mg/L (sentido organoléptico ou teste DPD). Se está consistentemente baixo, recalibrar.

7.4. Tensões

• Intervalo recomendado: anualmente ou após troca de placa.
• Procedimento: §5.

8. Validação após troca de placa ou reset

Quando uma placa é substituída ou o firmware é resetado para fábrica, todos os coeficientes devem ser restaurados a partir do backup operacional da unidade.

8.1. Procedimento

1. Localizar o backup da unidade específica: /11-Confidencial/YaraBox_<NNN>_Backup_Config.md (para a unidade 001, é YaraBox_001_Backup_Config.md).
2. Conectar à rede yarabox_AP (sem senha).
3. Acessar http://yarabox.local → login camelo / @gu@c@m3l0.
4. Em Calibrações, inserir cada coeficiente do backup (todos os valores a e b).
5. Em MQTT, inserir o token e o server.
6. Em Wi-Fi, inserir SSID e senha do cliente.
7. Salvar → unidade reinicia.

8.2. Validação pós-restauração (checklist)

• Display mostra leituras coerentes (pressão 0–30 PSI, vazão na faixa esperada, hipoclorito ~100%, tensão bateria ~12 V)
• LED YL400 reflete o estado correto
• No ThingsBoard, a unidade volta a aparecer 🟢 Active em até 30 s após o boot
• Dashboard mostra os valores corretos
• Comandos remotos (iniciar/parar tratamento) funcionam
• Ciclo de retrolavagem manual completa sem erros

Se qualquer item falhar, não devolver a unidade ao serviço — investigar antes.

Fontes deste capítulo

• Macroentregas_Embrapii/Macroentrega_3/5.1 Transferência da tecnologia ao cliente/picg-resposta-2026-05-14/procedimento_calibracao_sensor_pressao.pdf (procedimento formal de pressão)
• Macroentregas_Embrapii/Macroentrega_3/5.1 Transferência da tecnologia ao cliente/picg-resposta-2026-05-14/procedimento_calibracao_sensor_vazão_bomba_dosadora.pdf (procedimentos de vazão e dosadora + observação sobre drift)
• Macroentregas_Embrapii/Macroentrega_2/3.3 Testes preliminares dos subsistemas/Testes preliminares dos subsistemas.docx
• Macroentregas_Embrapii/Macroentrega_3/Testes/consolidado-ensaios.md (ensaios Fundenor)
• Macroentregas_Embrapii/Macroentrega_3/Testes/análise eficiência protótipo - rascunho - teste 1.pdf
• /11-Confidencial/YaraBox_001_Backup_Config.md (coeficientes reais da unidade 001)
• Código firmware: modulo-basico/lib/dispositivos_ads/ (implementação y = a·x + b)

Dados brutos completos (tabelas, foto do caderno do operador, exemplos numéricos): ver Apêndice C.

Status: 🚧 bloqueado (parcial) Última atualização: 2026-05-14 Audiência: técnico de campo / engenheiro de implantação

🚧 BLOQUEADO — aguardando sessão presencial com o PICG + experiência operacional acumulada com clientes reais

TODO ao destravar:

• Procedimento formal de comissionamento em campo (checklist completo)
• Tempo total estimado e número de pessoas necessárias (1 ou 2 técnicos)
• Lista definitiva de ferramentas + materiais de consumo
• Documentação fotográfica de instalações reais (3+ unidades de referência)
• Critérios objetivos de aceite pelo cliente
• Lições aprendidas das primeiras instalações de campo

Este capítulo cobre o que JÁ é conhecido a partir da unidade 001 em operação na Água Camelo, da documentação Embrapii e dos parâmetros do firmware. O passo-a-passo de comissionamento será fechado após operação acumulada.

Sumário

• 1. Pré-requisitos no local de instalação
• 2. Posicionamento da Yara Box
• 3. Conexões hidráulicas
• 4. Conexões elétricas
• 5. Conectividade (configurar device)
• 6. Comissionamento
• 7. Entrega ao cliente
• 8. Documentação da instalação

1. Pré-requisitos no local de instalação

1.1. Infraestrutura hidráulica

• Fonte de água a ser tratada: poço, rio, lago ou reservatório com profundidade adequada para captação (mín. 1 m da superfície para evitar materiais flutuantes).
• Linha de saída para o reservatório de água tratada (ex: caixa d'água, bebedouro animal).
• Linha de dreno para o efluente da retrolavagem (água com particulado retido). Pode descarregar em solo natural ou em sumidouro — não retornar à fonte de captação.

1.2. Infraestrutura elétrica

Identificar qual das 5 fontes está disponível no local (ver Cap 4 §3):

• A — Rede AC 110/220V: verificar tomada com tensão estável (variação <10%) e capacidade mínima de 20A para a fonte chaveada externa
• B — 12 VDC direto: banco de baterias externo com tensão estável e capacidade ≥5A
• C — Gerador: combustível e capacidade adequada para uso intermitente
• D — Solar: insolação >5 horas/dia útil em média; espaço para 2–4 painéis (depende da demanda local)
• E — Manual: sempre disponível como fallback (não precisa de pré-requisito)

1.3. Conectividade

• Wi-Fi do cliente: SSID + senha disponíveis; sinal verificado no local de instalação (mín. -75 dBm para conexão estável)
• GSM: sinal 3G/4G verificado no local com SIM card da Vivo, Claro, Tim ou Oi (Yara Box atualmente configurada para APN Vivo zap.vivo.com.br). Para outras operadoras, ajustar config.apn_gsm antes da instalação
• Sem conectividade? A Yara Box funciona offline; telemetria é perdida mas tratamento continua. Avaliar caso a caso

2. Posicionamento da Yara Box

2.1. Espaço necessário

• Footprint: 80 × 40 cm da Yara Box + ≥1 m de cada lado para manutenção
• Altura: ~40 cm da unidade + espaço acima para acessar a tampa de hipoclorito (~30 cm) = 70 cm mínimos
• Piso: plano, nivelado, resistente ao peso de até 30 kg (Yara Box + 2 L de hipoclorito + água em filtros)

2.2. Proteção ambiental

• Cobertura de chuva: abrigo simples, sem fechamento total para ventilação dos componentes eletrônicos
• Sol direto: evitar exposição prolongada (PEAD pode descolorir; bateria sofre com calor excessivo). Idealmente posicionar em sombra parcial
• Inundação: posicionar em piso elevado se houver risco

2.3. Acessibilidade

• A tampa lateral deve abrir completamente sem obstrução
• O reservatório de hipoclorito deve ser acessível pelo topo para reabastecimento sem desmontagem
• Conectores externos (entradas P1-P4, saída P7) acessíveis para troca rápida de fontes

3. Conexões hidráulicas

3.1. Entrada (captação)

1. Posicionar a captação na fonte de água com pré-filtro grosseiro externo (peneira ou tela) se a água tem sedimentos pesados — protege o Filtro 0 interno.
2. Mangueira de captação até a entrada da Yara Box (verificar diâmetro compatível — tipicamente 1/2" ou 3/4").
3. Conectar à entrada usando engate rápido ou rosca padrão.

3.2. Saída (água tratada)

1. Mangueira de saída até o reservatório de armazenamento (caixa d'água, bebedouro).
2. Altura de saída: acima do reservatório receptor para evitar contraflução.

3.3. Dreno (retrolavagem)

1. Conectar a linha de dreno à saída inferior do gabinete.
2. Direcionar para área de descarte permitida (não a fonte de captação).
3. Considerar válvula manual no dreno para permitir purga do sistema antes de manutenção.

3.4. Validação rápida

• Pressurizar manualmente com a bomba manual (HS500 em "manual" + acionar bomba pistão) — verificar ausência de vazamentos nas conexões
• Encher os filtros (Filtros 2, 3A, 3B podem precisar de ciclo de pré-uso conforme instrução do fabricante)

4. Conexões elétricas

Conforme Cap 4 §2:

4.1. Fonte primária

Conectar uma das fontes disponíveis ao conector correspondente da PCB Seletora:

4.2. Bateria 18650

A bateria já vem instalada no compartimento (Camada 4 — ver Cap 7 §6). Conectar via P6 da Seletora se a montagem foi feita fora do gabinete.

4.3. Saída para Bomba E

A Bomba E está conectada internamente à saída P7 da Seletora (Cap 4 §6). Nenhuma ação externa.

4.4. Validação visual

• LED de status na PCB Seletora aceso (fonte ativa detectada)
• Tensão de bateria normal (>12,3V) no display após boot
• LED YL400 do painel responde ao estado da unidade

5. Conectividade (configurar device)

5.1. Antes da chegada ao cliente — pré-configuração na Água Camelo

1. Criar device no ThingsBoard (ver Cap 6 §4.6) com nome YB-<NNN> (próximo número de série).
2. Copiar Access Token gerado.
3. Configurar config.json do firmware via AP mode em bancada com:
   • token_mqtt = Access Token copiado
   • server_mqtt = yarabox.aguacamelo.com.br
   • Outros parâmetros conforme calibração da unidade

5.2. Em campo — Wi-Fi do cliente

1. Conectar à rede yarabox_AP (sem senha) com celular ou notebook.
2. Acessar http://yarabox.local → login camelo / @gu@c@m3l0.
3. Inserir SSID e senha do Wi-Fi do cliente em ssid_wifi / psk_wifi.
4. Salvar → unidade reinicia e conecta no Wi-Fi do cliente.

5.3. Em campo — GSM (fallback automático)

Se o Wi-Fi do cliente falhar, a unidade automaticamente cai para GSM. Pré-requisitos:

• SIM card inserido no slot do SIM7080G (na PCB Joker)
• APN configurado para a operadora do SIM (apn_gsm, user_gsm, pass_gsm)
• Sinal de celular adequado no local

5.4. Configurar NTP e fuso horário

• Padrão atual: NTP servers br.pool.ntp.org, a.st1.ntp.br, pool.ntp.org
• Fuso: ntp_gmt_offset = -3 (BRT)
• Horário de verão: horario_verao_habilitado = false (atualmente desativado no Brasil)

6. Comissionamento

Sequência de testes antes de liberar a unidade para operação:

6.1. Teste de bombeamento (sem cloração)

1. Desativar a cloração temporariamente: menu → Hipoclorito → desabilitar (hipoclorito_habilitado = false).
2. Acionar HS500 → "elétrico", pressionar HS501 (iniciar).
3. Observar:
   • Bomba E liga
   • Vazão estabiliza na faixa configurada (~300 L/h por padrão)
   • Sem vazamentos
   • Pressão estabiliza na faixa normal (10–30 psi nos PT100/101)
4. Parar via HS502.

6.2. Teste de dosagem (ciclo curto manual)

1. Reativar cloração: hipoclorito_habilitado = true.
2. Acionar tratamento por 5 minutos com vazão controlada.
3. Medir cloro residual livre na saída com teste DPD ou kit colorimétrico.
4. Resultado esperado: 0,2–2,0 mg/L (Portaria 888).
5. Se fora da faixa: ajustar dose_hipoclorito_ug-L.valor e repetir.

6.3. Teste de telemetria

1. Acessar https://yarabox.aguacamelo.com.br como tenant admin.
2. Verificar que o device YB-<NNN> aparece 🟢 Active em até 30 s.
3. Aba Last Telemetry: confirmar valores coerentes com leitura do display local.
4. Disparar publicação manual via menu → Remoto → Publicar agora (se disponível) ou aguardar próximo ciclo (30 s).

6.4. Teste de retrolavagem

1. Menu → Filtro → Retrolavar agora.
2. Verificar sequência:
   • Solenóides S1 e S2 abrem (escutar clique)
   • Bomba E liga em sentido reverso
   • Após ~90 s, sistema retorna a Idle
3. Verificar dreno (água saindo pelo dreno externo).

6.5. Critérios de aceite

• Tratamento contínuo por 30 minutos sem alarmes
• Cloro residual livre dentro da faixa em pelo menos 2 medições consecutivas
• Pressão e vazão estáveis dentro da faixa normal
• Telemetria chegando ao ThingsBoard
• Comandos remotos (start/stop) funcionam

7. Entrega ao cliente

7.1. Demonstração da UI local

Treinar o operador do cliente em:

• Como ligar/desligar (chave ON/OFF + HS501/HS502)
• Como ler o display (telas gráfica e textual)
• Como navegar pelo menu via encoder rotativo
• Como reabastecer o hipoclorito (ver Cap 10 §7)
• Como acionar a bomba manual em caso de queda de energia (HS500 → "manual")
• Como interpretar alarmes (LEDs piscando, popups no display, buzzer)

7.2. Credenciais admin

• Senha admin padrão de fábrica: camelo / @gu@c@m3l0
• Orientar o operador a trocar a senha na primeira oportunidade via menu → Geral → Senha (se a unidade ficar exposta a terceiros)

7.3. Manual do usuário final

Entregar versão impressa ou digital do manual simplificado: Macroentregas_Embrapii/Macroentrega_3/5.1 Transferência da tecnologia ao cliente/Manual de Instalação e Operação - Tampa lateral - Yarabox .pdf

Este manual cobre operação básica do ponto de vista do usuário final (sem detalhes técnicos).

7.4. Cronograma de manutenção

Imprimir ou colar no painel:

• Lavagem do filtro: a cada 10.000 L (automática + manual quando alerta)
• Limpeza do filtro: a cada 50.000 L
• Troca do filtro: a cada 100.000 L ou 365 dias (o que vier primeiro)
• Recalibração da vazão: a cada 100.000 L

Detalhes em Cap 10 §5.

7.5. Contato de suporte

• Telefone / WhatsApp da Água Camelo (suporte Wara Tech)
• Email de suporte
• URL do dashboard com login do cliente

8. Documentação da instalação

Para cada unidade instalada, criar um registro de instalação (template a ser desenvolvido):

Arquivar em /02-Comercial/Instalações/YB-<NNN>/ ou local equivalente.

Fontes deste capítulo

• /11-Confidencial/YaraBox_001_Backup_Config.md (parâmetros de rede e GSM da unidade 001)
• Macroentregas_Embrapii/Macroentrega_3/5.1 .../Manual de Instalação e Operação - Tampa lateral - Yarabox .pdf (manual do usuário)
• Arquitetura_Yara_Box/Visao_Tecnica_Wara_Box.md §3.1 (sistema hidráulico), §3.3 (energia)
• Cap 4 — Elétrico, Cap 6 — Backend & Cloud, Cap 10 — Operação & Manutenção

Status: ✅ pronto Última atualização: 2026-05-14 Audiência: operador da Yara Box (usuário final) + técnico de manutenção preventiva Tempo de leitura estimado: 20 minutos

Sumário

• 1. Interface local da Yara Box
• 2. Fluxos operacionais
• 3. Sinalização e alarmes
• 4. Telemetria remota (ThingsBoard)
• 5. Manutenção preventiva por volume
• 6. Manutenção preditiva (ThingsBoard)
• 7. Reposição de hipoclorito
• 8. Troubleshooting comum
• 9. Reset e restauração
• 10. Plano de recalibração em aberto

1. Interface local da Yara Box

A Yara Box tem uma interface local self-contained acessível pela tampa frontal:

• Display gráfico SH1107 (128×128 pixels, OLED branco, contraste alto)
• Encoder rotativo (com push-button) — navegação e seleção
• Botoeiras físicas:
  • HS500 — chave seletora bombeamento elétrico vs manual
  • HS501 — botoeira "iniciar processo"
  • HS502 — botoeira "parar processo"
• Lâmpada YL400 — status visual de operação
• Buzzer — alarme sonoro

1.1. Display (alternância entre 2 telas)

O display alterna automaticamente entre 2 telas a cada 30 segundos:

Tela gráfica (4 quadrantes):

• Quadrante 1: pressão (PT100/101 atuais + indicador visual de range)
• Quadrante 2: vazão instantânea (gauge tipo velocímetro)
• Quadrante 3: nível de hipoclorito (barra vertical 0–100%)
• Quadrante 4: status (Tratamento / Idle / Lavagem / etc.) + tensão de bateria

Tela textual:

• Linhas com leitura numérica precisa de todos os parâmetros
• Volume tratado (sessão + total acumulado)
• Última publicação MQTT (timestamp)
• IP atual (se em rede Wi-Fi)

1.2. Encoder rotativo (HS503)

Debounce: 200 ms (configurado no firmware).

1.3. Menus disponíveis

Acessar via clique no encoder em qualquer momento. Estrutura:

Menu Principal
├── Hipoclorito (dose, concentração, nível atual)
├── Volume (total, sessão, limites)
├── Vazão (calibração, limites mín/máx)
├── Filtro (data troca, volumes desde manutenção)
├── Data/Hora (configurar NTP, fuso horário, horário de verão)
├── Remoto (MQTT server, token, status conexão)
└── Geral (Wi-Fi, AP mode, OTA, reset)

Cada item permite edição inline via encoder (valores numéricos) ou enter para submenu (configurações complexas como NTP).

2. Fluxos operacionais

2.1. Ligar a Yara Box

1. Conectar uma fonte de alimentação A/B/C/D (ver Cap 4 §2) ou garantir que a bateria tem carga suficiente.
2. Pressionar a chave ON/OFF geral na PCB Seletora.
3. Tela de boot aparece: logo Wara Box animado por 6 segundos.
4. Sistema entra no estado Idle (modo seguro, sem acionamento automático).

2.2. Iniciar tratamento (modo automático)

1. Garantir que HS500 está em "elétrico" (não manual).
2. Verificar que o reservatório de hipoclorito tem nível adequado (> LSL200, ver §7).
3. Pressionar HS501 ("iniciar processo").
4. Sistema transiciona para Tratamento:
   • Bomba elétrica liga (PWM 255, duty fixo)
   • Bomba dosadora começa a injetar hipoclorito proporcionalmente à vazão
   • Display mostra ícone "TRATAMENTO" em destaque
   • LED YL400 acende

2.3. Modo idle

• Sistema sempre retorna a Idle quando o tratamento é interrompido (manual ou automaticamente por intertravamento).
• Atuação a cada 250 ms (apenas verificações de segurança; nenhum atuador ligado).
• Display continua atualizando leituras.

2.4. Modo teste

Acessível via menu Geral → Teste. Permite acionar individualmente:

• LEDs (1 por 1)
• Solenóides S1 e S2
• Bomba E (sem fluxo)
• Bomba D (sem dosagem real)

Timeout automático: 10 s por teste (proteção contra esquecimento).

2.5. Modo retrolavagem

Acionável via menu Filtro → Retrolavar agora ou automaticamente quando volume_tratado_desde_ultima_lavagem_filtro >= 10000 L.

Sequência:

1. Solenóides S1 e S2 abrem por 30 segundos (inversão de fluxo).
2. Bomba E aciona por 60 segundos (vazão reversa para descolar particulado).
3. Solenóides fecham, sistema retorna a Idle.
4. Contador volume_tratado_desde_ultima_lavagem_filtro é resetado para 0.

2.6. Modo calibração (sensor de vazão)

Acessível via menu Vazão → Calibrar. Procedimento de bancada — detalhes em Cap 8 §3.

Nota interna: o estado EstadoControlarCalibracao está implementado no firmware mas inativo no fluxo de execução atual (reservado para uso futuro). A calibração da vazão hoje é feita externamente em bancada e o resultado é gravado em config.calibracao_vazao via menu local ou AP mode.

3. Sinalização e alarmes

A Yara Box monitora 5 parâmetros principais com limiares configuráveis e dispara alarmes visuais (LEDs, popups no display) e sonoros (buzzer):

3.1. Pressão (PT100/101 — bomba elétrica)

Configuráveis em config.pressao_bomba.*.

3.2. Vazão (FE300)

Configuráveis em config.vazao_litros_hora.*.

3.3. Nível de hipoclorito (LSL200, LSLL200)

Configuráveis em config.nivel_hipoclorito.*.

3.4. Tensão de alimentação

Configuráveis em config.tensao_alimentacao.*.

3.5. Tensão de bateria

Configuráveis em config.tensao_bateria.*.

3.6. Sinalização agregada

Além dos alarmes específicos, o LED YL400 fica:

• Apagado: Idle ou desligado
• Aceso fixo: Tratamento normal
• Piscando: Alarme ativo (verificar display)

Buzzer toca por 2 segundos em alarmes críticos (PAHH100, LALL200, tensão crítica).

4. Telemetria remota (ThingsBoard)

A Yara Box publica telemetria via MQTT no broker yarabox.aguacamelo.com.br:1883 (ver Cap 6). O operador remoto acessa dados via interface web do ThingsBoard.

4.1. O que o operador vê

Publicação parcial (30 s): apenas valores que mudaram. Permite acompanhamento near-real-time.

Publicação completa (10 min): todos os ~30 parâmetros. Permite recuperação histórica completa.

Dashboard típico do operador (V8 importado da PICG, será substituído pelo dashboard próprio Wara Tech):

• Indicador discreto: tratamento ativo / bombeamento / bomba elétrica / hipoclorito
• Gauge de velocidade: vazão instantânea
• Tabela de estado do sistema
• Botões de ação: iniciar/parar/selecionar bomba

4.2. Alarmes automáticos no ThingsBoard

Configurados nas rule chains do tenant:

• Pressão alta sustentada → email para operador
• Bateria crítica → SMS via integração (futuro)
• Sem telemetria por > 2 horas → alerta de unidade offline
• Volume tratado próximo do limite → lembrete de manutenção

Configuração detalhada em Cap 6 §4 (criar device profile com alarm rules).

5. Manutenção preventiva por volume

A Yara Box rastreia o volume tratado desde a última intervenção de cada tipo. Quando o limite é atingido, o display mostra alerta de manutenção.

5.1. Intervalos padrão (configuráveis em config.json)

Ao trocar um filtro, o operador deve resetar o contador correspondente via menu local (Menu → Filtro → Resetar contador) ou via comando MQTT remoto.

5.2. Procedimento de lavagem (retrolavagem)

Já documentado em §2.5 — modo automático. Pode também ser disparado manualmente.

5.3. Procedimento de limpeza (manual)

1. Acionar o modo bombeamento manual (HS500 → "manual") para garantir que a bomba elétrica não liga acidentalmente.
2. Desligar a alimentação principal da Seletora.
3. Despressurizar o sistema abrindo as válvulas de dreno.
4. Desmontar a tampa lateral.
5. Remover o cartucho do filtro MF (Filtro 2).
6. Enxaguar manualmente em água limpa (lado de dentro pra fora).
7. Inspecionar visualmente — se há colmatação severa, considerar troca.
8. Remontar.
9. Religar e validar pressão/vazão estáveis antes de retornar à operação.

5.4. Procedimento de troca de filtro

Similar ao da limpeza, mas substituindo o cartucho. Após a troca:

• Atualizar data_ultima_troca_filtro no menu (formato DD/MM/YYYY).
• Resetar contadores de volume.

5.5. Recalibração da vazão

Procedimento detalhado em Cap 8 §3. Atenção ao drift progressivo documentado pelo PICG (§10).

6. Manutenção preditiva (ThingsBoard)

Além dos intervalos fixos, o ThingsBoard pode aplicar rule chains preditivas baseadas em padrões nos dados:

• Pressão diferencial crescente entre PT100 e PT101 → filtros próximos do final de vida (colmatação). Alarme antes do limite de troca.
• Vazão caindo com pressão alta → indicação de colmatação severa, recomenda lavagem imediata.
• Variação anômala da vazão com bomba ligada → sensor FE300 derivando (ver §10) ou problema mecânico.
• Consumo de hipoclorito acima do esperado por volume → vazamento do reservatório ou erro de calibração da dosadora.

Implementação das rule chains: pendente. Plano: derivar curvas a partir de dados de 3+ unidades em operação por 6 meses.

7. Reposição de hipoclorito

7.1. Quando reabastecer

• LSL200 dispara (nível < 30%): display mostra "LLL200 — reabastecer hipoclorito"
• LSLL200 dispara (nível crítico): bomba elétrica é intertravada (não desliga a manual). Reabastecer imediatamente.

7.2. Como reabastecer

1. Reduzir o tratamento ao mínimo necessário ou parar via HS502.
2. Abrir a tampa do reservatório (TQ Cloro).
3. Encher com hipoclorito de sódio 4% (NaClO 4% massa/volume).
4. Fechar bem para evitar evaporação/contaminação.
5. Reiniciar o tratamento via HS501.

7.3. Concentração correta — pegadinha histórica documentada

⚠️ Atenção: o parâmetro config.concentracao_hipoclorito_porcentagem deve refletir a concentração real do produto que está sendo usado. Se você comprar hipoclorito 6% ou 12% e o firmware está configurado para 4%, a dosagem será proporcionalmente errada.

Histórico: no Ensaio 1 da Fundenor (03/03/2026), o cloro residual ficou em 0,1 mg/L (fora do padrão 0,2–5,0). Causa raiz: o firmware estava configurado com concentracao = 12% mas o produto real era 4%. Após corrigir para 4%, o cloro subiu para 0,8 mg/L (Ensaio 2, 11/03/2026, dentro do padrão). Detalhes em Cap 8 §6.

Sempre verifique este parâmetro ao trocar o fornecedor do hipoclorito.

8. Troubleshooting comum

Para troubleshooting do backend / VPS, ver Cap 6 §9.

9. Reset e restauração

9.1. Reset suave (reiniciar firmware)

Via menu local: Menu → Geral → Reiniciar. Equivalente a um power-cycle, sem perder configurações.

9.2. Reset de configuração (volta para fábrica)

Via menu local: Menu → Geral → Reset de fábrica. CUIDADO — apaga todas as configurações personalizadas e volta para data/config-padrao-fabrica.json. Senha admin necessária.

Após o reset, restaurar coeficientes de calibração reais — ver §9.3.

9.3. Restaurar a partir do backup

Procedimento completo em Apêndice C §8. Resumo:

1. Conectar à rede Wi-Fi yarabox_AP (sem senha).
2. Abrir http://yarabox.local ou http://192.168.4.1.
3. Em "ACESSO RESTRITO": user camelo / senha @gu@g@m3l0.
4. Em "Calibrações", inserir os coeficientes do backup operacional (/11-Confidencial/YaraBox_001_Backup_Config.md).
5. Salvar e reiniciar.

9.4. Trocar placa principal (PCB Joker)

Se a PCB Joker precisa ser substituída:

1. Antes de remover: garantir que o backup operacional está atualizado (/11-Confidencial/YaraBox_<NNN>_Backup_Config.md para a unidade específica).
2. Trocar a placa.
3. Gravar firmware (pio run -t upload via USB; ver Cap 5 §16).
4. Restaurar config.json conforme §9.3.
5. Validar telemetria chegando no ThingsBoard.

10. Plano de recalibração em aberto

⚠️ Observação técnica do PICG (relevante para manutenção contínua):

"A leitura fornecida pelo sensor de vazão tem apresentado uma discrepância progressiva em relação ao volume real de água. Faz-se necessário investigar a correlação entre o desgaste operacional do equipamento e a deriva da calibração, a fim de estabelecer a periodicidade ideal para a recalibração do sensor de vazão."

Fonte: procedimento_calibracao_sensor_vazão_bomba_dosadora.pdf (PICG, 14/05/2026).

Implicação operacional: o intervalo padrão atual de recalibração da vazão é 100.000 L, mas pode estar inadequado conforme o sensor envelhece. Em unidades de produção, recomendamos:

1. Coletar dados de drift comparando vazão lida pelo FE300 vs vazão real medida por becker graduado, a cada trimestre durante o primeiro ano de operação.
2. Plotar curva de erro acumulado vs volume tratado.
3. Derivar periodicidade definitiva quando houver dados de 3+ unidades por 6+ meses.
4. Considerar troca preventiva do sensor se o drift exceder ±5% antes de 100.000 L.

TODO Wara Tech: acumular esses dados de campo e atualizar config.volume_recomendado_nova_calibracao_vazao com base em evidência empírica.

Fontes deste capítulo

• Macroentregas_Embrapii/Macroentrega_3/5.1 Transferência da tecnologia ao cliente/Manual de configuração.docx (~70 pgs — UI completa da Yara Box, fluxos de operação, calibração da vazão via menu)
• Macroentregas_Embrapii/Macroentrega_3/5.1 .../Manual de Instalação e Operação - Tampa lateral - Yarabox .pdf (manual de usuário final)
• Macroentregas_Embrapii/.../picg-resposta-2026-05-14/procedimento_calibracao_sensor_vazão_bomba_dosadora.pdf (alerta sobre drift do sensor de vazão)
• Arquitetura_Yara_Box/Visao_Tecnica_Wara_Box.md §3.1 (manutenção preventiva), §3.4 (limiares)
• data/config.json do firmware (limiares e intervalos atuais)
• Macroentregas_Embrapii/Macroentrega_3/Testes/consolidado-ensaios.md (pegadinha histórica do cloro 12%→4%)

Para procedimentos de calibração em bancada: ver Cap 8 — Testes & Calibração. Para troubleshooting do backend/VPS: ver Cap 6 §9. Para valores reais da unidade 001: ver Apêndice C.

Status: ✅ pronto Última atualização: 2026-05-14 Audiência: engenheiro de compras / planejamento de produção Fonte primária: 01-Produto/Produto_Yara_Box/BOM/Yara_Box_BOM.xlsx Geração: automática via scripts/bom_xlsx_to_md.py (openpyxl, leitura read-only) Total de SKUs: 77

Sumário

• 1. Visão geral
• 2. Inventário das 7 chapas PEAD (PDFs cotados)
• 3. BOM completa por categoria
• 4. Notas sobre a BOM
• 5. Referência cruzada com PCB Seletora (BOM dedicada)
• 6. Como atualizar este apêndice

1. Visão geral

A BOM consolidada da Yara Box está mantida em Yara_Box_BOM.xlsx no caminho 01-Produto/Produto_Yara_Box/BOM/. O Excel é o source-of-truth e tem 11 abas com informações operacionais:

A tabela MD abaixo é uma projeção da aba BOM com as colunas mais úteis para o manual (SKU, descrição, quantidade, tipo, fornecedor, MPN, preço 10u, status). Para detalhes adicionais (leadtime, MOQ, NCM, alíquotas, certificações), consultar o .xlsx diretamente.

Distribuição por categoria:

⚠️ Inconsistência conhecida na planilha: existem duplicações de categoria sem/com acento (Hidraulica vs Hidráulica, Mecanica/Estrutura vs Mecânica/Estrutura). Isso reflete a evolução histórica da planilha — alguns SKUs antigos foram cadastrados sem acento. Normalizar é um TODO de manutenção da BOM (não bloqueia produção). Ver 00-Backlog/tasks.md item "BOM Mestre v2".

2. Inventário das 7 chapas PEAD (PDFs cotados)

Entregue pelo PICG em 12/05/2026 (autor: Marllon Batista). Material: PEAD 5 mm, padrão de cotagem ABNT, prontas para fabricação por corte CNC.

Correspondência aproximada com SKUs da BOM (a confirmar — a numeração PEAD-01 a PEAD-07 precisa ser conferida contra os nomes do PICG):

TODO: mapear cada PDF do PICG para o SKU correspondente na BOM (com auxílio do desenho dimensional). Item do backlog "BOM Mestre v2".

3. BOM completa por categoria

Eletroeletrônica (21 SKUs)

Alimentação

Controle

Hidraulica (7 SKUs)

Nota: estes SKUs estão na variante "Hidraulica" (sem acento) — agrupamento que reflete adições posteriores à BOM. Itens compatíveis com a categoria "Hidráulica" abaixo.

Dosagem

Entrada

Pré-filtração

Hidráulica (24 SKUs)

Dosagem

Entrada

MF (Microfiltração)

Pré-filtração

UF (Ultrafiltração)

Mecanica/Estrutura (8 SKUs)

Nota: estes SKUs estão na variante "Mecanica/Estrutura" (sem acento) — adições posteriores à BOM.

Estrutura

Mecânica/Estrutura (16 SKUs)

Estrutura

Produto (1 SKU)

Produto final

4. Notas sobre a BOM

4.1. Status dos preços

• Itens com fornecedor "Estimativa Claude (placeholder)" têm preços estimados e precisam de cotação real. Documentado no backlog 00-Backlog/tasks.md (item "BOM Mestre v2").
• Itens com status "PENDENTE_DADOS" ainda não foram totalmente caracterizados (fornecedor, MPN, leadtime).
• Os 12 SKUs novos adicionados em 12/05/2026 (SUP-ROD, CANT-01, PEAD-DIV, TAMPO-01, DOB-01, JOE-FEM, TUB-PERI, MANOM-01, ALC-01, SUP-RES-HIPO, FRM-540x500, SUP-BOM-PERI, VAL-RET, MIS-EST, FIL-BOM) estão na situação "PENDENTE_DADOS".

4.2. Componentes críticos (componente_critico)

São os SKUs cuja falha compromete diretamente a função do produto:

• ELE-07 (Fonte 12V/20A/240W IP67)
• ELE-08 (Bateria Li-ion 18650 com BMS)
• BOM-01 (Bomba de superfície Seaflo)
• BOM-02 (Bomba Peristáltica P40SMD)
• BOM-03 (Bomba manual) — removido (status REMOVIDO)
• SEN-01 (Sensor de vazão)
• SEN-02 (Sensor de pressão inox 150 PSI)
• SEN-03 (Sensor capacitivo de nível) × 2

Esses devem ter fornecedores alternativos mapeados antes da produção em volume.

4.3. Componentes consumíveis (consumivel)

São substituídos periodicamente em manutenção (ver Cap 10 §5):

• FIL-01 (Filtro Disco ¾")
• FIL-02 (Filtro microbiológico 0,2 μm) — gargalo identificado (~400 L de autonomia, ver Cap 8 §6.4)
• FIL-03 (Filtro membrana Althy 0,01 μm) × 2
• TUB-PERI (Tubo silicone da bomba peristáltica) — desgasta com o tempo, recalibrar dosadora após troca

4.4. PCBs (pcba)

São SKUs que internamente têm BOM própria (sub-BOM):

• ELE-01 (Placa Core/Joker): BOM completa no repositório YB-modulo-basico-pcb-principal-joker em Documentos/bom/. Ver Cap 2 §3 e Apêndice B §1.
• ELE-05 (Placa Seletora): BOM completa no repositório YB-modulo-basico-pcb-seletor-de-alimentacao em documentos/BOM/. Ver §5 abaixo e Cap 2 §4.
• ELE-15 (Placa Solar Flexível): componente comercial pronto (Neosolar).

5. Referência cruzada com PCB Seletora (BOM dedicada)

A PCB Seletora v1.1.1 (SKU ELE-05) tem BOM detalhada no próprio repositório KiCad — pronta para fabricação JLCPCB. Componentes principais (Cap 2 §4.3):

BOM completa em Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/modulo-basico-pcb-seletor-de-alimentacao-main/documentos/BOM/.

6. Como atualizar este apêndice

A tabela MD da §3 é gerada automaticamente. Para atualizar quando o Yara_Box_BOM.xlsx for editado:

# 1. Garantir que o Excel está fechado (verificar ~lock):
ls "/Users/rodrigobelli/Documents/Wara Tech/01-Produto/Produto_Yara_Box/BOM/.~lock.Yara_Box_BOM.xlsx#"

# 2. Rodar o script gerador:
python3 "/Users/rodrigobelli/Documents/Wara Tech/01-Produto/Produto_Yara_Box/manual-mestre/scripts/bom_xlsx_to_md.py" > /tmp/bom_table.md

# 3. Revisar /tmp/bom_table.md e copiar/colar na seção §3 deste arquivo.

O script bom_xlsx_to_md.py é versionado em manual-mestre/scripts/ e usa apenas openpyxl (read-only — não interfere com Excel aberto se for o caso).

Fontes deste apêndice

• 01-Produto/Produto_Yara_Box/BOM/Yara_Box_BOM.xlsx (source-of-truth da BOM consolidada)
• Macroentregas_Embrapii/Macroentrega_3/5.1 .../picg-resposta-2026-05-14/Desenhos 2D cotados das Chapas/ (7 PDFs ABNT das chapas PEAD)
• Macroentregas_Embrapii/.../modulo-basico-pcb-seletor-de-alimentacao-main/documentos/BOM/ (BOM dedicada da PCB Seletora)
• Macroentregas_Embrapii/.../modulo-basico-pcb-principal-joker-main/Documentos/bom/ (BOM dedicada da PCB Joker)
• Macroentregas_Embrapii/Macroentrega_1/RELAÇÃO - Aquisição de itens conforme requisitos tecnológicos.docx (BOM original)
• Macroentregas_Embrapii/Macroentrega_1/RELAÇÃO - Aquisição dos itens comerciais.docx (BOM original)
• 00-Backlog/tasks.md (item "BOM Mestre v2 — evoluir pro world-class")
• Script: manual-mestre/scripts/bom_xlsx_to_md.py

Status: ✅ pronto Última atualização: 2026-05-14 Audiência: engenheiro eletrônico/elétrico Função: índice consolidado de todos os esquemáticos, layouts e datasheets do projeto Yara Box

Sumário

• 1. PCB Joker (Core final com JNG-E)
• 2. PCB Seletora de Alimentação v1.1.1
• 3. PCB Principal-DevKit-ESP32S3 (prototipagem)
• 4. PCB DAQ Shield (Datalogger)
• 5. Esquemático elétrico geral (projeto-eletrico)
• 6. P&ID hidráulico formal (PICG)
• 7. Datasheets dos componentes principais
• 8. Convenções de nomenclatura

1. PCB Joker (Core final com JNG-E)

• Repo local: Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/modulo-basico-pcb-principal-joker-main/
• Repo GitHub: agua-camelo-cs/YB-modulo-basico-pcb-principal-joker (privado)

1.1. Esquemáticos e layout

1.2. PDFs e iBOM

Em Macroentregas_Embrapii/.../modulo-basico-pcb-principal-joker-main/Documentos/:

Em IMGs/:

• Arquitetura do Sistema.png
• LED-BUZZER - ALARME AUDIO VISUAL.png
• MODULO PCF8574.jpg
• MODULO ADS1115.jpeg
• SENSOR CAPACITIVO.png

1.3. Como abrir

# Pré-requisito: KiCad 8.x instalado
cd "Macroentregas_Embrapii/Macroentrega_3/fontes códigos  e projetos/modulo-basico-pcb-principal-joker-main"
kicad modulo-basico-pcb-principal-joker.kicad_pro   # abre o projeto

Detalhes do hardware em Cap 2 §3.

2. PCB Seletora de Alimentação v1.1.1

• Repo local: Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/modulo-basico-pcb-seletor-de-alimentacao-main/
• Repo GitHub: agua-camelo-cs/YB-modulo-basico-pcb-seletor-de-alimentacao (privado)
• Status: ✅ Fabricada e validada via JLCPCB

2.1. Esquemáticos e layout

2.2. Artefatos de produção (prontos para JLCPCB)

Em Macroentregas_Embrapii/.../modulo-basico-pcb-seletor-de-alimentacao-main/documentos/:

2.3. Componentes-chave

Detalhes do hardware em Cap 2 §4, conectores em Cap 4 §2.

3. PCB Principal-DevKit-ESP32S3 (prototipagem)

• Repo local: Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/modulo-basico-pcb-principal-devkit-esp32s3-main/
• Repo GitHub: agua-camelo-cs/YB-modulo-basico-pcb-principal-devkit-esp32s3 (privado)
• Status: Em uso para bancada / bring-up de firmware

Esta versão usa o módulo ESP32-S3-WROOM diretamente no formato DevKit (sem JNG-E). Útil para prototipagem, debug e bring-up. Não usar em unidades de produção — usar a Joker.

Detalhes em Cap 2 §2.

4. PCB DAQ Shield (Datalogger)

• Repo GitHub: agua-camelo-cs/YB-dataloggerpcb (privado)
• Firmware 1 (JSON Serial): agua-camelo-cs/YB-datalogger (privado)
• Firmware 2 (Modbus RTU): agua-camelo-cs/YB-datalogger-modbus (privado)

PCB auxiliar montada sobre Arduino Nano ATmega328 para instrumentação de bancada. Não vai no produto final.

Artefatos:

• pcb_daq.pdf — esquemático em PDF
• libs/mylibs/ — biblioteca KiCad customizada
• Datasheets de LTV-817, SI4483ADY, L78xx, LM317, LESD5D5

Detalhes em Cap 2 §5.

5. Esquemático elétrico geral (projeto-eletrico)

• Repo local: Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/projeto-eletrico-main/
• Repo GitHub: agua-camelo-cs/YB-projeto-eletrico (privado)

Não é uma PCB própria — é o esquemático em KiCad da instalação elétrica completa entre PCBs, sensores externos, atuadores, bateria, conectores no gabinete.

5.1. Sub-esquemáticos

5.2. Artefatos

Em Macroentregas_Embrapii/.../projeto-eletrico-main/DOCS/:

• PDFs consolidados
• Datasheets de componentes externos

Detalhes em Cap 4 §9-10.

6. P&ID hidráulico formal (PICG)

Fonte: Macroentregas_Embrapii/Macroentrega_3/5.1 Transferência da tecnologia ao cliente/picg-resposta-2026-05-14/Fluxogramas.docx

Documento entregue pelo PICG em 14/05/2026 contendo:

• Arquitetura macro do sistema
• Fluxograma P&ID do módulo básico
• Tabela completa de tags ISA-5.1: FV301, FE300, PT100-103, LSL200, LSLL200, PAHH100, PLH100, PLL100, LLL200, LALL200, FIQC300, HS500-503, MIX, TQ Cloro, S1, S2, Bombas E/D/manual, Filtros 0/1/2/3A/3B, YL400, Buzzer
• Mapeamento de pinos elétricos (GPIO ESP32, AP/BP expansores PCF8574, UART2 para SIM7080G)

Tabela e diagrama transpostos para Cap 3 §4.

7. Datasheets dos componentes principais

Compilados em cada repositório KiCad (Documentos/datasheet/ ou datasheet/). Lista de referência rápida:

Lista completa de bibliotecas externas em Cap 5 §2.

8. Convenções de nomenclatura

• Tags ISA-5.1 seguem a convenção do PICG no Fluxogramas.docx (ver Cap 3 §4)
• Referências de componente em PCB: padrão KiCad (U para CIs, R resistores, C capacitores, D diodos, Q transistores, K relés, J/P conectores)
• Nomenclatura GPIO: GPIO XX (ESP32-S3) ou APx/BPx (PCF8574 expansor 1/2) — convenção da JNG-E adotada no Fluxogramas.docx
• Endereços I²C: documentados em Cap 2 §3.3 e Cap 5 §15

Fontes deste apêndice

• Todos os repositórios agua-camelo-cs/YB-modulo-basico-pcb-* e YB-projeto-eletrico (mirrors privados dos GitLab originais do PICG)
• Macroentregas_Embrapii/Macroentrega_3/fontes códigos e projetos/ (clones locais)
• Macroentregas_Embrapii/.../picg-resposta-2026-05-14/Fluxogramas.docx (P&ID + tags ISA)

Status: ✅ pronto Última atualização: 2026-05-14 Audiência: técnico de bancada / engenheiro de metrologia Origem dos dados: unidade Yara Box 001 em operação (Água Camelo) + procedimentos PICG entregues em 14/05/2026

Sumário

• 1. Coeficientes em produção (firmware v2.1.4-alpha)
• 2. Calibração de pressão — dados brutos
• 3. Calibração de vazão — dados brutos
• 4. Calibração da bomba dosadora — dados brutos
• 5. Calibração de tensões
• 6. PT102 e PT103 — sensores não calibrados nesta unidade
• 7. Foto do registro manual no caderno do operador
• 8. Como restaurar esses valores em uma placa nova

1. Coeficientes em produção (firmware v2.1.4-alpha)

Backup operacional: /11-Confidencial/YaraBox_001_Backup_Config.md (snapshot tirado em 14/05/2026 durante a migração de infra PICG → Vultr).

1.1. Tabela completa de coeficientes