BMS LC30 – API Reference #

This page documents the API endpoints exposed by the BMS LC30 plugin. It covers endpoints for monitoring, diagnostics, advanced configuration, calibration, register read/write operations, profiles, advanced studio-type functions, and security management.

The routes described below correspond to the actual implementation of the provided Python plugin.

1. Overview #

Method	Road	Description
GET	/api/bms	Consolidated BMS Data
GET	/api/bms/diag	I²C Diagnostics and Basic Reading
GET / POST	/api/bms/advanced-config	Advanced configuration read/write
POST	/api/bms/calibration/voltage	Voltage calibration
POST	/api/bms/calibration/current	Current calibration
POST	/api/bms/calibration/reset	Reset calibration
POST	/api/bms/register/read	Direct reading of a register
POST	/api/bms/register/write	Direct write to a register
GET / POST	/api/bms/register/profiles	Reading/adding registry profiles
POST	/api/bms/register/profiles/import	Import profiles
POST	/api/bms/register/profile/apply	Applying a profile
GET	/api/bms/studio/info	Device information
GET	/api/bms/studio/sbs	Full SBS Reading
POST	/api/bms/studio/mac	Placing a MAC order
GET	/api/bms/studio/mac_commands	List of MAC Commands
GET	/api/bms/studio/status	Reading status flags
GET	/api/bms/studio/cells	Cell reading
GET	/api/bms/studio/df_classes	List of Data Flash classes
GET	/api/bms/studio/df_search	Search Data Flash
POST	/api/bms/studio/df_read	Reading from a Data Flash class
POST	/api/bms/studio/df_write	Data Flash Writing
POST	/api/bms/studio/df_raw	Raw read of a Data Flash block
GET / POST	/api/bms/studio/security	Viewing / changing the security mode

2. Monitoring #

GET /api/bms #

Returns consolidated data from the BMS. When monitoring is active, the response may include alarms, charge status, fully charged status, connection status, and values corrected through advanced calibration.

Sample response #

{
  "connected": true,
  "soc": 82,
  "voltage": 15.84,
  "current": -1.25,
  "temperature": 27.4,
  "remaining_capacity": 2460,
  "full_charge_capacity": 3000,
  "cycle_count": 18,
  "charging": false,
  "fully_charged": false,
  "alarms": [],
  "advanced_mode": false,
  "soc_source": "bms"
}

Main fields #

Field	Type	Description
connected	bool	BMS present on the monitoring side
soc	int	Charge level (%)
voltage	float	Pack voltage
current	float	Package current
temperature	float	Temperature
alarms	list	Active Alarms
charging	bool	Indicates whether the battery is charging
fully_charged	bool	Indicates whether the battery is considered fully charged

GET /api/bms/diag #

Returns an I²C diagnostic report: a list of detected buses, present addresses, target bus, target address, connection status, and readings from several standard registers such as voltage, current, SOC, temperature, status, cycle count, and serial number.

Sample response #

{
  "buses": [
    {
      "id": 1,
      "path": "/dev/i2c-1",
      "devices": ["0x0B"]
    }
  ],
  "target_bus": 1,
  "target_addr": "0x0B",
  "connected": true,
  "registers": {
    "voltage_mV": 15840,
    "current_mA": -1250,
    "soc_%": 82,
    "temperature_01K": 3001,
    "status": 512,
    "cycle_count": 18,
    "serial_number": 1234
  },
  "error": null
}

3. Advanced Settings #

GET /api/bms/advanced-config #

Reads the current advanced configuration: advanced mode, SOC source, full/empty cell parameters, calibration gains and offsets, and number of cells.

Sample response #

{
  "ok": true,
  "config": {
    "advanced_mode": false,
    "soc_source": "bms",
    "full_cell_voltage": 4.2,
    "empty_cell_voltage": 3.2,
    "voltage_gain": 1.0,
    "voltage_offset": 0.0,
    "current_gain": 1.0,
    "current_offset": 0.0,
    "cell_count": 4
  }
}

POST /api/bms/advanced-config #

Updates the advanced configuration. The supported SOC sources are bms and voltage_estimated. Any other value is converted to bms.

JSON Body #

{
  "advanced_mode": true,
  "soc_source": "bms",
  "full_cell_voltage": 4.2,
  "empty_cell_voltage": 3.2,
  "voltage_gain": 1.0,
  "voltage_offset": 0.0,
  "current_gain": 1.0,
  "current_offset": 0.0
}

Sample response #

{
  "ok": true,
  "message": "Configuration avancée BMS sauvegardée."
}

4. Calibration #

POST /api/bms/calibration/voltage #

Calculates and applies a new voltage gain based on an external reference voltage. The BMS must be initialized, and the measurements must be valid.

JSON Body #

{
  "reference_voltage": 15.92
}

Sample response #

{
  "ok": true,
  "message": "Calibration tension appliquée.",
  "measured_voltage": 15.84,
  "reference_voltage": 15.92,
  "voltage_gain": 1.005051
}

POST /api/bms/calibration/current #

Calculates and applies a new current gain based on an external reference current. If the measured current is too low, the request fails.

JSON Body #

{
  "reference_current": -1.48
}

POST /api/bms/calibration/reset #

Resets the gains, offsets, and SOC source to their default values.

Sample response #

{
  "ok": true,
  "message": "Calibration BMS réinitialisée."
}

5. Reading and Writing Registers #

POST /api/bms/register/read #

Reads a register in byte, word or block. The field signed allows you to correctly decode signed words.

JSON body – word count #

{
  "register": "0x09",
  "mode": "word",
  "signed": false
}

Sample response #

{
  "ok": true,
  "mode": "word",
  "register": "0x09",
  "value": 15840,
  "raw_value": 15840,
  "hex": "0x3DE0",
  "signed": false
}

JSON Body – read block #

{
  "register": "0x20",
  "mode": "block",
  "length": 20
}

Sample response #

{
  "ok": true,
  "mode": "block",
  "register": "0x20",
  "length": 20,
  "bytes": [84, 89, 86, 65],
  "hex": "54 59 56 41"
}

POST /api/bms/register/write #

Writes directly to a registry. Advanced mode must be enabled and confirm_write=true is required. Some fields are protected, including 0x00, 0x3E and 0x3F.

JSON Body #

{
  "register": "0x17",
  "mode": "word",
  "value": 12,
  "confirm_write": true
}

Sample response #

{
  "ok": true,
  "mode": "word",
  "register": "0x17",
  "value": 12,
  "raw_value": 12,
  "hex": "0x000C",
  "message": "Ecriture word OK"
}

6. Register Profiles #

The plugin includes default profiles, including sbs_monitoring and manufacturer_strings. It also allows you to add custom profiles.

GET /api/bms/register/profiles #

Sample response #

{
  "ok": true,
  "profiles": {
    "defaults": {
      "sbs_monitoring": {
        "label": "SBS Monitoring (lecture)",
        "description": "Registres SBS principaux en lecture seule."
      }
    },
    "custom": {}
  }
}

POST /api/bms/register/profiles #

Add a custom profile. Reserved names corresponding to default profiles are not allowed.

JSON Body #

{
  "name": "mon_profil",
  "label": "Mon profil de lecture",
  "description": "Lecture personnalisée",
  "entries": [
    {
      "register": "0x09",
      "mode": "word",
      "signed": false,
      "label": "Voltage"
    }
  ]
}

POST /api/bms/register/profiles/import #

Imports a set of custom profiles in JSON dictionary format.

POST /api/bms/register/profile/apply #

Applies a read or write profile based on write_mode. In writing, confirm_write is required.

JSON Body #

{
  "profile": "sbs_monitoring",
  "write_mode": false
}

Sample response #

{
  "ok": true,
  "profile": "sbs_monitoring",
  "write_mode": false,
  "results": [
    {
      "label": "Voltage",
      "register": "0x09",
      "mode": "word",
      "value": 15840,
      "raw_value": 15840,
      "hex": "0x3DE0",
      "signed": false,
      "status": "ok"
    }
  ]
}

7. Studio Routes #

GET /api/bms/studio/info #

Returns device information and the current security mode.

Sample response #

{
  "ok": true,
  "info": {
    "device_name": "BQ78350-R1",
    "manufacturer": "TI",
    "security": "SEALED"
  }
}

GET /api/bms/studio/sbs #

Returns the SBS registers read in bulk and the cell voltages.

Sample response #

{
  "ok": true,
  "registers": {
    "Voltage": 15840,
    "Current": -1250,
    "RelativeStateOfCharge": 82
  },
  "cells": [3960, 3955, 3963, 3962]
}

POST /api/bms/studio/mac #

Sends a MAC command. Some commands are marked as dangerous and require confirm=true.

JSON Body #

{
  "command": "0x0001",
  "confirm": false
}

GET /api/bms/studio/mac_commands #

Lists the available MAC commands along with their descriptions and risk levels.

GET /api/bms/studio/status #

Returns several sets of flags: safety alert, safety status, PF alert, PF status, operation status, charging status, gauging status, and safety information.

Sample response #

{
  "ok": true,
  "status": {
    "safety_alert": {},
    "safety_status": {},
    "pf_alert": {},
    "pf_status": {},
    "operation_status": {},
    "charging_status": {},
    "gauging_status": {},
    "security": {
      "mode": "UNSEALED"
    }
  }
}

GET /api/bms/studio/cells #

Returns the cell voltages based on the number of cells configured.

GET /api/bms/studio/df_classes #

Returns a list of available Data Flash classes.

GET /api/bms/studio/df_search?q=… #

Searches for a Data Flash parameter by name or address. The parameter q is required.

Example #

GET /api/bms/studio/df_search?q=0x45CC

POST /api/bms/studio/df_read #

Reads all the parameters of a Data Flash class.

JSON Body #

{
  "class": "gas_gauging"
}

POST /api/bms/studio/df_write #

Writes a Data Flash parameter. Advanced mode and confirm=true are required.

JSON Body #

{
  "address": "0x45CC",
  "value": 4200,
  "size": 2,
  "signed": false,
  "confirm": true
}

Sample response #

{
  "ok": true,
  "written": 4200,
  "readback": {
    "value": 4200
  }
}

POST /api/bms/studio/df_raw #

Reads a raw Data Flash block starting at an address between 0x4000 and 0x47FF.

JSON Body #

{
  "address": "0x4681"
}

8. Safety #

GET /api/bms/studio/security #

Returns the current security mode.

Sample response #

{
  "ok": true,
  "security": {
    "mode": "SEALED"
  }
}

POST /api/bms/studio/security #

Allows you to send a security action: seal, unseal or full_access.

JSON body – seal #

{
  "action": "seal"
}

JSON Body – unseal #

{
  "action": "unseal",
  "key1": "0x0414",
  "key2": "0x3672"
}

JSON body – full_access #

{
  "action": "full_access",
  "key1": "0xFFFF",
  "key2": "0xFFFF"
}

9. Error codes and behaviors #

Case	Behavior
BMS not initialized	400 error on certain calibration routes
Advanced mode is not enabled	Error 403 when writing to the registry or Data Flash
No confirmation	400 error on certain transactions
Profile not found	404 error on the profile app
Unknown Data Flash class	Response 400
Data Flash address out of range	400 response on /api/bms/studio/df_raw

10. Usage Notes #

• Start by /api/bms then /api/bms/diag to confirm the integration.
• Reserve the writing paths for controlled operations.
• Enable advanced mode only for maintenance or calibration.
• Verify that the number of cells configured matches the number of cells actually used.

API reference based on the provided Python plugin.