Collecting feedback…

Please forgive the early post…

When developing a control system feedback is critical; in creating a company wide software proces feedback (from your employees) is even more importaint.  What is the best way to gather that information and what is the information that you should be collecting?

AAEAAQAAAAAAAAIUAAAAJDM0YTBmOTg1LTFlY2MtNGI0MS1iNWJiLTcwNWY5NmRmZWExNQ

What did your bug reports tell you?

Bug tracking systems serves as the “first pass” for information reference.  When developing the software process a category of “workflow issues” should be included in the tracking software.  These workflow bugs will show problems related to

  • Poor documentation: The primary way users learn about the Model-Based Design workflow is through the documentation.
  • Architecture interfaces: Poor interfaces, either for model or data integration will emerge as new design patters are exploreed by new groups.  The process adoption team must determine if the interface should be extended or a new interface defined for the group specific requirements.
  • Test failures:
    • Modeling guidelines: Failures in modeling guidelines will show where users have difficulty in conforming to modeling standards.
    • Regression tests failures: These can indicate an improperly defined regression test system.  During the inital development of the test environent it is common for there to be errors in the system.

bugReport

Direct feedback / viewing

At the one, two and six month marks groups new to the process should be brought in for a formal process review meeting.  During the meeting the following activities should take place.

  • Design reviews:  The models, tests and data managment files should be reviewed to ensure that best practices are followed.
  • Pain points: Request feedback from the teams to capture existing pain points.

Final thoughts

Collecting feedback from new teams is critical understanding where processes can be improved.  The development is as always an iterative process requiring input from teams outside the inital “core” team.

Integration with existing software

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.

fault-line-earthquake.jpg

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”

klienBottle

Creating documentation!

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.

coveragePolyspace

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.

processTracking.jpg

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.

rtfm

 

 

 

Requirements Management

It is well documented that bugsthe 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 reqHiwriting 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.

IT-Maintenance

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.

farm to fork_3

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.

The house that Model-Based Design Builds

For the past year, I have followed a video blog called “primitive technology” in it the author takes you through, step-by-step, a process for first making tools, and then from those tools building structures. It is honestly fascinating; while watching him I see the antecedents of the tools that I have used.

However, it is counter to how I want to live my professional life as I wrote earlier about reuse versus building from scratch. Today I will expand on my video blog from Oct 20th and talk about tool selection and their application.

When all you have is a hammer, everything looks like a nail

Working in the embedded design world the “house” that I build is most commonly the control algorithms which run everything from refrigerators to satellites. Within that framework, as a consultant for The MathWorks, I am frequently asked: “what should be code by hand and what should we do following an Model-Based Design process.” In answering this I fall back to a new saying, “pick the tool based on the fit in your hand and the fit for the task.”

Fit in the hand: The first time I picked up a nail gun it was heavy, awkward and I was prone to badly placing nails. However by the end of the day, having completed framing of three rooms, it fit in my hand as comfortably as the best framing hammer.

Fit for the task: As much as I loved my nail gun, the next day I was doing border trim and a new tool was required; I grabbed a trim hammer.

How to decide with Model-Based Design: The problem with analogies is nothing ever maps perfectly one-to-one. A model based development process is more than just a power tool that let’s you perform the same task more quickly. Rather it is a set of power tools that let you perform the same task and new tasks more easily and more dependably.

My breakdown falls along the line of algorithm verses the external interfaces. I would reference last week’s blog post.

Inside Model-Based Design: Control algorithms, interface to low level device drivers, function scheduling

Outside Model-Based Design: Low level hardware device drivers, operating systems

Assorted thoughts and comments:

1.) The image of the tool box with every tool in it’s place and highly organized requires discipline in your software processes. Remember it is the processes that keep the tools from looking like this…

2.) My experience of home building is limited to some time while at university volunteering for habit for humanity. Spend some time with them if you get a chance.

3.) The banner image of the nail gun also includes a level in the handle; I like to think of this much like the MathWorks products, e.g. even as we drive the nail we give you additional information.

4.) Sorry there was no juggling in the video.