---
title: BMS LC30 – Référence API
description: "# BMS LC30 – Référence API Cette page documente les routes API exposées par le plugin **BMS LC30**. Elle couvre les endpoints de monitoring, diagnostic, configuration avancée, calibration, lecture / écriture de registres, profils, fonctions avancées de type studio et…"
url: "https://solutionsreeds.fr/wp/docs/bms-lc30-reference-api/"
updated: "2026-04-13"
category: Supports / The BlueStack / Power Board
---

# BMS LC30 – Référence API

# BMS LC30 – Référence API

Cette page documente les routes API exposées par le plugin **BMS LC30**. Elle couvre les endpoints de monitoring, diagnostic, configuration avancée, calibration, lecture / écriture de registres, profils, fonctions avancées de type studio et gestion de la sécurité.

Les routes décrites ci-dessous correspondent à l’implémentation réelle du plugin Python fourni.

## 1. Vue d’ensemble

| Méthode | Route | Description |
| --- | --- | --- |
| GET | `/api/bms` | Données consolidées du BMS |
| GET | `/api/bms/diag` | Diagnostic I²C et lecture de base |
| GET / POST | `/api/bms/advanced-config` | Lecture / écriture configuration avancée |
| POST | `/api/bms/calibration/voltage` | Calibration tension |
| POST | `/api/bms/calibration/current` | Calibration courant |
| POST | `/api/bms/calibration/reset` | Réinitialisation calibration |
| POST | `/api/bms/register/read` | Lecture directe d’un registre |
| POST | `/api/bms/register/write` | Écriture directe d’un registre |
| GET / POST | `/api/bms/register/profiles` | Lecture / ajout de profils registres |
| POST | `/api/bms/register/profiles/import` | Import de profils |
| POST | `/api/bms/register/profile/apply` | Application d’un profil |
| GET | `/api/bms/studio/info` | Informations device |
| GET | `/api/bms/studio/sbs` | Lecture SBS complète |
| POST | `/api/bms/studio/mac` | Envoi d’une commande MAC |
| GET | `/api/bms/studio/mac_commands` | Liste des commandes MAC |
| GET | `/api/bms/studio/status` | Lecture des flags de statut |
| GET | `/api/bms/studio/cells` | Lecture des cellules |
| GET | `/api/bms/studio/df_classes` | Liste des classes Data Flash |
| GET | `/api/bms/studio/df_search` | Recherche Data Flash |
| POST | `/api/bms/studio/df_read` | Lecture d’une classe Data Flash |
| POST | `/api/bms/studio/df_write` | Écriture Data Flash |
| POST | `/api/bms/studio/df_raw` | Lecture brute d’un bloc Data Flash |
| GET / POST | `/api/bms/studio/security` | Lecture / changement du mode de sécurité |

## 2. Monitoring

### GET /api/bms

Retourne les données consolidées du BMS. Lorsque le monitoring est actif, la réponse peut inclure les alarmes, l’état de charge, l’état fully charged, l’état de connexion et les valeurs corrigées par calibration avancée.

#### Réponse type

```
{
  "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"
}
```

#### Champs principaux

| Champ | Type | Description |
| --- | --- | --- |
| `connected` | bool | Présence du BMS côté monitoring |
| `soc` | int | État de charge en % |
| `voltage` | float | Tension pack |
| `current` | float | Courant pack |
| `temperature` | float | Température |
| `alarms` | liste | Alarmes actives |
| `charging` | bool | Indique si la batterie est en charge |
| `fully_charged` | bool | Indique si la batterie est considérée pleine |

### GET /api/bms/diag

Retourne un rapport de diagnostic I²C : liste des bus détectés, adresses présentes, bus cible, adresse cible, statut de connexion et lecture de plusieurs registres standards comme tension, courant, SOC, température, status, cycle count et serial number.

#### Réponse type

```
{
  "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. Configuration avancée

### GET /api/bms/advanced-config

Lit la configuration avancée active : mode avancé, source de SOC, paramètres cellule pleine / vide, gains et offsets de calibration, et nombre de cellules.

#### Réponse type

```
{
  "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

Met à jour la configuration avancée. Les sources de SOC acceptées sont `bms` et `voltage_estimated`. Toute autre valeur est ramenée à `bms`.

#### Corps JSON

```
{
  "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
}
```

#### Réponse type

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

## 4. Calibration

### POST /api/bms/calibration/voltage

Calcule et applique un nouveau gain de tension à partir d’une tension de référence externe. Le BMS doit être initialisé et les mesures doivent être valides.

#### Corps JSON

```
{
  "reference_voltage": 15.92
}
```

#### Réponse type

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

### POST /api/bms/calibration/current

Calcule et applique un nouveau gain de courant à partir d’un courant de référence externe. Si le courant mesuré est trop faible, la requête échoue.

#### Corps JSON

```
{
  "reference_current": -1.48
}
```

### POST /api/bms/calibration/reset

Réinitialise les gains, offsets et la source de SOC à leurs valeurs nominales.

#### Réponse type

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

## 5. Lecture et écriture de registres

### POST /api/bms/register/read

Lit un registre en mode `byte`, `word` ou `block`. Le champ `signed` permet de décoder correctement les mots signés.

#### Corps JSON – lecture word

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

#### Réponse type

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

#### Corps JSON – lecture block

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

#### Réponse type

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

### POST /api/bms/register/write

Écrit directement un registre. Le mode avancé doit être activé et `confirm_write=true` est obligatoire. Certains registres sont protégés, notamment `0x00`, `0x3E` et `0x3F`.

#### Corps JSON

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

#### Réponse type

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

  **Attention :** l’écriture de registres doit être réservée aux opérations de maintenance maîtrisées.

## 6. Profils de registres

Le plugin contient des profils par défaut, dont `sbs_monitoring` et `manufacturer_strings`. Il permet aussi d’ajouter des profils personnalisés.

### GET /api/bms/register/profiles

#### Réponse type

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

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

Ajoute un profil personnalisé. Les noms réservés correspondant aux profils par défaut sont refusés.

#### Corps JSON

```
{
  "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

Importe un bloc de profils personnalisés au format dictionnaire JSON.

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

Applique un profil en lecture ou en écriture selon `write_mode`. En écriture, `confirm_write` est requis.

#### Corps JSON

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

#### Réponse type

```
{
  "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. Routes studio

### GET /api/bms/studio/info

Retourne les informations device ainsi que le mode de sécurité courant.

#### Réponse type

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

### GET /api/bms/studio/sbs

Retourne les registres SBS lus en bloc et les tensions cellules.

#### Réponse type

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

### POST /api/bms/studio/mac

Envoie une commande MAC. Certaines commandes sont marquées dangereuses et nécessitent `confirm=true`.

#### Corps JSON

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

### GET /api/bms/studio/mac_commands

Liste les commandes MAC disponibles avec leur description et leur niveau de dangerosité.

### GET /api/bms/studio/status

Retourne plusieurs familles de flags : safety alert, safety status, PF alert, PF status, operation status, charging status, gauging status et informations de sécurité.

#### Réponse type

```
{
  "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

Retourne les tensions cellules en fonction du nombre de cellules configuré.

### GET /api/bms/studio/df_classes

Retourne la liste des classes Data Flash disponibles.

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

Recherche un paramètre Data Flash par nom ou adresse. Le paramètre `q` est requis.

#### Exemple

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

### POST /api/bms/studio/df_read

Lit l’ensemble des paramètres d’une classe Data Flash.

#### Corps JSON

```
{
  "class": "gas_gauging"
}
```

### POST /api/bms/studio/df_write

Écrit un paramètre Data Flash. Le mode avancé et `confirm=true` sont requis.

#### Corps JSON

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

#### Réponse type

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

### POST /api/bms/studio/df_raw

Lit un bloc Data Flash brut à partir d’une adresse comprise entre `0x4000` et `0x47FF`.

#### Corps JSON

```
{
  "address": "0x4681"
}
```

## 8. Sécurité

### GET /api/bms/studio/security

Retourne le mode de sécurité courant.

#### Réponse type

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

### POST /api/bms/studio/security

Permet d’envoyer une action de sécurité : `seal`, `unseal` ou `full_access`.

#### Corps JSON – seal

```
{
  "action": "seal"
}
```

#### Corps JSON – unseal

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

#### Corps JSON – full_access

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

## 9. Codes d’erreur et comportements

| Cas | Comportement |
| --- | --- |
| BMS non initialisé | Réponse 400 sur certaines routes de calibration |
| Mode avancé non activé | Réponse 403 sur écriture registre ou Data Flash |
| Confirmation absente | Réponse 400 sur certaines écritures |
| Profil introuvable | Réponse 404 sur application de profil |
| Classe Data Flash inconnue | Réponse 400 |
| Adresse Data Flash hors plage | Réponse 400 sur `/api/bms/studio/df_raw` |

## 10. Notes d’usage

- Commencer par `/api/bms` puis `/api/bms/diag` pour valider l’intégration.
- Réserver les routes d’écriture aux opérations maîtrisées.
- Activer le mode avancé uniquement pour maintenance ou calibration.
- Vérifier la cohérence du nombre de cellules configuré avec le pack réellement utilisé.

Référence API basée sur le plugin Python fourni.