Use Model-Based Design To Build a Battery Management System

This example uses:

This example shows best practices for collaborative design in large-scale modeling. The example shows how development teams can build a battery management system (BMS) that uses a Nickel-Manganese-Cobalt (NMC) cell with a capacity of 27 Ah. The example describes MathWorks® tools, tips, and processes that you and your teams can use in these development stages:

Requirements

For any software, the original equipment manufacturer (OEM) generally provides software requirements in Microsoft Excel or Word format. You can convert these requirements to a structured format by using the tools such as Get Started with Requirements Toolbox (Requirements Toolbox) before your team begins development. Having requirements in a structured format enables traceability between artifacts, such as requirements, the model, code, and tests.

Follow these steps to author and import requirements:

Author requirements in Microsoft Excel using the BMSSwRequirements.xlsx template.

On the Data tab of the spreadsheet, click Outline to hierarchically segregate the requirements based on title.

Open the Requirements Editor app in MATLAB. On the MATLAB Toolstrip, on the Apps tab, click Requirements Editor.

To import requirements, on the Requirements tab, in the File section, click Import.

In the Importing Requirements dialog box, for Document type, select Microsoft Excel Spreadsheet.

Specify the location where the document should be saved.
To make the images of the BMS inputs and outputs in the Excel spreadsheet available for import, under Content, select Include graphics and layout.

In the Use As row, set the ID column value to Custom ID, the Summary column value to Summary, and the Description column value to Description. Click OK.

Under Destination(s), in Requirement Set, specify where to store the to store the .slreqx file. By default, the .slreqx file uses the Excel file name.

To import the requirements in .slreqx format with the correct hierarchy, under Callbacks, add the post-callback script named excelHierarchyImport.m click Import.

To open the requirements and access the script, enter this command in the MATLAB® Command Window.

openProject("UseMBDtoBuildaBMS");   %Open project
open("BMSSwRequirements.slreqx");   %Open requirements file in Requirements Editor tool

Under Properties, set the requirement type by selecting an option for Type. Map user information to Informational. Map titles to Container. Map testable requirements to Functional.

Test the functional requirements as a final step. For more information, see System Integration and Test section.

Best Practices for Collaboration and Sharing Projects

MATLAB and Simulink® projects offer many advantages for teams of developers doing large-scale modeling using Model-Based Design. Projects help you to:

Streamline file-sharing and file management.
Handle dependencies across and within developer teams.
Integrate easily with source control and configuration management tools.
Enable componentization, reuse, and modular work.
Increase efficiency and enable organizational knowledge-transfer.

For more information, see What Are Projects?

This activity diagram depicts the workflow for collaborative design using Projects.

Managing Work with Projects

Once requirements are ready, follow these steps to manage work using projects in MATLAB and Simulink.

To create a project, on the Home tab, navigate to New > Project > From Folder. Select the available requirements file.

Define a folder structure that addresses the needs and use cases of various project collaborators. For example, create folders for Requirements, Design, Architecture, and Scripts.

Collaborators can expand the project by adding files to it.

To add files and folders to project path, right-click the file or folder and select Project Path > Add to the Project Path.

Label files for easy access and identification. You can create custom labels such as Code, Requirements, Integration etc, and so forth.

On the Project Shortcuts tab, create shortcuts to access important files quickly.

Once all project files and folders are ready, perform an integrity check on the project. Click Check Project. Make sure that all checks pass.

Version control the project.

System Architecture and Functionality

A modular, scalable, and reusable architecture allows you to more easily maintain your architecture when making updates.

System Composer is a widely used tool for design and development of system and software architecture. System Composer allows you to allocate requirements while refining an architecture model for design and simulation in Simulink. To get started with System Composer, see Compose and Analyze Systems Using Architecture Models (System Composer).

Consider using System Composer when your team has these objectives:

Building architecture models with interfaces and components and establishing relationships via model-to-model allocation
Behaviour modeling via sequence diagrams, state charts, or Simulink models
Defining execution order of component functions
Performing trade studies, investigating specific design concerns, capturing properties via stereotyping, and producing interface control documents

Best Practices for Model Composition and Components

Component-based modeling is the process of breaking down a complex system model into smaller, manageable components. Each component represents a specific functionality or behavior of the system. For information, see Component-Based Modeling.

This example shows a model reference. The model is built in a flat hierarchy, which creates fewer dependencies than a tall hierarchy and enhances parallel build performance.

You can componentize a model at the architecture level as well as at the design level. This section describes best practices for model composition during the design stage of the BMS model.

Follow these steps to create a battery management system and software architecture model using System Composer.

Open new System Composer architecture model.

Add subsystems and model components to meet the requirements you have defined.

You can manually include the input and output interfaces of the BMS in the architecture diagram at the initial stage. Pause on the component boundary to add the ports and then click the added port to configure it as an input or output port.

Name each output and input port according to your requirements.

Follow these steps for all subsystems and connect the outputs to the inputs.

Model the ports at the functional boundary level. In the BMS, external sources provide the StateRequest and Sensors inputs, while the BMS sends BMS_Info and BMS_Cmd as outputs to external modules.

Link each component in the architecture diagram to the independent Simulink models that you created at the design stage using model references. The name of the referenced model is circled in red in this figure.

Create a modular, structured, and scalable architecture by following the best practices for model composition and components described in this example.
Model the battery pack electrical architecture by following the previously mentioned steps. You can design the battery pack using the BatteryPackDesignScript.mlx script or the Battery Builder (Simscape Battery) app.
Model the system architecture by combining the battery plant model and the BMS controller model.

Check that the Simulink data dictionary used for data management in each Simulink model is available in the Interface Editor.

Simulate the model and check that the architecture meets your requirements.

To view example files demonstrating how to develop architecture from requirements, enter this command in the MATLAB Command Window.

open('BMSSwArchitecture.slx');           %Open the software architecture model
sim("BMSSwArchitecture.slx");
open('BMSSystemArchitecture.slx');       %Open the system architecture model

Battery Management System Design

In the BMS model, the architecture acts as the high-level design while the Simulink model functions as the low-level or unit design. The BMS controller includes these subsystems:

Current and Power Limit Calculation
State Of Charge (SOC) Estimation
Charge Management
State Machine
Passive Cell Balancing
Contactor Management
Fault Detection

Best Practices for Interface and Data Management

When using componentization, or model referencing, in collaborative Model-Based Design, you must choose the appropriate location to store model data based on the use case:

For experimenting with temporary models, store data in the MATLAB base workspace.
For permanently storing data that is local to the model, store data in the model workspace.
For permanently storing global data, sharing data between models, and tracking changes made to data, store data in a Simulink data dictionary.

This activity diagram illustrates the ideal workflow for interface and data management.

To help manage data when building a large composite model from scratch, follow best practices by describing the implementation at each level of the model. For more information, see Store Shared Data in Architectural Data Section.

Componentized data management supports:

Componentized development
Developing components or subcomponents independently, without starting from the system model and without the rest of the system files being available
Easy data sharing without excessive linkage between components
Checking consistency of duplicate data definitions
Scoping data to the system and specific level of system hierarchy

The BMS consists of a controller and a plant model. Follow these steps to develop a BMS plant model and a BMS controller model.

Design of BMS Controller Model

Develop separate Simulink models for the subsystems and include the associated Simulink data dictionary.

Use the model workspace or the MATLAB base workspace based on the use case. For guidance on choosing data storage locations, see Best Practices for Interface and Data Management.
Add any custom model reference configurations to the project.
Check that the correct set of reference configurations to the project.
Use libraries, subsystem, and model reference to meet your modeling needs. For more information, see Best Practices for Model Composition and Components.
The battery model of the BMS uses subsystem references. The charger and drive load models are separate subsystems that are referenced in the main model.

You can develop subsystems independently as part of componentization and then integrate them at the end.

Open the BMS controller model.

open('BMS_Software.slx');      %Open BMS controller model
sim("BMS_Software.slx");

### Searching for referenced models in model 'BMS_Software'.
### Found 7 model reference targets to update.
### Starting serial model reference simulation build.
### Successfully updated the model reference simulation target for: CellBalancing
### Successfully updated the model reference simulation target for: ChargeMgmt
### Successfully updated the model reference simulation target for: ContactorMgmt
### Successfully updated the model reference simulation target for: CurrPowerLimCalc
### Successfully updated the model reference simulation target for: DetectFault
### Successfully updated the model reference simulation target for: SOCEstimation
### Successfully updated the model reference simulation target for: StateMachine

Build Summary

Model reference simulation targets:

Model             Build Reason                                         Status                        Build Duration
===================================================================================================================
CellBalancing     Target (CellBalancing_msf.mexa64) did not exist.     Code generated and compiled.  0h 0m 17.804s 
ChargeMgmt        Target (ChargeMgmt_msf.mexa64) did not exist.        Code generated and compiled.  0h 0m 10.097s 
ContactorMgmt     Target (ContactorMgmt_msf.mexa64) did not exist.     Code generated and compiled.  0h 0m 12.261s 
CurrPowerLimCalc  Target (CurrPowerLimCalc_msf.mexa64) did not exist.  Code generated and compiled.  0h 0m 8.3636s 
DetectFault       Target (DetectFault_msf.mexa64) did not exist.       Code generated and compiled.  0h 0m 14.485s 
SOCEstimation     Target (SOCEstimation_msf.mexa64) did not exist.     Code generated and compiled.  0h 0m 9.7081s 
StateMachine      Target (StateMachine_msf.mexa64) did not exist.      Code generated and compiled.  0h 0m 11.563s 

7 of 7 models built (0 models already up to date)
Build duration: 0h 1m 34.535s

Design of Battery Plant Model

The plant model uses a Simscape battery model. The battery model consists of 12s3p cells, with three cells arranged in parallel and 12 cells arranged in series. To create a battery pack, refer to BatteryPackDesignScript.mlx or use the Battery Builder app.

To design a custom battery pack, modify the BatteryPackDesignScript.mlx file according to the required cell configuration.
The highlighted files will be available after you execute the battery pack design script.

The figure shows the generated Simscape battery model.

Open the BMS plant model.

open('Battery_Model.slx');   %Open the plant model

Implementation

The design stage model can generate code that you can verify and validate using various tools. For more information, see Verification and Validation (Simulink Check).

Simulate the model to check that it works as intended. Use the recommended best practices to manage multiple parallel simulations and improve performance.

Open the BMS_Software.slx model.
Simulate each subsystem separately to make sure that no subsystems contain errors.

Log the necessary signals to verify the expected results. Follow Best Practices for Speeding Up Simulation and perform data logging during multiple simulation runs.

Best Practices for Handling Multiple Simulation Run

You can test models with numerous simulations both locally and in the cloud while logging large amounts of data. For more information, see Running Multiple Simulations.

Best Practices for Speeding Up Simulation

Regardless of model complexity, you can speed up simulation performance. For more information, see Five Practical Tips to Speed Up Your Simulink Simulations and Improving Simulation Performance in Simulink.

System Integration and Test

Testing allows you to check that the model functions as intended. Early testing helps identify errors, failures, and defects in the model and code. Simulink® Test provides tools for creating, managing, and executing simulation-based tests for models and generated code to meet requirements. Simulink Test enables you to generate baseline data from previous runs and compares the data with the output of new tests. Additionally, you can compare data sets from different MATLAB versions. For more information, see Simulink Test.

Follow these steps to create Model-In-Loop (MIL) tests using Simulink Test.

Create the test harness that uses input sources for the model under test. For information, see Create a Test Harness (Simulink Test).
To test the subsystem, right-click on the StateMachine and select the TestHarness option, then click the Create for State_Machine option in the context menu.

In the Create Test Harness dialog box, specify the inputs and outputs, and leave the other options at their default selections.
Click OK to create the test harness. The system will create the test harness model in .slx format and the metadata file in .xml format.

Open Simulink Test from the Apps tab, located under Model Verification, Validation, and Test.

Open Simulink Test Manager from the Tests tab.

Create a new test file, name it, and specify the location for saving the .mldatx file.

Create test cases within the test file, setting the model under test and the test harness appropriately.

Map external inputs from a .mat file to the test case in the input section.

Configure the signal editor of the harness model to consider the scenario from the .mat file.

Save and run the testcase to verify the output.

Export test report if needed for analysis purpose.

Open and run Simulink Test.

open('StateMachine_Test.mldatx');    %Open test for state machine model

Data Traceability

The data traceability file (.slmx file) links to the model. Traceability between development artifacts allows you and your team to easily track defects and maintain files related to the project.

Link the software architecture components to their respective Simulink models to establish traceability between artifacts from different development stages.

Link the architecture components to respective models.

Link the software requirements to the Simulink model.

Best Practices for Upgrading Your Model

Upgrading your model each release allows you to integrate newer components and functionality. When you upgrade, you can:

Take advantage of new features.
Save time by replacing custom tools with built-in MATLAB and Simulink functionality.
Ensure continued compatibility with third-party tools.

Upgrading to the newest release also makes future upgrades easier to set up.

Create a MATLAB script that calls and runs the Upgrade Advisorruns regression testing, and generates reports for large projects or organization-wide upgrade efforts.

Conclusion

This example provides guidance for systematic Model-Based Design development and highlights best practices and tools for collaborative design, including: