Kanri 管理

Telemetria OBD2 read-only para ESP32. Lê os dados do carro por um adaptador ELM327 Bluetooth e mostra num display.

Kanri (管理) significa "gestão", "monitoramento" em japonês.

⚠️ Somente leitura. Sem exceção.

Este firmware nunca escreve na ECU do veículo. Só os modos OBD2 de leitura (0x01 e 0x09) são permitidos, e essa regra é imposta por código com testes que rodam em todo Pull Request — não é só uma promessa no README. Leia docs/SAFETY.md antes de contribuir.

A v0.1.0 é fundação, de propósito. Não tem telemetria funcionando.

O firmware da v0.1 roda: ele inicializa, tenta conectar, falha (o transporte é um placeholder), degrada, mostra o erro no monitor serial e retenta com backoff. Isso é intencional — exercita o caminho fail-safe completo no hardware antes de existir uma linha de Bluetooth.

graph LR
    CAR["🚗 Lancer 4B11<br/>ECU"]
    OBD["Conector OBD2<br/><i>CAN 500 kbit/s</i>"]
    ELM["Adaptador ELM327<br/><i>Bluetooth Classic</i>"]
    ESP["ESP32-WROOM-32"]
    DISP["Display"]

    CAR <-->|"somente leitura<br/>modos 01 e 09"| OBD
    OBD <--> ELM
    ELM <-->|"SPP / texto ASCII"| ESP
    ESP --> DISP

    style CAR fill:#5a1a1a,stroke:#ff4a4a,color:#fff
    style ESP fill:#1a3a5a,stroke:#4a9eff,color:#fff

Internamente, o projeto separa lógica pura (testável no PC) de código de hardware:

graph TD
    MAIN["src/main.cpp<br/><i>a cola</i>"]
    HAL["src/hal/<br/><i>adaptadores de hardware</i>"]

    CORE["kanri_core<br/>máquina de estados,<br/>backoff, telemetria"]
    OBD["kanri_obd<br/>parser ELM327,<br/>portão read-only"]
    CFG["kanri_config<br/>settings, validação"]
    DISP["kanri_display<br/>view model"]

    FAKES["test/helpers/<br/><i>dublês de teste</i>"]

    MAIN --> HAL
    MAIN --> CORE & OBD & CFG & DISP
    HAL -.implementa as portas.-> OBD
    HAL -.implementa as portas.-> DISP
    FAKES -.implementam as MESMAS portas.-> OBD
    FAKES -.implementam as MESMAS portas.-> DISP
    OBD --> CORE
    DISP --> CORE

    style CORE fill:#1a3a5a,stroke:#4a9eff,color:#fff
    style OBD fill:#1a3a5a,stroke:#4a9eff,color:#fff
    style CFG fill:#1a3a5a,stroke:#4a9eff,color:#fff
    style DISP fill:#1a3a5a,stroke:#4a9eff,color:#fff
    style HAL fill:#5a3a1a,stroke:#ff9e4a,color:#fff
    style MAIN fill:#5a3a1a,stroke:#ff9e4a,color:#fff
    style FAKES fill:#1a5a3a,stroke:#4aff9e,color:#fff

O ponto central: src/hal/ (hardware real) e test/helpers/ (dublês) implementam as mesmas interfaces. É isso que faz os testes rodarem no PC sem simulação aproximada.

Detalhes em docs/ARCHITECTURE.md.

Você vai ver muita gente dizer que ESP-IDF é "o profissional". Para este projeto, e para quem está começando em firmware, Arduino é a escolha certa:

O detalhe que resolve o dilema: o framework Arduino do ESP32 roda em cima do ESP-IDF. Não é um beco sem saída — dá para chamar API do IDF direto quando precisar. O main.cpp já faz isso com o watchdog (esp_task_wdt_*).

E a decisão fica ainda mais barata por causa da arquitetura: a lógica de negócio em lib/ não inclui Arduino.h. Se algum dia migrar para ESP-IDF puro, você reescreve os quatro arquivos de src/hal/ — não o projeto.

⚠️ pip install platformio não funciona no Ubuntu 24.04+ / Debian 12+ (PEP 668 — o Python do sistema é externally managed).

# Opção mais idiomática (precisa de sudo uma vez)
sudo apt install pipx && pipx ensurepath
pipx install platformio gcovr

Sem sudo, ou para outras opções, veja CONTRIBUTING.md.

pio test -e native

Isso compila a lógica pura com o g++ do seu PC e roda 122 testes em ~2 s. Rode isso antes de qualquer commit.

Política do projeto: código novo em lib/ chega com teste. Não é recomendação — o CI exige 100% de cobertura de linhas e bloqueia PR que mexa em lib/ sem mexer em test/. Ver docs/TESTING.md.

pio run -e esp32dev

pio run -e esp32dev -t upload
pio device monitor          # 115200 baud

./start.sh                  # abre http://127.0.0.1:8765

Um painel web local que mostra o estado do firmware ao vivo (lido dos logs da máquina de estados), o log serial com carimbo de tempo, e botões para gravar, reiniciar, compilar e rodar os testes — sem decorar comando nenhum.

Ele escuta apenas em 127.0.0.1, porque executa comandos na sua máquina. Detalhes em tools/kanri-console/.

kanri/
├── platformio.ini          # ambientes de build (esp32dev e native)
├── CLAUDE.md               # convenções do projeto (leia se for contribuir)
│
├── lib/                    # LÓGICA PURA — sem Arduino.h, testável no PC
│   ├── kanri_core/         # máquina de estados, backoff, telemetria, IClock
│   ├── kanri_obd/          # parser ELM327, portão read-only, catálogo de PIDs
│   ├── kanri_config/       # settings, validação, IConfigStore
│   └── kanri_display/      # view model, IDisplay
│
├── src/                    # FIRMWARE — aqui pode Arduino.h
│   ├── main.cpp            # a cola: escolhe adaptadores e junta tudo
│   └── hal/                # adaptadores de hardware
│
├── test/                   # TESTES — rodam no PC
│   ├── helpers/            # dublês (FakeClock, FakeTransport, …)
│   └── test_*/             # 6 suítes, 125 casos
│
├── start.sh                # sobe o painel de desenvolvimento
├── tools/
│   └── kanri-console/      # painel web local (estado, logs, gravar, reiniciar)
│
└── docs/
    ├── SAFETY.md           # ⚠️ requisitos de segurança — leia primeiro
    ├── TESTING.md          # política de testes (obrigatória)
    ├── ARCHITECTURE.md     # decisões de projeto e diagramas
    ├── HARDWARE.md         # veículo, placa, adaptador, alimentação
    └── ROADMAP.md          # o que vem em cada versão

⚠️ Ligar um ESP32 direto nos 12 V do carro destrói o ESP32. A rede elétrica veicular vai de 6 V (partida) a 40 V+ (load dump). Os requisitos obrigatórios de alimentação estão em SAFETY.md § 5 e a topologia recomendada em HARDWARE.md.

Leia CLAUDE.md (convenções), docs/SAFETY.md (requisitos) e docs/TESTING.md (política de testes) primeiro.

Resumo do fluxo:

git switch -c feat/nome-da-coisa
# ... trabalha ...
pio test -e native          # tem que estar verde
git commit -m "feat(obd): descrição curta"
git push -u origin feat/nome-da-coisa
gh pr create

• main é protegida: só recebe merge via PR com os 6 checks verdes
• Commits seguem Conventional Commits
• Código novo em lib/ chega com teste — cobrado por cobertura de 100% das linhas
• Mudança de código ou infra atualiza o CHANGELOG.md — também cobrado
• Versionamento SemVer

MIT — ver LICENSE.