1822 - Best Practices for Managing Bus Data in Simulink®

Introduction
General Best Practices for working with Bus Data
Storing and Loading Bus Object Data
Mapping bus objects to data source
Bus Signals crossing Model Reference boundaries

Section 1: Introduction

As models increase in size and complexity, the requirements on rigor and discipline managing them increase as well. This is true in Model Based Design just as it is in traditional development approaches. The development and enforcement of a Modeling Style is essential. The best practices and workflows discussed here will often require an investment in utilities and tools for enforcement ( for example: Model Advisor with custom Model Advisor Checks).

This article describes the best practices for managing Simulink Bus Signals and the associated Bus Object data that cross Model Reference boundaries. While some of the information and best practices may be relevant for other data management issues, these Best Practices do not attempt to resolve larger Simulink Data Management questions.

This article assumes basic knowledge of composite signals in Simulink. You can refer to the Simulink product documentation for detailed information on the use of busses. The Real-Time Workshop Embedded Coder documentation also has useful guidelines on the use of Bus signals from a code generation point of view.

Section 2: General Best Practices For Working With Bus Data

As discussed in the Simulink product documentation, bus signals can be virtual or non-virtual. Virtual busses are convenient modeling constructs which allow signals to be grouped and organized. Non-virtual busses generate corresponding data structures in the generated code but require a contiguous memory allocation in Simulation. Non-virtual buses are also more restrictive in usage than virtual buses. For example, non-virtual bus objects require that all the elements have the same sample rate. A good modeling style will employ both virtual and non-virtual busses depending on the model organization and code generation needs.

Bus Data Crossing Model Reference Boundaries

Model referencing is the idea of embedding an independent model file within another model. Model referencing requires that the external interfaces of the embedded model be fully defined such that the parent model can understand the input/output (I/O) structure and thus communicate with the referenced model. The first general best practice is to use non-virtual busses when crossing model reference boundaries. Users employ model reference to define a standalone and fully contained component of their algorithm. For the generated code of this component to have a well defined data interface it is required to pass bus signals which are non-virtual. Simulink actually requires this.

In case you are using Stateflow charts and Embedded MATLAB block as functional units of your algorithm that require the bus signal packaged into a data structure argument in the generated code, the input interface to these components also has to be explicitly using a Bus object. Without this Stateflow charts and EML blocks treat the inputs as vector signals.

Use Virtual Busses Within the Functional Unit

When working within a model reference block, use virtual busses whenever possible. This will reduce the burden of managing bus data. The check one should make before using a non-virtual bus is whether or not a separate data structure is absolutely needed in the generated code. Section 5 of this document has information on automating bus data packaging at the model reference boundaries. For more information on this topic, refer the following sections in Real-Time Workshop Embedded Coder documentation Optimizing Virtual and Nonvirtual Buses, Using Single-Rate and Multi-Rate Buses.

Strip Out Unneeded Data from the Bus Object

Another best practice is to develop modeling constructs which strip out unneeded data from bus objects crossing Model Reference Boundaries. In large models, bus objects can become quite large and have several levels of hierarchy. Often model references need some, but not all, of the data contained within these large busses. Passing unneeded data across Model Reference boundaries negatively impacts performance. The interface definition for a model should specify exactly what is used by that model.

Section 3: Storing and Loading Bus Object Data

Bus Object data can be stored in a variety of formats. The most common formats are discussed below:

MATLAB Files

Bus data can be read and saved via MATLAB file. The Simulink.Bus.save command saves all bus objects (instances of Simulink.Bus class residing in the MATLAB base workspace) in a MATLAB file. Alternately Simulink.saveVars function can be used to save variables from the base workspace to a MATLAB file. The file containing the variables is human-readable and can be edited. Running the file restores the saved variables to the base workspace. The main advantage in this approach is that MATLAB code directly supports all methods and data related to BUS Objects. It is also recommended to maintain a separate MATLAB file with a good naming convention for every model for better traceability. It has to be noted that MATLAB code (.m) may not be a standard data repository for larger organizations.

MAT-Files

Since Bus Objects are a standard MATLAB data, they can be saved and loaded with the standard MATLAB functions. Loading large data from MAT files is faster than using MATLAB(.m) files.

Database (External source)

Interface information can be captured in a database or other external source and then read into MATLAB via scripts and functionality in the Database Toolbox. Databases are often a standard data repository within an organization and can also naturally capture the relations between components. If the primary design environment is Simulink, having a primary data repository in an alternate environment usually requires maintaining scripts for reading external data sources. Using sl_customization, the Bus editor GUI can be customized to import from these data sources. For more information the following section in Simulink documentation can be referred:
http://www.mathworks.com/access/helpdesk/help/toolbox/simulink/ug/bq4icqm-1.html

Note that these approaches can also be combined. Consider the following example. Suppose that you had a large number of variables that you wanted to be able to maintain and difference in CM, but the use of MATLAB files for definition was resulting in slow loading times. MATLAB files gives you traceability and differencing, MAT files gives you fast load times. To workaround these limitations, you could use the following approach:

		if <time-stamps-of-MATLAB-files-same-as-before>
			 load saved_workspace.mat
		else
			 <run MATLAB files>
			 save saved_workspace <allVars>
			 clear all
			 load saved_workspace
		end

Section 4: Mapping bus objects to data source

In addition to storing the Bus objects, as models become complex, the need to keep track of which Bus Objects are used by which Models arises. From any Model or Bus Object, a user should be able to tell what component it needs or is needed by. While Simulink can determine whether all connections are valid and information is present before execution, keeping track of this information is essential for allowing automation and ensuring consistency across all models. The most common methods for storing this information are discussed below.

Map in Base Workspace Variable

A lookup table or other construct can be used to store in the base workspace. Storing data in a MATLAB construct can make accessing information easier. However using a base workspace variable as the central repository for this information can be error prone since it may be overwritten or cleared.

Use a Rigorous Naming Convention

Perhaps the most straightforward approach for managing this information is using a rigorous and standard naming convention. Consider the model and data required for an actuator control function. The model would have the name 'ACTUATOR' and the input and output ports would be named 'ACTUATOR_BUS_IN' and 'ACTUATOR_BUS_OUT' respectively. This naming convention will allow a user to know what models a particular Bus Object is related to and vice versa. Note that this approach can cause issues if the output from one model reference is fed directly to another model reference. In this case, the naming mismatch will result in Simulink error. An alternate approach is to have one MATLAB file per Model which defines the busses required by the model. Proper naming will allow traceability from the model to the definition file. Scripting can allow tracing from busses to models.

Section 5: Automating Bus interfaces at Model Reference boundaries

The practices discussed above are very relevant to large models with many referenced models that have well defined data interfaces. From a safety-critical point of view, this interface definition is not only highly desirable, but in most cases is required. The automation steps below to handle bus objects in referenced models can be a part of a workflow that supports traceability, repeatability, and scalability in large scale modeling. Note that this approach assumes that only one instance of each model will be referenced. Merging issues would arise if multiple instances were used in this approach.

Loading Bus Data: Bus Data is specified and loaded via MATLAB code. These definition scripts are then managed as part of the larger project.
Changing Bus Data - When changes to the bus objects crossing model reference boundaries are necessary, the following process is followed
- Scripts are run which change a Referenced Model to a subsystem and delete bus objects only used by this model
- Changes are made to the subsystem interface
- Scripts are run to convert the subsystem back into a Referenced Model and re-create the MATLAB scripts necessary to load the required Bus objects

Such a scheme would also require a rigorous naming convention. Also note that consideration needs to be given to the differences in structure and behavior between model reference blocks and subsystems. These could include loss of mask variables, elimination of the model workspace, etc. With this approach the referenced models can be more modular and self-contained without data dependencies. A similar scheme can be used to automate packaging required data at the referenced model output ports.