Twizy-Virtual-BMS/API.md

API & Usage

Hint: begin with the "Template" example to get a standard usage template including all callbacks.

Library inclusion

1. Create a TwizyVirtualBMS object (twizy is a good name for this)
2. Call twizy.begin() in your setup function
3. Call twizy.looper() in your main loop:

   #include "TwizyVirtualBMS_config.h"
   #include "TwizyVirtualBMS.h"
   
   TwizyVirtualBMS twizy;
   
   void setup() {
     Serial.begin(115200);
     twizy.begin();
   }
   
   void loop() {
     twizy.looper();
   }
   

Twizy control functions

Note: all control functions validate their parameters. If you pass any value out of bounds, nothing will be changed, an error message will be generated on the serial port and the function will return false.

• bool setChargeCurrent(int amps) -- Set battery charge current level

  • amps: 0 .. 35 A current level at battery
  • will stop charge if set to 0 while charging
  • Note: this has a 5 A resolution rounded downwards
  • Note: 35 A will not be reached with current charger generation (max ~32 A)

    Current level	Power drawn from socket
    35 A	~ 2.2 kW
    30 A	~ 2.1 kW
    25 A	~ 1.7 kW
    20 A	~ 1.4 kW
    15 A	~ 1.0 kW
    10 A	~ 0.7 kW
    5 A	~ 0.4 kW

• bool setCurrent(float amps) -- Set momentary battery pack current level

  • amps: -500 .. +500 (A, positive = charge, negative = discharge)

• bool setCurrentQA(long quarterAmps) -- Set momentary battery pack current level

  • quarterAmps: -2000 .. +2000 (1/4 A, positive = charge, negative = discharge)
  • This is the native BMS current resolution, so no float/division necessary

• bool setSOC(float soc) -- Set state of charge

  • soc: 0.00 .. 100.00 (%)
  • Note: the charger will not start charging at SOC=100%

• bool setPowerLimits(unsigned int drive, unsigned int recup) -- Set SEVCON power limits

  • drive: 0 .. 30000 (W)
  • recup: 0 .. 30000 (W)
  • Note: both limits have a resolution of 500 W and will be rounded downwards
  • Note: these limits do not apply if the SEVCON has been configured to ignore them

• bool setSOH(int soh) -- Set state of health

  • soh: 0 .. 100 (%)

• bool setCellVoltage(int cell, float volt) -- Set battery cell voltage

  • cell: 1 .. 14 (the original Twizy battery has 14 cells)
  • volt: 1.0 .. 5.0
  • Note: this does no implicit update on the overall pack voltage

• 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

• bool setModuleTemperature(int module, int temp) -- Set battery module temperature

  • module: 1 .. 7 (the original Twizy battery is organized in 7 modules)
  • temp: -40 .. 100 (°C)
  • Note: this does no implicit update on the overall pack temperature

• 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)

• bool setError(unsigned long error) -- Set display error/warning indicators

  • error: 0x000000 .. 0xFFFFFF (0 = no error) or use a bitwise ORed combination of…

    Code	Description
    TWIZY_OK	Clear all indicators
    TWIZY_SERV	Set SERV indicator
    TWIZY_SERV_12V	Set SERV + 12V battery indicator
    TWIZY_SERV_BATT	Set SERV + 12V main battery indicator
    TWIZY_SERV_TEMP	Set SERV + temperature indicator
    TWIZY_SERV_STOP	Set SERV + STOP indicator + beep

User callback registration

To hook into the control flow you may register custom functions to be called by the VirtualBMS.

All callbacks are optional. See "Template" example for code templates and example attachment.

• void attachEnterState(TwizyEnterStateCallback fn)

  • fn: void fn(TwizyState currentState, TwizyState newState)
  • called on all state transitions after framework handling
  • use this to apply custom settings on state changes

• void attachCheckState(TwizyCheckStateCallback fn)

  • fn: bool fn(TwizyState currentState, TwizyState newState)
  • called before transitions from Init, Start… and Stop… into Ready, Driving, Charging and Trickle
  • if the callback returns false, the transition will be retried on the next 10 ms ticker run
  • use this to check if the battery/BMS is ready for the state transition

• void attachTicker(TwizyTickerCallback fn)

  • fn: void fn(unsigned int clockCnt)
  • called by the 10 ms ticker after framework handling, i.e. after sending the Twizy CAN frames
  • clockCnt: cyclic 10 ms interval counter range 0 … 2999 (reset to 0 on Off/Init)
  • use this to add custom CAN sends or do periodic checks

• void attachProcessCanMsg(TwizyProcessCanMsgCallback fn)

  • fn: void fn(unsigned long rxId, byte rxLen, byte *rxBuf)
  • called on all received (filtered) CAN messages
  • see setCanFilter() for setup of additional custom CAN ID filters

State machine

The VirtualBMS will do state transitions automatically based on CAN input received from the Twizy.

TwizyStates:

• Off
• Init
• Error
• Ready
• StartDrive
• Driving
• StopDrive
• StartCharge
• Charging
• StopCharge
• StartTrickle
• Trickle
• StopTrickle

Normal startup procedure involves the wakeup phase Init followed by Ready. Depending on the mode of operation requested, this will be followed by one of the Start… states with operation mode established resulting in the according …ing state.

The shutdown procedure begins with a transition from the …ing state to the according Stop… state, followed by Ready and finally Off.

Use the Error state to signal severe problems to the Twizy and cause an emergency shutdown. Error turns off CAN sends and drops the 3MW (ECU_OK) signal. SEVCON and charger will switch off all battery power immediately. To resolve the Error state from driving, the user needs to do a power cycle. When used during a charge, the charger will send the BMS into Off state, so the charge can simply be restarted by replugging the charger.

Note: to indicate non-critical problems, do not enter the Error state but instead only use setError().

See protocol documentation for details.

API:

• TwizyState state() -- Query current state
• bool inState(TwizyState state1 [, … state5]) -- Test for 1-5 states
• void enterState(TwizyState newState) -- Force a state change
  • Call enterState(StopCharge) to stop a running charge process. Note that setChargeCurrent(0) will do so as well.
  • Call enterState(Error) to cause an emergency shutdown. Before doing this you should use setError() and (if possible) give the user some time to react when in state Driving.

Callbacks:

• Before entering states Ready, Driving, Charging and Trickle from any other state, the user callback CheckState() will be called. Exception is entering Ready from Error, this needs to be done manually anyway (don't expect SEVCON or charger to follow though).
• After any state transition, the user callback EnterState will be called.

CAN interface access

To hook into the CAN receiver, use attachProcessCanMsg() (see above).

Standard filters will pass IDs 0x423, 0x597 and 0x599. Three free CAN filters can be used. The mask is fixed to match the whole ID, so you can filter at most three additional IDs at a time.

• void setCanFilter(byte filterNum, unsigned int canId) -- Set a free ID filter

  • filterNum: 1 … 3
  • canId: 11 bit CAN ID i.e. 0x196

• bool sendMsg(INT32U id, INT8U len, INT8U *buf) -- Send a CAN message

  • Note: will do three retries if TX buffers are full.
  • Returns true if message has been sent, false on error.
  • Retry and error counts are logged every 10 seconds if debug logging is enabled.

Debug utils

• void dumpId(FLASHSTRING *name, int len, byte *buf) -- Dump a byte buffer in hex numbers

  • name: must be a PROGMEM string, i.e. dumpId(F("id123"), ...)

• void debugInfo() -- Dump VirtualBMS status, include frame buffers if debug level >= 2

  • this is automatically called every 10 seconds if debug level >= 1