BattPulse

Contents

1. Introduction
2. Data Model
3. CAN Bus Protocol — Overview
4. CAN Bus Protocol — Frame Reference
5. CAN Bus Protocol — Command Frame
6. CAN Bus Protocol — Code Examples
7. WiFi HTTP/JSON Protocol — Overview
8. WiFi HTTP/JSON Protocol — Endpoints
9. WiFi HTTP/JSON Protocol — Code Examples
10. Dynamic Hardware Support
11. Troubleshooting

1. Introduction

The BattPulse BMS Display 7" is an open-protocol touch display that shows real-time BMS data from any compatible battery management system. It supports two communication methods:

2. Data Model

Regardless of the transport (CAN or WiFi), the display maintains the same internal data model:

3. CAN Bus Protocol — Overview

Physical Layer

CAN ID Map

4. CAN Bus Protocol — Frame Reference

5. CAN Bus Protocol — Command Frame

 Display                          BMS
  │                                │
  │── 0x3A0 [01 52 53 54 52] ───►│  ARM → armed state, 2s timer
  │                                │
  │     (within 2 seconds)         │
  │                                │
  │── 0x3A0 [02 52 53 54 52] ───►│  EXECUTE → restart!
  │                                │
  │        ~~~ BMS reboots ~~~     │
  │        (2–4 second gap)        │
  │                                │
  │◄── 0x300, 0x330, etc. ────────│  BMS back online

6. CAN Bus Protocol — Code Examples

Sending BMS Data to the Display (C)

/* Build and transmit CAN frame 0x300 — Pack Status
 * Adapt can_send() to your platform's CAN driver. */
void sendPackStatus(float packVoltage, float packCurrent,
                    float soc, uint8_t status) {
    uint8_t data[8] = {0};

    uint16_t v = (uint16_t)(packVoltage * 100);   // 51.20 V → 5120
    int16_t  i = (int16_t)(packCurrent * 10);     // -12.5 A → -125
    uint16_t s = (uint16_t)(soc * 10);             // 85.0 % → 850

    data[0] = v & 0xFF;  data[1] = v >> 8;     // little-endian
    data[2] = i & 0xFF;  data[3] = i >> 8;
    data[4] = s & 0xFF;  data[5] = s >> 8;
    data[6] = status;    // 0=Idle, 1=Charge, 2=Discharge, 3=Fault
    data[7] = 0;          // reserved

    can_send(0x300, data, 8);  // ← your CAN driver's transmit function
}

/* Build and transmit cell voltage frames 0x330–0x337
 * Example: 7S pack — sends 4 frames, last cell padded with 0x0000. */
void sendCellVoltages(float *cellV, int cellCount) {
    for (int pair = 0; pair < (cellCount + 1) / 2; pair++) {
        uint8_t data[4] = {0};
        int c0 = pair * 2;
        int c1 = c0 + 1;

        uint16_t v0 = (uint16_t)(cellV[c0] * 1000);  // 3.650 V → 3650
        uint16_t v1 = (c1 < cellCount)
                    ? (uint16_t)(cellV[c1] * 1000) : 0;
        // ↑ Odd cell count: second slot = 0x0000 (display treats as padding)

        data[0] = v0 & 0xFF;  data[1] = v0 >> 8;
        data[2] = v1 & 0xFF;  data[3] = v1 >> 8;

        can_send(0x330 + pair, data, 4);
    }
}

Handling the Restart Command on the BMS (C)

/* Called when CAN frame 0x3A0 is received.
 * Implements the two-step ARM + EXECUTE safety protocol.
 * Adapt get_tick_ms() and system_restart() to your platform. */
static bool     restart_armed = false;
static uint32_t arm_time_ms   = 0;

void handleCommandFrame(const uint8_t *data, uint8_t dlc) {
    if (dlc < 5) return;
    // Verify safety key: "RSTR" = { 0x52, 0x53, 0x54, 0x52 }
    if (data[1] != 0x52 || data[2] != 0x53 ||
        data[3] != 0x54 || data[4] != 0x52) return;

    switch (data[0]) {
        case 0x01:  // ARM
            restart_armed = true;
            arm_time_ms   = get_tick_ms();
            break;
        case 0x02:  // EXECUTE
            if (restart_armed &&
                (get_tick_ms() - arm_time_ms) < 2000) {
                system_restart();  // ← your platform's reboot function
            }
            break;
    }
}

7. WiFi HTTP/JSON Protocol — Overview

The display connects to the BMS over WiFi using HTTP POST requests to a single endpoint. The BMS acts as an HTTP server.

The display sends two types of requests in alternation:

1. Dashboard request — returns pack status, temperatures, I/O states
2. Cell States request — returns individual cell voltages and colours

8. WiFi HTTP/JSON Protocol — Endpoints

POST /JsonHandle HTTP/1.1
Content-Type: text/plain

{"type":"dash"}

{
  "status": {
    "current": -12.5,
    "SoC": 85.0,
    "totSystV": 51.20,
    "MaxC": 3.65,
    "MinC": 3.60,
    "Balance": 1,
    "event": "OK"
  },
  "temps": {
    "ChipTemp": 32.0,
    "ShuntTemp": 19.0,
    "Aux_1": 18.0,
    "Aux_2": 19.0
  },
  "ntcs": {
    "NTC_1": 22.5,
    "NTC_2": 23.0
  },
  "IO_States": {
    "CHG": 1,
    "DSC": 1,
    "BAL": 0
  }
}

POST /JsonHandle HTTP/1.1
Content-Type: text/plain

{"type":"cellStates"}

{
  "cells": {
    "Cell1": 3.650,
    "Cell2": 3.645,
    "Cell3": 3.660,
    "Cell4": 3.640,
    "Cell5": 3.655,
    "Cell6": 3.648,
    "Cell7": 3.652
  },
  "colors": {
    "1": "#30B32D",
    "2": "#30B32D",
    "3": "#F5A623",
    "4": "#30B32D"
  },
  "status": {
    "current": -12.5
  },
  "IO_States": {
    "CHG": 1,
    "DSC": 1
  }
}

9. WiFi HTTP/JSON Protocol — Code Examples

Minimal BMS HTTP Server (C — Pseudocode)

/* Minimal example showing the JSON response structure.
 * Adapt to your platform's HTTP server library. */

void handleJsonRequest(const char *body, http_response_t *resp) {
    // Parse the "type" field from the POST body
    const char *type = json_get_string(body, "type");

    if (strcmp(type, "dash") == 0) {
        // Return pack status, temperatures, and I/O states
        http_send_json(resp,
            "{"
            "  \"status\": {"
            "    \"current\": -12.5,"
            "    \"SoC\": 85.0,"
            "    \"totSystV\": 51.20,"
            "    \"MaxC\": 3.65,"
            "    \"MinC\": 3.60,"
            "    \"Balance\": 1,"
            "    \"event\": \"OK\""
            "  },"
            "  \"temps\": { \"BoardTemp\": 32.0, \"Shunt\": 19.0 },"
            "  \"IO_States\": { \"CHG\": 1, \"DSC\": 1, \"BAL\": 0 }"
            "}"
        );
    }
    else if (strcmp(type, "cellStates") == 0) {
        // Return individual cell voltages
        http_send_json(resp,
            "{"
            "  \"cells\": {"
            "    \"Cell1\": 3.650, \"Cell2\": 3.645,"
            "    \"Cell3\": 3.660, \"Cell4\": 3.640,"
            "    \"Cell5\": 3.655, \"Cell6\": 3.648,"
            "    \"Cell7\": 3.652"
            "  }"
            "}"
        );
    }
}

/* Register the handler on your HTTP server:
 *   http_register_post("/JsonHandle", handleJsonRequest);
 * The display will POST to this endpoint every ~250 ms. */

10. Dynamic Hardware Support

The display is designed to work with many different BMS configurations without needing firmware changes. Here's what adapts automatically:

11. Troubleshooting