Seth on Simulink
April 18th, 2008
Bus Objects and Interface Specifications
A few recent comments on this blog have asked about bus
objects. Blog reader KMR
remarked that "bus objects are one of the most important parts of the
whole bus concept: allowing you to lock down an interface." This week I introduce bus objects
and how they can help avoid modeling errors.
Bus objects provide a specification
In an earlier
post, we saw that virtual bus signals do not have to include any
information about the size and datatype of their signals. This information
propagates from the other blocks (like sources and Inports) in the diagram.
The simplebusdemo.mdl
doesn’t need a specification for the bus signal because it is virtual. Our
mental model of the bus signal is a bundle of rainbow colored wires that link
the sources to their destinations. We often refer to a bus as a tie-wrap of
signals.
If you did want to lock down the description of this bus,
you must use a bus object. If the bus is the rainbow colored bundle of wires,
in my mental model the bus object is the definition for the cable
connector at the end of that bundle. It defines all the pins and their
exact configuration and asserts that only those types of signals may be
connected.
Check “Specify properties via bus object” and include the
bus object name on the Bus Creator blocks to add the specification to your
model. I’ll get to creating bus objects in the next section.
Bus Creators use bus objects for error checking. If the
input signals do not have the same types and dimensions as the elements in the
bus object Simulink will error. There is also a connectivity diagnostic to
check for element name mismatch in the bus object. Turn the diagnostic up to
warning or error to ensure your signals are consistent with the block
specification.
Making a bus object
The easiest way to make a bus object is directly from your
diagram. Simulink.Bus.createObject
is a function that generates a bus object for the block you specify based on
your diagram. Specify the bus creator or port that has the highest level in
the hierarchy of the bus. Simulink.Bus.createObject recursively creates bus objects for buses
that feed into the given block. For our example, the main_bus is specified by the
simplebusdemo/Bus Creator (not Bus Creator1 or Bus Creator2).
>> Simulink.Bus.createObject('simplebusdemo', 'simplebusdemo/Bus Creator');
>> whos
Name Size Bytes Class Attributes
ans 1x1 272 struct
bus1 1x1 Simulink.Bus
bus2 1x1 Simulink.Bus
main_bus 1x1 Simulink.Bus
To look at bus objects, use the buseditor. (click to enlarge)
As of R2008a Simulink has a new bus editor, so unless you
are using this release, your version will look different. The left pane shows
all bus objects in the workspace. The selected node in the tree displays its
children in the center pane, and on the right, you have the details for each
selected element. The information about dimensions, datatype and signal name
are all a part of the bus object. For hierarchical bus signals, the element
datatype is the name of another bus. Looking at the main_bus, it has two
signals, bus1 of type bus1, and bus2 of type bus2. The name and type do not
have to match, but they do in this case.
If you are happy with your bus objects, I recommend saving
them to a MAT-file so you do not have to regenerate them every time. Some
people prefer to generate an M-file and call that as part of their initialization
routines, instead of loading the MAT-file. I have automatically generated this
M-file during the call to Simulink.Bus.createObject. Given an output file
name, Simulink.bus.createObject also outputs the code you need to make that bus
object.
>> Simulink.Bus.createObject('simplebusdemo',...
'simplebusdemo/Bus Creator','simplebusdemo_busScript');
Bus specification in action
If I change my constant input signal to be type int8 instead
of double Simulink will throw an error during update diagram (Ctrl-D).
The input bus to block
'simplebusdemo_bo_error/Bus Creator1' does not match the bus specified by the
bus object 'bus1' on the block dialog. The following errors were detected :
Bus element 'Constant' of bus
object 'bus1' is specified to be of datatype 'double', but the incoming signal
has a datatype of 'int8'.
As you can see, the bus object has locked down the
specification for the signals fed into the bus creator. When something does
not match Simulink reports an error.
Bus objects can be specified on ports
In addition to the bus creators, Inports and Outports can
also be fully specified with a bus object. When a bus object is used on a port
you are asserting that only that special type of connector can be used with
that port. This port could be a root level Inport or Outport, or a port on a
subsystem. If the subsystem is in a library, you have defined its interface,
and all instances of the library block must match the specification.
Getting back to the comment that “[bus objects] are one of
the most important parts of the whole bus concept: allowing you to lock down an
interface.” The concept of locking down an interface is important to
developing reusable components as well as working with others on large modeling
projects. This is a very powerful concept I have seen used in conjunction with
an interface control document (ICD) to define the interface to a system. The
document specifies the characteristics of the bus signals, and the bus object
enforces that those characteristics are true.
I have also seen a Simulink model specify the interface, with a script used
to generate the ICD from the model. This makes the Simulink model the single
source of truth. Your model will always be in sync with the specification if
this is your workflow.
Now it’s your turn
What do you think about bus objects? Do you use them? I
still have not had anyone volunteer to show off their use of bus signals with a
screen capture from their model. Leave a comment
and then send
me an e-mail with the image. I will post it for you and we can all marvel
at your work.
3:30 pm |
Posted in Signals |
Permalink |
You can follow any responses to this entry through the RSS 2.0 feed.
You can skip to the end and leave a response. Pinging is currently not allowed.
Leave a Reply
|
Seth,
I’ve appreciated the progression of your recent posts (mux, virtual-buses, bus-objects).
I’ve suspected for a while that using bus-objects might be worthwhile but still haven’t seen much justification as to why I should spend the time to define bus-objects, and then incorporate the initialization logic to load the bus-objects in the model.
I guess I can see it would be worthwhile if I am delivering a model to another party, and want to ensure the interface is rigorously defined.
I’m hoping future posts can shed some additional light on the following points on bus objects:
1) What makes bus objects useful beyond locking down an interface
2) When is their use highly recommended
3) When is their use not worthwhile.
Also, some details of recommended strategies for loading bus objects would be appreciated. For example, should they be loaded in the subsystem initialization callback, or the Model Properties initialization callback?
Thanks much for the blog, it fills a much needed gap.
@ABindemann - Thanks for the feedback. The models I have been using don’t make the case for me, so here it is: bus objects were introduced in R14 to provide interface specification for model reference. Rigorous control over interfaces is needed when you are going to be doing modular development of a model. Model reference allows individual components to be developed separately and brought together at a later time. Bus signals are important in large scale model development to keep things organized, so the bus interface specification was born.
I am going to have to think about the best practices for loading information relevant to the model and post about that at a later time. I have seen great success in keeping it simple. Some of the largest models I work with are manually initialized with a startup script.
Hi Seth,
I’ve read your blog with great interest.
I have a suggestion in making buses even more useful for Code Generation.
When using Data Objects for parameters the user gets control on exporting parameters to an external interface (i.e. CAPI interface) by setting the storageclass to SimulinkGlobal. I am missing such a mechanism for signals. This leads to CAPI structures taking very much memory space.
One might use the Bus Data Object to control the export to the external interface.
In order to get around the memory subject I had to adapt the capi.tlc file.
Are you considering to use Data Objects (i.e. Bus Data Objects or Simulink.Signal objects) to manage this?
Seth,
I too could use more discussion on ABindemana’s three questions about bus objects. I would also add the questoin about when they are required. In addition I ask what’s the best way to save a bus signal to the workspace? From what I can see, the ToWorkspace block only accepts a virtual bus signal, so nonvirtual busses have to be converted first. Then, the signal is saved as a big array and one has to go back into the bus creator block to figure out which columns in the workspace variable are which bus signals. How come the the ToWorkspace block doesn’t just save the bus as a structure array with fieldnames set as the bus signal names?
Thanks,
Paul J
Dear Seth,
thank you for this blog on Simulink. With virtual vs. nonvirtual busses and bus objects I think you have tackled a very interesting topic. Do you also plan to expand to other Simulink data objects (signal objects, parameter objects …)? For me, and maybe also for others users the real value of this objects is unclear. So
* what is the value of signal objects ?
* where should I use them ?
Further I have the impression, that data declaration as done be Simulink data objects is inconsistent. For example since a bus is a collection of signals, a bus objects should be defined by a collection of signal objects, which is obviously not the casse. Maybe you can comment on this.
Best Regards
Georg Wiedermann
@Paul J - The To Workspace block does not support bus signals, so when you are passing it a virtual bus it is actually treating it like a vector. The best way to log bus signals is using Signal Logging. Right click on a signal and select Signal Properties… From the dialog you can specify to “Log signal data”. This will be added to the Time Series object logged to the workspace as specified in the Data Import/Export section of Configuration Parameters.
@George Wiedermann - You ask a very good question. There is a big difference between bus objects and the signal/parameter objects. The bus objects are a specification for an interface and contain no instance data. They can be used many times in a model. Signal objects define read/write memory which will define a specific signal or state used by the model. Parameter objects define the attributes of parameters used by blocks (such as gain blocks). The Signal and Parameter objects are important when you want to configure the characteristics of the generated code. For example, if you want to specify that a signal be an exported global in the generated code, this can be done with a Simulink.Signal object.
Seth,
I have just ‘tuned in’ to this discussion about bus signals. As I am in the process of integrating a large mode using Model References for all the major components of the system, this is highly relevant. I definitely need to lock down the interfaces to the different components - these are being developed across multiple sites in accordance with an Interface Control Document that we have produced.
I have a question:
The interconnects between our components are a mixture of busses and individual signal lines. I can use Simulink.Signal objects to define the characteristics of these individual signals, creating them using the Model Explorer, however, I don’t know how to save these signals as M-files (there does not appear to be an equivalent to Simulink.Bus.save for signal objects). Saving the objects as M-files rather than MAT-files gives us the option to look at the files and edit them.
Regards
Justin Mellor
Hello Seth!
I’ve been developing a model and I started using Bus Objects at the root-level inputs to specify the signals they are expected to receive. By doing this, I could propagate the expected signals at root-level Inputs to the rest of the model and use them at Bus Selectors, for exemple.
The time has come to simulate the model, and I wanted to use the Data Import/Export feature to apply several test cases to the inputs of the model. But, as far as I could find, the only way to import data to Inports that use Bus Objects is if the data is packed into an Simulink.TSArray object. The problem is that I didn’t find another way to create an Simulink.TSArray object other than to log the signals from a previous simulation and import this logged data back into the model through Data Import/Export.
Is there another way to import Data to Inports that use Bus Objects?
Thank you!
@Guilherme Dedecca - Excellent use of a bus for interface specification! There is a technical support solution about how to create a Simulink.TsArray. It contains a simple example.
There is also a nice file exchange submission from Robyn Jackey that demonstrates how this is done with a nested bus. The helper functions in that file really simplify the process of creating the Simulink TS Arrays.
Seth,
Have you heard of a script (perl or matlab) that can create a Matlab bus object from a C struct definition, (or C++ class definition)?
I am using legacy_code to import several different C functions that access (by reference) global data structures.
Each C function will become a separate S-Function and therefore can’t see global variables declared by the other S-Functions. I am now wanting to convert the C data structures to matlab bus objects that can be accessed by the separate S-Functions.
Thanks ~ Doug
Also,
Is there any relationship possible between a matlab struct and a non-virtual bus object?
Is there a simple transformation between the matlab struct and a non-virtual bus object?
@Doug - I have had many people ask about such a conversion tool. The challenge comes from the variety of types and syntax requirements that C/C++ allow which do not easily map back to Bus Objects. If you write such a tool, please share it on the File Exchange!
Regarding the MATLAB struct and the Bus Object, consider that there is a difference in what these two things are. The Bus Object is a specification, and the struct is an instance. They are similar, but Bus Objects have no values associated with their elements. Simulink.Timeseries and Simulink.TSArray provide a method for specifying the value of a bus signal for inputs to a model.