Skip to main content

Battery Management API

Real-time battery data from Huawei FusionSolar BMS integrated with autonomous charging robots.

Overview​

The Battery Management API provides real-time telemetry from Huawei FusionSolar Battery Management System (BMS), enabling monitoring of battery health, charging status, and energy metrics during robot charging operations.

Base URL: https://api.rollyy.com/v1/battery

Authentication​

All battery endpoints require API key authentication.

curl -H "X-API-Key: your_api_key_here" \
  https://api.rollyy.com/v1/battery/battery-001

Endpoints​

Get Battery Data​

Retrieve real-time battery metrics from the BMS.

Endpoint: GET /v1/battery/{battery_id}

Parameters:

  • battery_id (path, required): Battery identifier (e.g., battery-001, battery-002)

Response:

{
  "batteryId": "battery-001",
  "energyConsumed": 1.24,
  "energyDelivered": 0.18,
  "elapsedTime": 145,
  "timestamp": "2026-02-05T22:00:00.000Z",
  "status": "active"
}

Response Fields:

  • batteryId: Battery identifier
  • energyConsumed (kWh): Total energy discharged (delivered to vehicle)
  • energyDelivered (kWh): Total energy charged into battery
  • elapsedTime (seconds): Current session elapsed time (0 if idle)
  • timestamp: ISO 8601 timestamp
  • status: active (charging) or idle

Example:

curl -H "X-API-Key: your_api_key" \
  https://api.rollyy.com/v1/battery/battery-001

Get Battery Session​

Get current charging session status for a battery.

Endpoint: GET /v1/battery/{battery_id}/session

Parameters:

  • battery_id (path, required): Battery identifier

Response:

{
  "batteryId": "battery-001",
  "sessionActive": true,
  "energyConsumed": 1.24,
  "energyDelivered": 0.18,
  "elapsedTime": 145,
  "startTime": null,
  "timestamp": "2026-02-05T22:00:00.000Z"
}

Response Fields:

  • sessionActive (boolean): Whether battery is currently in a charging session
  • startTime: Session start time (ISO 8601) - Coming soon
  • Other fields same as battery data endpoint

Example:

curl -H "X-API-Key: your_api_key" \
  https://api.rollyy.com/v1/battery/battery-001/session

Integration Architecture​

Huawei FusionSolar BMS → bms.rollyy.com → api.rollyy.com → Your App
                         (Internal)        (Public API)

The Battery API acts as a proxy to the internal BMS service, providing:

  • Unified authentication via API keys
  • Consistent response format
  • Battery ID-based routing
  • Error handling and retry logic

Use Cases​

1. Real-Time Charging Monitor​

Poll battery data every 30 seconds during active charging:

const batteryId = 'battery-001';

setInterval(async () => {
  const response = await fetch(
    `https://api.rollyy.com/v1/battery/${batteryId}`,
    { headers: { 'X-API-Key': 'your_api_key' } }
  );
  const data = await response.json();
  
  if (data.status === 'active') {
    console.log(`Energy: ${data.energyConsumed} kWh`);
    console.log(`Time: ${Math.floor(data.elapsedTime / 60)} min`);
  }
}, 30000);

2. Session Tracking​

Check if battery is actively charging:

const session = await fetch(
  `https://api.rollyy.com/v1/battery/${batteryId}/session`,
  { headers: { 'X-API-Key': 'your_api_key' } }
).then(r => r.json());

if (session.sessionActive) {
  console.log('Charging in progress');
} else {
  console.log('Battery idle');
}

3. Robot Integration​

Link battery data to robot charging jobs:

// Get robot's battery ID from robot job
const robotJob = await fetch(
  `https://api.rollyy.com/v1/robot-jobs/${jobId}`,
  { headers: { 'X-API-Key': 'your_api_key' } }
).then(r => r.json());

const batteryId = robotJob.batteryId;

// Fetch real-time battery metrics
const batteryData = await fetch(
  `https://api.rollyy.com/v1/battery/${batteryId}`,
  { headers: { 'X-API-Key': 'your_api_key' } }
).then(r => r.json());

console.log(`Robot ${robotJob.robotId} battery: ${batteryData.energyConsumed} kWh`);

Error Responses​

503 Service Unavailable​

BMS service is temporarily unavailable:

{
  "detail": "BMS service unavailable: Connection timeout"
}

500 Internal Server Error​

Unexpected error occurred:

{
  "detail": "Internal error: ..."
}

Rate Limits​

  • Default: 1000 requests/minute per API key
  • Recommended polling: Every 30 seconds for active sessions

Battery IDs​

Current battery identifiers in the system:

  • battery-001 - Huawei FusionSolar Battery 1 (Device ID: 1000000193573380)
  • battery-002 - Huawei FusionSolar Battery 2 (Device ID: 1000000193573382)
  • Robot Jobs API - Manage autonomous robot charging tasks
  • Charging Sessions API - Track EV charging sessions
  • Charging Assets API - EV charging station data

Support​

For BMS integration support: