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

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.