Contents

Manage Bus Objects with the Bus Editor

Introduction

The Simulink® Bus Editor is a tool similar to the Model Explorer, but is customized for use with bus objects. You can use the Simulink Bus Editor to:

  • Create new bus objects and elements

  • Navigate, change, and nest bus objects

  • Import existing bus objects from a MATLAB® code file or MAT-file

  • Export bus objects to a MATLAB code file or MAT-file

For a description of bus objects and their use, see Bus Objects.

Base Workspace Bus Objects

All bus objects exist in the MATLAB base workspace. Bus Editor actions take effect in the base workspace immediately, and can be used by Simulink models as soon as each action is complete. The Bus Editor does not have a workspace of its own: it acts only on the base workspace. Bus Editor actions do not directly affect bus object definitions in saved MATLAB code files or MAT-files. To save changed bus object definitions, export them from the base workspace into MATLAB code files or MAT-files, as described in Export Bus Objects.

Open the Bus Editor

You can open the Bus Editor in any of these ways:

  • In the Simulink Editor, select Edit > Bus Editor.

  • In a bus object's dialog box in the Model Explorer, click the Launch Bus Editor button.

  • Enter buseditor at the command line of the MATLAB software.

If no bus objects exist, the Bus Editor looks like the one shown here:

Bus Editor Commands

The Bus Editor provides menu choices that you can use to execute all Bus Editor commands. The editor also provides toolbar icons and keyboard shortcuts for all commonly used commands, including the standard MATLAB shortcuts for Cut, Copy, Paste, and Delete. The Toolbar Tip for each icon describes the command, and the menu entry for each command shows any shortcut. The icons for commands that are specific to the Bus Editor are:

CommandIconDescription

Import

Import the contents of a MATLAB code file or MAT-file into the base workspace.

Export

Export all bus objects and elements to a MATLAB code file or MAT-file.

Create

Create a new bus object in the base workspace.

Insert

Add a bus element below the currently selected bus entity.

Move Up

Move the selected element up in the list of a bus object's elements.

Move Down

Move the selected element down in the list of bus object elements.

Create/Edit a Simulink.Parameter object

Create or edit a Simulink.Parameter object for the selected bus object.

Create a MATLAB structure

Create a MATLAB structure for the selected bus object.

You can use toolbar icons and keyboard shortcuts instead of menu commands whenever you prefer.

Display Bus Objects

The Bus Editor is similar to the Model Explorer (which can display bus objects but cannot edit them) and uses the same three panes to display bus objects:

  • Hierarchy pane (left) — Displays the bus objects defined in the base workspace

  • Contents pane (center) — Displays the elements of the bus object selected in the Hierarchy pane

  • Dialog pane (right) — Displays for editing the current selection in the Contents or Hierarchy pane

Items that appear in the Hierarchy pane or the Contents pane have Context menus that provide immediate access to the capabilities most likely to be useful with that item. The contents of an item's Context menu depend on the item and the current state within the Bus Editor. All Context menu options are also available from the menu bar and/or the toolbar. Right-click any item in the Hierarchy or Contents pane to see its Context menu.

Hierarchy Pane

If no bus objects exist in the base workspace, the Hierarchy pane shows only Base Workspace, which is the root of the hierarchy of bus objects. The Bus Editor then looks as shown in the previous figure. As you create or import bus objects, they appear in the Hierarchy Pane as nodes subordinate to Base Workspace. The bus objects appear in alphabetical order. The next figure shows the Bus Editor with two bus objects, control and main, defined in the base workspace:

The Hierarchy pane displays each bus object as an expandable node. The root of the node displays the name of the bus object, and (if the bus contains any elements) a button for expanding and collapsing the node. Expanding a bus node displays named subnodes that represent the bus's top-level elements. In the preceding figure, both bus objects are fully expanded , and control is selected.

Contents Pane

Selecting any top-level bus object in the Hierarchy Pane displays the object's elements in the Contents pane. In the previous figure, the elements of bus object control, valve1 and valve2, appear. Each element's properties appear to the right of the element's name. These properties are editable, and you can edit the properties of multiple elements in one operation, as described in Editing in the Contents Pane.

Dialog Pane

When a bus object is selected in the Hierarchy pane, or a bus object or element is selected in the Contents pane, the properties of the selected item appear in the Dialog pane. In the previous figure, valve1 is selected in the Contents pane, so the Dialog pane shows its properties. These properties are editable, and changes can be reverted or applied using the buttons below the Dialog pane, as described in Editing in the Dialog Pane.

Filter Boxes

By default, the Bus Editor displays all bus objects that exist in the base workspace. Where a model contains large numbers of bus objects, seeing them all at the same time can be inconvenient. To facilitate working efficiently with large collections of bus objects, you can use the Filter boxes, to the right of the iconic tools in the toolbar, to show a selected subset of bus objects. See Filter Displayed Bus Objects for details.

Create Bus Objects

To use the Bus Editor to create a new bus object in the base workspace:

  1. Choose File > Add Bus.

    A new bus object with a default name and properties is created immediately in the base workspace. The object appears in the Hierarchy pane, and its default properties appear in the Dialog pane:

  2. To specify the bus object name and other properties, in the Dialog pane:

    1. Specify the Name of the of the new bus object (or you can retain the default name). The name must be unique in the base workspace. See Choosing a Signal Name for guidelines for signal names.

    2. Optionally, specify a C Header file that defines a user-defined type corresponding to this bus object. This header file has no effect on Simulink simulation; it is used only by Simulink Coder™ software to generate code.

    3. Optionally, specify a Description that provides information about the bus object to human readers. This description has no effect on Simulink simulation; it exists only for human convenience.

  3. Click Apply.

    The properties of the bus object on the base workspace change as specified. If you rename BusObject to main, the Bus Editor looks like this:

You can use Add Bus at any time to create a new bus object in the base workspace, then set the name and properties of the object as needed. You can intersperse creating bus objects and specifying their properties in any order. The hierarchy pane reorders as needed to display all bus objects in alphabetical order. If you add an additional bus object named control, the Bus Editor looks like this:

You can also use capabilities outside the Bus Editor to create new bus objects. Such objects do not appear in the Bus Editor until the next time its window is selected.

Create Bus Elements

Every bus element belongs to a specific bus. To create a new bus element:

  1. In the Hierarchy pane, select the entity below which to create the new element. The entity can be a bus or a bus element. The new element will belong to the selected bus object, or to the bus object that contains the selected element. The previous figure shows the control bus object selected.

  2. Choose File > Add/Insert BusElement.

    A new bus element with a default name and properties is created immediately in the applicable bus object. The object appears in the Hierarchy pane immediately below the previously selected entity, and its default properties appear in the Dialog pane:

  3. To specify the bus element name and other properties, in the Dialog pane:

    1. Specify the Name of the of the new bus element (or you can retain the default name). The name must be unique among the elements of the bus object. See Signal Names for guidelines for signal names.

    2. Specify the other properties of the element. The properties must match the properties of the corresponding signal within the bus exactly, and can be anything that a legal signal might have. The Data Type Assistant appears in the Dialog pane to help specify the element's data type. You can specify any available data type, including a user-defined data type.

  4. Click Apply.

    The properties of the bus element of the bus object in the base workspace change as specified. If you rename the new element a to valve1, the Bus Editor looks like this:

You can use Add/Insert BusElement at any time to create a new bus element in any bus object. You can intersperse creating bus objects and specifying their properties in any order. The order of the other bus elements in the bus object does not change when a new element is added. If you add element valve2 to control, and secondary and primary to main, the Bus Editor looks like this:

You can also use capabilities outside the Bus Editor to add new bus elements to a bus object. Such an addition changes an existing bus object, so any new bus element appears immediately in the Bus Editor.

Nest Bus Definitions

As described in Nest Buses, any signal in a bus can be another bus, which can in turn contain subordinate buses, and so on to any depth. Describing nested buses with bus objects requires nesting the bus definitions that the objects provide.

Every bus object inherently defines a data type whose properties are those specified by the object. To nest one bus definition in another, you assign to an element of one bus object a data type that is defined by another bus object. The element then represents a nested bus whose structure is given by the bus object that provides its data type.

A data type defined by a bus object is called a bus type. Nesting buses by assigning bus types to elements, rather than by subordinating the bus objects that define the types, allows the same bus definition to be used conveniently in multiple contexts without unwanted interactions. To specify that an element of a bus object represents a nested bus definition:

  1. Create a bus element to represent the nested bus definition, in the appropriate position under the containing bus object, and give the element the desired name. (You can also use an existing element.)

  2. Use the Dialog pane to set the data type of the element to the name of a bus object. The Data Type Assistant shows the names of all available bus types. (You can also specify a nonexistent bus type and define the object later.)

In the preceding figure, if you add to bus object main a third element named valves, set the data type of valves to be control (the name of the other defined bus object) and expand the new element valves, the Bus Editor looks like this:

The bus object main shown in the Bus Editor now defines the same structure used by the bus signal main in the next figure:

The distinction between a bus object and the bus type that it defines can be useful for initially understanding how nested bus objects work and how the Bus Editor handles them. In other contexts, the distinction is mostly an implementation detail, and describing bus objects themselves as being nested is more convenient. The rest of this chapter follows that convention.

You can nest a bus object in as many different bus objects as desired, and as many times in the same bus object as desired. You can nest bus objects to any depth, but you cannot define a circular structure by directly or indirectly nesting a bus object within itself.

If you try to define a circular structure, the Bus Editor posts a warning and sets the data type of the element that would have completed the cycle to double. Click OK to dismiss the Notice and continue using the editor.

You can use the Hierarchy pane to explore nested bus objects by expanding the objects, but you cannot change any property of a bus object anywhere that it appears in nested form. To change the properties of a nested bus object, you must change the source object, which is accessible at the top level in the Hierarchy pane. You can jump from a nested bus object to its source object by selecting the nested object and choosing Go to 'element' from its Context menu.

Change Bus Entities

You can use the Bus Editor to change and delete existing bus objects and elements at any time. All three panes allow you to change the entities that they display. Changes that create, reorder, or delete entities take effect immediately in the base workspace. Changes to properties take effect when you apply them, or can be canceled, leaving the properties unchanged. The Bus Editor does not provide an Undo capability.

The Bus Editor provides comprehensive GUI capabilities for changing bus entities. You can Cut, Copy, and Paste within and between panes in any way that has a legal result. The Hierarchy and Dialog panes provide a Context menu for the current selection. Pasting a Copied entity always creates a copy, as distinct from a pointer to the original. The Bus Editor automatically changes names when needed to avoid duplication.

Changes made outside the bus editor can affect the information on display within it. Any change to an existing bus object or bus element is visible immediately in the editor. Any change that creates or deletes a bus object becomes visible in the bus editor next time its window is selected.

Editing in the Hierarchy pane

You can select the root node Base Workspace and perform various operations, like export, cut, copy, paste, and delete. The operation simultaneously affects all bus objects displayed in the Hierarchy pane, but does not affect any that are invisible because a filter is in effect. See Filter Displayed Bus Objects for details.

As you use the Bus Editor, the Hierarchy pane automatically reorders the bus objects it displays to maintain alphabetical order. This behavior cannot be changed. However, the elements under a bus object can appear in any order. To change that order, cut and paste elements as needed, or move elements up and down as follows:

  1. Select the element to be moved.

  2. Choose Edit > Move Element Up or Edit > Move Element Down.

You cannot Paste one bus object under another to create a nested bus object specification. To specify a nested bus, you must change the data type of a bus element to be the type of an existing bus object, as described in Nest Buses.

Editing in the Contents Pane

Selecting any top-level bus object in the Hierarchy pane displays the object's elements in the Contents pane. Each element's properties appear to the right of the element's name, and can be edited. To change a property displayed in the Contents pane, click the value, enter a new value, then press Return.

Choose View > Dialog View to hide the Dialog pane to provide more room to display properties in the Contents pane. Choose the command again to redisplay the Dialog pane.

You can use the mouse and keyboard to select multiple elements in the Contents pane. The selected entities need not be contiguous. You can then perform any operation that you could on a single entity selected in the pane, including operations performed with the Context menu. Clicking and editing a value in any selected element changes that value in them all.

The next figure shows the Bus Editor with Dialog View enabled, two elements selected in the Contents pane, and the DataType property selected for editing in the second element:

If you change the value of DataType to single and press Return, the value changes for both elements. The effect is the same no matter which element you edit in a multiple selection:

Editing in the Dialog Pane

When a bus object is selected in the Hierarchy pane, or a bus object or element is selected in the Contents pane, the properties of the selected item appear in the Dialog pane. In the next figure, valve1 is selected in the Contents pane, so the Dialog pane shows its properties:

The properties shown in the Dialog pane are editable, and the pane includes the Data Type Assistant. Click Apply to save changes, or Revert to cancel them and restore the values that existed before any unapplied changes. You can edit only one element at a time in the Dialog pane. If multiple entities are selected in the Contents pane, all fields in the Dialog pane are grayed out:

If you use the Dialog pane to change any property of a bus entity, then navigate elsewhere without clicking either Apply or Revert, a query box appears by default. The query box asks whether to apply changes, ignore changes, or continue as if the navigation had not been tried. You can suppress this query for future operations by checking Never ask me again in the box, or by selecting Options > Auto Apply/Ignore Dialog Changes.

If you suppress the query, and thereafter navigate away from a change without clicking Apply or Revert, the Bus Editor automatically applies or discards changes, depending on which action you most recently chose in the box. You can re-enable the query box for future operations by deselecting Options > Auto Apply/Ignore Dialog Changes.

Export Bus Objects

Like all base workspace objects, bus objects are not saved with a model that uses them, but exist separately in a MATLAB code file or MAT-file. You can use the Bus Editor to export some or all bus objects to either type of file.

  • If you export bus objects to a MATLAB code file, the Bus Editor asks whether to store them in object format or cell format (the default). Specify the desired format.

  • If exporting would overwrite an existing MATLAB code file or MAT-file, a confirmation dialog box appears. Confirm the export or cancel it and try a different filename.

To export all bus objects from the base workspace to a file:

  1. In the Bus Editor, choose File > Export to File.

    The Export dialog box appears.

  2. Specify the desired name and format of the export file.

  3. Click Save.

    All bus objects, and nothing else, are exported to the specified file in the specified format.

To export only selected bus objects from the base workspace to a file:

  1. Select a bus object in the Hierarchy pane, or one or more bus objects in the Contents pane.

  2. Right-click to display the Context menu.

  3. Choose Export to File to export only the selected bus objects, or Export with Related Bus Objects to File to also export any nested bus objects used by the selected objects.

  4. Use the Export dialog box to export the selected bus object(s).

Clicking the Export icon in the toolbar is equivalent to choosing File > Export, which exports all bus objects whether or not any are selected.

Customizing Bus Object Export

You can customize bus object export by providing a custom function that writes the exported objects to something other than the default destination, a MATLAB code file or MAT-file stored in the file system. For example, the exported bus objects could be saved as records in a corporate database. See Customize Bus Object Import and Export for details.

Import Bus Objects

You can use the Bus Editor to import the definitions in a MATLAB code file or MAT-file to the base workspace. Importing the file imports the complete contents of the file, not just any bus objects that it contains. If you import a file not exported by the Bus Editor, be careful that it does not contain unwanted definitions previously exported from the base workspace or created programmatically.

To import bus objects from a file to the base workspace:

  1. Choose File > Import into Base Workspace.

  2. Use the Open File dialog box to navigate to and import the desired file.

Before importing the file, the Bus Editor posts a warning that importing the file will overwrite any variable in the base workspace that has the same name as an entity in the file. Click Yes or No as appropriate. The imported bus objects appear immediately in the editor. You can also use capabilities outside the Bus Editor to import bus objects. Such objects do not appear in the Bus Editor until the next time its window becomes the current window.

Customizing Bus Object Import

You can customize bus object import by providing a custom function that imports the objects from something other than the default source, a MATLAB code file or MAT-file stored in the file system. For example, the bus objects could be retrieved from records in a corporate database. See Customize Bus Object Import and Export for details.

Close the Bus Editor

To close the Bus Editor, choose File > Close. Closing the Bus Editor neither saves nor discards changes to bus objects, which remain unaffected in the base workspace. However, if you also close MATLAB without saving changes to bus objects, the changes will be lost. To save bus objects without saving other base workspace contents, use the techniques described in Export Bus Objects. You can also save bus objects using any MATLAB technique that saves the contents of the base workspace, but the resulting file will contain everything in the base workspace, not just bus objects.

You can configure the Bus Editor so that closing it posts a reminder to save bus objects. To enable the reminder, select Options > Always Warn Before Closing. When this option is selected and you try to close the Bus Editor, a reminder appears that asks whether the editor should save bus objects before closing. Click Yes to save bus objects and close, No to close without saving bus objects, or Cancel to dismiss the reminder and continue in the Bus Editor. You can disable the reminder by deselecting Options > Always Warn Before Closing.

Was this topic helpful?