{"id":53,"date":"2009-04-17T14:05:17","date_gmt":"2009-04-17T14:05:17","guid":{"rendered":"https:\/\/blogs.mathworks.com\/seth\/2009\/04\/17\/s-functions-bus-signals-and-missing-documentation\/"},"modified":"2009-04-17T14:05:17","modified_gmt":"2009-04-17T14:05:17","slug":"s-functions-bus-signals-and-missing-documentation","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/simulink\/2009\/04\/17\/s-functions-bus-signals-and-missing-documentation\/","title":{"rendered":"S-functions, Bus Signals, and Missing Documentation"},"content":{"rendered":"

This almost never happens, but today I get to share with you\r\nan undocumented<\/em> Simulink capability! In R2009a the S-function builder\r\nhas the ability to accept bus signals at its input and output ports.\u00a0 We accidentally\r\nomitted the updated doc section when R2009a shipped.\u00a0 You can find the missing\r\ndocumentation here<\/a>, but I still want to tell you about how to use bus\r\nsignals with S-function Builder.<\/p>\r\n\r\n

What is an S-function?<\/strong><\/p>\r\n\r\n

If you want to build your own custom block in Simulink, we\r\nprovide a couple ways to do it.\u00a0 For now, I am going to ignoring masked\r\nsubsystems and reference models and focus on block authoring in the truest\r\nsense, the S-function.\u00a0 The "S" in S-function stands for System (or\r\nmaybe Simulink).\u00a0 S-functions define how a block works during the different\r\nparts of the simulation, for example: initialization, update, derivatives,\r\noutputs, and termination.\u00a0 S-function are often used as a gateway to other\r\nsimulation environments, interfaces to hardware or software.\u00a0 There are a few\r\nways to implement\r\nan S-function<\/a>, such as using an M-file or a C-MEX file.\u00a0 \u00a0There are also\r\ntools like the S-function\r\nBuilder Block<\/a> and the Legacy\r\nCode Tool<\/a> to make it easier to write S-functions.<\/p>\r\n\r\n

\"The<\/p>\r\n\r\n

The S-function must define itself as a system.\u00a0 You have to\r\ndefine the interfaces and algorithm for the system.\u00a0 The interfaces to the\r\nsystem are the ports and parameters of the block.\u00a0 For a long time, users have\r\nasked for the ability to write an S-function that accepts a bus signal as the\r\ninput, or provides a bus signal as the output.\u00a0 This is the capability added in\r\nR2009a for the S-function Builder.<\/p>\r\n\r\n

S-functions and Bus Signals<\/strong><\/p>\r\n\r\n

In January 2005, Tom\r\nErkkinen<\/a> posted the Legacy Code Tool (LCT) to the MATLAB Central File\r\nExchange.\u00a0 The Legacy Code Tool helps you integrate\r\nexisting C functions into your Simulink model<\/a> by generating an S-function.\u00a0\r\nLCT has been shipping with Simulink since R2006b.\u00a0 One of the major\r\ncapabilities of LCT is the ability to interface to bus signals.\u00a0 If your\r\nfunction requires a structure input or returns a structure output, LCT can\r\ngenerate the wrapper S-function that handles a bus signal.<\/p>\r\n\r\n

S-function Builder Bus Support<\/strong><\/p>\r\n\r\n

I think the S-function Builder block is the easiest way to\r\nbring a short C code algorithm into your Simulink model.\u00a0 New in R2009a, the S-function\r\nBuilder block now supports bus signals for the input and output ports.\u00a0 There\r\nis a demo model called sfbuilder_bususage<\/strong>.\u00a0 Here is how it works:<\/p>\r\n\r\n

The S-function builder works like many software wizards, and\r\nleads you through the process of writing an S-function.\u00a0 When you double click\r\non the S-function builder block, you get a GUI that looks like this.<\/p>\r\n\r\n

\"The<\/p>\r\n\r\n

If you start on the left most tab, add information in each\r\ntab, by the time you have reach the last tab, you are done.\u00a0 To include a bus\r\ninput in the S-function builder, you need to define a bus object.\u00a0 In a\r\nprevious post, I talked about how to do use bus\r\nobjects as interface specifications<\/a>.\u00a0 The Data Properties tab defines all\r\nthe information for the ports of the S-function.\u00a0 First, you have to define the\r\ninputs and outputs of your system.<\/p>\r\n\r\n

\"The<\/p>\r\n\r\n

To include a bus, turn the Bus property ON, and se the Bus\r\nName to the bus object in the base workspace.\u00a0 Next, you have to access\r\nelements of the bus using standard C structure indexing.\u00a0 Here is a snippet\r\nfrom Outputs function that accesses signals from the bus.<\/p>\r\n\r\n

\"C-code<\/p>\r\n\r\n

That is all there is to it.\u00a0 The bus object can optionally include\r\na C header file that defines the C structure definition for the bus. You can\r\nspecify this in the Bus Editor:<\/p>\r\n\r\n

\"The<\/p>\r\n\r\n

If you include the header file in your bus object, the S-function\r\nbuilder will use it.\u00a0 If you don\u2019t specify the header file, the S-function\r\nbuilder will generate one for you that looks like this:<\/p>\r\n\r\n

\"The<\/p>\r\n\r\n

Wait a second, why isn\u2019t this in the doc?<\/strong><\/p>\r\n\r\n

It was just an oversight.\u00a0 There were many changes made to\r\nthe doc, and we forgot to include this one.\u00a0 Luckily, when we realized the doc\r\nwas not complete, technical support came to the rescue.\u00a0 We have published a\r\nrevised section of the S-function builder documentation through a solution\r\ntitled:<\/p>\r\n\r\n

How can I\r\ninput and output Bus signals to and from an S-function created using the\r\nS-function builder in Simulink 7.3 (R2009a)?<\/a><\/p>\r\n\r\n

Now it\u2019s your turn<\/strong><\/p>\r\n\r\n

Do you write S-functions?\u00a0 Have you tried this feature?\u00a0\r\nLeave a comment\r\nhere<\/a> and tell me about your experience.<\/p>\r\n","protected":false},"excerpt":{"rendered":"

This almost never happens, but today I get to share with you\r\nan undocumented Simulink capability! In R2009a the S-function builder\r\nhas the ability to accept bus signals at its input and output... read more >><\/a><\/p>","protected":false},"author":40,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[87,11,16],"tags":[12,459,441],"_links":{"self":[{"href":"https:\/\/blogs.mathworks.com\/simulink\/wp-json\/wp\/v2\/posts\/53"}],"collection":[{"href":"https:\/\/blogs.mathworks.com\/simulink\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.mathworks.com\/simulink\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/simulink\/wp-json\/wp\/v2\/users\/40"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/simulink\/wp-json\/wp\/v2\/comments?post=53"}],"version-history":[{"count":0,"href":"https:\/\/blogs.mathworks.com\/simulink\/wp-json\/wp\/v2\/posts\/53\/revisions"}],"wp:attachment":[{"href":"https:\/\/blogs.mathworks.com\/simulink\/wp-json\/wp\/v2\/media?parent=53"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/simulink\/wp-json\/wp\/v2\/categories?post=53"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/simulink\/wp-json\/wp\/v2\/tags?post=53"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}