Embedded Muse 133 Copyright 2006 TGG September 6, 2006

You may redistribute this newsletter for noncommercial purposes. For commercial use contact jack@ganssle.com.

EDITOR: Jack Ganssle, jack@ganssle.com

- Editor’s Notes
- Preserving Design Decisions
- Tools
- Jobs!
- Joke for the Week
- About The Embedded Muse

Editor’s Notes

Want to become your company’s embedded guru? I’ll present my “Better Firmware Faster” seminar December 1 in Santa Clara, California. Check out https://www.ganssle.com/classes.htm for details. The site is just a few miles from San Jose airport, which is inexpensively served by Southwest Airlines and others. Come for the seminar on Friday and explore San Francisco over the weekend!

TV chef Emeril is always “kicking things up a notch” by adding garlic and other zestiness to his recipes. How are your firm’s engineering recipes? Want to kick up your development processes by more than a notch? I can present my Better Firmware Faster class at your facility. See https://www.ganssle.com/classes.htm .

The Embedded Systems Conference will be in Boston September 25-28. It’s always an interesting and fun event. I’m giving three talks. Some 150 exhibitors will be showing off their latest offerings. I’ll be wandering the show floor; stop me and say “hello.”

Preserving Design Decisions

“What the hell does this mean?” yelled Bill, his usual complacency violated by the peculiar behavior of a brand-new VHF radio. I looked at the LCD screen and saw the hand-held was in some sort of diagnostic mode, displaying “err 4C” whenever he pressed the transmit button.

I know he had agonized over the $300 purchase, his engineering attitude wanting to ensure the radio was the best possible value for the money. We were with our families well outside of the USA with no email access and phone service priced out of sight for support calls. The manual documented quite a few error messages, but strangely not this one.

Sound familiar? A year earlier my autopilot stopped steering. It sounded three short beeps, paused, and then one more before repeating the pattern over and over. Clearly this was some sort of diagnostic code, one not listed in the manual, and one that tech support couldn’t identify. “Send it in for repair” was the oh-so-standard response to all such unknown embedded systems behaviors.

Yet surely the firmware engineers went to a lot of trouble to put these exception conditions into the code. They mean something; but that meaning was lost due to poor documentation. Why bother detecting and reporting the condition when users will be baffled?

It’s easy to tell the programmers to log everything they do, and to hope that the documentation and customer support folks will turn these notes into useful web FAQs and manual addendums. But that’s tough. Developers are busy enough trying to fulfill requirements and work out system bugs. Creating a support doc in parallel just ain’t gonna happen, perhaps unless one has an always-available tool where it’s easy to make notations. In a collaborative environment the best tool is probably a wiki, coupled with training and an iron will to log everything we learn.

Maybe we need a documentation scavenger. Someone empowered to dig through the code looking for things that impact the customer. A person that bridges the development, support, and doc teams.

Or perhaps, if we’re wise enough to be doing code inspections, one of the inspectors is always a customer/documentation representative. If you’re using eXtreme Programming, where a pair of developers share one computer, the person not typing could capture each of these new exceptions and ensure they’re emailed to the doc team.

Some might insist that at requirements time we know all of the error codes and other intricacies of the system. In my experience, though, during coding we discover – and write code to trap - odd cases that should never happen, or that we’d hope would never happen. A three level deep IF can resolve into an awful lot of possible conditions, far more than we usually anticipate until we’re deep into the unit design or code. That’s when a lot of the error messages and exception handlers get written, and that’s where they get lost to the customers.

I do remember committing the same sin early in my career. Our instrument solved a very complex series of simultaneous polynomials using an iterative algorithm. (And this was on an 8008!). At times no solution was possible, so I’d programmed it to give up after 20 minutes and display “Help” on the 7 segment LEDs. Years later, long after the device was obsolete and most of the original staff dispersed to other companies, a unit came back for repair. The young technician appeared at my office door, ashen. He had been adjusting internal pots when the machine started flashing “help” messages. He thought some intelligence inside the box was reacting to his repair attempts…

What do you think? How can we pass the critical error messages created by our exception handlers into useful customer artifacts?


Simon Large contributed this: If you want a short and sweet (and free) replacement for the Windows standard Notepad, try Notepad2 from http://www.flos-freeware.ch/notepad2.html. At 250k bytes it is bigger than Notepad, but still small enough to load quickly. Unlike Notepad it handles Unix line-endings (and Unicode/UTF-8), has syntax highlighting for quite a variety of formats, and generally behaves much better than the MS default tool.

Another tip for those who haven't found it yet is to add Notepad (or your favourite text editor) to the Send To list. Just create a shortcut to the editor in Documents and Settings\{USER}\SendTo. That way you can view any document type as text directly from a right click.

Christopher Meisenzahl wrote: I'm always on the lookout for a great, free text editor, and I've tried many. ;-)

My current favorite is this one. Pretty small, can be easily scripted, and allows column editing! http://www.context.cx/


Joke for the Week

If architects had to work like programmers: http://www.stsc.hill.af.mil/resources/tech_docs/gsam3/appene.pdf .