Seth on Simulink

April 18th, 2008

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.

15:30 UTC | 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.

15 Responses to “Bus Objects and Interface Specifications”

1. ABindemann replied on April 21st, 2008 at 15:12 UTC :
   

   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.

2. Seth replied on April 21st, 2008 at 20:28 UTC :
   

   @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.

3. Han Geerligs replied on April 22nd, 2008 at 02:50 UTC :
   

   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?

4. Paul J. replied on April 24th, 2008 at 17:26 UTC :
   

   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

5. Georg Wiedermann replied on May 3rd, 2008 at 14:03 UTC :
   

   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

6. Seth replied on May 6th, 2008 at 21:35 UTC :
   

   @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.

7. Justin Mellor replied on May 8th, 2008 at 05:20 UTC :
   

   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

8. Guilherme Dedecca replied on June 6th, 2008 at 16:15 UTC :
   

   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!

9. Seth replied on June 6th, 2008 at 18:38 UTC :
   

   @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.

10. Doug Forman replied on July 9th, 2008 at 16:04 UTC :
    

    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

11. Doug Forman replied on July 9th, 2008 at 17:20 UTC :
    

    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?

12. Seth replied on July 17th, 2008 at 22:18 UTC :
    

    @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.

13. Maarten replied on August 26th, 2008 at 05:13 UTC :
    

    Seth,

    As far as I can gather, it is not possible to stream data created using signal logging of a virtual bus to an Input port of another model. Could you comment on this?

    I would like to avoid the non-virtual bus stuff since it sounds too much hassle for a medium sized project and I want to keep my diagrams clean (i.e. just press play)

14. Tyler replied on September 26th, 2008 at 16:44 UTC :
    

    Seth,
    I find this discussion helpful, and I would like to ask for further elaboration on Doug’s question about transformations between matlab structs and a non-virtual bus object. I read your response regarding an instance versus a specification. What I would like to be able to do is to avoid buses entirely and have structs be passed as outputs of embedded matlab blocks into other blocks that inherit the type. This doesn’t work, and so it seems that I am forced to make bus objects. Unfortunately, I don’t find an easy way to automatically generate bus objects from these structs (which I would like to edit inside the embedded matlab code). Any clarification is welcome - thanks in advance. -Tyler

15. garla replied on November 5th, 2009 at 11:13 UTC :
    

    what is advantage of exporting the bus object with the format as “cell” and “object”. what is the difference between them?

Leave a Reply

<pre class="code">
a = magic(3);
sum(a)
</pre>

These postings are the author's and don't necessarily represent the opinions of The MathWorks.