Referência completa da API Smart BMS

Autenticação, CORS e convenções

Todas as rotas exigem API REST ativada no EasyMonitor e o mesmo Bearer Token exibido em Dispositivo > API REST.

Authorization: Bearer SEU_TOKEN

A API usa HTTP no dispositivo. Para acesso fora da rede local, utilize VPN ou proxy reverso com HTTPS. Nunca exponha o token em código de frontend público.

Use para a tela inicial ou verificação rápida. Para células, temperaturas, ciclos e identificação completa, use /api/bms/status.

{
  "success": true, "protocolVersion": 1, "uptime": 583980,
  "data": {
    "device": { "id": "EASYM_68F29C", "name": "EasyMonitor", "hostname": "EasyMonitor", "software": "TechLabsOS Smart BMS", "version": "0.0.1" },
    "network": { "mode": "STA", "ip": "192.168.1.50" },
    "bms": { "online": true, "name": "EasyMonitor2", "model": "JK-BD6A24S10PD", "batteryType": "Li-ion", "cellCount": 7, "soc": 96, "capacityAh": 8, "remainingCapacityAh": 7.642, "alarmCode": 0, "pack": { "voltage": 28.926, "current": 0, "power": 0 } }
  }
}

Retorna os campos da BMS diretamente em data, sem um nível intermediário data.bms. A resposta continua disponível se a BMS estiver offline; nesse caso, valide data.online antes de utilizar os valores.

Formato de cada item de cells[]

{ "number": 1, "voltage": 4.134, "wireResistanceMilliOhm": 346 }

number é a posição da célula iniciando em 1; voltage está em V; wireResistanceMilliOhm está em miliohm (mOhm).

Le o frame de configuração que o EasyMonitor recebeu da BMS. A rota exige BMS online e frame de setup carregado.

{
  "success": true,
  "data": {
    "loaded": true,
    "battery": { "cellCount": 7, "capacityAh": 8, "bluetoothName": "EasyMonitor2" },
    "balance": { "enabled": true, "startVoltage": 3.7, "triggerVoltage": 0.02, "maxCurrent": 0.6 },
    "protections": { "cellUvpVoltage": 2.82, "cellUvprVoltage": 2.85, "cellOvpVoltage": 4.2, "cellOvprVoltage": 4.17, "cellRcvVoltage": 4.19, "powerOffVoltage": 2.8 },
    "temperature": { "chargeOtp": 70, "chargeOtpr": 60, "chargeUtp": -10, "chargeUtpr": 0, "dischargeOtp": 70, "dischargeOtpr": 60, "mosOtp": 80, "mosOtpr": 70 }
  }
}

Tensões são publicadas em V, maxCurrent em A e valores de temperature em graus Celsius.

Aciona uma função binária sem expor registradores Modbus brutos. Envie apenas um comando por requisição.

{ "command": "discharge_mos", "state": false }

Resposta aceita para processamento

HTTP/1.1 202 Accepted
{ "success": true, "status": "queued", "data": { "command": "discharge_mos", "state": false, "statusEndpoint": "/api/bms/commands" } }

Altera um único parâmetro por requisição. value pode ser número JSON ou texto. Para valores decimais, envie ponto como separador, por exemplo 3.700.

{ "setting": "balance_start_voltage", "value": 3.7 }

Aliases sem underscore também são aceitos para compatibilidade: cellcount, capacity, blename, balanceenabled, balancetrigger, startbalance, maxbalancecurrent, celluvp, celluvpr, cellovp, cellovpr, cellrcv, poweroff, chargeotp, chargeotpr, chargeutp, chargeutpr, dischargeotp, dischargeotpr, mosotp e mosotpr. Prefira sempre os nomes canônicos da tabela.

Resposta aceita para processamento

HTTP/1.1 202 Accepted
{ "success": true, "status": "queued", "data": { "setting": "balance_start_voltage", "statusEndpoint": "/api/bms/commands" } }

Consulte imediatamente depois de uma escrita e repita a leitura enquanto pending for true. Uma unica fila e usada por todas as escritas API, MQTT e interface web.

{
  "success": true,
  "data": { "bmsOnline": true, "configurationLoaded": true, "pending": false, "lastCommand": "Início do balanceamento atualizado", "lastCommandOk": true }
}

Fluxo recomendado para escrita

1. 1. Consulte GET /api/bms/commands. Prossiga somente com bmsOnline: true e pending: false.
2. 2. Envie um POST /api/bms/commands ou POST /api/bms/settings.
3. 3. Verifique o retorno HTTP 202.
4. 4. Consulte GET /api/bms/commands em intervalo de 1 segundo.
5. 5. Quando pending: false, aceite a mudanca apenas se lastCommandOk: true. Para parâmetros, releia GET /api/bms/config.

# Alterar início do balanceamento e confirmar
curl -X POST "http://IP_DO_EASYMONITOR/api/bms/settings" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"setting":"balance_start_voltage","value":3.7}'

curl "http://IP_DO_EASYMONITOR/api/bms/commands" \
  -H "Authorization: Bearer SEU_TOKEN"

Erros e como tratar

Um comando desconhecido retorna 409 com Comando não suportado. Um parâmetro desconhecido retorna 409 com Parâmetro não suportado. Limites inválidos retornam 409 com a mensagem do validador.