Version 1.3.0:

- Added support to generate extended info frame 0x700
- New API calls: setInfoBmsType(), setInfoState1(), setInfoState2(), setInfoError(), setInfoBalancing()
- Added support for module temperature #8 and cell voltages #15/#16

API.md

@@ -66,23 +66,25 @@ Note: all control functions validate their parameters. If you pass any value out
     - soh: 0 .. 100 (%)
   
   - `bool setCellVoltage(int cell, float volt)` -- Set battery cell voltage
-    - cell: 1 .. 14 (the original Twizy battery has 14 cells)
+    - cell: 1 .. 16 (the original Twizy battery has 14 cells)
     - volt: 1.0 .. 5.0
     - Note: this does no implicit update on the overall pack voltage
+    - Note: cell voltages #15 & #16 will be stored in frame 0x700 (custom protocol extension)
   
   - `bool setVoltage(float volt, bool deriveCells)` -- Set battery pack voltage
     - volt: 19.3 .. 69.6 (SEVCON G48 series voltage range)
-    - deriveCells: true = set all cell voltages to volt/14
+    - deriveCells: true = set cell voltages #1-#14 to volt/14
   
   - `bool setModuleTemperature(int module, int temp)` -- Set battery module temperature
-    - module: 1 .. 7 (the original Twizy battery is organized in 7 modules)
+    - module: 1 .. 8 (the original Twizy battery is organized in 7 modules)
     - temp: -40 .. 100 (°C)
     - Note: this does no implicit update on the overall pack temperature
+    - Note: module temperature #8 will be stored in frame 0x554 byte 7, which is unused on the original pack layout
   
   - `bool setTemperature(int tempMin, int tempMax, bool deriveModules)` -- Set battery pack temperature
     - tempMin: -40 .. 100 (°C)
     - tempMax: -40 .. 100 (°C)
-    - deriveModules: true = set all module temperatures to avg(min,max)
+    - deriveModules: true = set module temperatures #1-#7 to avg(min,max)
   
   - `bool setError(unsigned long error)` -- Set display error/warning indicators
     - error: 0x000000 .. 0xFFFFFF (0 = no error) or use a bitwise ORed combination of…
@@ -210,3 +212,71 @@ Standard filters will pass IDs `0x423`, `0x597` and `0x599`. Three free CAN filt
     - this is automatically called every 10 seconds if debug level >= 1
 
 
+## Extended info frame
+
+Beginning with version 1.3.0, the VirtualBMS supports sending an extended BMS status information on the CAN bus. The frame layout has been designed by Pascal Ripp and Michael Balzer to create a standard base for CAN bus tools like the Twizplay and the OVMS.
+
+The extended info frame is sent at CAN ID 0x700 once per second in all states except `Off`. The frame transports these fields:
+
+  - Byte 0: BMS specific state #1 (main state, i.e. twizy.state())
+  - Byte 1: highest 3 bits = BMS type ID (see below), remaining 5 bits = BMS specific error code (see below)
+  - Bytes 2-4: cell voltages #15 & #16 (encoded in 12 bits like #1-#14)
+  - Bytes 5-6: balancing status (bits 15…0 = cells 16…1, 1 = balancing active)
+  - Byte 7: BMS specific state #2 (auxiliary state or data)
+
+The VirtualBMS will not send frame 0x700 unless you set the BMS type. It will also not insert any data into the fields by itself, to fill in data you need to use the API calls as shown below. This way you can use the VirtualBMS library to implement other BMS types as well.
+
+
+### BMS types
+
+The BMS type is meant for CAN tools to be able to identify the BMS and decode the BMS specific states and error info.
+
+There are currently 7 possible BMS types, defined in `enum TwizyBmsType`:
+
+  - 0 = `bmsType_VirtualBMS` (states and error codes as documented here)
+  - 1 = `bmsType_EdriverBMS` (see Pascal's documentation for details)
+  - 2…6 = reserved
+  - 7 = `bmsType_undefined` (disables frame 0x700)
+
+Types #2…#6 can be assigned to future BMS types.
+
+Please contact us if you want to allocate an ID. Keep in mind: any new BMS type needs support in all CAN tools, so try to reuse one of the already defined BMS types as long as possible.
+
+
+### BMS error codes (for `bmsType_VirtualBMS`)
+
+Our basic standard proposition covers these error codes (defined in `enum TwizyBmsError`):
+
+  - 0 = `bmsError_None`
+  - 1 = `bmsError_EEPROM`
+  - 2 = `bmsError_SensorFailure`
+  - 3 = `bmsError_VoltageHigh`
+  - 4 = `bmsError_VoltageLow`
+  - 5 = `bmsError_VoltageDiff`
+  - 6 = `bmsError_TemperatureHigh`
+  - 7 = `bmsError_TemperatureLow`
+  - 8 = `bmsError_TemperatureDiff`
+  - 9 = `bmsError_ChargerTemperatureHigh`
+
+Custom error codes can be added beginning at 128. Please contact us if you'd like to add standard error codes.
+
+
+### API calls
+
+  - `bool setInfoBmsType(byte bmsType)` -- Set informational BMS type
+    - bmsType: 0 .. 7 (see above / enum TwizyBmsType)
+    - Note: type 7 (bmsType_undefined = default value) deactivates frame 0x700
+
+  - `bool setInfoState1(byte state)` -- Set informational state 1 (main state)
+    - state: 0x00 .. 0xFF (specific by BMS type)
+
+  - `bool setInfoState2(byte state)` -- Set informational state 2 (aux state)
+    - state: 0x00 .. 0xFF (specific by BMS type)
+
+  - `bool setInfoError(byte errorCode)` -- Set informational error code
+    - errorCode: 0x00 .. 0x1F (specific by BMS type)
+
+  - `bool setInfoBalancing(unsigned int flags)` -- Set informational balancing status
+    - flags: 16 bits = 16 cells (#16 = MSB, #1 = LSB), 1 = balancing
+
+

HISTORY.md

@@ -1,5 +1,12 @@
 # History
 
+## Version 1.3.0 (2017-08-30)
+
+- Added support to generate extended info frame 0x700
+- New API calls: setInfoBmsType(), setInfoState1(), setInfoState2(), setInfoError(), setInfoBalancing()
+- Added support for module temperature #8 and cell voltages #15/#16
+
+
 ## Version 1.2.1 (2017-08-17)
 
 - New API calls stateName(), stateName(state)

keywords.txt

@@ -28,6 +28,12 @@ setCurrent	KEYWORD2
 setCurrentQA	KEYWORD2
 setError	KEYWORD2
 
+setInfoBmsType	KEYWORD2
+setInfoState1	KEYWORD2
+setInfoState2	KEYWORD2
+setInfoError	KEYWORD2
+setInfoBalancing	KEYWORD2
+
 getChargerTemperature	KEYWORD2
 getDCConverterCurrent	KEYWORD2
 isPluggedIn	KEYWORD2
@@ -81,3 +87,19 @@ TWIZY_SERV_12V	LITERAL1
 TWIZY_SERV_BATT	LITERAL1
 TWIZY_SERV_TEMP	LITERAL1
 TWIZY_SERV_STOP	LITERAL1
+
+bmsType_VirtualBMS	LITERAL1
+bmsType_EdriverBMS	LITERAL1
+bmsType_undefined	LITERAL1
+
+bmsError_None	LITERAL1
+bmsError_EEPROM	LITERAL1
+bmsError_SensorFailure	LITERAL1
+bmsError_VoltageHigh	LITERAL1
+bmsError_VoltageLow	LITERAL1
+bmsError_VoltageDiff	LITERAL1
+bmsError_TemperatureHigh	LITERAL1
+bmsError_TemperatureLow	LITERAL1
+bmsError_TemperatureDiff	LITERAL1
+bmsError_ChargerTemperatureHigh	LITERAL1
+

library.properties

@@ -1,5 +1,5 @@
 name=Twizy Virtual BMS
-version=1.2.1
+version=1.3.0
 author=Michael Balzer
 maintainer=Michael Balzer <dexter@dexters-web.de>
 sentence=Emulation of Renault Twizy BMS (battery management system)

src/TwizyVirtualBMS.h

@@ -38,7 +38,7 @@
 #ifndef _TwizyVirtualBMS_h
 #define _TwizyVirtualBMS_h
 
-#define TWIZY_VBMS_VERSION		"V1.2.1 (2017-08-16)"
+#define TWIZY_VBMS_VERSION      "V1.3.0 (2017-08-30)"
 
 #ifndef TWIZY_TAG
 #define TWIZY_TAG               "twizy."
@@ -75,6 +75,36 @@
 // ==========================================================================
 
 
+// Standard BMS types for setInfoBmsType():
+// Note: contact us to allocate a reserved id for your BMS
+enum TwizyBmsType {
+  bmsType_VirtualBMS,
+  bmsType_EdriverBMS,
+  bmsType_reserved2,
+  bmsType_reserved3,
+  bmsType_reserved4,
+  bmsType_reserved5,
+  bmsType_reserved6,
+  bmsType_undefined // 7 = do not send extended info frame
+};
+
+
+// Standard informational error codes for setInfoError():
+// Note: add custom codes beginning at 128
+enum TwizyBmsError {
+  bmsError_None,
+  bmsError_EEPROM,
+  bmsError_SensorFailure,
+  bmsError_VoltageHigh,
+  bmsError_VoltageLow,
+  bmsError_VoltageDiff,
+  bmsError_TemperatureHigh,
+  bmsError_TemperatureLow,
+  bmsError_TemperatureDiff,
+  bmsError_ChargerTemperatureHigh
+};
+
+
 // Twizy states:
 enum TwizyState {
   Off,
@@ -213,6 +243,14 @@ public:
   bool setTemperature(int tempMin, int tempMax, bool deriveModules);
   bool setError(unsigned long error);
   
+  // Extended info frame access:
+  bool setInfoBmsType(byte bmsType);
+  bool setInfoState1(byte state);
+  bool setInfoState2(byte state);
+  bool setInfoError(byte errorCode);
+  bool setInfoBalancing(unsigned int flags);
+  
+  // Read access:
   int getChargerTemperature();
   float getDCConverterCurrent();
   bool isPluggedIn();
@@ -272,11 +310,14 @@ private:
   byte id628[3] = { 0x00, 0x00, 0x00 };
   byte id659[4] = { 0xFF, 0xFF, 0xFF, 0xFF };
   
-	// CHARGER:
+  // VirtualBMS extended frame (controlled by us):
+  byte id700[8] = { 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF };
+  
+  // CHARGER (read only):
   byte id423[8] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };
   byte id597[8] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };
   
-	// DISPLAY:
+  // DISPLAY (read only):
   byte id599[8] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };
   
   
@@ -423,11 +464,11 @@ bool TwizyVirtualBMS::setSOH(int soh) {
 }
 
 // Set battery cell voltage level
-//  cell: 1 .. 14
+//  cell: 1 .. 16
-//  volt: 1.0 .. 5.0
+//  volt: 0.0 .. 5.0
 bool TwizyVirtualBMS::setCellVoltage(int cell, float volt) {
-  CHECKLIMIT(cell, 1, 14);
+  CHECKLIMIT(cell, 1, 16);
-  CHECKLIMIT(volt, 1.0, 5.0);
+  CHECKLIMIT(volt, 0.0, 5.0);
   
   // cell voltages are packed 12 bit values
   // determine frame and position:
@@ -442,10 +483,14 @@ bool TwizyVirtualBMS::setCellVoltage(int cell, float volt) {
     frame = id557;
     cell -= 6;
   }
-  else {
+  else if (cell <= 14) {
     frame = id55E;
     cell -= 11;
   }
+  else {
+    frame = id700+2; // [2]-[4] = cells 15+16
+    cell -= 15;
+  }
   
   int pos = cell * 1.5;
   unsigned int level = volt * 200;
@@ -498,10 +543,10 @@ bool TwizyVirtualBMS::setVoltage(float volt, bool deriveCells) {
 }
 
 // Set battery module temperature
-//  module: 1 .. 7
+//  module: 1 .. 8
 //  temp: -40 .. 100 [°C]
 bool TwizyVirtualBMS::setModuleTemperature(int module, int temp) {
-  CHECKLIMIT(module, 1, 7);
+  CHECKLIMIT(module, 1, 8);
   CHECKLIMIT(temp, -40, 100);
   id554[module-1] = 40 + temp;
   return true;
@@ -541,6 +586,48 @@ bool TwizyVirtualBMS::setError(unsigned long error) {
   return true;
 }
 
+// Set informational BMS type
+//  bmsType: 0 .. 7 (see TwizyBmsType)
+// 0 = VirtualBMS
+// 1 = EdriverBMS
+// 2…6 reserved
+// 7 = undefined (disables info frame)
+bool TwizyVirtualBMS::setInfoBmsType(byte bmsType) {
+  CHECKLIMIT(bmsType, 0, 7);
+  id700[1] = (id700[1] & 0x1F) | (bmsType << 5);
+  return true;
+}
+
+// Set informational state 1
+//  state: 0x00 .. 0xFF (specific by BMS type)
+bool TwizyVirtualBMS::setInfoState1(byte state) {
+  id700[0] = state;
+  return true;
+}
+
+// Set informational state 2
+//  state: 0x00 .. 0xFF (specific by BMS type)
+bool TwizyVirtualBMS::setInfoState2(byte state) {
+  id700[7] = state;
+  return true;
+}
+
+// Set informational error code
+//  errorCode: 0x00 .. 0x1F (specific by BMS type)
+bool TwizyVirtualBMS::setInfoError(byte errorCode) {
+  CHECKLIMIT(errorCode, 0x00, 0x1F);
+  id700[1] = (id700[1] & 0xE0) | (errorCode);
+  return true;
+}
+
+// Set informational balancing status
+//  flags: 16 bits = 16 cells (#16 = MSB, #1 = LSB), 1 = balancing
+bool TwizyVirtualBMS::setInfoBalancing(unsigned int flags) {
+  id700[5] = (flags & 0xFF00) >> 8;
+  id700[6] = (flags & 0x00FF);
+  return true;
+}
+
 
 // Get charger temperature
 int TwizyVirtualBMS::getChargerTemperature() {
@@ -745,6 +832,10 @@ void TwizyVirtualBMS::ticker() {
     if (ms3000) {
       sendMsg(0x659, sizeof(id659), id659);
     }
+    // send frame 0x700 only if BMS type has been set:
+    if (ms1000 && (id700[1] & 0xE0) != 0xE0) {
+      sendMsg(0x700, sizeof(id700), id700);
+    }
     
     
     //
@@ -823,6 +914,26 @@ void TwizyVirtualBMS::ticker() {
   } // if ((twizyState != Off) && (twizyState != Error))
   
   
+  else if (twizyState == Error) {
+    
+    bool ms1000 = (clockCnt % 100 == 0);
+    bool ms10000 = (clockCnt % 1000 == 0);
+    
+    // send frame 0x700 only if BMS type has been set:
+    if (ms1000 && (id700[1] & 0xE0) != 0xE0) {
+      sendMsg(0x700, sizeof(id700), id700);
+    }
+    
+    // Debug info every 10 seconds
+    #if TWIZY_DEBUG_LEVEL >= 1
+    if (ms10000) {
+      debugInfo();
+    }
+    #endif
+    
+  } // if (twizyState == Error)
+  
+  
   //
   // Callback for BMS ticker code:
   //
@@ -899,6 +1010,7 @@ void TwizyVirtualBMS::debugInfo() {
   dumpId(F("id55F"), sizeof(id55F), id55F);
   dumpId(F("id628"), sizeof(id628), id628);
   dumpId(F("id659"), sizeof(id659), id659);
+  dumpId(F("id700"), sizeof(id700), id700);
   
   #endif
   

src/TwizyVirtualBMS_config.h

@@ -8,8 +8,8 @@
 #define _TwizyVirtualBMS_config_h
 
 // Serial debug output:
-// Level 0 = none, only output init & error messages
+// Level 0 = none, only output init message
-// Level 1 = log state transitions & CAN statistics
+// Level 1 = log state transitions, errors & CAN statistics
 // Level 2 = log CAN frame dumps (10 second interval)
 #define TWIZY_DEBUG_LEVEL         1