MQTT

Telemetria, comandos e Home Assistant

O EasyMonitor pública o estado da BMS em MQTT e aceita somente comandos nomeados e configurações validadas. Não aceita frames brutos ou registradores Modbus pelo broker.

Telemetria

A cada 5 segundos

Estado atual e retido no broker.

Disponibilidade

LWT retido

Pública online e offline.

Escrita

Dois tópicos

Operações e configurações da BMS.

Conexão e tópico base

Configure host, porta, usuário, senha e Discovery em Gerenciar dispositivo > MQTT. O cliente usa MQTT sobre TCP no Wi-Fi, keep alive de 30 segundos, timeout de 3 segundos e tenta reconectar a cada 5 segundos. TLS não está implementado no cliente atual.

easymonitor/EASYM_XXXXXX

Substitua EASYM_XXXXXX pelo Device ID exibido pelo EasyMonitor. A documentação usa BASE como abreviacao desse prefixo.

Tópicos publicados

Tópico	Retido	Quando	Conteúdo
`BASE/status`	Sim	Conexão, desconexão e LWT	`online` ou `offline`.
`BASE/data`	Sim	5 segundos	Telemetria, transporte, pack, temperaturas, operação e alarmes.
`BASE/cells`	Sim	5 segundos	Tensões de célula na ordem física.
`BASE/bms/config`	Sim	5 segundos após setup	Configurações confirmadas no frame de setup.
`BASE/bms/commands/status`	Sim	Fila ou resultado alterado	Estado da última escrita.
`BASE/bms/commands/result`	Não	Após pedido MQTT	Aceite ou rejeição local do pedido.

Payload `BASE/data`

{
  "online": true,
  "name": "EasyMonitor2",
  "model": "JK-BD6A24S10PD",
  "transport": "uart",
  "transportLabel": "Serial RS485",
  "protocol": "JK BMS RS485 Modbus V1.0",
  "soc": 96,
  "pack": { "voltage": 28.926, "current": 0, "power": 0 },
  "temperatures": { "mosfet": 32.8, "battery1": 30.5, "battery2": 30.3 },
  "operations": { "chargeMos": true, "dischargeMos": true },
  "alarmCode": 0,
  "alarmsHex": "0x00000000"
}

transport e uart ou ble. Capacidades usam Ah, tempos usam segundos, pack usa V/A/W e temperaturas usam C.

Células e configuração

BASE/cells
{ "count": 7, "values": [4.134, 4.134, 4.129] }

BASE/bms/config
{
  "battery": { "cellCount": 7, "capacityAh": 8 },
  "balance": { "startVoltage": 3.7, "triggerVoltage": 0.02, "maxCurrent": 0.6 },
  "protections": { "cellUvpVoltage": 2.82 },
  "temperature": { "chargeOtp": 70, "dischargeOtp": 70 }
}

values[0] é a célula 1 em V. O tópico de configuração somente aparece depois que a BMS fornece setup válido.

Tópicos de escrita

O EasyMonitor assina somente os tópicos abaixo. Envie JSON de no máximo 256 bytes e nunca use a flag retained em mensagens set, pois elas poderiam ser reaplicadas depois de uma reconexao.

Tópico	Payload	Uso
`BASE/bms/commands/set`	`{"command":"discharge_mos","state":false}`	Operação binária.
`BASE/bms/settings/set`	`{"setting":"balance_start_voltage","value":3.7}`	Configuração nomeada.

Comandos aceitos

command	true	false
`charge_mos`	Liga carga.	Desliga carga.
`discharge_mos`	Liga descarga.	Desliga descarga.
`balance`	Habilita.	Desabilita.
`emergency`	Ativa.	Desativa.
`display_always_on`	Mantém ligado.	Modo normal.
`temperature_sensors_disabled`	Desabilita sensores.	Habilita sensores.

Para configurações, use os mesmos setting, limites e aliases documentados na API REST. Em Bluetooth JK02, veja também a matriz de compatibilidade.

Resultado e confirmação

BASE/bms/commands/result
{ "success": true, "status": "queued", "message": "Ativação de carga", "key": "charge_mos" }

BASE/bms/commands/status
{ "transport": "uart", "pending": false, "lastCommandOk": true }

queued significa apenas fila local. Em UART, lastCommandOk confirma ACK Modbus; em BLE, confirma entrega GATT e exige conferir a proxima leitura de configuração.

Home Assistant Discovery

Com Discovery ativo, o EasyMonitor cria sensores de pack, SOC, capacidade, ciclos, alarmes, temperaturas e células; chaves para MOS; e, depois do setup, chaves e campos numéricos de configuração. Emergência fica fora do Discovery automático por ser crítica.

As configurações Home Assistant usam BASE/bms/config como estado, para refletir a leitura posterior da BMS.

Segurança.

Use ACLs permitindo escrita somente nos dois tópicos set, credenciais exclusivas por placa e rede privada ou VPN. O cliente MQTT atual não usa TLS; não exponha o broker diretamente na internet sem uma camada segura.