release wed dec 13 13:39:20 2017 utc · foxbms, release wed dec 13 13:39:20 2017 utc welcome to...

foxBMSRelease Wed Dec 13 13:39:20 2017 UTC

Dec 13, 2017

General information

1 Versions and Release Notes 31.1 Release 0.4.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Release 0.4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Release 0.4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Release 0.4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.5 Release 0.4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Licenses 52.1 foxBMS Software License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 foxBMS Hardware and Documentation License . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Motivation 73.1 What is foxBMS? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 What is foxBMS designed for? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.3 Who is the intended audience? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4 Overview of Hardware and Software 9

5 Roadmap 11

6 The foxBMS Team 136.1 Management Team Fraunhofer IISB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136.2 Development Team Fraunhofer IISB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136.3 Student Team Fraunhofer IISB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

7 Getting started with foxBMS 157.1 How to use this documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157.2 How to generate the HTML documentation and set up foxBMS rapidly . . . . . . . . . . . . . . 157.3 Where can the layout and schematic files be found? . . . . . . . . . . . . . . . . . . . . . . . . . 15

8 Getting Started with the Software 178.1 Installation of the needed software via the foxConda distribution . . . . . . . . . . . . . . . . . . 178.2 Configuration, Compilation and Flashing with the Graphical User Interface . . . . . . . . . . . . 20

9 Getting Started with Flashing 299.1 Convention for Connector Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299.2 Hardware Setup of foxBMS Master Unit and foxBMS Slave Units . . . . . . . . . . . . . . . . . 299.3 Supply of the foxBMS Master Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309.4 Primary and Secondary MCU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319.5 Flash the Compiled Source for the Primary MCU . . . . . . . . . . . . . . . . . . . . . . . . . . 319.6 Flashing the Secondary MCU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359.7 Debugging the Primary and Secondary MCU . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

i

10 Getting Started with the Hardware: Connecting foxBMS 3710.1 Convention for Connector Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3710.2 Global Description of the foxBMS Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3810.3 Detailed Description of the Hardware Parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3810.4 Use of foxBMS in a Battery System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4110.5 Hardware Setup of the BMS-Master board and the BMS-Slave board . . . . . . . . . . . . . . . 4110.6 Communication with the BMS-Master board . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5110.7 Current Sensor Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5110.8 Hardware Related Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

11 Hardware Specifications 5311.1 Electrical Ratings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5311.2 Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5311.3 Supply (X201 on BMS-Master board) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5411.4 CAN_0 (X801 on BMS-Master board) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5511.5 CAN_1 (X801 on BMS-Extension board) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5511.6 Isolation Monitor (Bender ISOMETER) (X701 on BMS-Master board) . . . . . . . . . . . . . . 5511.7 Contactors (X1201 - X1206 on BMS-Master board and X1201 - X1203 on BMS-Extension board) 5611.8 Interlock (X901 on BMS-Master board) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5611.9 Daisy Chain - Primary and Secondary (X1601 on BMS-Master board) . . . . . . . . . . . . . . . 5611.10 RS485 (X1301 on BMS-Extension board) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5711.11 Isolated GPIO (X1901 on BMS-Extension board) . . . . . . . . . . . . . . . . . . . . . . . . . . 5711.12 Isolated normally open contacts - isoNOC (X2001 on BMS-Extension board) . . . . . . . . . . . 5811.13 Analog Inputs (X1701 on BMS-Master board) . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

12 Communication via CAN 6112.1 CAN Matrix Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

13 Hardware-Software Quickcheck Guide 7113.1 Required Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7113.2 Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7213.3 Test Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

14 Software File Structure 75

15 Software Components 7715.1 Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7715.2 Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7715.3 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7815.4 HAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7815.5 Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7815.6 OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

16 Basic Function of the BMS Software 8116.1 Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8116.2 Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8116.3 Diagnostic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8416.4 User Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

17 Software Toolchain 85

18 Important Software Modules 8718.1 BMS Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8718.2 System Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9018.3 IO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9518.4 Contactor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9618.5 CAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9818.6 CAN Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10518.7 LTC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

ii

18.8 COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11418.9 UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11518.10 Checksum Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11618.11 SOX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11718.12 Isoguard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

19 Advanced Software Topics 127

20 Software FAQ and HOWTOs 12920.1 How to create a task and change its priority and period? . . . . . . . . . . . . . . . . . . . . . . 13020.2 How to add a software module and take it into account with WAF . . . . . . . . . . . . . . . . . 13220.3 How to change the multiplexer measurement sequence for the LTC driver? . . . . . . . . . . . . 13220.4 How to change the relation between voltages read by multiplexer via LTC6804-1/LTC6811-1 and

temperatures? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13320.5 How to configure the MCU clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13320.6 How to configure the LTC6804-1/LTC6811-1 and SPI clocks? . . . . . . . . . . . . . . . . . . . 13420.7 How to configure the CAN clock? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13420.8 How to configure and drive I/O ports? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13520.9 How to add and configure interrupts? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13620.10 How to add a database entry and to read/write it? . . . . . . . . . . . . . . . . . . . . . . . . . . 13720.11 How to store data in the backup SRAM of the MCU . . . . . . . . . . . . . . . . . . . . . . . . 13820.12 How to manually add CAN entries (transmit and receive) and to change the transmit time period? 13820.13 How to programmaticaly generate CAN entries? . . . . . . . . . . . . . . . . . . . . . . . . . . 13920.14 How to change the blink period of the indicator LEDs? . . . . . . . . . . . . . . . . . . . . . . . 13920.15 How to add an entry for the diag module? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14020.16 How to configure contactors without feedback? . . . . . . . . . . . . . . . . . . . . . . . . . . . 14120.17 How to simply trigger events via CAN? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14120.18 How to start/stop balancing the battery cells? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14120.19 How to set the initial SOC value via CAN? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14220.20 How to add/remove temperature sensors? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14220.21 How to change the resolution of the temperature values stored? . . . . . . . . . . . . . . . . . . 14420.22 How to use and disable the checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

21 Tools used for foxBMS 14721.1 Checksum Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

22 Build 14922.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14922.2 Obtaining the sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14922.3 Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

23 Hardware Description 15123.1 Supply 0 (primary) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15123.2 Supply 1 (secondary) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15223.3 MCU0 (primary) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15223.4 Interface between MCU0 and MCU1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15223.5 Interface to Bender ISOMETER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15523.6 CAN_0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15523.7 Interlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15523.8 Contactors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15723.9 Isolated USB interface (primary and secondary) . . . . . . . . . . . . . . . . . . . . . . . . . . 15823.10 EEPROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15823.11 Isolated RS485 Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15823.12 Isolated Normally Open Contacts (isoNOC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16023.13 Analog Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16023.14 Isolated GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16123.15 SD Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

24 PCB Schematics and Layouts 163

iii

24.1 BMS-Master board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16324.2 BMS-Extension board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16324.3 BMS-Interface board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16324.4 BMS-Slave board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

25 Recommended Additional Hardware 16525.1 Isolation Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16525.2 Power Contactors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16525.3 Current Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16525.4 DC Battery Pack Fuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

26 Example of a Battery Junction Box 16726.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16726.2 Battery Junction Box Part List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16826.3 Main and Precharge Contactors Wiring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17026.4 Insulation Monitor Wiring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17026.5 Current Sensor Wiring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17026.6 Summary of the Assembly Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

27 Hardware Toolchain 17327.1 Layout and schematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17327.2 Information on Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Bibliography 175

iv

foxBMS, Release Wed Dec 13 13:39:20 2017 UTC

Welcome to the foxBMS documentation of the first modular open source BMS development platform from theFraunhofer IISB. foxBMS is a free, open and flexible development environment to design state-of-the-art complexbattery management systems. The current version of foxBMS is 0.4.4 (more information in Versions andRelease Notes).

Note: The foxBMS hardware and software is still under development. The free and open research and develop-ment platform foxBMS is not designed to be used as-is in road vehicles or in a production environment or anysimilar usage: it is for evaluation only.

First, general information about foxBMS can be found (General information):

• Information about the versions and release notes (Versions and Release Notes)

• Licenses

• Motivation

• Overview (purpose and intended audience)

• Roadmap

• Who made it

Then the getting started guide (Getting started) allows starting foxBMS rapidly:

• The location of the electronic schematic and layout files in the HTML documentation is indicated

• The hardware guide describes how the hardware is structured and works

• The software guide explains how to configure and flash the software

• The CAN documentation shows how to communicate with the system via the CAN bus

To study and modify the software, the software documentation (Software documentation) then explains the struc-ture of the software and of the most import modules, how the basic tasks run and how to call user-defined functionseasily. A FAQ answers the most common questions. A detailed description of the software functions and variablescan be found in the Doxygen documentation.

Finally, the hardware documentation (Hardware documentation) gives the details needed to understand thefoxBMS hardware.

General information 1

https://www.foxbms.org/

http://www.iisb.fraunhofer.de/


2 General information

CHAPTER 1

Versions and Release Notes

The following table describes the different versions of foxBMS that were released. The first line is the most recentone, the last one the oldest one.

DocumentationEmbedded Software foxBMS Hardware foxCondaPri-mary

Sec-ondary

BMS-Masterboard

BMS-Interfaceboard

BMS-Slaveboard

BMS-Extensionboard

0.4.4 0.4.4 0.4.4 1.0.1 1.0.1 1.0.1 1.0.1 0.4.30.4.3 0.4.3 0.4.3 1.0.0 1.0.0 1.0.0 1.0.0 0.4.30.4.2 0.4.2 0.4.2 1.0.0 1.0.0 1.0.0 1.0.0 0.4.00.4.1 0.4.1 0.4.1 1.0.0 1.0.0 1.0.0 1.0.0 0.4.00.4.0 0.4.0 0.4.0 1.0.0 1.0.0 1.0.0 1.0.0 0.4.0

The following section summarizes the release notes for the different versions of the documentation.

1.1 Release 0.4.4

Release notes:

• Full update and correction of the documentation based on the feedback received

• Consistency check and update of the wording and naming used in the hardware, software and documentation

• Improved checksum process

– faster implementation of checksum script

– checksum script is called automatically after “python tools/waf-1.8.12 configure build”

– build command “python tools/waf-1.8.12 configure build chksum” NO longer supported

1.2 Release 0.4.3

Starting from this version, a checksum mechanism was implemented in foxBMS. If the checksum is active and itis not computed correctly, it will prevent the flashed program from running. Details on deactivating the checksumcan be found in the Software FAQ and HOWTOs, in How to use and disable the checksum.

3


Release notes:

• Important: Changed contactor configuration order in the software to match the labels on the front

– Contactor 0: CONT_PLUS_MAIN

– Contactor 1: CONT_PLUS_PRECHARGE

– Contactor 2: CONT_MINUS_MAIN

• Fixed an bug which could cause an unintended closing of the contactors after recovering from error mode

• Increased stack size for the engine tasks to avoid stack overflow in some special conditions

• Added a note in the documentation to indicate the necessity to send a periodic CAN message to the BMS

• Fixed DLC of CAN message for the current sensor measurement

• Added checksum verification for the flashed binaries

• Updated linker script to allow integration of the checksum tool

• Activated debug without JTAG interface via USB

1.3 Release 0.4.2

Release notes:

• Removed schematic files from documentation, registration needed to obtain the files

• Added entries to the software FAQ

1.4 Release 0.4.1

Release notes:

• Corrected daisy chain connector pinout in quickstart guide

• Corrected code for contactors, to allow using contactors without feedback

• Corrected LTC code for reading balancing feedback

• Quickstart restructured, with mention of the necessity to generate the HTML documentation

1.5 Release 0.4.0

Beta version of foxBMS that was supplied to selected partners for evaluation.

4 Chapter 1. Versions and Release Notes

CHAPTER 2

Licenses

2.1 foxBMS Software License

© 2010-2017, Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. All rights reserved.

The foxBMS embedded software and computer software are licensed under the BSD 3-Clause License.

BSD 3-Clause License

Redistribution and use in source and binary forms, with or without modification, are permitted pro-vided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions andthe following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditionsand the following disclaimer in the documentation and/or other materials provided with thedistribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to en-dorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS“AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITEDTO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC-ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER ORCONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EX-EMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PRO-CUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABIL-ITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCEOR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IFADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Important: We kindly request you to use one or more of the following phrases to refer to foxBMS in yourhardware, software, documentation or advertising materials:

This product uses parts of foxBMS ®This product includes parts of foxBMS ®This product is derived from foxBMS ®

5


2.2 foxBMS Hardware and Documentation License

© 2010-2017, Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. All rights reserved.

The foxBMS hardware and documentation are licensed under the Creative Commons Attribution 4.0 International(CC BY 4.0) License. To view a copy of this license, visit CC BY 4.0.

Important: We kindly request you to use one or more of the following phrases to refer to foxBMS in yourhardware, software, documentation or advertising materials:

This product uses parts of foxBMS ®This product includes parts of foxBMS ®This product is derived from foxBMS ®

6 Chapter 2. Licenses

https://creativecommons.org/licenses/by/4.0/

CHAPTER 3

Motivation

3.1 What is foxBMS?

With foxBMS, Fraunhofer IISB delivers the first generation of its open source battery management system (BMS)research and development platform. The foxBMS platform is completely free and open, designed for a maximumof flexibility, and comprehensively documented. It includes all necessary hardware and software for potentiallyany kind of mobile and stationary application that uses modern rechargeable electrochemical energy storage sys-tems (e.g., lithium-ion batteries, redox-flow batteries, supercapacitors):

• foxBMS Hardware: the schematics and the layout of all electronic boards are available for download and thedesign is based on commonly available components and devices, that do not require NDAs or confidentialityagreements.

• foxBMS Software: the software toolchain uses only own developed open source and free of charge com-ponents or free of charge third-party software, and the entire BMS source code is provided online with itsown development environment and configuration files, thus enabling immediate use on Windows, Mac, andLinux operating systems.

3.2 What is foxBMS designed for?

Experience gained from international research and development projects over the last 15 years in the field ofelectrochemical energy storage systems at Fraunhofer IISB has been implemented in the hardware and softwareof the foxBMS platform. It is designed to manage high-performance prototypes of advanced and innovativelithium-ion battery systems of any size (i.e., from a few cells up to several hundreds of kWh and kW), especiallyfor systems requiring the highest availability and safety levels.

The free and open source version of foxBMS is not intended for immediate use in commercial products as theyhave to meet specific standards and require application-dependent certifications. In fact, foxBMS is a safe research,development, and test platform providing all functions for managing the complexity and size of state-of-the-artelectrochemical energy storage systems.

Specific adaptions of foxBMS can be ordered directly from Fraunhofer IISB or can be jointly developed, forexample for automotive, aviation, space, submarine, industrial, and renewable energy storage applications.

7


3.3 Who is the intended audience?

foxBMS is a free and open BMS platform that can be used for developing and testing products. The foxBMShardware and documentation are licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0)license. The foxBMS software is licensed under the BSD 3-Clause license. This means, foxBMS parts can beutilized unrestrictedly, including commercial use. The foxBMS platform addresses especially:

• R&D and test engineers requiring a smart and powerful, well documented BMS platform

• Engineering companies requiring a maintained and supported BMS for their developments

• Small enterprises requiring a flexible and future proof BMS for developing their products

• Large enterprises requiring a reliable and safe BMS for testing their prototypes

• Research organizations requiring a simple and universal BMS development platform

• Students looking for a free and open BMS software development toolchain

8 Chapter 3. Motivation

CHAPTER 4

Overview of Hardware and Software

The foxBMS Master Unit consists of 3 boards: BMS-Master board, BMS-Interface board, BMS-Extension board.Two ARM-based microcontroller units (Cortex-M4) are used on BMS-Master board: MCU0 (also called primaryMCU) and MCU1 (also called secondary MCU). The BMS software runs on MCU0, while MCU1 is used forredundant safety.

MCU0 communicates with the outside world via a CAN bus. The current flowing through the battery system ismeasured via a current sensor connected via the CAN bus. The sensor is controlled via CAN by MCU0 and sendsthe resulting measurement via CAN.

The foxBMS Slave Unit (BMS-Slave board) are used to measure cell voltages and cell temperatures in the batterymodules. The foxBMS Slave Units are linked via a proprietary daisy chain from the company Linear Technology(i.e., isoSPI).

In order for the foxBMS Master Unit to communicate with the foxBMS Slave Units, an interface board (i.e.,BMS-Interface board) is needed. It converts the SPI signals from the BMS-Master board into differential signalsused by the daisy chain and vice versa.

Three power contactors are used to connect and disconnect the battery modules (or pack) from the load:

• Main Contactor Plus

• Main Contactor Minus

• Pre-charge contactor

These contactors are driven by MCU0. Requests are made via CAN to the system to open and close the contactors.Based on the measurements and the algorithms implemented in the software, MCU0 decides if the contactorsshould be closed or opened. It sends information via CAN so that the user knows the state of the system.

An interlock line is also present. If it is opened, either by MCU0, MCU1 or somewhere else (e.g., emergencystop), all contactors will immediately open.

A secondary ARM-based microcontroller is present on the master, called MCU1 (or secondary MCU). It monitorsthe slaves via a second and separate daisy chain. Like the MCU1, it can open the interlock in case something goeswrong with the system.

In case more inputs and outputs and further functions are required, an BMS-Interface board is available and canbe easily adapted to specific needs.

This description reflects the current state of foxBMS. Due to the open nature of the system, many other possibilitiescan be implemented, like for example:

• Use of other types of current sensors (e.g., shunt-based or Hall-effect based)

9


• No foxBMS Slave Unit needs to be used: a direct measurement of the cell voltages and cell temperaturescan be performed by the foxBMS Master Unit

• A higher number of contactors can be controlled (e.g., up to 9)

• etc...

10 Chapter 4. Overview of Hardware and Software

CHAPTER 5

Roadmap

The following table gives the roadmap for the coming features of foxBMS. Please note that the priority can changeanytime.

Category Product/Service/Feature Free Notfree

Earliestschedule

Re-leased

Environment Eclipse project files for easier code parsingand development

X Q2 2017

foxConda Linux support X Q2 2017EmbeddedSoftware

Code cleanup for more comprehensivestructure

X Q2 2017

BMS-Masterboard

Migration of MCU0 and MCU1 fromCortex-M4 to Cortex-M7

X Q3 2017

BMS-Slaveboards

15 battery cells support X Q3 2017

BMS-Slaveboards


BMS-Slaveboards

12/15/18 battery cells support with active cellbalancing

X Q3 2017

BMS-Extensionboard

Onboard CAN-to-USB adapter for directlogging

X Q4 2017

BMS-Extensionboard

Raspberry Pi connection and Ethernet support X Q4 2017

EmbeddedSoftware

Support for interconnection of multipleBMS-Master board

X Q1 2018

BMS-Slaveboards


BMS-Masterboard

Fast charging with CCS support X Q3 2018

11


12 Chapter 5. Roadmap

CHAPTER 6

The foxBMS Team

6.1 Management Team Fraunhofer IISB

Vincent Lorentz Project Initiator and Technical MarketingStéphane Koffel Project Management and CoordinationMartin März Technical ConsultingJürgen Lorenz Licenses and Legal ConsultingLothar Frey Technical Marketing and Legal Consulting

6.2 Development Team Fraunhofer IISB

Martin Wenger Hardware Team Coordination, Hardware DevelopmentStéphane Koffel Software Team Coordination, Algorithm DevelopmentMüsfik Akdere Technical Lead Embedded SoftwareTim Fühner Technical Lead Software, Algorithm DevelopmentMartin Giegerich Software DevelopmentStefan Waldhör Software DevelopmentJohannes Wachtler Software DevelopmentChristian Freund Software Configuration ManagementRadu Schwarz Hardware DevelopmentSebastian Wacker Hardware DevelopmentJoshua Grosch Hardware DevelopmentMarkus Gepp Mechanical ConstructionReinhold Waller Validation and Tests

6.3 Student Team Fraunhofer IISB

Robin Heim Hardware and Software DevelopmentChristian Thomas Software DevelopmentLucas Grunenberg Software DevelopmentPauline Thierauf Documentation

[email protected]

13

mailto:[email protected]


14 Chapter 6. The foxBMS Team

CHAPTER 7

Getting started with foxBMS

7.1 How to use this documentation

The complete foxBMS documentation is available and maintained in HTML, PDF and EPUB formats.

Note: A search function is available under the foxBMS logo in the HTML version of the documentation.

7.2 How to generate the HTML documentation and set up foxBMSrapidly

First, the software getting started guide explains how to generate the complete HTML generation and how toconfigure the software. Then, the flashing getting started guide explains how to supply the hardware and how toflash the foxBMS program on MCU0 and MCU1 located on the BMS-Master board in the foxBMS Master Unit.

If these steps are done, foxBMS already runs. The last step is longer because connectors must be made. In thislast step, it is explained how to prepare the other parts of the foxBMS hardware.

7.3 Where can the layout and schematic files be found?

The layout and schematic are available in the HTML documentation in the section Hardware documentation, inPCB Schematics and Layouts.

15


16 Chapter 7. Getting started with foxBMS

CHAPTER 8

Getting Started with the Software

The foxBMS software consists of a program written in C. Before it can be flashed and run on the microcontrollerunits (i.e., MCU0 and MCU1 located on the BMS-Master board), it must be compiled to generate a binary file.

Different softwares (i.e., the software toolchain) are needed for this compilation step. They are based on a Pythonenvironment. All the needed software, including the Python environment, are contained in a Python distributioncalled foxConda. It will be installed in the next steps.

In addition, some parameters can be adjusted in the sources before compilation, to change the behavior of the soft-ware. A graphical environment is provided to simplify all theses tasks (i.e., configuration, compilation, flashing).

This section shows how to:

1. Set up the development environment, foxConda (the software toolchain)

2. Launch the graphical development tool

3. Configure the foxBMS source

4. Compile the foxBMS source

In the section Getting Started with Flashing, it is shown how the compiled sources are flashed on the foxBMSMaster Unit.

8.1 Installation of the needed software via the foxConda distribu-tion

The first step is to install the software environment needed to compile and flash the foxBMS sources. First, thefoxConda installer must be run by executing foxcondainstaller-0-4-3.exe.

The window shown in fig. 8.1 will appear.

On this window, the foxBMS webpage can be accessed by clicking on the link in blue.

Then by clicking on Next > the license shown in fig. 8.2 is displayed.

To continue, the license terms must be accepted (check I accept the terms) before clicking on Next >.

An installation directory must be selected fig. 8.3.

A default location is proposed, which can be changed. Clicking on Next > starts the installation as shown in fig.8.4. This step can take several minutes.

17


Fig. 8.1: Installer start page

Fig. 8.2: Installer license terms

18 Chapter 8. Getting Started with the Software


Fig. 8.3: Installation path for the Front Desk environment

Fig. 8.4: Installation progress

8.1. Installation of the needed software via the foxConda distribution 19


The login credentials may be asked to generate start menu and desktop shortcuts for the development tools.

Once the installation is complete, the message shown in fig. 8.5 appears.

Fig. 8.5: Installation end

Here, it can be chosen to launch the foxBMS Front Desk—the graphical user interface that configures, builds andflashes the software—immediately after finishing the installation.

If shortcuts were created, they can be used to start the Front Desk or a terminal environment.

To start the Front Desk manually, it must be navigated to the FOXCONDA\Scripts directory, where FOXCONDAis the installation directory of the foxConda distribution, for example, C:\Users\Me\foxconda. After theprogram, called foxbms.exe was found, a double click on it will launch it.

In addition, if it is preferred to build foxConda from the command line, the convenience terminal environment canbe used by executing fbterminal.exe, which is also located under FOXCONDA\Scripts. It will open aCMD window with a PATH environment ready to configure, compile and flash foxBMS.

8.2 Configuration, Compilation and Flashing with the GraphicalUser Interface

The foxBMS configuration and flash IDE is started with foxbms.exe as described in the previous section.

When the program starts, a terminal window appears. This is normal. It will dissapear when the program is closed.

8.2.1 Select the sources

The IDE starts with the source selection tab shown in fig. 8.6.



Fig. 8.6: Project selection tab

8.2. Configuration, Compilation and Flashing with the Graphical User Interface 21


A project corresponds to the foxBMS source code tree located on the computer. A folder must be created were theprojects will be stored. First, the foxBMS workspaces directory must be clicked on to select the folderthat was created, under which all the new foxBMS projects will be placed.

If an archive was provided, next, the latest foxBMS release source code archive must be fetched and placedat a convenient folder. Clicking on the Add from archive button allows opening the archive. Thearchive must not be extracted, this is done by the IDE. For the quickstart guide, the archive is calledfoxbms_primary-0-4-4.tar.gz. The source tree will be extracted into the workspace directory, and theproject will be added to the list of available projects, as shown in fig. 8.7.

Fig. 8.7: Project selection tab, one project added

An existing source tree directory can also be added, which, for example, was downloaded from GitHub andmanually unpacked. The button Add from existing directory must be used. The folder will not becopied to the workspace directory. It will only be linked to the list of available directories. This possibility is notused in the quickstart guide.

8.2.2 Generate complete HTML documentation and code reference

The Sphinx documentation available on ReadTheDocs is included as RST files and can be generated. A projectfrom the Available projects list must be selected by clicking on it. The project that has just been createdmust be selected. It will be highlighted in the list. Then it must be initialized by clicking on Initializeproject. During the initialization, the project is configured for the current development environment, andthe documentation is generated, including the complete HTML documentation and the code reference. Oncegenerated, the documentation can be accessed fronm the interface in the Help menu. The complete HTMLdocumentation can then be accessed directly by pressing F1, too.

During initialization, some terminal windows may open. They will close automatically. It must be noted that



the last column in the projects list shows if a project has been successfully initialized. A project can always bere-initialized, for example, if the foxConda environment has been upgraded or the documentation modified. Foran already initialized project, the initialization button reads Re-initialize project.

The result of the initialization procedure is displayed in the Output area. The Clear button can be pressed toclean the output sub-window.

8.2.3 Configure the Code

After the selected project has been initialized, it can be proceeded to the Configuration page, shown in fig.8.8.

Fig. 8.8: Configuration tab

It must be noted that selecting the configuration page is not possible as long as the selected project has not beeninitialized.

The different areas of the window can be resized with the mouse. For instance, it is useful to make the propertyarea bigger for a better visibility.

The behavior of foxBMS can be adapted to the requirements and needs through a number of configuration vari-ables. For that purpose, a configuration method called Foxygen was developed. Configuration variables arequalified within the source through annotations. The configuration engine displayed on this page compiles a listof such variables and displays them. This may take a few seconds.

The properties are divided into five different categories that can be selected by clicking on the respective icon:

1. User: standard configuration for the BMS (e.g., number of battery modules, number of cells per module,battery cell capacity)



2. Advanced: advanced configuration for the BMS (e.g., clock timings)

3. Devel: configuration for user modifying the source code

4. Debug: configuration needed for user debugging the source code

5. Read-only: parameters shown as information

Underneath the property list, a description for each item can be found. Different types of parameters can bedistinguished:

• Numeric value (integer of floating point number)

• True or False

• Activated or Deactivated

• A list of options

If the property expects a numerical value, a range of validity is typically given. It can be found in the descriptionwindow. If a value outside of the permitted range is entered, the entry appears in red, as shown in fig. 8.9.

Fig. 8.9: Configuration tab, incorrect parameter value

Fig. 8.10 shows an example for a list of options to choose from.

To modify the sources according to the configuration settings, the Write Configuration to Filesbutton must be pressed. The modifications will be lost if another page is selected without pressing WriteConfiguration to Files. The default values of all parameters can be restored by the Reset allvalues to default button.

Note: The Write Configuration to Files button must also be pressed after a reset, to proceed building



Fig. 8.10: Configuration tab, multiple choice parameter



an unmodified foxBMS instance.

The current configuration can be saved (no matter if it was written to the source files or not) by clicking on SaveConfiguration. To restore a previously saved configuration, Load Configuration must be chosen. It isimportant not to forget to select Write Configuration to Files. For the quickstart, it is not necesary touse this save/load feature.

8.2.4 Build Configured Sources

After configuration, the firmware can be build by proceeding to the next page Build foxBMS (see fig. 8.11).There the Build foxBMS button must be pressed.

Fig. 8.11: Build tab

During the build process, some terminal windows may open. They will close automatically.

The result of the compilation can be found in the Output pane.

The next step is to flash the sources on the foxBMS Master Unit.

8.2.5 Software Related Frequently Asked Questions

Where are the sources?

Once a foxBMS archive has been imported in Front Desk, they are automatically extracted and copied on disk.



What libraries and programs must be installed?

None, because they are installed with the foxConda installer.


CHAPTER 9

Getting Started with Flashing

This section describes how to supply the foxBMS Master Unit in order to flash compiled sources.

This section shows how to connect the different parts of the foxBMS.

9.1 Convention for Connector Numbering

Fig. 9.1 presents the convention for the connector numbering. It is used throughout the documentation.

Fig. 9.1: Supply connector pin out, receptable - rear view, header - front view (image source: MOLEX)

There are two types of connectors:

• Header

• Receptable, plugged into the header

The numbering shown on the left in fig. 9.1 is always valid when viewing in the direction indicated by the arrowwith the indication viewing direction. This must be taken into account when crimping the receptables.

9.2 Hardware Setup of foxBMS Master Unit and foxBMS Slave Units

The foxBMS system can be mounted in a metal housing, as shown in fig. 9.2.

29


Fig. 9.2: foxBMS Master Unit housing

Connectors are available, shown in Fig. 9.3, which presents all the connectors of the foxBMS Master Unit.

Fig. 9.3: Front view of the foxBMS Master, indicating the location of each header

For this section on flashing, only the connector “Supply” is needed.

9.3 Supply of the foxBMS Master Unit

The first step is to supply the foxBMS Master Unit, which works with supply voltages between 12 and 24V DC.To supply the foxBMS Master Unit, a connector must be prepared for the Supply connector as shown in table9.1, which describes the different pins used.

30 Chapter 9. Getting Started with Flashing


Table 9.1: BMS-Master board Supply Connector

Pin Signal Input/Output Description1 SUPPLY_EXT_2 Input 12 - 24V2 SUPPLY_EXT_2 Input 12 - 24V3 GND_EXT_2 Input GND4 SUPPLY_EXT_0 Input 12 - 24V5 GND_EXT_0 Input GND6 GND_EXT_2 Input GND

The supply is separated as follows:

• With pins SUPPLY_EXT_0 and GND_EXT_0, the microcontroller and the isolation devices are supplied

• With SUPPLY_EXT_2 and GND_EXT_2, the contactors and the interlock are supplied

To power up the foxBMS Master Unit, plug in the supply connector and apply a voltage between 12 and 24V.SUPPLY_EXT_0 / GND_EXT_0 and SUPPLY_EXT_2 / GND_EXT_2 may be connected to the same source forthis initial test. At this point, the foxBMS Master Unit should draw approximately 150mA at 12V or 110mA at24V.

9.4 Primary and Secondary MCU

The BMS-Master board has two MCUs: primary (MCU0) and secondary (MCU1). The secondary MCU is presentto ensure redundant safety especially in prototyping applications.

First, the primary MCU will be flashed.

In order to program the primary MCU, the mini USB jack indicated as Prim. USB in fig. 9.3 must be used toconnect the foxBMS Master Unit to a PC. The foxBMS Master Unit can be connected to a PC immediately. Whenconnecting foxBMS Master Unit for the first time, the required drivers will install automatically. After the drivershave been installed, the USB cable should be disconnected from the computer before going on with the quickstartguide.

Note: Before the connection is made between the foxBMS Master Unit and the computer for the first time, thecomputer must be connected to the internet, because the operating system might look for drivers on the internet.It this fails, administrators right are needed to install the driver.

In case of problems by the installation of the drivers, administrator rights might be needed. Once the hardware issupplied, the foxBMS binaries can be flashed.

The same procedure must be made for secondary: the mini USB jack indicated as Sec. USB in fig. 9.3 mustbe used to connect the foxBMS Master Unit to a PC. As for the primary MCU, the PC must be connected to theinternet before the connection is made with the foxBMS Master Unit.

9.5 Flash the Compiled Source for the Primary MCU

In the section Getting Started with the Software, the foxBMS sources have been compiled and the generated binaryis ready to be flashed. As the archive foxbms_primary-0-4-4.tar.gz was used, the sources are made forthe MCU0: the MCU0 will be flashed first.

These binaries are needed:

9.4. Primary and Secondary MCU 31


1. a binary file with the header and

2. a binary file with the main code.

Unless the build process has been altered or different binaries should be flashed, there is no need to change thedefault file locations.

For the quickstart, the default file locations are used.

First, when no device is connected, No device found. is displayed, as shown in fig. 9.4. The flash button isdeactivated.

Fig. 9.4: Flashing tab, no device connected

The device must be connected to the computer with the USB cable. The MCU0 must be used. In the GettingStarted with the Hardware: Connecting foxBMS, it is explained how to find the MCU0 and where the primaryUSB connector is located.

Once a device was connected and detected, Device found. is displayed and the flash button becomes active,as shown in fig. 9.5.

When the flash button is clicked, a windows appears, reminding not to touch the device that is being flashed, asshown in fig. 9.6.

The connection state can also be checked by watching the LEDs on the foxBMS Master Unit hardware: for arunning board, the green power LED is on, and the two indicator LEDs (green and red) are blinking alternately. Ifthe device is connected and being flashed, the power-on LED is on but the two indicator LEDs are off.

The LEDs for the MCU0 must be used. In the Getting Started with the Hardware: Connecting foxBMS, it isexplained how to find the MCU0 indicator LEDs.



Fig. 9.5: Flashing tab, device connected

9.5. Flash the Compiled Source for the Primary MCU 33


Fig. 9.6: Flashing tab, device connected, flashing



Note: After connecting the device and before flashing, if clicking on the flash button has no effect even if Devicefound. is displayed, disconnecting and connecting the device should solve the problem.

When the flashing is complete, the flashing windows disappears and the indicator LEDs start to blink again.

Under Windows 7 (64 bit),it can happen that the COMPORT number is increased by Windows,leading to problems during flashing. This can be reset in registry, by setting ComDB to zeroin the entry HKEY_LOCAL_MACHINE::SYSTEM::CURRENT_CONTROL_SET::CONTROL::COM NAMEARBITER. This way, all COM ports used are reset.

9.6 Flashing the Secondary MCU

A source code archive is provided to flash the secondary MCU, called foxbms_secondary-0-4-4.tar.gz.The same procedure as explained above must be followed with this archive, with the following differences:

• A second project must be created in the IDE

• The secondary MCU must be flashed with the USB connector corresponding to secondary.

With the supplied code, the MCU1 checks the temperatures and voltages. If one or more of the values are outsidethe limits, the MCU1 opens the interlock line (thus opening the contactors). The interlock line remains open untilthe MCU1 is reset.

Before the flashing procedure, the limits can be set via the configuration page of the graphical user interface, asshown previously.

Note: Setting these limits is safety relevant and must be done with care.

If the user wishes to work without these protection, to experiment more easily, this can be changed in the filebmsctrl_cfg.h by setting

#define BMSCTRL_TEST_CELL_LIMITS TRUE

to

#define BMSCTRL_TEST_CELL_LIMITS FALSE

Note: Working without configuring the right battery cell voltage limits is dangerous and should never bedone when real batteries are connected, since they may burn and explode when overcharged or shorted.

The next step is to connect a foxBMS Slave Unit to perform voltage and temperature measurement.

9.7 Debugging the Primary and Secondary MCU

The following two debuggers can be used for debugging foxBMS and are used by the foxBMS team.

• Segger J-Link Plus, with the 19-Pin Cortex-M adapter (needed to connect to foxBMS)

• Lauterbach µTrace Debugger for Cortex-M

9.6. Flashing the Secondary MCU 35

https://www.segger.com/j-link-plus.html

https://www.segger.com/jlink-adapters.html#CM_19pin

http://www.lauterbach.com

CHAPTER 10

Getting Started with the Hardware: Connecting foxBMS

In the preceeding sections, the foxBMS Master Unit has been supplied and the foxBMS firmware flashed on it.

This section describes the foxBMS hardware in more details and how to connect the foxBMS Master Unit to thefoxBMS Slave Units that perform the cell voltage and temperature measurements. The CAN communication isalso described.

Note: When the connection is made between the foxBMS Master Unit and the foxBMS Slave Units, both primaryand secondary isoSPI daisy chains have to be connected.

10.1 Convention for Connector Numbering

Fig. 10.1 presents the convention for the connector numbering. It is used throughout the documentation.

Fig. 10.1: Supply connector pin out, receptable - rear view, header - front view (image source: MOLEX)

There are two types of connectors:

• Header

• Receptable, plugged into the header

37


The numbering shown on the left in fig. 10.1 is always valid when viewing in the direction indicated by the arrowwith the indication viewing direction. This must be taken into account when crimping the receptables.

10.2 Global Description of the foxBMS Hardware

The foxBMS system can be mounted in a metal housing, shown in fig. 10.2.

Fig. 10.2: foxBMS Master Unit housing

In this configuration, the top plate can be removed to have access to the foxBMS electronic boards. This is doneby unscrewing the four screws holding the top plate.

The open housing is shown in fig. 10.3.

The boards can be removed from the housing. The boards without housing are shown in fig. 10.4. To start, it isnot necessary to remove the boards from the housing, but it is helpful to be able to look at the LEDs located onthe BMS-Master board.

Fig. 10.5 shows how to put the boards back in the housing.

10.3 Detailed Description of the Hardware Parts

The heart of foxBMS is the BMS-Master board, shown in fig. 10.6.

As shown in fig. 10.6, the BMS-Master board has two microcontroller units (MCU):

• Primary (also called MCU0)

• Secondary (also called MCU1)

Primary is the MCU where the foxBMS software is run. The secondary MCU is present for redundant safety whendeveloping software code on the primary MCU.

38 Chapter 10. Getting Started with the Hardware: Connecting foxBMS


Fig. 10.3: foxBMS Master Unit housing, top plate removed

Each MCU has a set of LEDs, as shown in fig. 10.6:

• Power LED

• Red indicator LED

• Green indicator LED

The power LED must lit when power is supplied to the BMS-Master board, and the indicator LEDs should blink,except during flashing of software on the MCU.

If a debugger is used, it must be connected to the debug port (i.e., JTAG-interface) corresponding to the MCUbeing used.

An extension board named BMS-Extension board is present under the BMS-Master board and is shown in fig.10.7).

It is used to provide more I/O and interfaces than with the BMS-Master board alone.

The BMS-Interface board is located on top of the BMS-Master board (shown in fig. 10.8).

Its purpose is to convert the signals sent by the Serial Peripheral Interface (SPI) of the BMS-Master board to thefirst BMS-Slave board in the daisy by using a proprietary isoSPI interface from Linear Technology.

A BMS-Slave board is shown in fig. 10.9.

The BMS-Slave board is based on the LTC6804-1/LTC6811-1 battery cell monitoring chip. More informa-tion on the LTC6804-1/LTC6811-1 integrated circuit can be found in the datasheet ([ltc_datasheet6804] and[ltc_datasheet6811]). It supervises up to 12 battery cells connected in series. It performs voltage measurements,temperature measurements and passive cell balancing. In the daisy chain, the BMS-Slave boards are connectedvia differential pair cables.

The BMS-Slave board is not designed to be used in a specific housing.

10.3. Detailed Description of the Hardware Parts 39


Fig. 10.4: foxBMS board stack removed from the housing (both BMS-Master board and BMS-Interface board areshown)



Fig. 10.5: Introduction of the board stack in the foxBMS Master Unit housing

A block diagram of a BMS-Slave board is shown in fig. 10.10

10.4 Use of foxBMS in a Battery System

Fig. 10.11 present the organization of the hardware. The system consists of 𝑛 battery modules and 𝑚 BMS-Slave boards. Each BMS-Slave board is connected to a battery module, where it measures cell voltages and celltemperatures. The BMS-Slave boards are connected in a daisy chain configuration: when a data package is sentto the daisy chain, it is first received by slave 1, which transmits it to slave 2 and so on until the data package isreceived by the last BMS-Slave board.

The BMS-Interface board converts the messages sent by the BMS-Master board so that they can be transmitted tothe daisy chain and vice versa.

The foxBMS Master Unit communicates with the Isabellenhuette current sensor IVT-MOD or IVT-S via CAN.

Communication with the control unit (for instance, a personal computer), is also made via CAN.

10.5 Hardware Setup of the BMS-Master board and the BMS-Slaveboard

Fig. 10.12 presents all the connectors of the BMS-Master board.

The connectors needed for this quickstart guide are indicated in the following parts.

10.4. Use of foxBMS in a Battery System 41


Fig. 10.6: foxBMS BMS-Master board



Fig. 10.7: foxBMS BMS-Extension board

10.5. Hardware Setup of the BMS-Master board and the BMS-Slave board 43


Fig. 10.8: foxBMS BMS-Interface board



Fig. 10.9: foxBMS BMS-Slave board



Fig. 10.10: Block diagram of a BMS-Slave board

10.5.1 Connecting the BMS-Slave board to the BMS-Master board

Note: When the connection is made between the BMS-Master board and the BMS-Slave board, two communi-cation lines have to be connected: the primary and the secondary daisy chain.

The connector indicated as Daisy Chain in fig. 10.12 must be used on the BMS-Master board. Its layout isdescribed in table 10.1.

Table 10.1: BMS-Master board Daisy Chain Connec-tor

Pin Signal1 NC2 OUT+ (Secondary LTC6804-1/LTC6811-1)3 OUT- (Secondary LTC6804-1/LTC6811-1)4 NC5 NC6 OUT+ (Primary LTC6804-1/LTC6811-1)7 OUT- (Primary LTC6804-1/LTC6811-1)8 NC9 NC10 NC11 NC12 NC13 NC14 NC15 NC16 NC

Note: This connector pin out is only valid for use of a foxBMS Master Interface board for the LTC6804-



Fig. 10.11: foxBMS in the battery system




1/LTC6811-1 monitoring IC.

On the BMS-Slave board, the connectors indicated as Primary Daisy Chain connector andSecondary Daisy Chain connector in fig. 10.10 must be used. Their layout is described in table 10.2.

Table 10.2: Primary Daisy Chain Connector

Connector Pin Daisy Chain1 IN+ (Primary LTC6804-1/LTC6811-1)2 OUT- (Primary LTC6804-1/LTC6811-1)3 IN- (Primary LTC6804-1/LTC6811-1)4 OUT+ (Primary LTC6804-1/LTC6811-1)

The OUT+ and OUT- pins of the BMS-Master board go to the IN+ and IN- pins of the BMS-Slave board. A cablewith a receptable on both ends must be crimped correctly to make the connection.

In case a second BMS-Slave board must be connected to the daisy chain, the OUT+ and OUT- pins of the firstBMS-Slave board must be connected to the IN+ and IN- pins of the second BMS-Slave board.

10.5.2 Cell Voltage Connector on the foxBMS Slave Units

The connector indicated as Battery cell connector (16 pin) in fig. 10.10 has two purposes:

• Supply of the slaveboard

• Input of the cell voltages to the LTC6804-1/LTC6811-1 monitoring chip

The layout of the connector is described in table 10.3. Up to 12 battery cells can be connected in series, betweenVBAT+ and VBAT-. The BMS-Slave board is supplied by VBAT+ and VBAT-. The total voltage of all cells inseries must be between 11V and 55V (see [ltc_datasheet6804] and [ltc_datasheet6811]). 0- correspond to thenegative pole of cell 0, 0+ to the positive pole of cell 0, 1- correspond to the negative pole of cell 1, 1+ to thepositive pole of cell 1 and so one till 11+, the positive pole of cell 11. As the cells are connected in series, the



positive pole of one cell is connected to the negative pole of the next cell: 0+ to 1-, 1+ to 2+ and so on. The polesshould be connected to the cell voltage connector as shown in table 10.3.

If less than 12 battery cells are used, information on how to connect them can be found LTC6804-1/LTC6811-1datasheets ([ltc_datasheet6804] and [ltc_datasheet6811]).

Table 10.3: BMS-Slave board, bat-tery cell voltage connector

Connector Pin Battery Cell1 VBAT-2 0+ (1-)3 2+ (3-)4 4+ (5-)5 6+ (7-)6 8+ (9-)7 10+ (11-)8 NC9 0-10 1+ (2-)11 3+ (4-)12 5+ (6-)13 7+ (8-)14 9+ (10-)15 11+16 VBAT+

In case no cells are available, they can be simulated with a series of voltage divider. A voltage supplied of30V should be used and 12 resistors with the same value connected in series between the positive and negativeconnectors of the voltage supply. The positive connector is linked to VBAT+, the negative connector to VBAT-and each pole of a resistor correspond to a pole of a battery cell. The voltage of 30V is chosen so that everysimulated cell voltage lies around 2.5V, which lies in the center of the safe operating area defined by default in thefoxBMS software.

10.5.3 Cell Temperature Connector on the foxBMS Slave Units

The connector indicated as Temperature sensor connector (24 pin) in fig. 10.10 is used to connecttemperature sensors to the BMS-Slave board.

Table 10.4 describes the temperature connector.



Table 10.4: Temperature Sensor Connector

Connector Pin Temperature Sensor1, 24 T-Sensor 02, 23 T-Sensor 13, 22 T-Sensor 24, 21 T-Sensor 35, 20 T-Sensor 46, 19 T-Sensor 5

Fig. 10.13 shows the functioning of a temperature sensor.

Fig. 10.13: Temperature sensor circuit.

The voltage VREF (3V) is generated by the LTC6804-1/LTC6811-1 chip. A temperature-dependent resistor mustbe added to build a voltage divider (drawn as a dashed line in fig. 10.13, not delivered with the BMS-Slave boards).The resulting voltage is measured by the LTC6804-1/LTC6811-1 chip. Knowing the temperature dependence ofthe resistor, the relation between measured voltage and temperature can be determined.

A function is present in the code to make the conversion between measured voltage and temperature. It mustbe adapted to the temperature sensor used. This is described in the software FAQ (How to change the relationbetween voltages read by multiplexer via LTC6804-1/LTC6811-1 and temperatures?). In case temperatures areread incorrectly, this function is the first step to verify.

It must be noted that if no sensor is connected, 3V are measured. For the quickstart guide, no sensor needs to beconnected: the conversion function is simply a multiplication by 10, so 30°C will be displayed, which again liesin the center of the safe operating area defined by default in the foxBMS software.

If sensors are added, they must be connected between the connector pins corresponding to the sensors 0 to 5, asshown in table 10.4.

10.5.4 CAN Connector

The connector indicated as CAN 0 in fig. 10.12 must be used on the BMS-Master board. Its layout is describedin table 10.5.



Table 10.5: Master CAN connection

Pin Signal Direction Description1 GND_EXT_0 Output2 NC –3 CAN_0_L Input/Output4 CAN_0_H Input/Output

Ground of CAN_0 is shared with supply ground GND_EXT_0. CAN bus 0 is isolated from the MCU0 via theisolated CAN transceiver TJA1052. The CAN transceiver may be put into standby mode by MCU0.

10.6 Communication with the BMS-Master board

Once foxBMS is running, CAN messages should be sent.

Note: A periodic state request must be made to the system by sending a message with ID 0x152 on the busCAN periodically. If not, the system will go into an error state. The period must be 100ms. More information onstate requests can be found in the section Communication via CAN. Typically the request “Standby state” can bemade.

If voltages have been applied to the voltage connector, they are sent with the message IDs 0x550, 0x551, 0x552and 0x553. Details can be found in the section Communication via CAN.

If temperature sensors have been connected and the conversion function changed in the software, temperature aresent with the messages with IDs 0x353 and 0x354. Details can be found in the section Communication via CAN.

10.7 Current Sensor Configuration

Further information on the current sensor tested with foxBMS can be found in the datasheet of the current sen-sor. To be used in foxBMS, the current sensor IVT-MOD from Isabellenhütte was reprogrammed. The changescompared to factory default are:

• The CAN Message IDs was changed

• The triggered measurement mode was activated

The two following parts sum up the differences between factory setup and foxBMS setup.

10.7.1 Factory Default

• CAN IDs

– 0x411 (dec: 1041) Command

– 0x521 (dec: 1313) Current Measurement

– 0x522 (dec: 1314) Voltage Measurement 1



– 0x511 (dec: 1297) Response

• Measurement Mode: Cyclic (Disabled and Triggered are other possible modes)

10.6. Communication with the BMS-Master board 51

http://www.isabellenhuette.de/uploads/media/IVT_Modular_datasheet_1.20_02.pdf

http://www.isabellenhuette.de/uploads/media/IVT_Modular_datasheet_1.20_02.pdf


10.7.2 After Configuration

• CAN IDs

– 0x35B (dec: 859) Command

– 0x35C (dec: 860) Current Measurement

– 0x35D (dec: 861) Voltage Measurement 1

– 0x35E (dec: 862) Voltage Measurement 2

– 0x35F (dec: 863) Voltage Measurement 3

– 0x7FF (dec: 2047) Response

• Measurement Mode: Triggered

10.8 Hardware Related Frequently Asked Questions

10.8.1 Are the schematic and layout source files available?

Yes, the complete foxBMS schematic and layout files are available in EAGLE format in the HTML documentationin the section PCB Schematics and Layouts.

10.8.2 Have both primary MCU and secondry MCU to be connected?

Yes, they should always tbe connected and configured to provide redundant monitoring and improved safety duringsoftware development in prototyping applications.


CHAPTER 11

Hardware Specifications

The following specifications must be met to ensure a safe and optimal work with the foxBMS hardware.

11.1 Electrical Ratings

Description Minimum Typical Maximum UnitSupply Voltage DC 10 – 26 VContactor Continuous Current – – 4 AContactor Feedback Supply Voltage – 5.0 – VAnalog Input – – 3.3 VIsolated Contacts Continuous Current – – 4 AInterlock Circuit Sink Current – 10 – mAfoxBMS Idle Supply Current at 12V supply – 150 – mAfoxBMS Idle Supply Current at 24V supply – 110 – mA

11.2 Connectors

This section describes the pin out of all connectors on the foxBMS Master Unit.


53


foxBMS uses only Molex Micro-Fit 3.0 type connectors, except for USB. A comprehensive set of connectors andcrimps is supplied with foxBMS to start connecting immediately. In case crimps or housings are missing, they arecommonly available at major distributors.

Molex Micro-Fit 3.0 Crimps Part Number: 46235-0001 (Farnell 2284551)

Molex Micro-Fit 3.0 Connectors:

Pin Count Molex Housing Part Number Farnell Order Number2 43025-0200 6728894 43025-0400 6728906 43025-0600 67290710 43025-1000 67292012 43025-1200 62928516 43025-1600 9961321

Fig. 11.2: Defined viewing direction for the connector pin out; receptable - rear view; header - front view (imagesource: MOLEX)

11.3 Supply (X201 on BMS-Master board)

Pin Signal Direction Description1 SUPPLY_EXT_2 Input 12 - 24V2 SUPPLY_EXT_2 Input 12 - 24V3 GND_EXT_2 Input GND4 SUPPLY_EXT_0 Input 12 - 24V5 GND_EXT_0 Input GND6 GND_EXT_2 Input GND

• SUPPLY_EXT_0 / GND_EXT_0: Microcontroller supply and isolation devices supply

• SUPPLY_EXT_2 / GND_EXT_2: Contactor supply and interlock supply

54 Chapter 11. Hardware Specifications


11.4 CAN_0 (X801 on BMS-Master board)

Pin Signal Direction Description1 GND_EXT_0 Output2 NC –3 CAN_0_L Input/Output4 CAN_0_H Input/Output

Ground of CAN_0 is shared with supply ground GND_EXT_0. CAN_0 is isolated from the MCU0 via the isolatedCAN transceiver TJA1052. The CAN transceiver may be put into standby mode by MCU0.

11.5 CAN_1 (X801 on BMS-Extension board)

Pin Signal Direction Description1 GND_EXT_1 Input2 SUPPLY_EXT_1 Input3 CAN_1_L Input/Output4 CAN_1_H Input/Output

CAN_1 has to be supplied externally (GND_EXT_1 / SUPPLY_EXT_1) with 12 - 24V. CAN_1 is isolated fromthe MCU0 via the isolated CAN transceiver TJA1052. The CAN transceiver may be put into standby mode byMCU0.

11.6 Isolation Monitor (Bender ISOMETER) (X701 on BMS-Masterboard)

Pin Signal Direction Description1 BENDER_NEGATIVE_SUPPLY Output Supply to isolation monitoring device2 SUPPLY_EXT_0 Output Supply to isolation monitoring device3 BENDER_OK_EXT Input Status signal of isolation monitoring device4 BENDER_PWM_EXT Input Isolation monitoring device diagnostic signal

This interface is intended to be used with a Bender isolation monitoring device. Bender ISOMETER IR155-3203/-3204/-3210 are supported. The Bender ISOMETER is supplied and may be switched on or off (lowside) by thefoxBMS Master Unit. By factory, the foxBMS Master Unit is configured to operate with the Bender ISOMETERIR155-3204/-3210. In order to operate with the Bender ISOMETER IR155-3203, Jumper R705 must be removedon BMS-Master board. For more details, check the schematic of the BMS-Master board in section PCB Schematicsand Layouts.

11.4. CAN_0 (X801 on BMS-Master board) 55


11.7 Contactors (X1201 - X1206 on BMS-Master board and X1201 -X1203 on BMS-Extension board)

Pin Signal Direction Description1 GND_EXT_0 – Contactor auxiliary contact2 CONTACTOR_X_FEEDBACK_EXT – Contactor auxiliary contact3 CONTACTOR_X_COIL_POS Output Positive contactor coil supply4 CONTACTORS_COMMON_NEG Output Negative contactor coil supply

All contactor connectors share one common ground. This common ground is switched lowside by the interlockcircuit. Opening the interlock loop deactivates the contactor supply and opens all contactors. A contactor auxiliarycontact may be read by connecting the auxiliary contact to the corresponding pins of the contactor connector.

Freewheeling diodes are not populated on the PCB, since some contactors like the Gigavac GX16 have built-indiodes and should not be used with additional external freewheeling diodes in parallel. If the used contactors do nothave built-in freewheeling diodes, freewheeling diodes must be added to protect the contactor control circuitry.The load current is limited by the optically isolated power switch AQV25G2S (6A continuous load). Everycontactor connector is fused with an onboard slow blow fuse type Schurter UMT-250 630mA (3403.0164.xx).

11.8 Interlock (X901 on BMS-Master board)

Pin Signal Direction Description1 INTERLOCK_IN Input –2 INTERLOCK_OUT Output –

The interlock circuit has a built-in current source, adjusted to 10mA constant current. In fault conditions, allcontactors are opened by opening the interlock circuit. If the interlock circuit is externally opened, the contactorsupply is deactivated immediately. This circuit has no effect on the foxBMS supply or communication interfaces.

11.9 Daisy Chain - Primary and Secondary (X1601 on BMS-Masterboard)



Pin Signal1 NC2 OUT+ (Secondary LTC6804-1/LTC6811-1)3 OUT- (Secondary LTC6804-1/LTC6811-1)4 NC5 NC6 OUT+ (Primary LTC6804-1/LTC6811-1)7 OUT- (Primary LTC6804-1/LTC6811-1)8 NC9 NC10 NC11 NC12 NC13 NC14 NC15 NC16 NC

Please note that this connector pin out is only valid when the BMS-Interface board with the LTC6820 interfacingIC to the LTC6804-1/LTC6811-1.

11.10 RS485 (X1301 on BMS-Extension board)

Pin Signal Direction Description1 GND_EXT_2 Output2 RS485_A Input/Output3 RS485_B Input/Output4 SUPPLY_EXT_2 Output5 SUPPLY_EXT_2 Input6 GND_EXT_2 Input

The RS485 interface uses the ESD rugged transceiver LT1785. Moreover, the interface is galvanically isolated.An external supply has to be provided (12 - 24V).

11.11 Isolated GPIO (X1901 on BMS-Extension board)

11.10. RS485 (X1301 on BMS-Extension board) 57


Pin Signal Direction Description1 ISOGPIO_IN_0 Input2 ISOGPIO_IN_1 Input3 ISOGPIO_IN_2 Input4 ISOGPIO_IN_3 Input5 ISOGPIO_OUT_0 Output6 ISOGPIO_OUT_1 Output7 ISOGPIO_OUT_2 Output8 ISOGPIO_OUT_3 Output9 GND_EXT_0 Output10 GND_EXT_0 Output

The BMS-Extension board provides 4 isolated general purpose inputs and 4 isolated general purpose outputs. TheGPIOs are isolated by an ADUM3402 (i.e., ESD rugged version of the ADUM1402). The inputs are equippedwith 10kOhm pull down resistors and are intended for a maximum input voltage of 5V. The output voltage is also5V. An external supply is not needed.

11.12 Isolated normally open contacts - isoNOC (X2001 on BMS-Extension board)

Pin Signal Direction Description1 ISONOC_0_POSITIVE2 ISONOC_1_POSITIVE3 ISONOC_2_POSITIVE4 ISONOC_3_POSITIVE5 ISONOC_4_POSITIVE6 ISONOC_5_POSITIVE7 ISONOC_0_NEGATIVE8 ISONOC_1_NEGATIVE9 ISONOC_2_NEGATIVE10 ISONOC_3_NEGATIVE11 ISONOC_4_NEGATIVE12 ISONOC_5_NEGATIVE

The BMS-Extension board features 6 isolated normally open contacts. The load current of each channel is limitedby the optically isolated power switch AQV25G2S. The channels are not fused, however freewheeling diodes typeGF1B are installed on board.

11.13 Analog Inputs (X1701 on BMS-Master board)



Pin Signal Direction Description1 V_REF Output2 ANALOG_IN_CH_0 Input3 V_REF Output4 ANALOG_IN_CH_1 Input5 V_REF Output6 ANALOG_IN_CH_2 Input7 V_REF Output8 ANALOG_IN_CH_3 Input9 V_REF Output10 ANALOG_IN_CH_4 Input11 GND_0 Output12 GND_0 Output

On the BMS-Extension board 4 nonisolated analog inputs to MCU0 are available. For applications using NTCsas temperature sensors, also a reference voltage of 2.5V is provided. The maximum input voltage is limited to3.3V and is Zener protected. For further information on the input circuit, please refer to the foxBMS HardwareDescription and to the foxBMS PCB Schematics and Layouts.

11.13. Analog Inputs (X1701 on BMS-Master board) 59

CHAPTER 12

Communication via CAN

12.1 CAN Matrix Description

The table CAN Messages shows the CAN messages sent and received by the BMS with their respective names andIDs, the direction and a short comment.

The table CAN Signals gives the CAN signals sent and received in these messages.

To add or change a signal it must be refered to the software FAQ: How to manually add CAN entries (transmit andreceive) and to change the transmit time period?. It must be kept in mind that the back annotation to the *.dbc or*.sym file is broken by coding it manually.

To add or change a message with automatic code generation it must be refered to the software FAQ: How toprogrammaticaly generate CAN entries?.

12.1.1 CAN Messages

Contrary to the messages in the DBC file, message names are with the prefix ‘CANS_MSG_’ in the code and inthe documentation, in order to be compliant with the coding guidelines, while complying with the 32 characterlimit of DBC files.

61


Message Name Message ID DLC Direction DescriptionCANS_MSG_BMS0 0x152 (338) 8 RX State RequestCANS_MSG_BMS1 0x150 (336) 8 TX General statesCANS_MSG_BMS2 0x550 (1360) 8 TX Cell Voltages of Cells 0, 1, 2CANS_MSG_BMS3 0x551 (1361) 8 TX Cell Voltages of Cells 3, 4, 5CANS_MSG_BMS4 0x552 (1362) 8 TX Cell Voltages of Cells 6, 7, 8CANS_MSG_BMS5 0x553 (1363) 8 TX Cell Voltages of Cells 9, 10, 11CANS_MSG_BMS6 0x555 (1365) 8 TX Cell Voltages of Cells 12, 13, 14CANS_MSG_BMS7 0x351 (849) 8 TX Temperatures/CoolingCANS_MSG_BMS8 0x352 (850) 8 TX SOC/SOHCANS_MSG_BMS9 0x151 (337) 8 TX SOFCANS_MSG_BMS10 0x554 (1364) 8 TX Isolation/BalancingCANS_MSG_BMS11 0x353 (851) 8 TX Temperatures 0 - 7 of ModulesCANS_MSG_BMS12 0x354 (852) 8 TX Temperatures 8 - 15 of ModulesCANS_MSG_BMS13 0x556 (1366) 8 TX Cell Voltages Max Min AverageCANS_MSG_ISENS_TRIG 0x35b (859) 8 TX Trigger for CurrentSensorCANS_MSG_ISENS0 0x35c (860) 6 RX Current Sensing Current ValueCANS_MSG_ISENS1 0x35d (861) 6 RX Current Sensor Voltage 1CANS_MSG_ISENS2 0x35e (862) 6 RX Current Sensor Voltage 2CANS_MSG_ISENS3 0x35f (863) 6 RX Current Sensor Voltage 3CANS_MSG_DEBUG 0x55e (1374) 8 RX Debug Message

12.1.2 CAN Signals

Message:CANS_MSG_BMS0

Message ID:0x152

DLC: 8

Signal name Start bit Bitlength

Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS0_Overflow 0 8 False 1.0 0.0 0.0 256.0 IntelBMS0_Request 8 8 False 1.0 0.0 0.0 256.0 Intel

In the messages described in the previous table, the signal BMS0_Request is used to change the state of thefoxBMS Master Unit. This is one of the most important signals: it allows initiating the procedure to close thepower contactors. Possible request numbers in default configuration are 3 (Normal state) and 8 (Standby state),but can be configured using Foxygen (0 is No Request). More details can be found in the documentation of themodule BMS Control.

A state request has to be sent every 100ms, otherwise the BMS enters into an error state. The requests must comein the window 95-105ms to be valid.

The signal BMS0_Overflow is not used in the foxBMS embedded software. Its intended use is to have afeedback if the supervisory control unit is still alive (i.e., as a heartbeat signal).

62 Chapter 12. Communication via CAN



Message ID:0x150

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS1_general_error 0 2 False 1.0 0.0 0.0 4.0 IntelBMS1_current_state 2 6 False 1.0 0.0 0.0 64.0 IntelBMS1_error_overtemp_bat 8 2 False 1.0 0.0 0.0 4.0 IntelBMS1_error_overtemp_ic 10 2 False 1.0 0.0 0.0 4.0 IntelBMS1_error_overcurrent_charge12 2 False 1.0 0.0 0.0 4.0 IntelBMS1_error_overcurrent_discharge14 2 False 1.0 0.0 0.0 4.0 IntelBMS1_error_overvoltage 16 2 False 1.0 0.0 0.0 4.0 IntelBMS1_error_undervoltage 18 2 False 1.0 0.0 0.0 4.0 IntelBMS1_error_contactor 20 2 False 1.0 0.0 0.0 4.0 IntelBMS1_error_selftest 22 2 False 1.0 0.0 0.0 4.0 IntelBMS1_status_contactors 24 6 False 1.0 0.0 0.0 64.0 IntelBMS1_error_cantiming 30 2 False 1.0 0.0 0.0 4.0 IntelBMS1_balancing_active 49 1 False 1.0 0.0 0.0 1.0 IntelBMS1_msg_overflow_cnt 52 4 False 1.0 0.0 0.0 8.0 IntelBMS1_reserved 56 8 False 1.0 0.0 0.0 0.0 Intel

The signals of these messages display status information of the foxBMS Master Unit.

The status of contactors is represented as a bitfield in BMS1_status_contactors (0: open, 1: closed):

• First bit: Precharge contactor

• Second bit: (not used)

• Third bit: Main Plus contactor

• Fourth bit: Main Minus contactor

• Fifth bit: (not used)

• Sixth bit: (not used)

The various error signals BMS1_error_xxx give information about limit violations and internal errors. Ingeneral, a value of 0 indicates no error and the higher the number the more hazardous is the error. The signalBMS1_general_error indicates the highest error level of all the errors occurring in the foxBMS MasterUnit. The signal BMS1_balancing_active is a simple flag to show if balancing is ON (1) or OFF (0).BMS1_msg_overflow_cnt is a counter that is incremented every time the message is sent (not implementedright now in the foxBMS embedded software). This can help implementation in supervisory control units thathave no possibility to get timestamps of CAN message reception.

The current state signal in BMS1_current_state is currently not filled with information.


Message ID:0x550

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS2_reserved 56 8 False 1.0 0.0 0.0 0.0 IntelBMS2_Mux 0 4 False 1.0 0.0 0.0 15.0 IntelBMS2_Mod0_Cell0_Value4 16 False 1.0 0.0 0.0 65535.0 IntelBMS2_Mod0_Cell1_Value20 16 False 1.0 0.0 0.0 65535.0 IntelBMS2_Mod0_Cell2_Value36 16 False 1.0 0.0 0.0 65535.0 Intel

12.1. CAN Matrix Description 63



Message ID:0x551

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS3_Mux 0 4 False 1.0 0.0 0.0 0.0 IntelBMS3_Mod0_Cell3_Value4 16 False 1.0 0.0 0.0 65535.0 IntelBMS3_Mod0_Cell4_Value20 16 False 1.0 0.0 0.0 65535.0 IntelBMS3_Mod0_Cell5_Value36 16 False 1.0 0.0 0.0 65535.0 Intel


Message ID:0x552

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order



Message ID:0x553

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order



Message ID:0x555

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS6_reserved 56 8 False 1.0 0.0 0.0 0.0 IntelBMS6_Mux 0 4 False 1.0 0.0 0.0 0.0 IntelBMS6_Mod0_Cell12_Value4 16 False 1.0 0.0 0.0 65535.0 IntelBMS6_Mod0_Cell13_Value20 16 False 1.0 0.0 0.0 65535.0 IntelBMS6_Mod0_Cell14_Value36 16 False 1.0 0.0 0.0 65535.0 Intel

The signals of the previous tables give the cell voltages. The signal BMSx_Mux is indicating the module numberbeginning with 0, so for example, if 8 modules are used, the messages of cell voltages of modules 0 to 7 are trans-mitted subsequently and then restart from 0 again. This also shows that a maximum of 16 modules is supportedright now.

The cell voltage values are transmitted in 1mV resolution. Nevertheless, 16 bit signal length are reserved forhigher resolutions.

When a module is not connected properly (e.g., a loose connection), the transmission of the voltage measurementsignal from the foxBMS Slave Unit to the foxBMS Master Unit is interrupted. For the LTC6804-1/LTC6811-1monitoring chip, this results in a measurement of hexadecimal 0xFFFF and a conversion to a CAN cell voltagesignal of 6.55V.

Battery systems with more than 12 cells per module can be supported by foxBMS, by using specific foxBMS SlaveUnits (available on request by contacting us under [email protected]) and enhanced software. For this special case,the message CANS_MSG_BMS6 has been implemented. It should state voltage measurement values of 0V whenthe number of battery cells per module is less than 13.





Message ID:0x351

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS7_Cooling_Needed 0 1 False 1.0 0.0 0.0 1.0 IntelBMS7_Heating_Needed 1 1 False 1.0 0.0 0.0 1.0 IntelBMS7_Tempering_Demand 2 6 False 1.0 -

32.0-32.0

31.0 Intel

BMS7_Average_Temp 8 8 False 0.5 -40.0

-40.0

87.5 Intel

BMS7_Minimum_Temp 16 8 False 0.5 -40.0

-40.0

87.5 Intel

BMS7_Maximum_Temp 24 8 False 0.5 -40.0

-40.0

87.5 Intel

BMS7_MaxTemp_Module_Number32 4 False 1.0 0.0 0.0 15.0 IntelBMS7_MinTemp_Module_Number36 4 False 1.0 0.0 0.0 15.0 IntelBMS7_reserved 40 24 False 1.0 0.0 0.0 1.0 Intel

The minimum, maximum and average temperature are transmitted in the signals BMS7_Minimum_Temp,BMS7_Maximum_Temp and BMS7_Average_Temp, respectively. Contrary to the temperature measurementvalues in messages CANS_MSG_BMS11 and CANS_MSG_BMS11, the resolution here is 0.5°C, because there are8 bits available for signal length.

Additionally, the number of the module with minimum and maximum temperature is indicated in the sig-nals BMS7_MinTemp_Module_Number and BMS7_MaxTemp_Module_Number, respectively. Indexingof module numbers starts from zero.

The signals BMS7_Cooling_Needed, BMS7_Heating_Needed and BMS7_Tempering_Demandare left free for use for application specific development. Here, BMS7_Cooling_Needed andBMS7_Heating_Needed could be simple ON/OFF flags and BMS7_Tempering_Demand could be a ‘con-tinuous’ value indicating the cooling/heating power.


Message ID:0x352

DLC: 8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS8_SOC_Average 0 8 False 0.5 0.0 0.0 50.0 IntelBMS8_SOC_Minimum 8 8 False 0.5 0.0 0.0 50.0 IntelBMS8_SOC_Maximum 16 8 False 0.5 0.0 0.0 50.0 IntelBMS8_SOH_Average 24 8 False 0.5 0.0 0.0 50.0 IntelBMS8_SOH_Minimum 32 8 False 0.5 0.0 0.0 50.0 IntelBMS8_SOH_Maximum 40 8 False 0.5 0.0 0.0 50.0 IntelBMS8_reserved 48 16 False 1.0 0.0 0.0 1.0 Intel

In the free and open version of foxBMS, BMS8_SOC_Average, BMS8_SOC_Minimum,BMS8_SOC_Maximum are set to the same value, that is implemented by a Coulomb counter.BMS8_SOH_Average, BMS8_SOH_Minimum, BMS8_SOH_Maximum are set to an arbitrary SOH value of50. Specific SOH algorithms must be implemented by the user to change this value. Since Non-Disclosure-Agreements are required to analyze battery cells and intensive effort is necessary to develop accurate SOC/SOHbattery models, specific state estimation algorithms can be purshased on request by contacting us [email protected].





Message ID:0x151

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS9_Current_Charge_Max 0 16 False 0.01 0.0 0.0 655.35 IntelBMS9_Current_Charge_Max_Peak16 16 False 0.01 0.0 0.0 655.35 IntelBMS9_Current_Discharge_Max32 16 False 0.01 0.0 0.0 655.35 IntelBMS9_Current_Discharge_Max_Peak48 16 False 0.01 0.0 0.0 655.35 Intel

The current capability of the battery system is indicated by the signals of the previous table. For both dischargeand charge directions, two values are stated, one for the continuous current capability and one for the peak currentcapability. Currently, the peak value is simply the same as the continuous value. The resolution of the values is0.01A, which should be of sufficient granularity for most applications. It is a tradeoff that enables a range up to655.35A in charge and discharge direction with reasonable resolution.


Message ID:0x554

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS10_Isolation_Good 0 1 False 1.0 0.0 0.0 1.0 IntelBMS10_Isolation_Value 1 7 False 1.0 0.0 0.0 127.0 IntelBMS10_Balancing_Module_Number8 4 False 1.0 0.0 0.0 15.0 IntelBMS10_Balancing_Active_Cells12 12 False 1.0 0.0 0.0 4095.0 IntelBMS10_reserved 40 24 False 1.0 0.0 0.0 16777215.0IntelBMS10_Selftest_state 24 8 False 1.0 0.0 0.0 1.0 IntelBMS10_Selftest_Debug 32 8 False 1.0 0.0 0.0 1.0 Intel

The signals presented in the previous table are for the peripheral functions of the battery system, namely theisolation monitoring device, the balancing and the self testing capabilities. The isolation monitoring valuesare sent over CAN while the balancing feedback values are not. The signals BMS10_Selftest_state andBMS10_Selftest_Debug are left open for custom developments.


Message ID:0x353

DLC: 8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS11_Mux 0 4 False 1.0 0.0 0.0 12.0 IntelBMS11_reserved 60 4 False 1.0 0.0 0.0 15.0 IntelBMS11_Temp_Mod0_Temp04 7 False 1.0 -

40.0-40.0

87.0 Intel

BMS11_Temp_Mod0_Temp111 7 False 1.0 -40.0

-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel




Message ID:0x354

DLC: 8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS12_Mux 0 4 False 1.0 0.0 0.0 0.0 IntelBMS12_reserved 60 4 False 1.0 0.0 0.0 15.0 IntelBMS12_Temp_Mod0_Temp84 7 False 1.0 -

40.0-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel


-40.0

87.0 Intel

The signals of the previous tables give the temperatures. The signal BMSx_Mux is indicating the module numberbeginning with 0. So for example, if 8 modules are configured, the messages of temperatures of modules 0 to 7are transmitted subsequently and then restart from 0 again. This also shows that a maximum of 16 modules issupported right now.

The cell temperatures values are transmitted in 1°C resolution with an offset of -40°C. With a signal bit length of7 bits, a range from -40°C to +87°C is possible with this CAN signal design. This should be sufficient for mostbattery systems (lithium-ion battery systems). The placement of the temperature sensors is application specificand can be adapted in the mechanical design of the battery system.

Currently, battery systems with up to 16 temperature sensors per module are usable. When the number of tem-perature sensors per module is configured to be less than 16, temperatures of -40°C should be sent per CAN(corresponding to 0x00 being sent via CAN).


Message ID:0x556

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

BMS13_VoltageAverage 0 16 False 1.0 0.0 0.0 65535.0 IntelBMS13_VoltageMinimum 16 16 False 1.0 0.0 0.0 65535.0 IntelBMS13_VoltageMaximum 32 16 False 1.0 0.0 0.0 65535.0 IntelBMS13_ModuleNrMinVolt 48 4 False 1.0 0.0 0.0 15.0 IntelBMS13_ModuleNrMaxVolt52 4 False 1.0 0.0 0.0 15.0 Intel

The minimum, maximum and average voltage are transmitted in the signals BMS13_VoltageMinimum,BMS13_VoltageMaximum and BMS13_VoltageAverage. Additionally, the number of the mod-ule with minimum and maximum voltage is indicated in the signals BMS13_ModuleNrMinVolt andBMS13_ModuleNrMaxVolt. Indexing of module numbers starts from 0.

Message:CANS_MSG_ISENS_TRIG

Message ID:0x35b

DLC:8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

ISENS_Trigger 0 32 False 1.0 0.0 0.0 2.0 Intel

ISENS_Trigger is set to 0x31FFFF and sent via CAN bus to trigger a current sensor measurement cycle. Thisis the command of the Isabellenhütte sensor to trigger a measurement of all internal measurement channels.



Message:CANS_MSG_ISENS0

MessageID: 0x35c

DLC:6


Multi-plexed

Fac-tor

Offset Min Max Byte-order

ISENS0_I_Byte0 0 8 False 1.0 0.0 0.0 0.0 IntelISENS0_I_Byte1 8 8 False 1.0 0.0 0.0 1.0 IntelISENS0_I_Measurement16 32 False 0.001 -

2147483.648-2147483.648

2147483.647Intel

ISENS0_I_ByteX indicate status values and counters of the current sensor measurement and are not used. Fordetails the datasheet of the current sensor must be consulted. ISENS0_I_Measurement is the current valuemeasured by the sensor. It is a 32 bit signed value with 1mA resolution. It must be noted that resolution in CANtransmission is not the same as the measurement accuracy.


MessageID: 0x35d

DLC:6


Multi-plexed

Fac-tor


ISENS1_U1_Byte0 0 8 False 1.0 0.0 0.0 0.0 IntelISENS1_U1_Byte1 8 8 False 1.0 0.0 0.0 1.0 IntelISENS1_U1_Measurement16 32 False 0.001 -

2147483.648-2147483.648

2147483.647Intel

ISENS1_U1_ByteX indicate status values and counters of the current sensor measurement and are not used. Fordetails the datasheet of the current sensor must be consulted. ISENS1_U1_Measurement is the voltage valuemeasured by the sensor at the voltage input channel 1. It is a 32 bit unsigned value with 1V resolution. It must benoted that resolution in CAN transmission is not the same as the measurement accuracy.


MessageID: 0x35e

DLC:6


Multi-plexed

Fac-tor



2147483.648-2147483.648

2147483.647Intel

ISENS2_U2_ByteX indicate status values and counters of the current sensor measurement and are not impor-tant. For details the datasheet of the current sensor must be consulted. ISENS2_U2_Measurement is thevoltage value measured by the sensor at the voltage input channel 2. It is a 32 bit unsigned value with 1V resolu-tion. It must be noted that resolution in CAN transmission is not the same as measurement accuracy.


MessageID: 0x35f

DLC:6


Multi-plexed

Fac-tor



2147483.648-2147483.648

2147483.647Intel

ISENS3_U3_ByteX indicate status values and counters of the current sensor measurement and are not im-portant. For details see the datasheet of the current sensor. ISENS3_U3_Measurement is the voltage valuemeasured by the sensor at the voltage input channel 3. It is a 32 bit unsigned value with 1V resolution. It must benoted that resolution in CAN transmission is not the same as measurement accuracy.

Message:CANS_MSG_DEBUG

Message ID:0x55e

DLC: 8


Multi-plexed

Fac-tor

Off-set

Min Max Byte-order

DEBUG_Data 0 64 False 1.0 0.0 0.0 0.0 Intel


http://www.isabellenhuette.de/uploads/media/IVT_Modular_Brief_Datasheet_1.0_01.pdf





This message contains only one single signal. The debug data is interpreted by the embedded software differentlydepending on its actual databits. In the software FAQ (How to simply trigger events via CAN?), further details aregiven on the handling of debug messages.


CHAPTER 13

Hardware-Software Quickcheck Guide

This section describes how to test the BMS-Master board with one BMS-Slave board connected. These testsshows if the hardware and software components are working correctly:

• BMS-Slave board

– Hardware

– Software

* LTC driver

* SPI driver

• BMS-Master board

– Hardware

– Software

* operating system

* syscontrol and bmscontrol

* interlock and contactors

* SRAM and EEPROM

* CAN, SPI

* diagnosis

13.1 Required Hardware

• BMS-Master board

• Supply cable

• one BMS-Slave board (and additional voltage divider for voltage simulation)

• CAN-Bus to PC (e.g., PCAN USB)

• Normally closed switch for opening the interlock (hereafter referred to as emergency off)

71


• 3 contactors with normally open feedback (hereafter referred to as plus main contactor, plusprecharge contactor, minus main contactor)

• Debugger

13.1.1 Testing Without Debugger

It is also possible to get little information if the system is running correctly without variable checking on thedebugger. When requesting the later described states to the BMS, the contactors opening and closing can be hear.

13.2 Required Software

• foxBMS firmware for MCU0

• foxBMS firmware for MCU1

• Debugger

• CAN-Bus to PC

• CAN message for Drive and Standby

13.3 Test Procedure

The test procedure consists of two steps:

1. preparing the hardware

2. building the software from source

3. requesting bms-states to BMS-Master board and checking variable values on the debugger

If no debugger is available, only a partially test if all parts of foxBMS are running correctly can be performed. Asmentioned above, it can be checked accoustically if the contactors are opening and closing. This is marked in theTest with (H) and a following explanation if needed.

13.3.1 Hardware Setup

1. Use a voltage divider for voltage simulation at the LTC6804-1/LTC6811-1 and connect it to the BMS-Slaveboard.

2. Connect the two daisy chain connectors from the BMS-Slave board to the BMS-Master board. A daisychain of 2 foxBMS Slave Units is simulated.

3. Connect the emergency off to the interlock of the BMS-Master board.

4. Connect the following contactors to the BMS-Master board:

(a) contactor 0 the plus main contactor in the positive current path

(b) contactor 1 the plus precharge contactor in the positive current path

(c) contactor 2 the minus main contactor in the negative current path

5. The debugger is connected from the PC to the JTAG-interface of MCU0 of BMS-Master board.

6. Connect the CAN-interface

72 Chapter 13. Hardware-Software Quickcheck Guide


13.3.2 Software Setup

1. Build foxBMS version 0.4.4 with python Tools\waf-1.8.12 configure--check-c-compiler=gcc build.

13.3.3 Test

1. Power foxBMS

2. Flash foxBMS MCU0

3. Start PCAN-View

4. Start foxBMS

5. Request “Standby”-state via CAN

6. Check on the debugger if the system timer is running; variable: os_timer

7. Check if BMS-Slave board reads voltages; variable: ltc_cellvoltage


(a) Check on the debugger if interlock is closed; variable: cont_interlock_state(cont_interlock_state.set = 1)

9. Request “Drive”-state via CAN

(a) Check on the debugger if contactors are closed in the correct order; variable:cont_contactor_states

i. close minus main contactor

ii. close plus precharge contactor

iii. close plus main contactor

iv. open plus precharge contactor

(H): If this test is performed with no debugger, contactors should be heard clicking four times.

(a) Check contactor counter; variable: struct bkpsram_ch_1 member: contactors_count


(a) Check on the debugger if interlock is closed; variable: cont_interlock_state

(b) Check on the debugger if contactors are opened in the correct order; variable:cont_contactor_states

i. Open plus main contactor

ii. Open minus main contactor

(H): If this test is performed with no debugger, each contactor should be heard clicking one time (too fast tohear the two contactors clicking separately).








13.3. Test Procedure 73




12. Open interlock by pressing emergency off

(a) Check on the debugger if interlock is opened; variable: cont_interlock_state

(b) Check on the debugger if contactors are opened in the correct order; variable:cont_contactor_states

i. Open plus main contactor

ii. Open minus main contactor

(H): If this test is performed with no debugger, each contactor should be heard clicking one time (too fast tohear the two contactors clicking separately).


(a) BMS should switch to SYSCTRL_STATE_ERROR as the interlock is still open; variablesysctrl member: SYSCTRL_STATEMACH_e

14. Close interlock by releasing emergency off

(a) Check on the debugger if interlock is still open; variable: cont_interlock_state

(b) BMS has to stay in error state: variable sysctrl member: SYSCTRL_STATEMACH_e has to stayin SYSCTRL_STATE_ERROR



(b) Check on the debugger if contactors are still open; variable: cont_contactor_states











(b) Check on the debugger if contactors are still open; variable: cont_contactor_states

18. Power foxBMS off

19. Power foxBMS

20. Break on main() with debugger

21. Distort contactor counter in SRAM; variable: struct bkpsram_ch_1 member: contactors_count

22. Go on/release break point

(a) Check the debugger if the contactor counter values get reloaded from EEPROM; variable: structbkpsram_ch_1 member: contactors_count

23. done

74 Chapter 13. Hardware-Software Quickcheck Guide


|____________intermcu|____________io|____________isoguard|____________ltc|____________mcu|____________rcc|____________rtc|____________spi|____________timer|____________uart|____________utils|____________watchdog|____________wscript

|__os|____________FreeRTOS|____________os.c|____________os.h|____________wscript

|____________doxygen.h|____________STM32F429ZIT6_FLASH.ld|__wscript

76 Chapter 14. Software File Structure

CHAPTER 15

Software Components

The foxBMS software is made out of the following components:

• application

• engine

• general

• hal

• module

• os

15.1 Application

The application directory contains the user applications.

Element Descriptionconfig Contains the configuration for the user applications (e.g., task configuration)sox Coulomb-counter (current integrator) and State-of-Function calculatortask User specific cyclic tasks (10ms and 100ms)

15.2 Engine

The engine directory contains all the core functions of the BMS.

Element Descriptionbmsctrl Decision are taken here by the BMS (e.g., open contactors in case of a problem)config Contains the configuration of engine components (e.g., task configuration)database Implementation of the asynchronous data exchangediag With this software module, other modules can report problemssysctrl Manages the power contactorstask Cyclic engine tasks (1, 10 and 100ms) that call system related functions

Application tasks should be used to call user-defined functions.

77


15.3 General

The general directory contains the main function and configuration files.

Ele-ment

Description

main.c Initialization of hardware modules, of interrupts and of the operating systemcon-fig

Contains the configuration for the system initialization: configuration and interface functions to HALand FreeRTOS, global definitions, interrupt configurations and startup code

nvic.c interrupt initializationin-cludes

Contains the standard types

15.4 HAL

hal contains the Hardware Abstraction Layer. It is used by the system but is provided by the MCU manufacturer,in this case ST-Microelectronics. It is used by foxBMS but not part of foxBMS.

Element DescriptionCMSIS Interface and configuration of CMSISSTM32F4xx_HAL_Driver STM32F4xx family Hardware Abstraction Layer drivers

15.5 Module

The module directory contains all the software modules needed by the BMS.

Element Descriptionadc Driver for analog to digital converter, measurement of lithium backup battery voltagecan Driver to receive/transmit CAN messagecansignal Definition of CAN messages and signalschksum Checksum algorithms for modulo 32-bit addition and CRC32com Serial port communication layer (for debug purposes)config Contains the configuration for the software modulescontactor Driver to open/close contactors and read contactor feedbackdma Configuration for Direct Memory Access (e.g. used for SPI Communication)eeprom Driver for non-volatile storage of data. Retains data even if the 3V button cell failsintermcu Driver for communication between MCU0 (primary) and MCU1 (secondary)io Driver and interfaces for I/O ports (control of output pins and read of input pins)isoguard Driver for monitoring galvanic isolation in the systemltc Driver for battery cell monitoring ICmcu MCU-dependent low-level functions (specific registers, MCU timestamps)rcc Configuration of the prescaler for the MCU clock systemrtc Real time clock driver, Control and Access of Backup SRAM Registersspi Driver for communication via Serial Peripheral Interface (SPI bus)timer Driver for MCU timer peripheralsuart Driver for serial communication (UART, RS232 , RS485)utils Contains utilities like the LED blink driverwatchdog Driver for the watchdog timer

15.6 OS

The os directory contains configurations for the operating system.

78 Chapter 15. Software Components


Element DescriptionFreeRTOS Operating System Software (FreeRTOS)os.c Interface to FreeRTOS (e.g., wrapper functions of cyclic application and engine tasks)

15.6. OS 79


80 Chapter 15. Software Components

CHAPTER 16

Basic Function of the BMS Software

16.1 Startup

The startup code begins at the label Reset_Handler in general/config/startup_stm32f429xx.s. Af-ter initialization of the basic microcontroller registers, the system clock unit and the memory data (e.g., stack-and program pointer, system control block (SCB), interrupt vector, pre-initialization of data-sections, FPU set-tings), the C function main() is called. In general/main.c the second step of initializations of themicrocontroller unit, peripherals and software modules are done (e.g., interrupt priorities, hardware moduleslike SPI and DMA). At this point, interrupts are still disabled. The steps are indicated by the global vari-able os_boot. At the end of the main function, the operating system resources (tasks, events, queues, mu-tex) are configured in OS_TaskInit() (os/os.c) and the scheduler is started by enabling the interrupts.Scheduling is started by invoking all configured tasks (FreeRTOS threads) regarding their priority. The activa-tion of the scheduling is indicated by os_boot = OS_RUNNING. The OS-scheduler first calls the task voidOS_TSK_Engine(void) as the highest priority is assigned to this task. All other tasks are blocked in a while-loop until OS_TSK_Engine() finishes the third initialization step and enters the periodic execution.

16.2 Engine

The task void OS_TSK_Engine(void) executes the third (and last) step of system initialization with en-abled interrupts in OS_PostOSInit(). Then after OS_TSK_Engine() manages the database and systemmonitoring via periodically call of DATA_Task() and DIAG_SysMon() periodically in 1ms.

After that, os_boot is set to OS_SYTEM_RUNNING and the system runs the following tasks periodically:

• void OS_TSK_Cyclic_1ms(void)



It must be noted that no changes should be made directly in these functions, since they are used as wrapper: theycall the following functions:

• void ENG_TSK_Cyclic_1ms(void)



81


where the effective calls for system tasks are made. These three functions and OS_TSK_Engine() make up thecore of the system and are called engine. These function calls are found in engine/task/enginetask.c.Additionally, two users tasks run periodically. They are described in User Applications. The start-up sequence isshown in fig. 16.1.

Fig. 16.1: foxBMS system start-up

The database runs with the highest priority in the system and provides asynchronous data exchange for the wholesystem. Fig. 16.2 shows the data exchanges implemented via the database.

Fig. 16.3 shows the basic structure of foxBMS, which is based on the engine tasks.

The two key functions called within the engine tasks are:

• SysControl

• BMSControl

SysControl has a lower priority than the database and a higher priority than BMSControl. Both modulesare implemented as a state machine, with a trigger function that implements the transition between the statesand a control function that makes state requests to navigate between the states. The trigger and control func-tions are called in void ENG_TSK_Cyclic_1ms(void) and void ENG_TSK_Cyclic_10ms(void).SysControl controls the operating state of the BMS and the contactors. As it is implemented as a state machine,SysControl state requests have to be done by SYSCTRL_SetStateRequest(). SysControl controlsthe contactors accordingly.

BMSControl gathers info on the system via the database and takes decisions based on this data. The BMS isdriven via CAN. Requests are made via CAN to go either in STANDBY mode (i.e., contactors are open) or inNORMAL mode (i.e., contactors are closed). A safety feature is that these requests must be sent periodicallyevery 100ms. BMSControl retrieves the state requests received via CAN from the database and analyses them.If the requests are not sent correctly, this means that the controlling unit driving the BMS has a problem and thecorrectness of the orders sent to the BMS may not be given anymore. As a consequence, in this case BMSControlmakes a request to SysControl to open the contactors. Currently, BMSControl checks the cell voltages, thecell temperatures and the global battery current. If one of these physical quantities show a value out of the safeoperating area, BMSControl makes the corresponding state request to SysControl to open the contactors.BMSControl is started via an initial state request, after which it functions without other requests.

A watchdog instance is needed in case one of the aforementioned tasks hangs: in this case, the control over thecontactors would not be provided anymore. This watchdog is made by the System Monitor module which monitorsall important tasks (e.g., Database, SysControl, BMSControl): if any of the monitored tasks hangs, the

82 Chapter 16. Basic Function of the BMS Software


Fig. 16.2: Asynchronous data exchange with the foxBMS database

Fig. 16.3: Basic tasks in foxBMS

16.2. Engine 83


contactors are opened to prevent damage and protect persons and the battery. To ensure the highest level of safety,opening the contactors is made by two ways:

• State request to SysControl to open the contactors

• Direct access to the contactor module in case SysControl is not responding anymore

A last barrier is present in case all the preceding measures fail: the hardware watchdog timer. In case it is nottriggered periodically, it resets the systems, provoking the opening of the contactors. Function calls (other thanSysControl and BMSControl) and closely related to the system are made in the engine tasks, for example:

• CAN

• Battery cells monitoring (voltages and temperatures)

• Galvanic isolation monitoring

• Lithium 3V button cell voltage monitoring

• System LED blink

16.3 Diagnostic

The diag module is designed to report problems on the whole system. The events that trigger the diag modulehave to be defined by the user. The event handler DIAG_Handler(...) has to be called when the event isdetected. The way the system reacts to a Diag event is defined via a callback function or by the caller accordingthe return value.

Diagnostic events are stored in the Backup SRAM memory in variable DIAG_ERROR_ENTRY_sdiag_memory[]

typedef struct {uint8_t JJ; // date and time of event (JJMMDDhhmmss)uint8_t MM;uint8_t DD;uint8_t hh;uint8_t mm;uint8_t ss;DIAG_EVENT_e event; // event OK (no error), event NOK (error)DIAG_CH_ID_e event_id; // diagnosis event IDuint8_t item; // unique item of event (optional sub-ID)uint8_t dummy1;uint8_t dummy2;uint8_t dummy3;uint32_t dummy4;uint32_t Val0; // specific value of event (optional)uint32_t Val1; // specific value of event (optional)uint32_t Val2; // specific value of event (optional)uint32_t Val3; // specific value of event (optional)

} DIAG_ERROR_ENTRY_s;

16.4 User Applications

For the user applications, two periodic tasks are available:

• void APPL_Cyclic_10ms(void)

• void APPL_Cyclic_100ms(void)

Here, the user can implement its own functions, like new battery state estimation algorithms. The user has accessto system data via the database. These function calls are found in application/task/appltask_cfg.c.

84 Chapter 16. Basic Function of the BMS Software

CHAPTER 17

Software Toolchain

Section being drafted.

85


86 Chapter 17. Software Toolchain

CHAPTER 18

Important Software Modules

This section contains a documentation of the most important software modules.

18.1 BMS Control

BMScontrol (bmsctrl module) handles requests of superior control units (e.g., via CAN messages) and checksfor limits of voltage, current and temperature and monitors correct CAN timing.

18.1.1 Structure

Fig. 18.1 shows the organization of the BMScontrol statemachine.

18.1.2 Module Files

Driver:

• src\engine\bmsctrl\bmsctrl.c

• src\engine\bmsctrl\bmsctrl.h

Driver Configuration:

• src\engine\config\bmsctrl_cfg.c

• src\engine\config\bmsctrl_cfg.h

18.1.3 BMSCTRL Configuration

Foxygen configurable variables that define safe operating area:

87


Fig. 18.1: BMScontrol state machine

88 Chapter 18. Important Software Modules


NAME LEVEL TYPE VALIDA-TOR

UNIT DESCRIPTION standardvalue

BMSC-TRL_TEMPMAX

devel int -40<x<80 °C maximum temperature safeoperating limit

55

BMSC-TRL_TEMPMIN

devel int -40<x<80 °C minimum temperature safeoperating limit

-10

BMSC-TRL_VOLTMAX

devel int 0<x<5000 mV maximum cell voltage safeoperating limit

3600

BMSC-TRL_VOLTMIN

devel int 0<x<5000 mV minimum cell voltage safeoperating limit

2100

BMSC-TRL_CURRENTMAX

devel int 0<x mA maximum current safeoperating limit

15000

BMSC-TRL_CURRENTMIN

devel int x<0 mA minimum current safeoperating limit

-15000

These configuration values are building the main safety feature together with the derating (SOX Configuration)and are therefore considered highly safety-relevant.

Example of safe operating area for lithium-ion LFP/Graphite chemistry:

This configuration is very conservative and limits are defensive. It is the default standard configuration forrechargeable lithium-ion batteries and has to be set up correctly to ensure safety. These values must be adaptedcarefully and specificly to the used battery cells.

NAME UNIT VALUE DESCRIPTIONBMSCTRL_TEMPMAX °C 55 maximum temperature safe operating limitBMSCTRL_TEMPMIN °C -10 minimum temperature safe operating limitBMSCTRL_VOLTMAX mV 3600 maximum cell voltage safe operating limitBMSCTRL_VOLTMIN mV 2100 minimum cell voltage safe operating limitBMSCTRL_CURRENTMAX mA 15000 maximum current safe operating limitBMSCTRL_CURRENTMIN mA -15000 minimum current safe operating limit

Example of safe operating area for lithium-ion NMC/LTO chemistry:


Example of safe operating area for lithium-ion NCA/Graphite and NMC/Graphite chemistries:


Foxygen configurable variables that switch off or on specific checks:

NAME LEVEL DESCRIPTION default valueBMSCTRL_CAN_TIMING_TEST user CAN timing test enable TRUEBMSCTRL_TEST_CELL_LIMITS devel Cell limits test enable TRUEBMSCTRL_TEST_CELL_SOF_LIMITS user SOF limits test enable FALSE

Foxygen configurable IDs of requests receivable via CAN signal:

18.1. BMS Control 89


NAME LEVEL DESCRIPTION default valueBMSCTRL_REQ_ID_NORMAL user ID to request for NORMAL state 3BMSCTRL_REQ_ID_STANDBY user ID to request for STANDBY state 8

18.1.4 Dependencies

DATABASE

• src\engine\database\database.h (included indirectly by general.h)

BMSCTRL accesses minimum and maximum measurement values, SOF calculation results, can request data andcan timing data from DATABASE

SYSCTRL

• src\engine\sysctrl\sysctrl.h

BMSCTRL requests states of SYSCTRL statemachine depending on the input from CAN signals from DATABASE.

SOX

• src\engine\sox\sox.h

BMSCTRL triggers the SOC initialization (until now only dummy implementation).

MCU

• src\module\mcu\mcu.h

BMSCTRL enables and disables interrupt functionality and gets timestamps from MCU module.

CONT

• src\module\contactor\contactor.h

BMSCTRL gets the feedback of the contactors.

18.1.5 Inputs and Outputs to BMSCTRL

Called by 1ms Task:

Input:

• current measurements

• voltage measurement minimum and maximum

• temperature measurement minimum and maximum

• requests received from CAN bus

• current derating values (i.e., SOF calculation results)

Output:

• trigger to SOC initialization

• requests to SYSCTRL statemachine

18.2 System Control

SYS Control (syscontrol module) handles states request from BMS Control (bmsctrl module) or errorrequests from the Diagnosis Module (can module). System Control drives the contactors via the contactormodule.



18.2.1 Included Files

Driver:

• src\engine\syscontrol.c

• src\enginesyscontrol.h


• src\engine\config\syscontrol_cfg.c

• src\engine\config\syscontrol_cfg.h

18.2.2 Dependencies

Contactor

• src\module\config\contactor_cfg.c

• src\module\config\contactor_cfg.h

Database

• src\engine\config\database_cfg.c

• src\engine\config\database_cfg.h

Diagnosis

• src\engine\config\diag_cfg.c

• src\engine\config\diag_cfg.h

• src\engine\config\diag_id.h

18.2.3 Detailed Description of SYSCTRL

Fig. 18.2 shows the organization of the Syscontrol statemachine.

Description of States

The main states of the statemachine are:

Nr. State Description1 SYSCTRL_STATE_UNINITIALIZEDInitial state at startup.2 SYSCTRL_STATE_INITIALIZINGFirst state that is requested after startup. Does basic startup checks, e.g.

checking if the contactors can be opened.6 SYSCTRL_STATE_AWAKE7 SYSCTRL_STATE_SLEEP8 SYSCTRL_STATE_IDLE9 SYSCTRL_STATE_NORMALMain contactors are closed.17 SYSCTRL_STATE_ERRORCan be accessed from every other state. Opens the <br>interlock at software

side. (and in consequence at he hardware) and all contactors.18 SYSCTRL_STATE_PRECHARGE_ERROROpens all contactors but not the interlock.20 SYSCTRL_STATE_STANDBY

Procedure in State NORMAL

18.2. System Control 91


Fig. 18.2: System Control state machine



Note: If the normal state (SYSCTRL_STATE_NORMAL) is left in the statemachine, it has to be ensured that thecontactors are opened in the next state.

Procedure in normal state: Check if interlock line is still closed. If not, open interlock and contactors at softwareside to be in line with the hardware.

If the interlock is closed, the following procedure is performed:

1. close minus main contactor, then wait and go to 2

2. check if main minus contactor is closed

1. if minus main contactor is closed: go to 3

2. if minus main contactor open and timeout reached: exit to error state

3. close plus precharge contactor and wait and go to 4

4. check if plus precharge contactor is closed

1. if plus precharge contactor is closed: go to 5

2. if open and timeout reached: exit to error state

5. loop and check precharge end conditions (U diff < threshold, I < threshold)

1. precharge end condition OK: close plus main contactor and wait and go to 6

2. precharge end condition BUSY (means waiting): wait if timer has not elapsed, else go to error state

6. open plus precharge contactor and go to 7

7. check if plus main contactor is closed

1. if plus main contactor is closed: go to 8

2. if open and timeout reached: exit to error state

8. continuous check if main plus and main minus is closed

1. if plus main or minus main contactor open: exit to error state

2. if plus main and minus main contactor open closed: go to 8 (loop)

Fig. 18.3 shows the detailed sequence of the normal state of the Syscontrol statemachine.

18.2.4 SYSCTRL Configuration

The configuration of timeouts, thresholds etc. is done in syscontrol_cfg.h. All configurations are accessiblewith Foxygen. The macros of the contactor module are mapped to syscontrol macros. Finally new macrosfor switching the contactors are introduced.

18.2.5 Usage

Initialization

The statemachine is initialized by SYSCTRL_Trigger(SYS_MODE_CYCLIC_EVENT) and the starting pointof the syscontrol state machine is SYSCTRL_STATE_UNINITIALIZED. In this state the contactor initializationis called, and checks if all contactors are open.

18.2. System Control 93


Fig. 18.3: Detailed view of SysControl state NORMAL



Functions

static void SYSCTRL_StateControl(void) performs the state transitions with all needed sub-stepsbetween the states. It is important to know, that when entering the error state (SYSCTRL_STATE_ERRORor SYSCTRL_STATE_PRECHARGE_ERROR) the contactors have to be opened manually by using the macroSYSCTRL_ALL_CONTACTORS_OFF(); Therefore, if the user adds another error, this macro should be calledin the added error state. For the other states it is referred to the Doxygen documentation.

18.3 IO

This section describes the configuration of the pins of the foxBMS microcontrollers on the BMS-Master boardusing the io module. The io module allows an easy way to configure all pins of the microcontroller at a centralposition, reading the input signals and writing signals to the output pins of the microcontroller.

18.3.1 Module Files

Driver:

• src\module\io\io.c

• src\module\io\io.h


• src\module\config\io_cfg.c

• src\module\config\io_cfg.h

• src\module\config\io_mcu0.h

• src\module\config\io_package_cfg.h

18.3.2 Configuration of the GPIOs

Initialization of the GPIOs

The following example shows how to configure the pins of the microcontrollers. The starting point is the followingpin configuration:

Package Pin Port-Pin Signal name Alternative Function...16 F-0 PIN_MCU_0_FMC_RAM_A0 flexible memory controller (FMC)17 F-1 PIN_MCU_0_FMC_RAM_A1 flexible memory controller (FMC)...128 D-13 PIN_MCU_0_ISO_GPIO_IN_1 Digital Input133 G-9 PIN_MCU_0_ISO_GPIO_OUT_0 Digital Output...

To define a signal, a #define has to be set in io_cfg_foxbms.h describing the signal:

...#define PIN_MCU_0_FMC_RAM_A0 IO_PF_0#define PIN_MCU_0_FMC_RAM_A1 IO_PF_1...#define PIN_MCU_0_ISO_GPIO_IN_1 IO_PD_13#define PIN_MCU_0_ISO_GPIO_OUT_0 IO_PG_9...

18.3. IO 95


The initialization of this configuration on the hardware is executed through the io module functionIO_Init(*io_cfg). The const IO_PIN_CFG_s io_cfg[] has to be configured in io_cfg.h. Inthe given example, this looks like:

IO_PIN_CFG_s io_cfg[] = {{PIN_MCU_0_FMC_RAM_A0, IO_MODE_AF_PP, IO_PIN_NOPULL, IO_SPEED_HIGH,→˓ IO_ALTERNATE_AF12_FMC, IO_PIN_LOCK_ENABLE},{PIN_MCU_0_FMC_RAM_A1, IO_MODE_AF_PP, IO_PIN_NOPULL, IO_SPEED_HIGH,→˓ IO_ALTERNATE_AF12_FMC, IO_PIN_LOCK_ENABLE},...{PIN_MCU_0_ISO_GPIO_IN_1, IO_MODE_INPUT, IO_PIN_PULLDOWN, IO_SPEED_FAST,→˓ IO_ALTERNATE_NO_ALTERNATE, IO_PIN_LOCK_ENABLE},{PIN_MCU_0_ISO_GPIO_OUT_0, IO_MODE_OUTPUT_PP, 0, 0,→˓ IO_ALTERNATE_NO_ALTERNATE, IO_PIN_LOCK_ENABLE},}

The configuration options of each pin are documented in1. The naming conventions of foxBMS for set-ting the pin (alternate) function is found in io_cfg.h at IO_PIN_ALTERNATE_e. The clocks of theports are enabled automatically when the pins are initialized through IO_Init(&io_cfg) as this functioncalls IO_ClkInit(void). In order to prevent other modules and functions to change the configurationof the pins, the macro IO_PIN_LOCKING in io_cfg.h has to be defined. This macro automatically callsIO_LockPin(pin) for every pin which has defined IO_PIN_LOCK_ENABLE in io_cfg[] and locks theconfiguration registers of the corresponding pin.

Reading and Writing the Pins

• Reading the digital input of PIN_MCU_0_ISO_GPIO_IN_1

...IO_PIN_STATE_e pinstate;pinstate = IO_ReadPin(PIN_MCU_0_ISO_GPIO_IN_1);...

• Writing the digital output of PIN_MCU_0_ISO_GPIO_OUT_0

...IO_PIN_STATE_e pinstate = IO_PIN_SET;IO_WritePin(PIN_MCU_0_ISO_GPIO_OUT_0, pinstate);...

18.3.3 Related Modules

The contactor configuration is dependent on the io module configuration. The contactor configuration is foundin the contactor module:



Sources:

18.4 Contactor

This section describes the configuration of the contactor using the contactor module. The behavior of thecontactors is only depended on the configuration. There sould be no need to modify the driver.

1 Datasheet DM00071990 [PDF] http://www.st.com/st-web-ui/static/active/en/resource/technical/document/datasheet/DM00071990.pdf


http://www.st.com/st-web-ui/static/active/en/resource/technical/document/datasheet/DM00071990.pdf


18.4.1 Module Files

Driver:

• src\module\cont\contactor.h

• src\module\cont\contactor.c




18.4.2 Dependencies

• io module

18.4.3 Configuration of the Contactors

In the configuration header the set-up of the following variables is configurableat user level through Foxygen: - CONT_HAS_NO_FEEDBACK_SWICHTING_TIME,(100ms) - CONT_MAXIUMUM_ALLOWED_CONTACTOR_SWITCHING_TIME (100ms)- CONT_NUMBER_OF_BAD_COUNTINGS - BAD_SWITCHOFF_CURRENT_POS -BAD_SWITCHOFF_CURRENT_NEG

A contactor physically consists of an control pin, an optional feedback pin, which can be configured as normallyopen or normally closed. This hardware condition is mapped in the software in the contactor set-up files incontactor_cfg.c and contactor_cfg.h.

The entry point to change the contactor configuration is the configuration header file contactor_cfg.h.At first the general naming of the contactors the io configuration (PIN_MCU_0_CONTACTOR_0_CONTROL,etc.) is mapped in the contactors to something meaningful names for the contactors have to be defined (e.g., thecontactor0 should be the precharge contactor and provides a feedback pin):

#define CONT_PLUS_MAIN_PRECHARGE_CONTROL PIN_MCU_0_CONTACTOR_0_CONTROL#define CONT_PLUS_MAIN_PRECHARGE_FEEDBACK PIN_MCU_0_CONTACTOR_0_FEEDBACK

Note: if the contactor had no feedback one would define

#define CONT_PLUS_MAIN_PRECHARGE_CONTROL PIN_MCU_0_CONTACTOR_0_CONTROL#define CONT_PLUS_MAIN_PRECHARGE_FEEDBACK CONT_HAS_NO_FEEDBACK

At next the contactors are identified by setting up the typedefed enumeration CONT_NAMES_e. If there are threecontactors, two in the positive path (one for precharge and a main contactor) and a main contactor in the negativepath, the configuration of the CONT_NAMES_e looks like this (the names are free of choice):

typedef enum {CONT_PLUS_MAIN = 0,CONT_PLUS_MAIN_PRECHARGE = 1,CONT_MINUS_MAIN = 2,

} CONT_NAMES_e;

At this point the configuration of the header is done and the configuration is finished in contactor_cfg.c.

The pins where the contactors are connected to the MCU and the hardware configuration are now composed toa contactor object/struct. By using the example above, the contactors must now be configured accordingly. It isassumed that the contactors have a feedback and are of type normally open. The setup summed up would looklike this:

18.4. Contactor 97


Contactor Control pin Feedback pin Hardware feedbackconfiguration

CONT_PLUS_MAIN CONT_PLUS_MAIN_CONTROLCONT_PLUS_MAIN_FEEDBACKCONT_FEEDBACK_NORMALLY_OPENCONT_PLUS_MAIN_PRECHARGECONT_PLUS_MAIN_PRECHARGE_CONTROLCONT_PLUS_MAIN_PRECHARGE_FEEDBACKCONT_FEEDBACK_NORMALLY_OPENCONT_MINUS_MAIN CONT_MINUS_MAIN_CONTROLCONT_MINUS_MAIN_FEEDBACKCONT_FEEDBACK_NORMALLY_OPEN

This would result in the following configuration in the source code for the hardware configuration:

CONT_CFG_s cont_contactors_cfg[NR_OF_CONTACTORS] = {{CONT_PLUS_MAIN_CONTROL, CONT_PLUS_MAIN_FEEDBACK, CONT_FEEDBACK_

→˓NORMALLY_OPEN},{CONT_PLUS_PRECHARGE_CONTROL, CONT_PLUS_PRECHARGE_FEEDBACK, CONT_FEEDBACK_

→˓NORMALLY_OPEN},{CONT_MINUS_MAIN_CONTROL, CONT_MINUS_MAIN_FEEDBACK, CONT_FEEDBACK_

→˓NORMALLY_OPEN}};

The corresponding feedback state configuration would look like this:

CONT_STATES_s cont_contactor_states[NR_OF_CONTACTORS] = {{{FALSE, 0}, {CONT_SWITCH_OFF, 0}, {CONT_SWITCH_OFF, 0}},{{FALSE, 0}, {CONT_SWITCH_OFF, 0}, {CONT_SWITCH_OFF, 0}},{{FALSE, 0}, {CONT_SWITCH_OFF, 0}, {CONT_SWITCH_OFF, 0}}

};

Important: The configuration in CONT_CFG_s contactors_cfg[] must have the same order as definedin CONT_NAMES_e.

The parameters after the feedback type parameter display the state in which the contactor is. The initial stateof the contactor is always switched off. The state variables store the set value (TRUE or FALSE), the ex-pected feedback (CONT_SWITCH_OFF or CONT_SWITCH_ON), the measured feedback (CONT_SWITCH_OFFor CONT_SWITCH_ON) and the according timestamp to each (os_timer).

At this point the setup of the contactors is finished.

Fig. 18.4 gives a visualization of the configuration.

18.4.4 Interaction

The syscontrol module uses the contactor module APIs.

18.5 CAN

The driver interfaces the CAN networks and supports the CAN protocols version 2.0A and B. It has been designedto manage incoming messages and transmit messages with the help of message buffers. It is highly customizableand works efficiently with a high number of messages and minimum CPU load.

18.5.1 Module Files

Driver:

• src\module\can\can.h

• src\module\can\can.c


• src\module\config\can_cfg.h



Fig. 18.4: Contactor configuration

18.5. CAN 99


• src\module\config\can_cfg.c

18.5.2 Dependencies

CPU:

• src\module\cpu\cpu.h

OS:

• src\os\os.h

Other dependencies can arise from callback functions in configuration of can module.

18.5.3 Detailed Description of the can module

Main Features

• Two CAN nodes (CAN_0 and CAN_1)

• CAN protocol version 2.0A, B active

• Bit rates up to 1Mbit/s

Transmission:

• Configurable transmit priority

• Configurable transmit message buffer

• Possible bypassing of transmit message buffer

• Periodic message transmitting

Reception:

• Identifier list and mask mode featured

• Configurable software receive message buffer

• Possible bypassing of receive message buffer

For a detailed overview of the CAN peripheral see source1.

File Structure and Interfaces

The can module is a one-file module with one-file configuration: The module itself consists of one can.c andits associated can.h file. The configuration is given in can_cfg.c and its related can_cfg.h file.

The external interface to the can module is easy and consists of seven functions and is viewable in fig. 18.5.

CAN_Init(void) Initializes CAN settings and message filtering

CAN_TxMsg(CAN_NodeTypeDef_e canNode, uint32_t msgID, uint8_t* ptrMsgData, ... )Transmits message directly on the CAN bus

CAN_Send(CAN_NodeTypeDef_e canNode, uint32_t msgID, uint8_t* ptrMsgData, ... )Adds message to transmit buffer

CAN_TxMsgBuffer(CAN_NodeTypeDef_e canNode) Transmits a CAN message from transmit buffer

CAN_ReceiveBuffer(CAN_NodeTypeDef_e canNode, Can_PduType* msg) Reads a CAN mes-sage from RxBuffer

CAN_SetSleepMode(CAN_NodeTypeDef_e canNode) Set CAN node to sleep mode

1 Datasheet RM0090 [PDF] http://www.st.com/web/en/resource/technical/document/reference_manual/DM00031020.pdf


http://www.st.com/web/en/resource/technical/document/reference_manual/DM00031020.pdf


Fig. 18.5: External CAN Driver interface

CAN_WakeUp(CAN_NodeTypeDef_e canNode) Wake CAN node up from sleep mode

Data/Control Flow

Transmission There are two different possibilities to transmit a message on the CAN bus. Both possibilities areequally correct and transmit the messages via interrupts. The first possibility is to transmit the messagedirectly through the CAN_TxMsg function. The second possibility is to add the message first with a call ofCAN_Send to the message transmit buffer and then later transmit it with the CAN_TxMsgBuffer functionfrom the buffer on the CAN bus.

Reception After a successful reception a messages is either stored in the transmit message buffer or it bypassesthe buffer and is directly interpreted during the ISR via callback functions. The buffered messages can beaccessed through the CAN_ReceiveBuffer function.

A detailed overview over how the CAN driver software interacts with the hardware is shown in the following flowchart in fig. 18.6.

18.5.4 Configuration

The activation of CAN_0 and CAN_1 is set in the can_cfg.h file. Additionally are in this file the messagebuffer options and the message reception options to be configured.

The can_cfg.c file is responsible for the general CAN options (CAN bit-rate, sending behaviour). The receivedmessages are to be defined here.

The interrupt priority of the CAN interrupts is set in the nvic_cfg.c file.

can_cfg.h

The configurable options are

/* CAN bus baudrate *///#define CAN_BAUDRATE 1000000#define CAN_BAUDRATE 500000//#define CAN_BAUDRATE 250000//#define CAN_BAUDRATE 125000

/* CAN options */#define CAN_USE_CAN_NODE1 1

18.5. CAN 101


Fig. 18.6: CAN flow chart of the interaction between hardware and software

/* transmit buffer */#define CAN1_USE_TRANSMIT_BUFFER 1#define CAN1_TRANSMIT_BUFFER_LENGTH 16

/* receive buffer */#define CAN1_USE_RECEIVE_BUFFER 1#define CAN1_RECEIVE_BUFFER_LENGTH 16

/* number of RX message IDs */#define CAN1_NUMBER_OF_RX_IDs 5

/* Number of messages that will bypass the receive buffer and will be interpreted→˓right

* on reception. Set the respective IDs and implement the wished functionality→˓either in

* an individual callback function or in the default STD_RETURN_TYPE_e CAN_→˓BufferBypass(...)

* function in the can.c file. Use bypassing only for important messages because→˓of handling

* during ISR */#define CAN1_BUFFER_BYPASS_NUMBER_OF_IDs 1

There are four predefined values for the CAN bus baud-rate and only one define must be enabled at the sametime. If another baud-rate is wished, the time quants need to be calculated and then this option can be added in theconfiguration. If the define CAN_USE_CAN_NODE1 is disabled (i.e., set to zero), all other options of the chosenCAN bus (i.e., CAN_0 or CAN_1) have no influence on the program execution.

Warning: The bypass possibility should be used carefully because the message interpreting is then donein the context of the corresponding ISR-Handler and can lead to a violation of the timing constraints. The



recommended setting is to use both buffers and to bypass as little messages as possible.

can_cfg.c

The CAN_HandleTypeDef hcan configures the CAN bus transfer settings. The default setting is a bit rate of0.5MHz, automatic bus-off management, automatic wake-up mode, automatic retransition mode, locked receiveFIFOs against overrun and an identifier driven transmission of messages. The bitrate is set through the prescalerand two bit segments (BS) and is calculated with the following formula:

𝑏𝑖𝑡 𝑟𝑎𝑡𝑒 =𝐶𝐴𝑁_𝐶𝐿𝐾𝑃𝑟𝑒𝑠𝑐𝑎𝑙𝑒𝑟

𝑆𝑦𝑛𝑐𝑆𝑒𝑔 +𝐵𝑆1 +𝐵𝑆1

With the STM32F429 this calculates to a default bitrate of:

𝑏𝑖𝑡 𝑟𝑎𝑡𝑒 =42𝑀𝐻𝑧

6

1 + 6 + 7= 0.5𝑀𝐻𝑧

Moreover the settings for message reception need to be set in the source file. The received messages are definedin the CAN_MSG_RX_TYPE_s can_RxMsgs[CAN_NUMBER_OF_RX_IDs] array structs:

typedef struct CAN_MSG_RX_TYPE {uint32_t ID; // message IDuint32_t mask; // mask or 0x0000 to select list modeuint8_t DLC; // data lengthuint8_t RTR; // RTR bituint8_t fifo; // selected CAN hardware (CAN_FIFO0 or CAN_FIFO1)STD_RETURN_TYPE_e (*func)(uint32_t ID, uint8_t*, uint8_t, uint8_t); //

→˓callback function} CAN_MSG_RX_TYPE_s;

Each message can get an individual callback function assigned to. If a message shall bypass the receptionbuffer and be interpreted right on reception, the message identifier needs to be additionally defined in thecan_bufferBypass_RxMsgs[] array. The callback function of the bypassed message is then automati-cally called on reception of the message. If no callback function is defined (NULL in the callback parameter), thenthe default function STD_RETURN_TYPE_e CAN_BufferBypass(...) in the can.c file is called and theinterpretation needs to be implemented there.

More detailed information is provided in the comments in the source code and the STM32F429 microcontrollerreference manual1.

18.5.5 Usage

The following sections describe the usage of the CAN driver.

Initialization

The calling hierarchy and the control/data flow of the initialization process is visible in fig. 18.7. The user datainput is made in the can_cfg.c/h files.

Send Messages

There are two different possibilities to transmit a message on the CAN bus. Both possibilities are equally cor-rect and transmit the message via interrupt. The first possibility is to transmit the message directly with theCAN_TxMsg(...) function. The second possibility is to add the message first, with CAN_Send(...), to thetransmit buffer and then later transmit it buffer with the CAN_TxMsgBuffer(...) function on the CAN bus.

The recommended transmission possibility via message buffer is visible in the following sequence diagram in fig.18.8:

18.5. CAN 103


Fig. 18.7: CAN driver initialization calling hierarchy

Fig. 18.8: CAN driver transmission sequence diagram with buffer usage



Receive Messages

CAN messages are received after configuring the hardware filter banks. As mentioned above, the reception initial-ization is based on the receiving messages and generated automatically. After a successful reception the messagesare either stored in the receive message buffer or corresponding to the configuration, they bypass the buffer and aredirectly interpreted. The bypassing is executed during the ISR and therefore, to avoid a violation of timing con-straints, as little messages as possible should be bypassed. The buffered messages are interpreted asynchronous totheir reception by the function CAN_ReceiveBuffer(...) from the application layer. If the receive buffer isdisabled, then all messages are interpreted right on reception during the ISR.

The interpreting mechanism is shown in the sequence diagram in fig. 18.9.

Fig. 18.9: CAN driver reception sequence diagram

18.5.6 References

18.6 CAN Signal

The cansignal module is a software module to handle the conversion from data providers like a database ormeasurement modules to the can module. It works similar to a typical IPO (input-processing-output) pattern.

18.6.1 Module Files

Driver:

18.6. CAN Signal 105


• src\module\cansignal\cansignal.h

• src\module\cansignal\cansignal.c


• src\module\config\cansignal_cfg.h

• src\module\config\cansignal_cfg.c

18.6.2 Dependencies

CAN:

• src\module\can\can.h

Other dependencies can arise from callback functions in configuration of cansignal module.

18.6.3 Detailed Description of the cansignal module


The cansignal module is a simple one-file module with one-file configuration:

• The module itself consists of one file cansignal.c and its associated cansignal.h

• The configuration is given in cansignal_cfg.c and its associated cansignal_cfg.h

The external interface to the cansignal module is very easy and consists of just two functions:

• CANS_Init

• CANS_MainFunction

CANS_Init is for parameter and configuration checking of the cansignal module.

CANS_MainFunction is for data processing and should be called periodically.

Data Flow

The data flow is generally divided in two different domains, one for reception of CAN messages and signal valuedistribution, the other for transmission of CAN message and signal value assembling/message composition.

When a CAN message is received physically, it is stored in a buffer in can module (not in cansignal module).From this buffer all CAN messages are fetched periodically by call of CANS_MainFunction. If the fetch wassuccessful (i.e., a CAN message has been received and stored in the buffer), the message is processed, the signalsincluded in this message are extracted, scaled and handed over to a data consumer via the callback setter function.

When a CAN message needs to be transmitted physically, the signals data belonging to this CAN message arecollected via their getter callback function. From this signals data, the CAN message is assembled. If everythingworked fine, it is stored in the buffer in CAN module, and will be sent out over the CAN peripheral hardware.

fig. 18.10 shows the data flow used to assemble a CAN message.

Control Flow

The module operates from a single function call to CANS_MainFunction.

First the periodic message transmission is handled in this function. If correspondence of an internal tick counterto a message repetition time and phase is detected (i.e., the periodic time expired) the CAN message is composedfrom its signals. Therefore all signals, which are included in a message, are collected via their getter callback andwritten to the message data block at the right position in the right length. This message data block together with



Fig. 18.10: CAN data flow to assemble messages

the ID, Data Length Code and so on, is handed over to the can module, which handles the low level transmissionto the CAN specific peripheral registers.

The message reception in turn is done by reading out the buffer of the can module. Then the signals configurationis searched for this message(s). If one signal is represented in these received messages it is extracted and handedover to the setter callback function configured for this signal.

18.6.4 CAN Configurations

Default Configuration

The configuration comprises:

• arrays for message definition, for both receive and transmit signals

• arrays for signal definition, for both receive and transmit signals

• callback function implementations for getting and setting of signals

• callback function implementations for post-processing after transmission and reception of messages

Custom Configuration Examples

Multiplexed TX message example

A message can contain signals (called multiplexed signals), that have different meaning depending on anothersignal (called multiplexor signal).

Typical examples for multiplexed signals in foxBMS software are the signals for the transmission of the batterycell voltages. When there are a lot of modules and transmit every voltage measurement in its specific singlesignal, this could result in many messages with different CAN IDs. Also the CAN bus load can increase to anunacceptable level by sending all of these messages periodically with a high cycle time.

For example, in the foxBMS software, four CAN messages are used for the twelve battery cell voltages of asingle module, in which three voltage measurement values are combined in one CAN message together witha multiplexor (e.g., 3 * 16bit voltage measurement + multiplexor + status + counter < 64 bit maximum CANmessage length). This results in the need for four CAN IDs. The multiplexor value then specifies the modulenumber to which the actual voltage measurement signals belong.

In the cansignal_cfg.c this is represented in the signal definition array cans_signals_tx andcans_signals_rx of type CANS_signal_s by the following struct members:

18.6. CAN Signal 107


• boolean isMuxed;

• boolean isMuxor;

• uint8_t muxValue;

• CANS_signals_t muxor;

In detail these members can be described as:

• isMuxed: flag, indicates if multiplexed (TRUE for multiplexed signals)

• isMuxor: flag, indicates if multiplexor (TRUE for the multiplexor signal)

• muxValue: number of multiplex value, e.g., 0 for the first module, when indicating module number

• muxor: symbolic name of multiplexor signal, for example {CANS_BMSx_Mux}

The control flow for transmission of a multiplexed signal in the cansignal module is shown in fig. 18.11.

Disadvantage of the multiplexing is the asynchronous transmission of the voltage measurement values of differentmodules (but asynchronous transmission does not necessarily mean asynchronous A/D sampling).

Note: The getter of the multiplexor signal is responsible for incrementing and resetting the multiplexor value.

Specific example with transmission of the battery temperatures

TX signal array:

const CANS_signal_s cans_signals_example[9] = {// ID isMuxed isMuxor muxVal setter getter

{ {MSD_ID_TEMP}, 0, 2, 3, 0, 1, 0,FALSE, TRUE, 0, 0, &setmux, &→˓getmux}, //!< multiplexor

{ {MSD_ID_TEMP}, 8,16, 0, 0, 1, 0, TRUE, FALSE, 0, 0,&setTemp, &→˓getTemp}, //!< temp1 of module0







{ {MSD_ID_TEMP}, 32,16, 0, 0, 1, 0, TRUE, FALSE, 3, 0,&setTemp, &→˓getTemp}, //!< temp2 of module3}

18.6.5 Usage/Examples

To use can module and cansignal module with a correct CAN Configurations, just callCANS_MainFunction in the cyclic tasks timeslot, that is configured in CANS_TICK_MS.

18.7 LTC

The driver communicates with the LTC6804-1/LTC6811-1 monitoring chips in daisy-chain configuration. Thechips are used to:

• measure the battery cell voltages



Fig. 18.11: CAN data flow to assemble message

18.7. LTC 109


• measure the voltages directly on the GPIOs

• measure the voltage of up to 32 inputs via I2C-driven multiplexer

• enable passive balancing of the connected battery cells

18.7.1 Module Files

Driver:

• src\module\ltc\ltc.c

• src\module\ltc\ltc.h


• src\module\config\ltc_cfg.c

• src\module\config\ltc_cfg.h

18.7.2 Dependencies


• src\module\diag\diag.h

• src\module\spi\spi.h

18.7.3 Detailed Description of the ltc module

State Machine

The ltc module is organized in a state machine, which is mainly implemented with 4 functions:

• LTC_Trigger(): called every 1ms, contains the sequence of events in the state machine

• LTC_Ctrl(): makes state requests to the state machine, so that the LTC6804-1/LTC6811-1 performs itstasks

• LTC_SetStateRequest(): used in LTC_Ctrl() to make the state requests

• LTC_CheckStateRequest(): called by LTC_SetStateRequest() to check the state requests.Returns the result of the check immediately.

The operation of the state machine is described hereafter. First, the daisy chained LTC6804-1/LTC6811-1 isinitialized as shown in fig. 18.12.

After initilization, the state machine goes in the idle state, where the user can make five different requests:

• measure voltages

• read measured voltages

• read multiplexer inputs

• read GPIO inputs

• balance cells

The function LTC_SetStateRequest() is used to make these state requests to the LTC6804-1/LTC6811-1state machine. Fig. 18.13 and 18.14 detail how these possible state requests are handled.



Fig. 18.12: LTC6804-1/LTC6811-1 internal state machine (initialization)

Fig. 18.13: LTC6804-1/LTC6811-1 state machine (voltage measurement, voltage readout, all GPIOs measure-ment)

18.7. LTC 111


Fig. 18.14: LTC6804-1/LTC6811-1 state machine (measurement of a single GPIO)

Results Retrieval and Balancing Orders

The results of the measurements are written in the database. The balancing is made according to the controlvariable set in the database. The corresponding variables are:

DATA_BLOCK_CELLVOLTAGE_s ltc_cellvoltage; //cell voltagesDATA_BLOCK_CELLTEMPERATURE_s ltc_celltemperature; //cell temperatureDATA_BLOCK_MINMAX_s ltc_minmax; //minimum and maximum values at→˓battery pack

//level for voltages and→˓temperaturesDATA_BLOCK_BALANCING_FEEDBACK_s ltc_balancing_feedback; //result from balancing→˓feedback

//(is each cell→˓balanced or not)DATA_BLOCK_BALANCING_CONTROL_s ltc_balancing_control; //balancing orders read→˓from database

18.7.4 Configuration of the ltc module

SPI Interface

In ltc_cfg.h, the SPI devices used by the LTC6804-1/LTC6811-1 is defined by the macroSPI_HANDLE_LTC. The SPI handle must be chosen from the list SPI_HandleTypeDef spi_devices[]in spi_cfg.c. The frequency of the used SPI must be adjusted with the configuration in spi_cfg.c, so thatthe frequency is not higher than 1MHz. This is the maximum allowed frequency for the LTC6804-1/LTC6811-1chip. The function LTC_SetTransferTimes() sets the waiting times used for the ltc module automaticallyat startup. It uses LTC_GetSPIClock() to get the SPI clock frequency automatically.



Measurement Mode and Channel Selection

When a request is made with the function LTC_SetStateRequest() to measure cell voltages or multiplexerinputs, two arguments must be given. The first one is the measurement mode, which can be:

• normal

• filtered

• fast

These modes are defined in the LTC6804-1/LTC6811-1 datasheet [ltc_datasheet]. For cell voltage measurements,the macro VOLTAGE_MEASUREMENT_MODE is defined in ltc_cfg.h. For multiplexers measurement, themacro GPIO_MEASUREMENT_MODE is defined in ltc_cfg.h.

The second argument is the number of channels: The following enums are defined in ltc.h:

• LTC_ADCMEAS_ALLCHANNEL to measure all cell voltages/to measure all 5 GPIO inputs

• LTC_ADCMEAS_SINGLECHANNEL to measure 2 cell voltages/to measure 1 GPIO input

Multiplexer Sequence

In case of a single GPIO measurement, the multiplexer sequence to be read is defined in ltc_cfg.c with thevariable LTC_MUX_CH_CFG_t ltc_mux_seq_main_ch1[]. It is a list of elements of the following form:

{.muxID = 1,.muxCh = 3,

}

where the multiplexer to select (muxID, can be 0, 1, 2 or 3) and the channel to select (muxCh, from 0 to 7) aredefined. Channel 0xFF means that the multiplxer is turned off. This is used to avoid two or more multiplexers tohave their outputs in a low-impedance state on the same time.

Temperature Sensor Assignment

For temperature sensors, the variable is used to give the correspondence between the channel measured and theindex used:

uint8 ltc_muxsensortemperaturmain_cfg[8] ={ 8-1 , //channel 0

7-1 , //channel 16-1 , //channel 25-1 , //channel 34-1 , //channel 43-1 , //channel 52-1 , //channel 61-1 //channel 7

}

In the above example, channel 0 of the multiplexer corresponds to temperature sensor 8. If muxseqptr is themultiplexer sequence of type LTC_MUX_CH_CFG_t as defined above, the sensor index is retrieved in the variablesensor_idx via:

sensor_idx = ltc_muxsensortemperaturmain_cfg[muxseqptr->muxCh];

18.7. LTC 113


18.7.5 Usage

The ltc module cycle (cell voltage measurement, GPIO measurement, balancing control) is implemented inthe function LTC_Ctrl(). The default configuration is a measurement with multiplexers. Once the LTC6804-1/LTC6811-1 daisy chain has been initialized, the cycle is as follow:

• measure cell voltages

• measure NUMBER_OF_MUX_MEASUREMENTS_PER_CYCLE multiplexer inputs

• measure cell voltage

• repeat till all multiplexer inputs have been read

• balance cells according to the data in database

18.7.6 References

18.8 COM

The com module handles communication between the MCU and external devices. It makes use of differentinterfaces (e.g., uart module) for this purpose.

18.8.1 Module Files

Driver:

• src\module\com\com.h

• src\module\com\com.c

18.8.2 Dependencies

UART:

• src\module\uart\uart.c

• src\module\uart\uart.h

18.8.3 Establishing connection with PC

1. Connect PC with USB cable to primary USB interface

2. Start a terminal program (e.g., HTerm)

3. Select correct COM Port

4. Select following settings:

• Baudrate: 115200 Bd

• Databits: 8, Stopbits: 1, Parity: None

• DTR: disabled, RTS: disabled

• Send on enter: CR



18.8.4 Functionality of com module

The com module provides possibilities for communication with external devices using UART. For incoming re-quests, it provides some kind of basic command parser/handler and access to the syscontrol module. Further-more, it provides the user with some informations about the system and a testmode where the system settings canbe alternated and basic system tests can be performed.

The com module can be enabled by using the BUILD_MODULE_ENABLE_COM define. Its handler needsto be called periodicaly (e.g., by using ENG_TSK_Cyclic_10ms()). Currently the COM_Decoder supportsfollowing commands:

Command Descriptionhelp get available command listgettime get system timegetruntime get runtime since last resetprintdiaginfo get diagnosis entries of DIAG module (entries can only be printed once)printcontactor-info

get contactor information (number of switches/hard switches) (entries can only be printedonce)

teston enable testmode, testmode will be disabled after a predefined timeout of 30s when no newcommand is sent

Following commands are only available during enabled testmode:

Command Descriptiontestoff disable testmodesettime YY MM DD HHMM SS

set mcu time and date (YY-year, MM-month, DD-date, HH-hours,MM-minutes, SS-seconds)

reset enforces complete software reset using HAL_NVIC_SystemReset()watchdogtest performs watchdog test, watchdog timeout results in system reset (predefined

1s)setsoc xxx.xxx set SOC value (000.000% - 100.000%)ceX enables contactor number X (only possible if BMS is in no error state)cdX disables contactor number X (only possible if BMS is in no error state)

18.9 UART

The uart module provides the capability to send and receive data using the RS232/UART interface.

18.9.1 Module Files

Driver:

• src\module\uart\uart.c

• src\module\uart\uart.h


• src\module\config\uart\uart_cfg.c

• src\module\config\uart\uart_cfg.h

18.9.2 Description of the uart module

The uart module uses a user-defined buffer for transmitting data. A custom IRQ handler is responsible forhandling all receive/transmit processes. Those operations are dispatched to sub-functions according to the setflags in the status register.

18.9. UART 115


18.9.3 UART Configuration

The default configuration is done within the UART_Init() function, which gets called during startup. Below isan example showing the UART configuration which uses usart3 with a baudrate of 115200Bd:

UART_HandleTypeDef uart_cfg[UART_NUMBER_OF_USED_UART_CHANNELS] = {{

.Instance = USART3,

.Init.BaudRate = 115200,

.Init.WordLength = UART_WORDLENGTH_8B,

.Init.StopBits = UART_STOPBITS_1,

.Init.Parity = UART_PARITY_NONE,

.Init.Mode = UART_MODE_TX_RX,

.Init.HwFlowCtl = UART_HWCONTROL_NONE,

.Init.OverSampling = UART_OVERSAMPLING_16,}

};

18.9.4 Usage

The initialization has to be done during startup for subsequent function calls to succeed. UART_IntRx andUART_IntTx are interrupt driven and do not need to be called by the user. Assuming initialization was done prop-erly, the user only needs to copy content from the internal ring buffer for reading purpose, or call UART_vWritefor writing purpose.

18.10 Checksum Module

This section describes the checksum feature in foxBMS. For the toolchain/buildprocess of the checksum feature,see Checksum Tool.

The chksum module provides the capability to verify data integrity during runtime for multiple purposes (e.g.,firmware validation and verification of sent/received data).

18.10.1 Module Files

Source:

• src\module\chksum\chksum.h

• src\module\chksum\chksum.c

18.10.2 Description of the chksum module

The chksum module offers 2 possibilities to check data integrity, Modulo32BitAddition and a hardwarebased, slightly modified CRC32 implementation. The following short examples demonstrate the usage of thechksum module:

uint32_t chksum = CHK_crc32((uint8_t*)0x08000000, 0x1000) -> hashes 4kB of code,→˓starting at 0x08000000 using CRC32 algorithm

uint32_t chksum = CHK_modulo32addition((uint8_t*)0x08000000, 0x1000) -> hashes 4kB→˓of code, starting at 0x08000000 using Modulo32BitAddition algorithm

During the startup, the CHK_crc32 function is used to verify the integrity of the flashed firmware image. Afterthe calculation of the CRC32 checksum, it is compared to a hardcoded value within the flashheader struct. Whenboth values match, the firmware is valid and execution continues. If both values do not match, an error is reported.



The flashheader contains the validation and checksum information with memory areas of separate software parti-tions, it gets generated during compilation by an external checksum tool, written in python. Furthermore it alsoprovides the possibility for software versioning.

18.10.3 Checksum Configuration

Enabling/disabling of the checksum verification at startup is set by the following macro (the macro is Foxygenconfigurable):

/*fox

* enables checking of flash checksum at startup.

* @var enable flash checksum

* @level advanced

* @type select(2)

* @default 0

* @group GENERAL

*/#define BUILD_MODULE_ENABLE_FLASHCHECKSUM 1//#define BUILD_MODULE_ENABLE_FLASHCHECKSUM 0

18.10.4 Checksum Default Configuration

The default value enables checksum verification at startup.


The checksum tool is related on the Checksum Tool configuration (see Checksum Tool).

18.11 SOX

This section describes where and how to implement state estimation algorithms (e.g., SOC, SOH, SOF). Thebasic SOC calculation is done by a simple Coulomb counter. Its implementation is shown here. Current deratingdepending on cell voltages, temperatures and SOC is performed to compute the SOF.


Driver:

• src\application\sox\sox.h

• src\application\sox\sox.c


• src\application\config\sox_cfg.h

• src\application\config\sox_cfg.c

18.11.2 Dependencies

Database:

• src\engine\database\database.h (included implicitly by general.h)

The sox module gets the relevant measurement minimum and maximum values from the database and stores thecurrent derating values in the database.

18.11. SOX 117


18.11.3 Detailed Description of the sox module

SOC - State of Charge

The state of charge estimation (SOC) is implemented in the form of a simple Coulomb counter. The SOC initial-ization is done after startup by reading the value from the non volatile memory. Not implemented right now is aintialization of the SOC by VOLTAGE-SOC relation (lookup table), but configuration placeholders are already inSOX Configuration. These placeholders define the constraints at which the initialization with lookup table is valid.

SOF - State of Function

The state of function estimation (SOF) consists of some current derating values. These derating values are calcu-lated according to battery cell specific constraints. For this, three parameters are taken into account:

• temperature

• voltage

• SOC

Specific points in the following derating curves have to be defined by Foxygen configurable variables:

Fig. 18.15: Temperature dependent current derating

These specific points are the values where derating starts and where it is at full extent. They are described in Con-figuration Variables and battery specific values can be seen for example in Configuration Example for Lithium-IonNMC/LTO Chemistry and Configuration Example for Lithium-Ion NCA/Graphite or NMC/Graphite Chemistries.



Fig. 18.16: Voltage dependent current derating

Fig. 18.17: SOC dependent current derating

18.11. SOX 119


18.11.4 SOX Configuration

Configuration Variables

For the Coulomb counting method the cell capacity (in case of parallel cell configuration, it is the sum of theparallel connected cells) has to be given here:

NAME LEVEL TYPE UNIT DESCRIPTION DE-FAULT

SOX_CELL_CAPACITY devel float mAh cell capacity in SOC formula coulombcounter

20000.0

Currently there is only placeholder for the initialization by a Voltage-SOC relation. The following configurationcan be used after implementation:

NAME TYPE UNIT DESCRIPTION DE-FAULT

SOX_SOC_INIT_CURRENT_LIMIT int mA at initialization the current must bebelow

100

SOX_DELTA_MIN_LIMIT int mV see source code 10SOX_DELTA_MAX_LIMIT int mV see source code 10

These are the configuration variables of the safe operating area:



NAME LEVEL TYPE UNIT DESCRIPTION VALIDA-TOR

SOX_CURRENT_MAX_CONTINUOUS_CHARGEde-vel

float A maximum current continuouscharge

1<x<240

SOX_CURRENT_MAX_CONTINUOUS_DISCHARGEde-vel

float A maximum current continuousdischarge

1<x<240

SOX_CURRENT_LIMP_HOME de-vel

float A discharge current in limp homeemergency mode

1<x<40

SOX_TEMP_LOW_CUTOFF_DISCHARGEde-vel

float °C low temperature dischargederating start

-40.0<x<80.0

SOX_TEMP_LOW_LIMIT_DISCHARGEde-vel

float °C low temperature dischargederating full

-40.0<x<80.0

SOX_TEMP_LOW_CUTOFF_CHARGEde-vel

float °C low temperature charge deratingstart

-40.0<x<80.0

SOX_TEMP_LOW_LIMIT_CHARGE de-vel

float °C low temperature charge deratingfull

-40.0<x<80.0

SOX_TEMP_HIGH_CUTOFF_DISCHARGEde-vel

float °C low temperature dischargederating start

-40.0<x<80.0

SOX_TEMP_HIGH_LIMIT_DISCHARGEde-vel

float °C low temperature dischargederating full

-40.0<x<80.0

SOX_TEMP_HIGH_CUTOFF_CHARGEde-vel

float °C low temperature charge deratingstart

-40.0<x<80.0

SOX_TEMP_HIGH_LIMIT_CHARGE de-vel

float °C low temperature charge deratingfull

-40.0<x<80.0

SOX_SOC_CUTOFF_CHARGE de-vel

int 0.01% high SOC derating starts 0<=x<=10000

SOX_SOC_LIMIT_CHARGE de-vel

int 0.01% high SOC derating full extent 0<=x<=10000

SOX_SOC_CUTOFF_DISCHARGE de-vel

int 0.01% low SOC derating starts 0<=x<=10000

SOX_SOC_LIMIT_DISCHARGE de-vel

int 0.01% low SOC derating full extent 0<=x<=10000

SOX_VOLT_CUTOFF_CHARGE de-vel

int mV high voltage derating starts 0<=x<=5000

SOX_VOLT_LIMIT_CHARGE de-vel

int mV high voltage derating full extent 0<=x<=5000

SOX_VOLT_CUTOFF_DISCHARGE de-vel

int mV low voltage derating starts 0<=x<=5000

SOX_VOLT_LIMIT_DISCHARGE de-vel

int mV low voltage derating full extent 0<=x<=5000

These configuration values are building the main safety feature together with the BMSCTRL Configuration andare therefore considered highly safety-relevant.

Configuration Example for Lithium-Ion LFP/Graphite Chemistry

This configuration is very conservative and limits are defensive. It is the default standard configuration. Pleaseadapt these values specific to your battery cells.

18.11. SOX 121


NAME UNIT VALUE DESCRIPTIONSOX_CURRENT_MAX_CONTINUOUS_CHARGEA 10.00 maximum current continuous chargeSOX_CURRENT_MAX_CONTINUOUS_DISCHARGEA 10.00 maximum current continuous dischargeSOX_CURRENT_LIMP_HOME A 3.00 discharge current in limp home

emergency modeSOX_TEMP_LOW_CUTOFF_DISCHARGE °C 5.0 low temperature discharge derating startSOX_TEMP_LOW_LIMIT_DISCHARGE °C -5.0 low temperature discharge derating fullSOX_TEMP_LOW_CUTOFF_CHARGE °C 10.0 low temperature charge derating startSOX_TEMP_LOW_LIMIT_CHARGE °C 0.0 low temperature charge derating fullSOX_TEMP_HIGH_CUTOFF_DISCHARGE °C 45.0 low temperature discharge derating startSOX_TEMP_HIGH_LIMIT_DISCHARGE °C 55.0 low temperature discharge derating fullSOX_TEMP_HIGH_CUTOFF_CHARGE °C 30.0 low temperature charge derating startSOX_TEMP_HIGH_LIMIT_CHARGE °C 37.0 low temperature charge derating fullSOX_SOC_CUTOFF_CHARGE 0.01% 8500 high SOC derating startsSOX_SOC_LIMIT_CHARGE 0.01% 9500 high SOC derating full extentSOX_SOC_CUTOFF_DISCHARGE 0.01% 1500 low SOC derating startsSOX_SOC_LIMIT_DISCHARGE 0.01% 500 low SOC derating full extentSOX_VOLT_CUTOFF_CHARGE mV 3300 high voltage derating startsSOX_VOLT_LIMIT_CHARGE mV 3550 high voltage derating full extentSOX_VOLT_CUTOFF_DISCHARGE mV 2700 low voltage derating startsSOX_VOLT_LIMIT_DISCHARGE mV 2300 low voltage derating full extent

Configuration Example for Lithium-Ion NMC/LTO Chemistry


emergency modeSOX_TEMP_LOW_CUTOFF_DISCHARGE °C 0.0 low temperature discharge derating startSOX_TEMP_LOW_LIMIT_DISCHARGE °C -10.0 low temperature discharge derating fullSOX_TEMP_LOW_CUTOFF_CHARGE °C 0.0 low temperature charge derating startSOX_TEMP_LOW_LIMIT_CHARGE °C -10.0 low temperature charge derating fullSOX_TEMP_HIGH_CUTOFF_DISCHARGE °C 45.0 low temperature discharge derating startSOX_TEMP_HIGH_LIMIT_DISCHARGE °C 55.0 low temperature discharge derating fullSOX_TEMP_HIGH_CUTOFF_CHARGE °C 45.0 low temperature charge derating startSOX_TEMP_HIGH_LIMIT_CHARGE °C 55.0 low temperature charge derating fullSOX_SOC_CUTOFF_CHARGE 0.01% 8500 high SOC derating startsSOX_SOC_LIMIT_CHARGE 0.01% 9500 high SOC derating full extentSOX_SOC_CUTOFF_DISCHARGE 0.01% 1500 low SOC derating startsSOX_SOC_LIMIT_DISCHARGE 0.01% 500 low SOC derating full extentSOX_VOLT_CUTOFF_CHARGE mV 2400 high voltage derating startsSOX_VOLT_LIMIT_CHARGE mV 2550 high voltage derating full extentSOX_VOLT_CUTOFF_DISCHARGE mV 2000 low voltage derating startsSOX_VOLT_LIMIT_DISCHARGE mV 1750 low voltage derating full extent



Configuration Example for Lithium-Ion NCA/Graphite or NMC/Graphite Chemistries


emergency modeSOX_TEMP_LOW_CUTOFF_DISCHARGE °C 25.0 low temperature discharge derating startSOX_TEMP_LOW_LIMIT_DISCHARGE °C -10.0 low temperature discharge derating fullSOX_TEMP_LOW_CUTOFF_CHARGE °C 20.0 low temperature charge derating startSOX_TEMP_LOW_LIMIT_CHARGE °C 10.0 low temperature charge derating fullSOX_TEMP_HIGH_CUTOFF_DISCHARGE °C 45.0 low temperature discharge derating startSOX_TEMP_HIGH_LIMIT_DISCHARGE °C 55.0 low temperature discharge derating fullSOX_TEMP_HIGH_CUTOFF_CHARGE °C 35.0 low temperature charge derating startSOX_TEMP_HIGH_LIMIT_CHARGE °C 45.0 low temperature charge derating fullSOX_SOC_CUTOFF_CHARGE 0.01% 8500 high SOC derating startsSOX_SOC_LIMIT_CHARGE 0.01% 9500 high SOC derating full extentSOX_SOC_CUTOFF_DISCHARGE 0.01% 1500 low SOC derating startsSOX_SOC_LIMIT_DISCHARGE 0.01% 500 low SOC derating full extentSOX_VOLT_CUTOFF_CHARGE mV 4000 high voltage derating startsSOX_VOLT_LIMIT_CHARGE mV 4100 high voltage derating full extentSOX_VOLT_CUTOFF_DISCHARGE mV 3100 low voltage derating startsSOX_VOLT_LIMIT_DISCHARGE mV 2750 low voltage derating full extent

18.11.5 Usage/Examples

To be drafted.

18.11.6 References

To be drafted.

18.12 Isoguard

The isoguard module measures the insulation resistance between the insulated and the active high-voltageconductors of the battery and the reference earth (e.g., chassis ground/Kl.31 in automotive applications).


Driver:

• src\engine\isoguard\isoguard.h

• src\engine\isoguard\isoguard.c

• src\engine\isoguard\ir155.h

• src\engine\isoguard\ir155.c


• src\engine\config\isoguard_cfg.h

• src\engine\config\isoguard_cfg.c

18.12. Isoguard 123


18.12.2 Dependencies

CPU


Database

• src\engine\database\database.h

• src\engine\config\database_cfg.h

Diag

• src\engine\diag\diag.h

• src\engine\config\diag_cfg.h

IO

• src\module\io\io.h

• src\module\config\io_cfg.h

RTC

• src\module\rtc\rtc.h

• src\module\config\rtc_cfg.h

TIMER

• src\module\timer\timer.h

• src\module\config\timer_cfg.h

18.12.3 Detailed description of isoguard module


The isoguard module is separated into two different layers, a bottom and a top layer. The top layer consists ofthe isoguard.c and its associated isoguard.h file. It provides an easy interface to initialize the isoguardmodule and to access the measurement data. The insulation threshold to differentiate between a good and badinsulation can be set in the isoguard_cfg.h file. The bottom layer contains the ir155.c and ir155.hfiles. They are both dedicated to the Bender ISOMETER IR155-3204 hardware (IR155-3203/-3204/-3210 aresupported) and handle the connection of the ISOMETER to the MCU, as well as the evaluation and interpretationof the measurement data.

The external interface to the isoguard module is simple and consists of three functions and is viewable in fig.18.18:

Fig. 18.18: External isoguard driver interface

ISO_Init(void) Initializes software isoguard module and enables the hardware Bender module



ISO_ReInit(void) Resets software isoguard module and hardware Bender module

ISO_MeasureInsulation(void) Measures and evaluates the insulation

Configuration

The configuration is done in the isoguard_cfg.h file and consists of two defines:

#define ISO_CYCLE_TIME 200

ISO_CYCLE_TIME is the periodic calling time of the ISO_MeasureInsulation(void) function and mustnot be chosen lower than 150ms due to the lowest possible frequency of the Bender ISOMETER of 10Hz. Thedefault value is 200ms.

#define ISO_RESISTANCE_THRESHOLD 400

ISO_RESISTANCE_THRESHOLD specifies the resistance threshold to differentiate between good and bad insu-lation. This value has no impact if the threshold is set lower than the intern resistance threshold of the BenderISOMETER. The default value is 400kOhm.

Initialization

The initialization is done via the interface function ISO_Init(void), which is forwarded to the BenderISOMETER specific initialization functions, as shown in fig. 18.19.

Fig. 18.19: Initialization of the isoguard module

The most important steps in the initialization process are:

• Enabling of PWM input measurement

• Reading of BKP_SRAM variable for previous Ground Error

• Set start-up time before measurement results are trustworthy (dependent on the previous state)

• Enabling of Bender hardware module

The function ISO_ReInit(void) resets the whole isoguard module and the initialization process is doneagain, including the waiting time until the measurement values are declared as trustworthy.

18.12.4 Usage

After initializing the isoguard module, the ISO_MeasureInsulation(void) function needs to be calledperiodically according to the set cycle time. The Bender ISOMETER measurement values are evaluated and then

18.12. Isoguard 125


written into the database where further modules can operate on this data. Following measurement values aresaved:

typedef struct {uint8_t valid; // 0 -> valid, 1 -> resistance unreliableuint8_t state; // 0 -> resistance/measurement OK , 1 -> resistance too

→˓low or erroruint8_t resistance; // in intervals (max 3bit)uint32_t timestamp;uint32_t previous_timestamp;

}DATA_BLOCK_ISOMETER_s;

The measured insulation is split into intervals according to the array uint16 const staticir155_ResistanceInterval[7]. For more detailed information see source code.

18.12.5 References


CHAPTER 19

Advanced Software Topics

Section being drafted.

127


128 Chapter 19. Advanced Software Topics

CHAPTER 20

Software FAQ and HOWTOs

This sections shows different kind of actions related to the software.

• How to create a task and change its priority and period?

• How to add a software module and take it into account with WAF

• How to change the multiplexer measurement sequence for the LTC driver?

• How to change the relation between voltages read by multiplexer via LTC6804-1/LTC6811-1 and tem-peratures?

• How to configure the MCU clock

• How to configure the LTC6804-1/LTC6811-1 and SPI clocks?

• How to configure the CAN clock?

• How to configure and drive I/O ports?

• How to add and configure interrupts?

• How to add a database entry and to read/write it?

• How to store data in the backup SRAM of the MCU

• How to manually add CAN entries (transmit and receive) and to change the transmit time period?

• How to programmaticaly generate CAN entries?

• How to change the blink period of the indicator LEDs?

• How to add an entry for the diag module?

• How to configure contactors without feedback?

• How to simply trigger events via CAN?

• How to start/stop balancing the battery cells?

• How to set the initial SOC value via CAN?

• How to add/remove temperature sensors?

• How to change the resolution of the temperature values stored?

129


• How to use and disable the checksum

20.1 How to create a task and change its priority and period?

First, declare a new task configuration appltask_cfg.h file:

/*** Task configuration of the 10ms application task

*/extern BMS_Task_Definition_s appl_tskdef_10ms;

The task configuration is a struct of type BMS_Task_Definition_s and defined as follows:

/*** struct for FreeRTOS task definition

*/typedef struct {

uint32_t Phase; /*!< (ms) */uint32_t CycleTime; /*!< (ms) */OS_PRIORITY_e Priority; /*!< */uint32_t Stacksize; /*!< Defines the size, in words, of the

stack allocated to the idle task. */} BMS_Task_Definition_s;

• Phase: phase offset of the task in ms

• CycleTime: cycle time of the task in ms

• Stacksize: stack size allocated to the task

• Priority: task priority for scheduling

The task priorities are defined by CMSIS and consist of seven priorities:

typedef enum {osPriorityIdle = -3, // /< priority: idle (lowest)osPriorityLow = -2, // /< priority: lowosPriorityBelowNormal = -1, // /< priority: below normalosPriorityNormal = 0, // /< priority: normal (default)osPriorityAboveNormal = +1, // /< priority: above normalosPriorityHigh = +2, // /< priority: highosPriorityRealtime = +3, // /< priority: realtime (highest)osPriorityError = 0x84 // /< system cannot determine priority

// or thread has illegal priority} osPriority;

The priorities osPriorityRealtime, osPriorityHigh, osPriorityAboveNormal andosPriorityNormal are already used by the foxBMS engine and therefore should not be used. Inconlusion the priorities osPriorityBelowNormal and osPriorityLow shall be used.

Second, add the task configuration in the appltask_cfg.c file:

/*** predefined 10ms task for user code

*/BMS_Task_Definition_s appl_tskdef_10ms = { 0, 10, osPriorityBelowNormal, 512/4 };

Third, declare a task handle and a task function in the ´´appltask.c/h´´ file:

/*** Definition of task handle 10ms task

130 Chapter 20. Software FAQ and HOWTOs


*/xTaskHandle appl_handle_tsk_10ms;

/*** @brief 10ms engine application task

*/extern void APPL_TSK_Cyclic_100ms(void);

The task initialization and creation is done in the function APPL_CreateTask() in the appltask.c file.Before assigning the task handle to the newly created task, a new thread needs to be defined for the operatingsystem. This is done by a call of the function osThreadDef(name, thread, priority, instances,stacksz). The function parameters are:

• name: name of the function that represents the task

• thread: os_pthread-pointer to the function that represents the task

• priority: initial priority of the thread function

• instances: number of possible thread instances (0 -> only one instance)

• stacksize

The task handle is now, with a call of osThreadCreate, assigned to the task.

// Cyclic Task 10msosThreadDef(APPL_TSK_Cyclic_10ms, (os_pthread )APPL_TSK_Cyclic_10ms,

appl_tskdef_10ms.Priority, 0, appl_tskdef_10ms.Stacksize);appl_handle_tsk_10ms = osThreadCreate(osThread(APPL_TSK_Cyclic_10ms), NULL);

The implementation of the task should be done like shown in the following example:

void APPL_TSK_Cyclic_10ms(void) {while (os_boot != OS_SYSTEM_RUNNING){

;}

osDelayUntil(os_schedulerstarttime, appl_tskdef_10ms.Phase);

while(1){

uint32_t currentTime = osKernelSysTick();

APPL_Cyclic_10ms();

osDelayUntil(currentTime, appl_tskdef_10ms.CycleTime);}

}

Note:

• Every task should have the while loop while(os_boot != OS_SYSTEM_RUNNING) at the beginningof the funtion. This prevents the task from being executed before foxBMS is completely initialized.

• osDelayUntil(os_schedulerstarttime, appl_tskdef_10ms.Phase) sets the wishedphase offset of the task

• Tasks in FreeRTOS should never finish. Therefore, the actual task implementation is done in a while(1)-loop

• APPL_TSK_Cyclic_10ms serves as wrapper function for task implementation inAPPL_Cyclic_10ms()

20.1. How to create a task and change its priority and period? 131


• The call of osDelayUntil(currentTime, appl_tskdef_10ms.CycleTime) sets the task inblocked state until the cycle time until the next period arrives

• Every task should be secured by the system monitoring module (DIAG_SysMonNotify())

• foxBMS provides two default tasks for user applications with a periods of 10ms and 100ms

void APPL_Cyclic_10ms(void) {DIAG_SysMonNotify(DIAG_SYSMON_APPL_CYCLIC_10ms, 0); // task is

→˓running, state = ok

/* User specific implementations: *//* ... *//* ... */

}

20.2 How to add a software module and take it into account withWAF

The steps to follow are:

• Creation of a new subfolder (for example mymodule) in one of the existing source folders application,engine, general, module, module/utils)

• Copy of all source files to the newly created subfolder

• Modification of the wscript file located in the chosen existing source folder, to add the new module. Forexample, to add a software module in the application folder, in the includes section of the wscript,the following new line has to be added:

os.path.join(bld.srcnode.abspath(), 'src', 'application', 'mymodule'),

In case the new software module has to be used in another existing module, the same line has to be added in thewscript file corresponding to the existing module where it is imported.

20.3 How to change the multiplexer measurement sequence for theLTC driver?

The sequence is defined in module/config/ltc_cfg.c, via the array LTC_MUX_CH_CFG_tltc_mux_seq_main_ch1[], which contains a concatenation of elements like:

{.muxID = 1,.muxCh = 0xFF,

},{

.muxID = 2,

.muxCh = 0,},{

.muxID = 2,

.muxCh = 1,},

There are 4 multiplexers with IDs from 0 to 3 on the foxBMS Slave Units. The multiplexer is chosen with thevariable muxID. Each multiplexer has 8 channels, chosen with the variable muxCh (between 0 and 7). Channel0xFF means that the multiplexer is disabled (i.e., high-impedance mode: none of the 8 inputs is connected to the



output). With the code sequence shown above, multiplexer is first disabled, then channel 0 of multiplexer 2 isread, then channel 1 of multiplexer 2 is read.

Typically, multiplexer 0 and 1 are used for temperature measurement, and multiplexer 2 and 3 areused for balancing feedback (i.e., monitor if a cell is being balanced or not). As a conse-quence, by default, measurements of multiplexer 0 and 1 are stored in a database structure of typeDATA_BLOCK_CELLTEMPERATURE_s and measurement of multiplexer 2 and 3 are stored in a database struc-ture of type DATA_BLOCK_BALANCING_FEEDBACK_s.

For temperature measurements, the variable uint8_t ltc_muxsensortemperatur_cfg[6] contains thelook-up table between temperature sensors and cells: the first entry defines the temperature sensor number as-signed to the first cell, the second entry defines the temperature sensor number assigned to the second cell, andso on. If no look-up table is needed, this array should simply be filled with integers increasing from 0 to numberof temperature sensors minus 1. In this example, muxsensortemperaturmain_cfg[6] has a size of 6 be-cause it is the default number of temperature sensors supported by the foxBMS Slave Units. This must be adaptedat two places:

• In module/config/ltc_cfg.c, where the variable is defined

• In module/config/ltc_cfg.h, in the declaration extern uint8_tltc_muxsensortemperatur_cfg[6]

20.4 How to change the relation between voltages read by multi-plexer via LTC6804-1/LTC6811-1 and temperatures?

The function float LTC_Convert_MuxVoltages_to_Temperatures(float Vout) is defined inltc.c. It gets a voltage as input and returns a temperature. It can simply be changed to meet the applicationneeds.

20.5 How to configure the MCU clock

The configuration is defined in module/config/rcc_cfg.c via two structures:

RCC_OscInitTypeDef RCC_OscInitStruct = {.OscillatorType = RCC_OSCILLATORTYPE_HSE,.HSEState = RCC_HSE_ON,.PLL.PLLState = RCC_PLL_ON,.PLL.PLLSource = RCC_PLLSOURCE_HSE,.PLL.PLLM = RCC_PLL_M, // Oscillator Clock: 8MHz -> (8Mhz / 8) * 336 / 2 ->

→˓168MHz.PLL.PLLN = RCC_PLL_N,.PLL.PLLP = RCC_PLL_P,.PLL.PLLQ = RCC_PLL_Q // Oscillator Clock: 8MHz -> (8Mhz / 8) * 336 / 7 -

→˓> 48MHz};

RCC_ClkInitTypeDef RCC_ClkInitStruct = {.ClockType = RCC_CLOCKTYPE_SYSCLK|RCC_CLOCKTYPE_HCLK|RCC_CLOCKTYPE_PCLK1|RCC_

→˓CLOCKTYPE_PCLK2,.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK, // System Clock Source: PLL-Clock

// (Cortex-Core, AHB-Bus, DMA,→˓memory)

.AHBCLKDivider = RCC_AHBCLKDivider, // Div=1 , AHB CLOCK: 168MHz

.APB1CLKDivider = RCC_APB1CLKDivider, // Div=4 , APB1 CLOCK: 42MHz

.APB2CLKDivider = RCC_APB2CLKDivider // Div=2 , APB2 CLOCK: 84MHz};

20.4. How to change the relation between voltages read by multiplexer viaLTC6804-1/LTC6811-1 and temperatures?

133


Fig. 20.1: Clock system of the microcontroller used in foxBMS

Fig. 20.1 shows a summary of the system clocks, with the variables defined via the structures and their effect(either as divider or multiplier).

On the BMS-Master board, a 8MHz oscillator is used as clock source. It should be noted that some of themultipliers/dividers can take all integers values in a certain range, while others can only take a specific set ofvalues. The values must be defined so that the clock values are within the allowed ranges. These are defined inthe microcontroller datasheet.

20.6 How to configure the LTC6804-1/LTC6811-1 and SPI clocks?

In module/config/ltc_cfg.h, the macro #define SPI_HANDLE_LTC &spi_devices[0] is de-fined. It points to a SPI handle: this SPI device will be used for the communication with the LTC6804-1/LTC6811-1. SPI handles are defined in module/config/spi_cfg.c. Depending on the SPI device chosen, theclock used will be peripheral clock 1 or 2 (this information is found in the STM32F4 datasheet). The clockused by the SPI device is obtained after division of the peripheral clock frequency. In the SPI handle, the valuefor the divider is defined via .Init.BaudRatePrescaler = SPI_BAUDRATEPRESCALER_128. In theLTC6804-1/LTC6811-1 driver, the SPI frequency is read directly via a HAL function and all timings are adaptedautomatically. The user must only ensure that the SPI frequency used for the LTC6804-1/LTC6811-1 is not higherthan 1MHz. This is the maximal frequency allowed for the LTC6804-1/LTC6811-1 communication (as defined inthe LTC6804-1/LTC6811-1 datasheet).

20.7 How to configure the CAN clock?

If the APB1 (Peripheral) clock changes, the CAN timing has to be adapted according to the following formula:

clockCAN =APB1

(prescaler + timequantums)timequantums = 1 + timequantumsBS1 + timequantumsBS2

The timequantums (TQ) are constrained to specific discrete values by the STM32 microcontroller.

Sample Configurations



CAN clock APB1 Prescaler BS1 BS21.0 MHz 42 MHz 3 6 TQ 7 TQ1.0 MHz 32 MHz 4 5 TQ 2 TQ0.5 MHz 42 MHz 6 6 TQ 7 TQ0.5 MHz 32 MHz 8 5 TQ 2 TQ

Example:

change the relevant low level driver handle in file /modules/config/can_cfg.c

CAN_HandleTypeDef hcan1 or CAN_HandleTypeDef hcan2

.Init.Prescaler = 3, // CAN_CLOCK = APB1 = 42 MHz// resulting CAN speed: APB1/prescaler/sumOfTimequants// sum: 1tq for sync + BS1 + BS2

.Init.BS1 = CAN_BS1_6TQ, // --> CAN = 42 MHz/(3*14) = 1.0 MHz

.Init.BS2 = CAN_BS2_7TQ,

timequantums = 1 + 6 + 7 = 14

clock𝐶𝐴𝑁 =42.0

(3 · 14)= 1.0

Further details can be found in STM32F4 datasheet.

20.8 How to configure and drive I/O ports?

The pin configuration of the hardware is is defined in const IO_PIN_CFG_s io_cfg[] in the filemodule/config/io_cfg.c with entries like:

{PIN_MCU_0_BMS_INTERFACE_SPI_MISO, IO_MODE_AF_PP, IO_PIN_NOPULL,IO_SPEED_HIGH, IO_ALTERNATE_AF5_SPI1, IO_PIN_LOCK_ENABLE}

The parameters are:

• Pin: Defines the pin name (defined in module/config/io_mcu0_cfg.h).

• Mode: The possibilities of the mode are defined in module/config io_cfg.c via the enum typeIO_PIN_MODES_e. Often used modes are IO_MODE_AF_PP for use of one alternate function of the pin,IO_MODE_INPUT to use the pin as an input, IO_MODE_OUTPUT_PP to use the pin as an output withpush-pull functionality.

• Pinpull: Defines wether the pin is used without pull-up or pull-down (IO_PIN_NOPULL), to use the pinwith pull-up (IO_PIN_PULLUP) or to use the pin with pull-down (IO_PIN_PULLDOWN).

• Speed: Defines the speed of the pin (IO_SPEED_LOW, IO_SPEED_MEDIUM, IO_SPEED_FAST orIO_SPEED_HIGH).

• Alternate: Defines if the signal/pin uses an alternate function or not. If no alternate function is used this isset to IO_ALTERNATE_NO_ALTERNATE. If the signal/pin uses a alternate function one can choose fromthe possibilities from the enumeration IO_PIN_ALTERNATE_e in module/config/io_cfg.h.

• Pinlock: IO_PIN_LOCK_DISABLE or IO_PIN_LOCK_ENABLE to disable or enable pin locking.

• Initvalue: Sets the initial state of the pin in case of an output pin; The pin is set to IO_PIN_RESET for0/low and to IO_PIN_SET for 1/high. If no value is given for a output pin it is set to low.

As explained above, the signal names are to be defined in module/config/io_mcu0_cfg.h with macroslike:

#define PIN_MCU_0_BMS_INTERFACE_SPI_MISO IO_PA_6

20.8. How to configure and drive I/O ports? 135


where IO_Px_y corresponds to the physical pin on the MCU, with x the port (e.g., A,B,C) and y the pin numberon the port (e.g., 0,1,2).

This configuration is initialized in main.c with the function call IO_Init(&io_cfg[0]).

Pins configured as output are driven with the function with IO_PIN_RESET or IO_PIN_SET to set thepin to low or high. Example (The signal/pin name corresponds to the one defined in module/config/io_mcu0_cfg.h).:

IO_WritePin(PIN_MCU_0_BMS_INTERFACE_SPI_MISO, IO_PIN_RESET); // set pin lowIO_WritePin(PIN_MCU_0_TO_MCU_1_INTERFACE_SPI_MISO, IO_PIN_SET); // set pin high

The states of pins configured as input are read with the IO_ReadPin(<Signalname>) function. The functionreturns IO_PIN_RESET or IO_PIN_SET (0 or 1). Example with the signal/pin name corresponding to the onedefined in module/config/io_mcu0_cfg.h:

IO_PIN_STATE_e pinstate = IO_PIN_RESET;pinstate = IO_ReadPin(PIN_MCU_0_BMS_INTERFACE_SPI_NSS);

20.9 How to add and configure interrupts?

The interrupt configuration can be found in general/config/nvic_cfg.c via the vari-able NVIC_InitStruct_s nvic_interrupts[], which contains entries of the form: {DMA2_Stream2_IRQn, 2, NVIC_IRQ_LOCK_ENABLE, NVIC_IRQ_ENABLE }

The configuration parameters are:

• Symbolic name of interrupt source (as defined in the system file stm32f429xx.h)

• Interrupt priority: number between 0 and 15, a lower number means a higher priority

• Parameter irqlock: if set to NVIC_IRQ_LOCK_ENABLE, the interrupt is locked according to theinitial state and cannot be modified by the interface functions NVIC_EnableInterrupts() orNVIC_DisableInterrupts()

• Initial state of interrupt source: set to NVIC_IRQ_ENABLE to get the interrupt enabled by the ini-tialization function. In case of NVIC_IRQ_DISABLE, the interrupt must be activated by callingNVIC_EnableInterrupts() after the initialization

In general/config/stm32f4xx_it.c, a corresponding callback function must be defined (for examplevoid DMA2_Stream2_IRQHandler(void) for DMA stream 2 of DMA device 2). It will be called whenthe interrupt is triggered.

For a proper operation, the interrupt handling (callback function) has to execute the following steps:

• Clear the pending interrupt with for example HAL_NVIC_ClearPendingIRQ(DMA2_Stream2_IRQn)

• Call the HAL IRQ handler (or a custom handler) with for example:HAL_DMA_IRQHandler(&dma_devices[0])

Note: Interrupt routines with interrupt priority above the maximum FreeRTOS configuration level(configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY) must not call FreeRTOS API functions.These interrupts are real-time interrupts, which are bypassing the operating system. Interrupt routines with in-terrupt priority equal or lower than this maximum level must call the corresponding FreeRTOS API functions withending ...._FROM_ISR().

Check the documentation (datasheet, reference manual) of the interrupt source for additional steps.



20.10 How to add a database entry and to read/write it?

The example of the entry for cell voltages is taken. In engine/config/database_cfg.h, the definitionof a block must be added #define DATA_BLOCK_ID_CELLVOLTAGE DATA_BLOCK_1 with one availableblock. The blocks are defined via the following enumeration:

typedef enum {DATA_BLOCK_1 = 0,DATA_BLOCK_2 = 1,DATA_BLOCK_3 = 2,DATA_BLOCK_4 = 3,DATA_BLOCK_5 = 4,DATA_BLOCK_6 = 5,DATA_BLOCK_7 = 6,DATA_BLOCK_8 = 7,DATA_BLOCK_9 = 8,DATA_BLOCK_10 = 9,DATA_BLOCK_11 = 10,DATA_BLOCK_MAX = DATA_MAX_BLOCK_NR,

} DATA_BLOCK_ID_TYPE_e;

If more than DATA_BLOCK_MAX blocks are needed, it must be changed in the defines:

#define DATA_MAX_BLOCK_NR 11#define DATA_MAX_USED_BLOCK_NR 11

A structure must then be declared for the block ID created:

/* data structure declaration of DATA_BLOCK_ID_CELLVOLTAGE */typedef struct {

uint16_t voltage[NR_OF_BAT_CELLS]; //unit: mVuint32_t previous_timestamp;uint32_t timestamp;uint8_t state;

} DATA_BLOCK_CELLVOLTAGE_s;

This structure can contain all the data needed for the entry. In engine/config/database_cfg.c, a variable with the structure type must be declared DATA_BLOCK_CELLVOLTAGE_sdata_block_cellvoltage[DOUBLE_BUFFERING]. The user can choose SINGLE_BUFFERINGor DOUBLE_BUFFERING. The last step is to add an entry in the structure DATA_BASE_HEADER_sdata_base_header[]:

{(void*)(&data_block_cellvoltage[0]),sizeof(DATA_BLOCK_CELLVOLTAGE_s),DOUBLE_BUFFERING,},

With either SINGLE_BUFFERING or DOUBLE_BUFFERING (the same as in the structure declaration). Whenaccess to the created database entry is needed, a local variable with the corresponding type must be created in themodule where it is needed: DATA_BLOCK_CELLVOLTAGE_s cellvoltage;

Access to a data field is made with the usual C-syntax: cellvoltage.voltage[i]

Getting the data from the database in the local variable is made via: DATA_GetTable(&cellvoltage,DATA_BLOCK_ID_CELLVOLTAGE)

Storing data from the local variable to the database is made via: DATA_StoreDataBlock(&cellvoltage,DATA_BLOCK_ID_CELLVOLTAGE)

20.10. How to add a database entry and to read/write it? 137


20.11 How to store data in the backup SRAM of the MCU

The STM32F4 has 4kB Backup SRAM. Variables can be stored there with the keywork BKP_SRAM which isdefined in src/general/config/gobal.h.

Example:

#define DIAG_FAIL_ENTRY_LENGTH (50)DIAG_ERROR_ENTRY_s BKP_SRAM diag_memory[DIAG_FAIL_ENTRY_LENGTH];

20.12 How to manually add CAN entries (transmit and receive) andto change the transmit time period?

Several steps have to be done to add a transmit message and signal (message and signal in receive direction inparentheses):

File: module/config/cansignal_cfg.h

1. The message name must be added. For TX, i.e., transmit data, a message entry must be added in theenumeration CANS_messagesTx_e: (RX, i.e., receive, CANS_messagesRx_e)

2. The macro #define NR_MESSAGES_TX (#define NR_MESSAGES_RX) must be incremented ac-cordingly

3. Then one or more signal names must be added in the enumeration CANS_signalsTx_e(CANS_signalsRx_e)

4. The macro NR_SIGNALS_TX must be incremented accordingly (NR_SIGNALS_RX)

File: module/config/cansignal_cfg.c

5. The next step is to implement the message.

For TX data, the message must be added in array const CANS_message_tcans_messages_tx[NR_MESSAGES_TX] (const CANS_message_tcans_messages_rx[NR_MESSAGES_RX]).

The message looks like { 0x550, 8, 100, 20, NULL_PTR }

The parameters are:

• Message ID (11bit standard identifier used in foxBMS)

• Data Length Code (i.e., number of bytes), usually 8

• Transmit period in ms: must be multiple of CANS_TICK_MS (irrelevant for RX messages)

• Delay in ms for sending the message the first time: must be multiple of CANS_TICK_MS (irrelevantfor RX messages)

• A function pointer to be called after transmission (or reception), usually NULL_PTR to do nothing

6. Then the signals added in the header must be added in the .c file and in constCANS_signal_s cans_signals_tx[NR_SIGNALS_TX] (const CANS_signal_scans_signals_rx[NR_SIGNALS_RX]).

A signal looks like:

{CANS_MSG_BMS2}, 0, 4, 15, 0, 1, 0, FALSE , FALSE, FALSE, {CANS_SIGNAL_→˓NONE}, &cans_setmux, &cans_getupdatemux

The parameters are:

• Symbolic name of the message containing the signal (defined in cans_messagesTx_e, inthe header file)



• Start bit of signal

• Signal length in bits

• Maximum value (float), not relevant in software at the time

• Minimum value (float), not relevant in software at the time

• Scaling factor (float), not relevant in software at the time

• Scaling offset (float), not relevant in software at the time

• Flag multiplexed (boolean, use FALSE)

• Flag multiplexor (boolean, use FALSE)

• Number of multiplex value (int)

• Symbolic name of multiplexor signal, if not multiplexed use {CANS_SIGNAL_NONE}

• Callback function for setter (when CAN msg is received) (NULL_PTR if no function needed,e.g., for transmit)

• Callback function gor getter (when CAN msg is transmitted) (NULL_PTR if no function needed,e.g., for receive only)

The callback functions must be declared and implemented in cansignal_cfg.c.

The multiplexed signal management is a little bit more complex and therefore described in detail inthe CAN signal module Custom Configuration Examples.

For special cases, a getter and a setter function pointer can be necessary (e.g., a multiplexor signal),but usually:

• setter function pointer directs to function where received signal is stored

• getter function pointer directs to function where signal for transmission is returned

20.13 How to programmaticaly generate CAN entries?

In future releases of foxBMS the automatic code generation for CAN signal and message definition will be used.This is done with a set of python scripts and is currently in alpha stage. Here is a simple introduction of theprocedure to generate a code for CAN related modules:

1. Adapt the CAN database file in .\tools\genCAN\config\BMS.dbc to your needs

2. Call genCAN.py in tools python tools\genCAN.py -i tools\genCAN\config\BMS.dbc

3. Compare and merge the generated files to the respective source and documentation files

The following files are generated per default:

• cansignal_cfg.h

• cansignal_cfg.c

• canmatrix.rst

• can_cfg.c

20.14 How to change the blink period of the indicator LEDs?

It is defined via the three variables in module/utils/led.c:

• led_0_nbr_of_blink

• led_1_nbr_of_blink

20.13. How to programmaticaly generate CAN entries? 139


• led_blink_time

Currently the three variables are set directly in the function LED_Ctrl(). If desired or needed, the three valuescan be read from the database and so set elsewhere in the code.

The time is set in ms via led_blink_time. The LED cycle is divided in two periods, T0 and T1. Each of bothperiods lasts led_blink_time ms. During T0, LED0 is on or blinks and LED1 is off. During T1, LED0 is offand LED1 is on or blinks. The behavior described as ‘’is on or blinks” is defined via led_0_nbr_of_blink forLED0 and via led_1_nbr_of_blink for LED1. If led_0_nbr_of_blink is set to 1, LED0 is on duringT0. If led_0_nbr_of_blink is set to n greater than 1, LED0 will blink n times during T1. For example, ifthe period is set to 3000ms and led_0_nbr_of_blink set to 3, LED0 will have the following behavior duringT0:

• On for 500ms

• Off for 500ms

• On for 500ms

• Off for 500ms

• On for 500ms

• Off for 500ms

The behavior is the same for LED1 with led_1_nbr_of_blink. With this functionality, each LED can blinkindependently n times. If each LED can blink up to 4 times, the LEDs can visually give 16 different messages.

The adjustment of the blink period is provided to make reading by the user easier: for higher number of blinks,the blink period can be made longer: for example, it is easier to count 4 blinks in 3s than 4 blinks in 1s).

20.15 How to add an entry for the diag module?

Adding a new sensitivity level is done in src/engine/config/diag_cfg.h by adding a new #definein:

#define DIAG_ERROR_SENSITIVITY_HIGH (0) // logging at first event#define DIAG_ERROR_SENSITIVITY_MID (5) // logging at fifth event#define DIAG_ERROR_SENSITIVITY_LOW (10) // logging at tenth event#define DIAG_ERROR_SENSITIVITY_CUSTOM (100) // logging at 100th event

and errors can be defined:

#define DIAG_CH_CUSTOM_FAILURE DIAG_ID_XX

and the error is then added in DIAG_CH_CFG_s diag_ch_cfg[] in file src/engine/config/diag_cfg.c:

DIAG_CH_CFG_s diag_ch_cfg[] = {{DIAG_CH_CUSTOM_FAILURE, DIAG_GENERAL_TYPE, DIAG_ERROR_SENSITIVITY_HIGH,DIAG_RECORDING_ENABLED, DIAG_ENABLED, dummyfu},

The number of logged error events can be changed by modifying the value of the macro:

#define DIAG_FAIL_ENTRY_LENGTH (50) // Number of errors that can→˓be logged

Note: The diag module is a powerfull module for general error handling. The user has to be aware of tim-ings when using custom diag entries. As example how to use this module correct syscontrol is choosen. -The function SYSCTRL_Trigger() is called in the 10ms task (ENG_TSK_Cyclic_10ms()), meaning ev-ery 10ms this function must be executed. - In the diagnosis-module header diag_cfg.h there is the enumDIAG_SYSMON_MODULE_ID_e for the different error types that are handeled by the diagnosismodule. For



syscontrol errors there is DIAG_SYSMON_SYSCTRL_ID. - In the diagnosis-module source diag_cfg.c thereis the diag_sysmon_ch_cfg[] array assigning timings to this error, in this case 20ms.

{DIAG_SYSMON_SYSCTRL_ID, DIAG_SYSMON_CYCLICTASK, 20,DIAG_RECORDING_ENABLED, DIAG_ENABLED, dummyfu2},

This means every time SYSCTRL_Trigger() is called, the function indicating “syscontrol is running” has tobe exectued. If this is not done, the diagnosis module will set the syscontrol to the error state. Therefore, the usermust set up functions, which are wanted to be supervised by the diagnosis module, and that they are still running,in this way:

void SYSCTRL_Trigger(SYSCTRL_TRIG_EVENT_e event) {DIAG_SysMonNotify(DIAG_SYSMON_SYSCTRL_ID, 0); // task is running,

→˓therefore// reset state to 0

/* user code */}

20.16 How to configure contactors without feedback?

In the file src/module/config/contactor_cfg.c, the contactors are defined with:

CONT_CFG_s cont_contactors_cfg[NR_OF_CONTACTORS] = {{CONT_PLUS_MAIN_CONTROL, CONT_PLUS_MAIN_FEEDBACK, CONT_

→˓FEEDBACK_NORMALLY_OPEN},{CONT_PLUS_PRECHARGE_CONTROL, CONT_PLUS_PRECHARGE_FEEDBACK, CONT_

→˓FEEDBACK_NORMALLY_OPEN},{CONT_MINUS_MAIN_CONTROL, CONT_MINUS_MAIN_FEEDBACK, CONT_

→˓FEEDBACK_NORMALLY_OPEN}};

The following change must be made to configure a contactor without feedback. In this case, the precharge contac-tor is taken as example:

{CONT_PLUS_PRECHARGE_CONTROL, CONT_HAS_NO_FEEDBACK, CONT_FEEDBACK_TYPE_DONT_→˓CARE}

With this configuration, the feedback value will always be equal to the expected value for the precharge contactor.This configuration should not be used without precautions since the safety level will be reduced.

20.17 How to simply trigger events via CAN?

The CAN message with ID 0x55E is considered as a “debug message”. If received, the functioncans_setdebug() defined in cansignal_cfc.c is called. There, a switch case is used on the first byte(byte0) of the message to define what to do. This means that 256 actions are possible, and that 7 bytes remain totransfer data in the debug message.

20.18 How to start/stop balancing the battery cells?

Currently, this is done by sending the debug message with the first byte (byte0) equal to 14 (0x0E). If the secondbyte is set to 1, balancing will start. If set to 0, balancing stops. The third byte corresponds to the thresholdfor balancing. The minimum voltage is determined at pack level, and every cell whose voltage is greater thanminimum+threshold is balanced.

20.16. How to configure contactors without feedback? 141


20.19 How to set the initial SOC value via CAN?

This is done via the debug message with the first byte (byte0) equal to 11 (0x0B). The SOC is defined via thenext two bytes (i.e., on 16bit: byte1 byte2). The SOC is given in 0.01% unit, which means that the 16bit numbershould be comprised between 0 and 10000. If a smaller value is given, the SOC will be set to 0%. If a greatervalue is given, SOC will be set to 100%.

20.20 How to add/remove temperature sensors?

To remove one temperature sensor, the first step is to change:

#define NR_OF_TEMP_SENSORS_PER_MODULE 6

to:

#define NR_OF_TEMP_SENSORS_PER_MODULE 7

in global.h.

However, this obvious step is not sufficient.

In ltc_cfg.c, the variable LTC_MUX_CH_CFG_s ltc_mux_seq_main_ch1[]which indicates the chan-nel sequence to read on the multiplexer has to be modified. One sensor channel on one multiplexer has to be added.In this example, on the multiplexer with the ID 0 and channel 6 is read additionally.

Concretely:


},{

.muxID = 2,

.muxCh = 0xFF,},{

.muxID = 3,

.muxCh = 0xFF,},{

.muxID = 0,

.muxCh = 0,},{

.muxID = 0,

.muxCh = 1,},{

.muxID = 0,

.muxCh = 2,},{

.muxID = 0,

.muxCh = 3,},{

.muxID = 0,

.muxCh = 4,},{

.muxID = 0,



.muxCh = 5,},{

.muxID = 0, //configure the multiplexer to be used

.muxCh = 6, //configure input to ne used on the selected→˓multiplexer},

must be used instead of:


},{

.muxID = 2,

.muxCh = 0xFF,},{

.muxID = 3,

.muxCh = 0xFF,},{

.muxID = 0,

.muxCh = 0,},{

.muxID = 0,

.muxCh = 1,},{

.muxID = 0,

.muxCh = 2,},{

.muxID = 0,

.muxCh = 3,},{

.muxID = 0,

.muxCh = 4,},{

.muxID = 0,

.muxCh = 5,},

Then the look-up table must be modified: it allows defining the correspondence between multiplexer channel andsensor order in the temperature array. By default, the mapping keeps the same order. In the previous example:

const uint8_t ltc_muxsensortemperatur_cfg[6] = {1-1 , /*!< index 0 = mux 0, ch 0 */2-1 , /*!< index 1 = mux 0, ch 1 */3-1 , /*!< index 2 = mux 0, ch 2 */4-1 , /*!< index 3 = mux 0, ch 3 */5-1 , /*!< index 4 = mux 0, ch 4 */6-1 , /*!< index 5 = mux 0, ch 5 *///7-1 , /*!< index 6 = mux 0, ch 6 *///8-1 , /*!< index 7 = mux 0, ch 7 *///9-1 , /*!< index 8 = mux 1, ch 0 *///10-1 , /*!< index 9 = mux 1, ch 1 *///11-1 , /*!< index 10 = mux 1, ch 2 */

20.20. How to add/remove temperature sensors? 143


//12-1 , /*!< index 11 = mux 1, ch 3 *///13-1 , /*!< index 12 = mux 1, ch 4 *///14-1 , /*!< index 13 = mux 1, ch 5 *///15-1 , /*!< index 14 = mux 1, ch 6 *///16-1 /*!< index 15 = mux 1, ch 7 */

};

must be changed to:

const uint8_t ltc_muxsensortemperatur_cfg[7] = {1-1 , /*!< index 0 = mux 0, ch 0 */2-1 , /*!< index 1 = mux 0, ch 1 */3-1 , /*!< index 2 = mux 0, ch 2 */4-1 , /*!< index 3 = mux 0, ch 3 */5-1 , /*!< index 4 = mux 0, ch 4 */6-1 , /*!< index 5 = mux 0, ch 5 */7-1 , /*!< index 6 = mux 0, ch 6 *///8-1 , /*!< index 7 = mux 0, ch 7 *///9-1 , /*!< index 8 = mux 1, ch 0 *///10-1 , /*!< index 9 = mux 1, ch 1 *///11-1 , /*!< index 10 = mux 1, ch 2 *///12-1 , /*!< index 11 = mux 1, ch 3 *///13-1 , /*!< index 12 = mux 1, ch 4 *///14-1 , /*!< index 13 = mux 1, ch 5 *///15-1 , /*!< index 14 = mux 1, ch 6 *///16-1 /*!< index 15 = mux 1, ch 7 */

};

A last step has to be done in ltc_cfg.h: adjust the size of the array, by changing:

extern const uint8_t ltc_muxsensortemperatur_cfg[6];

into:

extern const uint8_t ltc_muxsensortemperatur_cfg[7];

20.21 How to change the resolution of the temperature valuesstored?

The scaling of the raw values read from the LTC6804-1/LTC6811-1 is made in ltc.c, in the function staticvoid LTC_SaveTemperatures_SaveBalancingFeedback(void). First, the raw data are read fromthe SPI buffer with:

val_ui=*((uint16_t *)(&LTC_MultiplexerVoltages[2*((LTC_NUMBER_OF_LTC_PER_→˓MODULE*i*LTC_N_MUX_CHANNELS_PER_LTC)+muxseqptr->muxID*LTC_N_MUX_CHANNELS_PER_→˓MUX+muxseqptr->muxCh)]));

Then the raw data are scaled and are available in Volt:

val_fl = ((float)(val_ui))*100e-6;

Then the read voltage is converted into a temperature with a look-up table:

val_si = (int16_t)(LTC_Convert_MuxVoltages_to_Temperatures(val_fl));

The last step is to store the temperature into a sint16 variable:

ltc_celltemperature.temperature[i*(NR_OF_TEMP_SENSORS_PER_MODULE)+sensor_idx]=val_→˓si;



At this step, the resolution can be changed. For instance, m°C could be stored instead of °C.

20.22 How to use and disable the checksum

The checksum mechanism is enabled via the following define in the file general.h:

/*fox

* enables checking of flash checksum at startup.

* @var enable flash checksum

* @level advanced

* @type select(2)

* @default 0

* @group GENERAL

*/

#define BUILD_MODULE_ENABLE_FLASHCHECKSUM 1

If the checksum is active, the following parameters must be used at compilation:

python tools\waf-18.12 configure --check-c-compiler=gcc build chksum

Otherwise, the flashed code will not work. In case of problems with the checksum, it can be disabled by settingthe define to 0.

20.22. How to use and disable the checksum 145

CHAPTER 21

Tools used for foxBMS

This section contains a documentation of the tools used with foxBMS.

21.1 Checksum Tool

This section of the documentation shows the software build process and the integration of the checksum intothat process in foxBMS. To setup and enabling/disabling the checksum verification on the microcontroller, seeChecksum Module.

21.1.1 Module Files

Source:

• tools\checksum\chksum.py

Configuration:

• tools\checksum\chksum.ini

21.1.2 Dependencies

Python modules used:

• sys

• os

• ConfigParser

• Bits

• binascii

• numpy

• struct

• argparse

These modules usually are included in a foxConda Python environment.

147


21.1.3 Procedure

Checksum is an after-build process.

python tools\waf-1.8.12 configure --check-c-compiler=gccpython tools\waf-1.8.12 build

21.1.4 How does it work

1. The step

python tools\waf-1.8.12 configure --check-c-compiler=gcc

configures waf as needed to build.

2. The step

python tools\waf-1.8.12 build

builds the files

• foxbms.elf

• foxbms.hex

• foxbms_flash.bin

• foxbms_flashheader.bin

The chksum featured task is perfmored at next as defined in the main wscript. The steps are ofthis task are:

(a) Reading the foxbms.hex file and calculates the checksum. The checksum is written backinto the foxbms.hex file by the checksum script.

(b) Calling the GDB debugger and replaces the initial ver_sw_validation.Checksum_u32 in foxbms.elf with the correct checksum.

(c) Calling the objcopy to regenerate the foxbms_flashheader.bin of foxbms.elf.


The checksum tool is related on the Checksum Module configuration (see Checksum Module).

148 Chapter 21. Tools used for foxBMS

CHAPTER 22

Build

22.1 Requirements

The build process of foxBMS heavily depends on Python, for example, for code generation purposes. foxBMShence comes with its own Python distribution, called foxConda, powered by Anaconda. These build instructionsassume that foxConda was successfully installed and that the PATH environment has been adjusted accordingly.For further information refer to the foxConda documentation.

22.2 Obtaining the sources

FIXME GitHub instruction are to follow.

22.3 Build

python tools/waf-1.8.12 configure --check-c-compiler=gcc build

149

https://continuum.io


150 Chapter 22. Build

CHAPTER 23

Hardware Description

This part of the documentation describes the hardware modules used in foxBMS. Fig. 23.1 shows a block diagramof the foxBMS Master Unit with all its components.

Fig. 23.1: foxBMS Master Unit hardware block diagram

23.1 Supply 0 (primary)

The external supply for the BMS-Master board is divided in a part supplying the interlock circuit, the contactors(SUPPLY_EXT_2), and the rest of the circuit (SUPPLY_EXT_0) as shown in Fig. 23.2 . The foxBMS MasterUnit can be supplied with a voltage between 12V and 24V DC. The primary part of the foxBMS is isolated fromSUPPLY_EXT_0 by an isolating DC/DC converter (IC202). The 5V output of the DC/DC converter is steppeddown to 3.3V by an LM1085 LDO (IC201). The output of IC201 (+3.3V_0) supplies the primary microcontrollerMCU0 and the related circuits.

151


Fig. 23.2: Supply for all circuit parts related to the primary part of foxBMS

23.2 Supply 1 (secondary)

Fig. 23.3: Supply for all circuit parts related to the secondary part of foxBMS

The secondary part of foxBMS is also supplied by SUPPLY_EXT_0 as shown in Fig. 23.3. Also the secondarypart of the BMS-Master board is isolated from SUPPLY_EXT_0 by an isolating DC/DC converter (IC302). The5V output of the DC/DC converter is stepped down to 3.3V by an LM1085 LDO (IC301). The output of IC301(+3.3V_1) supplies the secondary microcontroller MCU1 and the related circuits.

23.3 MCU0 (primary)

Fig. 23.4 shows the boot and reset related circuits of the primary microcontroller MCU0. MCU0 can be manuallyreset by push button S401. Please note that the housing has to be opened to reach S401, therefore resetting MCU0by means of S401 is intended for use in a laboratory setting/debugging situation.

The ADCs of the primary microcontroller MCU0 are supplied with a 2.5V reference voltage provided by anADR3425 (IC401) as shown in Fig. 23.5.

The primary microcontroller MCU0 is clocked by an 8MHz oscillator as shown in Fig. 23.6. An separate oscillator(Q402) is used to clock the RTC (real time clock) integrated in MCU0.

23.4 Interface between MCU0 and MCU1

Besides being linked over the common interlock line, the primary and secondary microcontroller also have acommon SPI data interface. The secondary microcontroller MCU1 acts as the master in the SPI communication.The interface is isolated using an ADUM3401 as shown in Fig. 23.7.

152 Chapter 23. Hardware Description


Fig. 23.4: Boot and reset circuit for the primary microcontroller

Fig. 23.5: ADC reference voltage for the primary microcontroller

23.4. Interface between MCU0 and MCU1 153


Fig. 23.6: Clock circuits of the primary microcontroller

Fig. 23.7: Interface between primary and secondary microcontroller



Fig. 23.8: Interface to the Bender ISOMETER

23.5 Interface to Bender ISOMETER

The BMS-Master board supports Bender ISOMETER IR155-3203/-3204/-3210. Two inputs are provided: onefor a PWM coded diagnostic signal and one for a simple status signal (OK or NOK) as shown in Fig. 23.8. TheBender ISOMETER is supplied SUPPLY_EXT_0 and may be switched on or off (lowside) by the BMS-Masterboard. The input signals are limited to level of 5V with Zener diodes D701 and D702. In order adapt the interfacefor use with a IR155-3204/-3210 device, the solder jumper R705 has to be removed. The input signals are isolatedfrom the microcontoller by an ADUM3301 (IC702).

23.6 CAN_0

The CAN_0 interface is intended to connect additional sensors, such as the Isabellenhütte IVT-MOD-300 currentsensor to the foxBMS Master Unit and the foxBMS Master Unit to other devices such as a test bench control unitor an HMI unit. The circuit in Fig. 23.9 shown the input circuit consisting of protection diode D801, commonmode choke L801, C804, and termination resistors R801 and R802. The CAN transceiver TJA1052 providesisolation and can be put to sleep by the primary microcontroller MCU0 via an CPC1008N optocoupler (IC803).The external part of the CAN_0 interface is supplied by SUPPLY_EXT_0.

23.7 Interlock

The primary and secondary microcontroller share a common interlock line as shown in Fig. 23.10. The interlockline is isolated from both microcontrollers MCU0 and MCU1 by optocouplers. The interlock line is supplied with10mA by a current source (LM317 - IC901). It can be interrupted by the primary microcontroller MCU0 viaoptocoupler IC902 and can be read back by MCU0 via optocoupler IC903. The secondary microcontroller MCU1can interrupt the interlock line via IC904 and read the interlock status via IC905. The 10mA cause a voltage drop

23.5. Interface to Bender ISOMETER 155


Fig. 23.9: Circuit of the CAN interface (CAN_0)



Fig. 23.10: Interlock circuit

on R906, which turns on MOSFET T901. T901 switches the common ground of all contactors (connected to theBMS-Master board and BMS-Extension board). Therefore, when the interlock line is interrupted, the contactorsare no longer supplied and open.

23.8 Contactors

Fig. 23.11: Contactor circuit, exemplariliy shown for contactor 0

The foxBMS Master Unit can control up to 9 contactors: 6 on the BMS-Master board and 3 on the BMS-Extensionboard. The according control and feedback circuit is exemplarily shown for contactor 0 in Fig. 23.11. The contac-tor is switched on and off by an AQV25G2S PhotoMOS (IC1001) by the primary microcontroller MCU0. Everycontactor channel is protected with slow blowing fuse (F1001) type Schurter UMT-250 630mA (3403.0164.xx).The free wheeling diode D1001 is not populated. It has to be inserted when contactors are used, that do not pro-

23.8. Contactors 157


vide an internal free wheeling diode. The contactor interface also supports a feedback functionality for contactorswith auxiliary contacts. The contactor status can be read back by MCU0 via an ADUM3300 (IC1103).

23.9 Isolated USB interface (primary and secondary)

Fig. 23.12: USB interface circuit

Both mircocontrollers MCU0 and MCU1 provide an isolated USB interface, as exemplarily shown for MCU0 inFig. 23.12. A FT231XS-R interface IC (IC1402) converts the USB signal to UART, which can easily be interfacedby the microcontroller. The UART signals are isolated by an ADUM3401 isolation IC (IC1403). The USBinterface can be used to flash the microcontroller and for communication.

23.10 EEPROM

The BMS-Master board provides an 2MB EEPROM for data storage for the primary and secondary MCU (seeFig. 23.13). It uses an SPI interface, which is shared with the SD-Card, which is also connected to MCU0.

23.11 Isolated RS485 Interface

On the BMS-Extension board an isolated RS458 interface is provided. It can be used to communicate with thefoxBMS Master Unit as an alternative to the CAN interface or the UART over USB interface. Moreover, viathis interface, monitoring circuits (slaves) using RS485 instead of CAN or another proprietary communication



Fig. 23.13: EEPROM, exemplarily shown for the MCU0

Fig. 23.14: Isolated RS485 interface circuit

23.11. Isolated RS485 Interface 159


protocol can be connected to the foxBMS Master Unit. Fig. 23.14 shows the RS485 interface schematic. Theexternal part of the circuit is supplied via a voltage applied to pins 5 (7V - 20V) and 6 (GND) of connector X1301.The external supply voltage is also available on pin 1 (GND) and pin 4. IC1301 provides 5V supply voltage for thetransceiver (IC1302) and the external side of the isolator (IC1303). The transceiver (LT1785) features a receiverenable (!RE) and a driver enable (DE) functionality, which can be controlled by the primary microcontrollervia the signals RS485_MCU_0_NRE and RS485_MCU_0_DE respectively. For data transmission the signalsRS485_MCU_0_TX and RS485_MCU_0_RX are used. The data signals are available on connector X1301 pins1 and 2. The data signals and the enable signals are galvanically isolated from the BMS-Master board by anADUM3401 isolator IC.

23.12 Isolated Normally Open Contacts (isoNOC)

Fig. 23.15: Isolated normally open contacts (ISONOC_0 examplarily)

The BMS-Extension board provides 6 normally open contacts (ISONOC_0 to ISONOC_5) for multi-purpose use.Their function is exemplarily described for ISONOC channel 0 ( shown in Fig. 23.15). Isolation and switchingfunctionality are realized by AQV25G2S PhotoMOS (IC2001). The PhotoMOS are controlled by a MOSFET(T2001), which again is switched by the primary microcontroller (ISONOC_0_CONTROL). The PhotoMOSis configured for a maximum load current of 6A at 50V. Diode D1002 is optionally and not populated by de-fault. Both power terminals of the PhotoMOS are available on connector X2001 as ISONOC_0_POSITIVE andISONOC_0_POSITIVE on consecutive pins 1 and 2.

23.13 Analog Inputs

For the acquisition of analog data, there are 5 ADC channels (ANALOG_IN_CH_0 - ANALOG_IN_CH_4) avail-able on BMS-Extension board board. Fig. 23.16 shows the input circuit for channel 0. The analog input of themicrocontroller (ADC_MCU_0_CH_0) is protected by diode D1701, which clamps the input voltage to 3.3V. Bydefault R1701 is shorted with jumper, while R1702 is 7.75kOhm and C1701 is 100nF. The analog input channelsare available on connector X1701. A reference voltage of 2.5V is provided by IC1701 (ADR3425), which cansupply a total load current up to +10mA and sink up 3mA. The reference voltage is available in X1701 next toevery analog input pin. Pin 11 and 12 are connected to GND.



Fig. 23.16: Non isolated analog inputs (analog channel 0 exemplarily)

Note: The analog inputs are not isolated. They are referenced to the same potential as the primary microcontroller.

23.14 Isolated GPIO

Fig. 23.17: Isolated GPIOs (Input 0 and 1; Output 0 and 1 shown exemplarily)

The BMS-Extension board provides 4 isolated inputs and 4 isolated outputs for general purpose (shown in Fig.23.17 ). Two ADUM3402 (IC1902 and IC1903) are used for isolation. Their external side of is supplied bySUPPLX_EXT_0 via a 78L05F linear voltage regulator (IC1901). The inputs are equipped with a 10kOhm pulldown resistor. All isolated GPIOs are available on the connector X1901 pins 1 to 8. Pins 9 and 10 of X1901 areconnected to GND_EXT_0.

23.14. Isolated GPIO 161


23.15 SD Card

Fig. 23.18: SD Card

On the BMS-Extension board also a SD card slot can be found. It is directly connected to the Data Storage SPIof the primary microcontroller. Fig. 23.18 shows the schematic. Via the signal SDCARD_SUPPLY_CONTROL(primary microcontroller) the supply voltage of the SD card can be switched on and off.


CHAPTER 24

PCB Schematics and Layouts

The schematics and the layout of files for the BMS-Master board, the BMS-Extension board, the BMS-Interfaceboard and the BMS-Slave board are available in their dedicated GitHub repository.

Note: To open the schematic and layout files, please download AUTODESK EAGLE.

This repository also contains the bill of material (BOM) and a PDF version of the schematics. Since the BMS-Master board and BMS-Extension board were designed as one unit, the schematic may include pages that wereleft blank intentionally.

Note: To manufacture the printed circuit boards, the BOM (Microsoft Excel file) in each corresponding repositoryshould be used. Before sending the board layout to a PCB manufacturer, the layout files must be checked againstthe design rules provided by this manufacturer, since some board layout settings may depend on its specific designrules and may cause clearance violations (e.g., pad layout).

24.1 BMS-Master board

The PCB layout, schematic and BOM files for the BMS-Master board are available on GitHub: BMS-Master.

24.2 BMS-Extension board

The PCB layout, schematic and BOM files for the BMS-Extension board are available on GitHub: BMS-Extension.

24.3 BMS-Interface board

The PCB layout, schematic and BOM files for the BMS-Interface board are available on GitHub: BMS-Interface.

163

https://github.com/foxBMS/foxBMS-hardware/tree/release-1.0.x

https://www.autodesk.com/products/eagle/overview

https://github.com/foxBMS/foxBMS-hardware/tree/release-1.0.x/BMS-Master

https://github.com/foxBMS/foxBMS-hardware/tree/release-1.0.x/BMS-Extension

https://github.com/foxBMS/foxBMS-hardware/tree/release-1.0.x/BMS-Extension

https://github.com/foxBMS/foxBMS-hardware/tree/release-1.0.x/BMS-Interface


24.4 BMS-Slave board

The PCB layout, schematic and BOM files for the BMS-Slave board are available on GitHub: BMS-Slave.

164 Chapter 24. PCB Schematics and Layouts

https://github.com/foxBMS/foxBMS-hardware/tree/release-1.0.x/BMS-Slave

CHAPTER 25

Recommended Additional Hardware

Before using foxBMS Master Unit and the foxBMS Slave Units with lithium-ion batteries, safety must be con-sidered carefully. The following parts and components are recommended to be used in addition to the foxBMSMaster Unit and the foxBMS Slave Units.

25.1 Isolation Monitor

foxBMS supports an isolation monitor to detect faulty isolation of the battery pack against chassis or batterypack enclosure. Bender ISOMETER IR155-3203/-3204/-3210 are supported and tested, while IR155-3204 isrecommended.

25.2 Power Contactors

To switching high-current capable batteries, mechanical power contactors (power relays) shall be used. For safetyreasons, contactors with auxiliary contacts providing true state feedback are strongly recommended. foxBMS wasdeveloped and tested with the contactors of type Gigavac GX14 (GX14BAB: 12V coil voltage and normally openauxiliary contacts), but will probably work with many other contactors. The most important safety parameters arethe maximum break current and the maximum allowed voltage to be broken. This must carefully be checked bythe user of the foxBMS research and development platform. Further, the pick-up and continuous current of thecontactor coil must be checked to be within the foxBMS electrical ratings. Nevertheless, contactors matching theused battery pack specification (e.g., continuous current, maximum voltage, short circuit current) are mandatory.

25.3 Current Sensor

To measure the battery pack current, CAN based current sensors can be used. The Isabellenhütte IVT-MODand IVT-S shunt based current sensors were tested with foxBMS. The automotive current sensor IVT-MOD 300provides a current measurement range of +/-300A and in addition three voltage measurement inputs with a voltagemeasurement range of +/-600V. Current sensors with higher current measurement ranges are available. Pleasecheck the Isabellenhütte homepage and contact a salesperson to get more information. If another CAN basedcurrent sensor is used, the embedded software on the BMS-Master board must be adapted.

165

https://www.isabellenhuette.de/en/home

https://www.isabellenhuette.de/en/contact


25.4 DC Battery Pack Fuse

When using foxBMS with batteries, a DC fuse in the current path is mandatory. In case of external short circuit ofthe battery pack, this fuse must be able to break the current at the maximum high-voltage of the complete battery.This DC fuse is a critical safety component and needs to be selected very carefully. The different parameters ofthe specific battery pack used must be taken into account (e.g., maximum voltage, expected short circuit current,continuous current).

Fig. 25.1 shows how to set up a basic battery system using these components. In the section Example of a BatteryJunction Box, details can be found on how to use these and other components depending on the used batterysystem.

Fig. 25.1: Block diagram showing the typical topology of a battery system

166 Chapter 25. Recommended Additional Hardware

CHAPTER 26

Example of a Battery Junction Box

This section presents an example of a typical battery junction box. The design must be adapted to the applicationand specific care must be taken by sizing the components to ensure the required safety level.

26.1 Introduction

26.1.1 System Specifications

The Battery Junction Box (BJB) described in this document is designed for mobile and stationary battery systems.The target system has a voltage range between 315V and 567V, while being capable to source and sink a continuouscurrent of up to 320A. The stationary battery consists of up to 14 series connected battery modules. Each moduleis a 15s2p configuration of 2.3V 20Ah lithium-ion NMC/LTO prismatic battery cells.

26.1.2 System Overview

The BJB contains the Battery Management System (BMS) and all safety relevant components. Fig. 26.1 shows aBJB integrated into a 19” enclosure with a 4U height.

Fig. 26.2 shows the block diagram of the BJB. The battery is connected to the BJB at the left side(Batt_Positive and Batt_Negative). The source/sink (e.g., load, charger, inverter) is connected to theright side (Out_Positive and Out_Negative).

The main contactors disconnect the battery from the output terminals. These are normally off and switched on inBMS ON-Mode. The contactors are opened if the BMS detects hazardous conditions (e.g., abnormal battery celltemperature) or in BMS OFF-Mode.

Important: A precharge contactor and resistor are used to limit the inrush current into the inverter DC-linkcapacitor when closing the main contactors at startup.

To break the current flowing if a short circuit condition occurs, a fuse is placed in the positive current path. ACooper-Bussmann FWP-350A fuse was selected for this system. The fuse is rated to 700V DC/AC.

167


Fig. 26.1: BJB top view

Danger: A special high-voltage DC fuse must be used to break high short circuit currents in high voltagebattery systems.

A Manual Service Disconnect (MSD) is placed in the positive current path to ensure a manual disconnection whilethe system is serviced. It is mounted on the front of the BJB for easy access. The MSD used is available with anintegrated fuse or as shunted version without fuse. In case the fused version is chosen, the Cooper-Bussmann fusecan be omitted, but the integrated fuse version is limited to 200A.

The Battery Management System (BMS) is the main control unit of the whole battery system. It collects datafrom the battery modules (e.g., battery cell voltages, cell temperatures) and from the current sensor, and uses thesedata for battery state calculations (e.g., SOC, SOH, SOF). In addition, the BMS controls the power contactors andcommunicates with a superior management unit through the CAN bus.

26.2 Battery Junction Box Part List

26.2.1 In-stock Products

Table 26.1 shows the components used in the BJB. All components were selected to fit the system specificationslisted in System Specifications. If another battery configuration than specified here is used, the voltage and currentratings of these components have to be checked and adapted.

168 Chapter 26. Example of a Battery Junction Box


Fig. 26.2: BJB block diagram

Table 26.1: BJB part list

Part Description Manufacturer Part Suggested SupplierPower Contactors Gigavac GX16BEB (600A) HVC TechnologiesPrecharge Contactor TE LEV200A4ANA MouserPrecharge Resistor 100W 680Ohm FarnellDC Fuse* Cooper

BussmannFWP-Series Mouser

Current Sensor Isabellenhuette IVT-MOD 300 IsabellenhuetteEmergency Off Button Moeller M22-PV/K11 + M22 K01 FarnellInsulation Monitoring Bender ISO F1 IR155 3204 BenderBMS Fraunhofer

IISBfoxBMS Master Unit with foxBMSSlave Units

Fraunhofer IISB

Manual ServiceDisconnect

TE AMP + Manual Service Disconnect Power & SignalGroup

12V Power Supply Meanwell WDR-120-12 MouserPower Switch Kraus &

NaimerG20S D322-600 E Kraus & Naimer

* rated currents and voltages are depending from the used battery cells

26.2.2 Custom Parts

In addition to the components listed in table 26.1, sundries not listed here are needed (e.g., terminal blocks). Table26.2 shows the wires used inside the BJB. Basically only 0.5mm2 wires are used. Wires are used for signals andlow voltage only (e.g., 12V or 24V power supply). The continuous insulation rating must exceed the maximumvoltage of the whole battery pack.

26.2. Battery Junction Box Part List 169


Table 26.2: Litz wires used inside the BJB

Color Cross Section UsageRed 0.5mm2 12V Supply PositiveBlue 0.5mm2 12V Supply GroundOrange 0.5mm2 Insulation MonitoringBlue/Yellow 0.5mm2 Insulation MonitoringBrown/Grey 0.5mm2 CAN HighBrown/Orange 0.5mm2 CAN LowGreen/Orange 0.5mm2 Interlock LineGreen 0.5mm2 Battery Monitoring Backup InterfaceGrey/White 0.5mm2 Battery Monitoring Backup InterfaceBrown/Purple 0.5mm2 Battery Monitoring Main InterfaceRed/Green 0.5mm2 Battery Monitoring Main Interface

For the high power DC connections, copper bus bars are used, since high current pulses can occur. The copperbus bars were fabricated with a cross section of 150mm2 (5mm x 30mm) for the maximum continuous currentspecified in System Specifications.

26.3 Main and Precharge Contactors Wiring

The main and precharge contactors are delivered with bare wire ends. The corresponding crimps and plugs mustbe used to connect them to the foxBMS Master Unit.

26.4 Insulation Monitor Wiring

The Bender insulation monitor is delivered with a socket on its PCB. The corresponding crimps and plugs mustbe used used to connect it to the foxBMS Master Unit.

26.5 Current Sensor Wiring

The current sensor is supplied without its crimps and housings (e.g., by JST). The current sensor has to be wiredto the CAN bus and to a power supply. In addition, voltage sense wires may be connected to measure up to 3voltages in the battery system (e.g., battery voltage, voltage over the DC fuse, voltage over the contactors, voltageon the load side). In the given BJB example, the voltage sensing inputs are monitoring the following:

• Voltage measurement 1: between fuse and main contactor

• Voltage measurement 2: between fuse and service disconnect (MSD)

• Voltage measurement 3: between battery positive and precharge contactor

Note: When the precharge contactor is closed after the main negative contactor has been closed, themeasured voltages are used to ensure a correct precharge procedure.

26.6 Summary of the Assembly Procedure

For developing and building the BJB, the following procedure may be used:

1. Defining the specification of the battery (e.g., maximum current, maximum voltage)



2. Defining the placement of the input (from the battery) and the output (to the user) connectors and the manualservice disconnect

3. Placement of the main parts of the current path (e.g., main contactors)

4. Designing of the copper bus bars (alternatively wire with appropriate cross section may be used)

5. Placement of the BJB electronic parts (e.g., BMS)

6. Wiring of the electronic parts

26.6. Summary of the Assembly Procedure 171

CHAPTER 27

Hardware Toolchain

27.1 Layout and schematics

The layout and schematics were done with Cadsoft Eagle version 6.5.0 which is now owned by AUTODESK.

27.2 Information on Debugging

Two types of debugger have been tested with foxBMS.

• The first one is the Segger J-Link Plus with the adapter for 19-Pin Cortex-M (the adpter is needed to connectthe debugger to the foxBMS Master Unit). A cheaper debugger solution is the Segger J-Link Base whichalso needs the adapter.

• The second type of debugger is the Lauterbach Debugger µTrace for Cortex-M (see the “Products” sectionin the navigation bar on the left). The Lauterbach debugger provides more debugging functionalities, but isalso more expensive than the J-Link.

173

https://www.autodesk.com/products/eagle/overview

https://www.segger.com/j-link-plus.html

https://www.segger.com/jlink-adapters.html#CM_19pin

https://www.segger.com/jlink_base.html

http://www.lauterbach.com


174 Chapter 27. Hardware Toolchain

Bibliography

[ltc_datasheet6804] LTC6804 Datasheet http://cds.linear.com/docs/en/datasheet/680412fb.pdf

[ltc_datasheet6811] LTC6811 Datasheet http://cds.linear.com/docs/en/datasheet/68111f.pdf

[ltc_datasheet] LTC6804 Datasheet http://cds.linear.com/docs/en/datasheet/680412fb.pdf

175

http://cds.linear.com/docs/en/datasheet/680412fb.pdf

http://cds.linear.com/docs/en/datasheet/68111f.pdf

http://cds.linear.com/docs/en/datasheet/680412fb.pdf

release wed dec 13 13:39:20 2017 utc · foxbms, release wed dec 13 13:39:20 2017 utc welcome to...

Documents