Software Diagramming In Embedded Systems?

afd100 writes "I work for a medium-sized company building embedded systems using C. As of yet, we do not have a great design methodology, but it is something we're working on. For the last 7 years now, we've been documenting our embedded software in an IEEE'esque Software Detailed Design, and using a very cryptic block diagram to explain our software. What does the embedded software community at large currently use to graphical represent their software or do they even try this? Since the programming is functionally decomposed, is UML the right way to go?"

Comments

Re:Ditch diagrams. I'm serious.

[H0p313ss]

About the only case where diagrams are helpful are FSM diagrams.

UML includes state machines, real-time UML is all about state machines.

Maybe Try Formal Modeling?

[Shade of Pyrrhus]

Take it a step up and evaluate some modeling languages and tools, such as AADL and OSATE.

http://www.aadl.info/

This stuff is MADE for real-time, embedded systems. The ultimate goal is to use it through design and analysis, and then go ahead and generate code. It does take some getting used to, and there is a lot to it so keep that in mind.

It's not perfect, and still under development, but very cool. So give it a try, see if you can pick it up. I'm generally a supporter of UML, but after being introduced to AADL and OSATE in an architecture course I was eventually convinced that it could be better than UML for this field.

Statecharts

[Dr.Who]

Most times when people think about using flowcharts, they really should create state transition diagrams http://en.wikipedia.org/wiki/State_diagram/ to discuss, describe, and document behavior. Statecharts are an improvement on earlier state transition diagrams and are included in the latest UML specification.

Some Statechart references:

1. Samek, Miro; Montgomery, Paul: State-Oriented Programming. Embedded.com. 2000-08. http://www.embedded.com/2000/0008/0008feat1.htm/
2. Samek, Miro: Practical Statecharts in C/C++: Quantum Programming for Embedded Systems. CMP Books. 2002-07. http://www.amazon.com/exec/obidos/tg/detail/-/1578201101/002-2659023-9156009/

Re:Ditch diagrams. I'm serious.

[Cyberax]

I did this many times. UML class, use-case and sequence diagrams were NEVER helpful - it's just much easier to explore code with a good IDE.

The argument that a new architect will have to spend days familiarizing with the code is moot. Architects are arguably THE main people in a project - their mistakes can cost A LOT. So I'd rather let him/her spend some time and get acquainted with the code and code 'style' then let him/her rush into drawing more diagrams.

Also, diagrams have a very nasty habit to fall out of sync from the real code.

FSM diagrams are very useful, though. Especially if they are automatically generated.

Doing Hard-Time (with UML)

[two basket skinner]

by Bruce Powel Douglass explains how to use UML to model real-time embedded systems. I picked it up when i needed to come up with graphical designs for my senior thesis a couple of years ago. I had never once worked on a real-time system but this book helped me a lot in that it stresses the importance of the state and sequence diagrams (as many previous posters are also). Douglass does a good job of showing how to use the state diagram and nested states for multi-threading which helped me on my specific project. With this book i was able to catch a lot mistakes in my initial "swag" design and better able to understand how all the multi-threading parts would need to fit together. And why wouldn't UML work for decomposed functions? Use case, sequence, and state diagrams are not limited to any level of abstraction/detail, right?

Re:Ditch diagrams. I'm serious.

[AuMatar]

And uses all the wrong ideas. EEs had a drawing standard for state machines for decades, UML ignored all of it. Yet another reason to ignore UML.

Re:Ditch diagrams. I'm serious.

[raddan]

Since I am currently in the middle of drawing one (and yes, I'm kinda spacing out, reading /.), I would also argue that ER diagrams are useful. Just the drawing of them makes you think through some things that might never have occurred to you if you just started creating tables in a database.

Re:Ditch diagrams. I'm serious.

[jgrahn]

Ditch your diagrams. They're far too often used to: 1) As a thing to show boss that you're working. 2) Unnecessary cruft which no one uses.

And/or 3) something everyone except the boss knows is out-of-date and dangerous to refer to for anything important.

It's strange that the question explicitly asked for diagrams. What if this particular system is better described in plain text -- should there still be diagrams instead?

Apart from that I only have three pieces of advice:

• Any documentation which isn't under revision control together with the software is doomed to fail. That means among other things it has to be inside the source code, or in separate plain text files (so your changes can be merged with my changes, and so they can be reviewed alongside the source code).
• Spend a day or two with doxygen. Make sure you enable its graph-rendering capabilities, and then play with different settings. You can get quite a lot of overview and insight from its output, and it supports plain C.
• Doxygen cannot capture the architectural decisions and rules. Those that change rarely should, I think, be written down in plain text by someone who knows a lot about the system and who can write readable technical documentation. But for the volatile details, I'd rather trust the source code (and the views of the source code which doxygen, emacs, various IDEs ... can offer).