6.11. Contactor

The contactor module is part of the foxBMS-Modules layer.

The contactor module switches the contactors according to the requests that are made to it. It checks the feedback line of each contactors periodically.

6.11.1. Module Files

  • embedded-software\mcu-primary\src\module\contactor\contactor.c (contactor.c)
  • embedded-software\mcu-primary\src\module\contactor\contactor.h (contactor.h)
Driver Configuration:
  • embedded-software\mcu-primary\src\module\config\contactor_cfg.c (contactor_cfg.c)
  • embedded-software\mcu-primary\src\module\config\contactor_cfg.h (contactor_cfg.h)

6.11.2. Structure

Fig. 6.15 shows the statemachine managing the contactors in foxBMS.


Fig. 6.15 Contactor state machine

Three states are implemented:


STANDBY corresponds to the state where all the contactors are open. NORMAL and CHARGE correspond to a state where the contactors of one of the powerlines are closed to allow current flowing.

The CHARGE state is available only if the switch BS_SEPARATE_POWERLINES in embedded-software\mcu-primary\src\general\config\batterysystem_cfg.h is set to 1. It corresponds to the use of a separate powerline compared to the powerline used in the normal state.

The PRECHARGE state performs the transition between STANDBY and NORMAL /CHARGE: the plus precharge contactor is closed before the plus main contactor, to avoid shorting the battery when closing the contactors.

The transition between the states is made through state request. These are made by the bms module. From STANDBY, the state machine can transition to NORMAL or CHARGE, or the opposite. No transition is possible directly between NORMAL and CHARGE.

6.11.3. Switching Counter

Contactors have a specified number of switching cycles. The number of switching cycles varies depending if the contactor has been opened under load or not. The values have to be taken from the manufacturers manual.

foxBMS uses the following strategy to allow it the user to store the number of switching cycles each contactor has done and track their usage.

The counters for closing, opening and opening under load are stored in the variable bkpsram_contactors_count. The counters are backup into the the second non-volatile memory (EEPROM), when the foxBMS Master Unit is power cycled. This ensures, that even if the RTC battery is at some point completely discharged, the second last counter number of all contactors is still safely stored and available for diagnostic purposes.


Limitations of the contactor swichting counter

If the RTC battery is removed or empty AND the mcu is power cycled, all countings since the last saving (therefore a valid power cycle with charged RTC battery) on the EEPROM are lost.

For details of the counter implementation see the modules diag and the bkpsram.

6.11.4. Module Files

  • embedded-software\mcu-primary\src\module\contactor\contactor.h
  • embedded-software\mcu-primary\src\module\contactor\contactor.c
Driver Configuration:
  • embedded-software\mcu-primary\src\module\config\contactor_cfg.h
  • embedded-software\mcu-primary\src\module\config\contactor_cfg.c

6.11.5. Configuration of the Contactors

A contactor physically consists of an control pin, an optional feedback pin, which can be configured as normally open or normally closed. This hardware condition is mapped in the software in the contactor set-up files in contactor_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., the contactor0 should be the precharge contactor and provides a feedback pin):


Note: if the contactor had no feedback one would define


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

typedef enum {
    CONT_MAIN_PLUS              = 0,
    CONT_PRECHARGE_PLUS         = 1,
    CONT_MAIN_MINUS             = 2,

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 to a contactor object/struct. By using the example above, the contactors must now be configured accordingly. It is assumed that the contactors have a feedback and are of type normally open. The setup summed up would look like this:

Contactor Control pin Feedback pin Hardware feedback configuration

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

CONT_CONFIG_s cont_contactors_config[BS_NR_OF_CONTACTORS] = {

The corresponding feedback state configuration would look like this:

 CONT_ELECTRICAL_STATE_s cont_contactor_states[BS_NR_OF_CONTACTORS] = {
     {0,    CONT_SWITCH_OFF},
     {0,    CONT_SWITCH_OFF},
     {0,    CONT_SWITCH_OFF},


The configuration in cont_contactors_config[] must have the same order as defined in CONT_NAMES_e.

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

At this point the setup of the contactors is finished.

Fig. 6.16 gives a visualization of the configuration.


Fig. 6.16 Contactor configuration

6.11.6. Interaction

The bms module uses the contactor module APIs.