Month: April 2017

In 90% of cases, Model-Based Design software there is an integrating with an existing software base.  The primary question “who integrates into whom?”  With answers of either the MBD integrates into the Existing or the Existing integrates into the MBD(1).

The ability to integrate is dependent on the defined interfaces.  There are three interfaces of interest

• Schedule: The calling method (e.g. timing) must be defined.
• Function: The function signature must be well defined.
• Data: Encapsulation of data simplifies the integration

Assuming that the interfaces are well defined then the MBD, or the existing software can easily incorporate the software entities.

A into B or B into A?

The question of what integrates into what can be easy or difficult.  When one environment, say the existing code, consists of utility functions then those functions should be integrated into MBD environment.  If both environments consist of a large body of functions and modules, then the question becomes more difficult.

The first option is to have both code bodies sit “side by side.”  In this case, the interfaces are defined at the top level of the code bases, and the communicate only through this interface.  This is a ‘clean’ approach, but it can create a bottleneck for the data.

The second option is to decompose one of the existing code bases and integrate it into the other environment.  This option takes more upfront work, but it is more flexible and robust in the long run.

Integration methods within Simulink

Simulink provides multiple methods for integrating C and C++ code into MBD models.  The methods for integrating the code assumes that the schedule, function, and data interfaces are well defined as described above.

Final thoughts

This post, by its’ nature, is shorter than most.  Information on what “well defined” and “encapsulated data” is covered in other blog posts.

Footnotes

(1)There is, of course, the third case of the “Klein bottle integration”

The title above is one of the few times you will see an exclamation point after the word “documentation.”  However, you should see it more often.  Document generation, as part of an overall Model-Based Design workflow, enables developers to improve their models more quickly and more efficiently.  For the most part, the required documentation can be automatical generated as part of the Model-Based Design workflow.

Types of documentation

Test and verification activity reports

There are two primary types of test and verification reports; instance and trending.

• Instance report:  This report provides the information on the results of a given “instance” of one or more tests.
• Trending report: Trending reports collect high-level statics such as the total number of tests passed/failed.

Traceability reports

Traceability reports provide information on the coverage of the requirements.  These reports should show the following information

• Percentage of requirements with links to models
• Requirements with tests
• Requirement test status

Unlike test and verification, traceability reports are always trending reports.

“Process” and “documentation” reports

The final type of report tracks the adherence to a defined process; this type of documentation is most frequently seen in safety critical systems.  A process document tracks how models move through the development process.  It is used to verify that all defined stages in the development cycle are completed.

Final thoughts

Documentation serves a vital purpose in the development of software.  It both allows developers to understand the state of their product (tracking documents).  For companies following safety critical processes, both the traceability and process documents are artifacts that are used in support of the development cycle.

 

 

 

It is well documented that the most cost effective point to find a bug is during the requirements definition phase.  Yet companies struggle to enforce good requirement writing guidelines and to maintain the requirements throughout the development lifecycle.  Why?

Requirements hierarchy

When writing requirements the first thing to understand is that there is a hierarchy to requirements.  There are “top level” and “derived” requirements(1).  In some instances, there are test requirements.

• Top-level requirements:  Can be characterized as “end user requirements.”  They describe the top-level interactions of the device.
• Derived requirements: They decompose the top-level requirements into individually testable statements.  Depending on the complexity of the device there may be two layers of derived requirements.
• Test requirements: Test level requirements are a special case of the derived requirements.  For some requirements tracking tools decomposing the derived requirements into individual test requirements for tracking is advantageous.

Guidelines for writing requirements

There are 5 fundamental guidelines for writing clear requirements.

1. Write atomic requirements: Requirements should have only one requirement per item.
2. Use action language:  Each requirement must contain a subject (user/system) and a predicate (intended result, action or condition).
3. Describe what the system will do: Avoid describing how the system will do something. Only discuss what the system will do.
4. Use consistent language: The requirement documents should use consistent language.  A definition document should be written and followed.
5. Write testable requirements:  The requirements should be written in a testable fashion.

A further best practice is to perform design reviews on requirements early on in the writing process.  This ensures that people are following these guidelines.

Maintaining requirements

There are two ways in which requirements change.  First changes to the top level requirements push changes down to the derived requirements(2).  In this case affected derived requirements should be updated.  This is helped if there is a mapping document between the top-level and derived requirements.

The second way in which requirements change is due to limitations or errors found during the design and analysis phase.  These are found when the tests, based on the requirements, fail.  At this point in time, it is up to the test engineer and developer to determine if the error is in the implementation or the requirement. If the error is in the requirement then the requirement should be updated.  Note, using bug tracking software to link tests back to the status of requirements will simplify this process.

Establish requirements traceability

Most Model-Based Design software allows you to establish links between the models and the requirements.  Using these links can help automate and enforce good requirements maintenance habits.  A Simulink example can be found through this link.

Final thoughts

This blog post serves as an introduction to requirements management. Additional thoughts and resources will be laid out in future posts.

Footnotes

(1) The terms “top level” and derived requirements vary from industry to industry; however, the core concept is consistent across industries.
(2) Ideally, any changes in the top level requirements take place early in the design and analysis phase to reduce impacts on cost and time.