A requirements document before a project pays big dividends in time and money
Scott Rosenthal
April, 1996
Quite often magazine articles concentrate on all the gory details of one isolated
aspect of an embedded project. That approach is fine if that one topic is all you need for
a job. In reality, though, your little embedded project is only one part of a larger
project or product whose ultimate goal is to bring in money. Recently, I completed a small
embedded project and want to share thoughts on the development process--both the good and
the bad--to help you gain an understanding of the processes involved in building a quality
design. The goal isn't to show the only way to approach a project but to outline one
process that combines a quality output with high productivity.
The project
The genesis for this project came when a client hired my firm to design a new type of
consumer-electronics device. Without going into specifics, the proposed design was
composed of three main sections, one of which--the front panel--is the topic of this
column. For operator interfacing, the panel incorporated dozens of LEDs as both numeric
and discrete indicators along with two dials and a small keypad. We had to keep the
electronics for driving this hardware to a minimum while not overburdening the main CPU,
which resides on a separate board.
The traditional approach to controlling LEDs involves multiplexing them with
special-purpose display-driver chips. Unfortunately, these chips typically drive only six
or eight displays, so this application would require three or four chips--not to mention
associated current sinks and sources plus current-limiting resistors. This solution,
besides being cost-prohibitive, required too much board real estate.
In addition, because the front-panel display board is separate from the computer board,
I would also need to design an interface to route the main CPU's data bus and control
signals to the display board. This interface would in turn increase the device's overall
cost while increasing its EMI emissions.
Adding to these woes, the display board would still need an interface for the dial
encoders and keypad. Although discrete circuits could undoubtedly handle these tasks, I
determined that to meet the customer's response-time requirements, the software would need
to read the dial encoders once every millisecond, an impossible task given the CPU's other
responsibilities.
To avoid these problems, I decided to design the display board around an 8051. With
little in the way of added circuitry and expense, this local micro would handle all LED
display functions, dial-encoder interfacing as well as keypad debouncing and encoding. For
interfacing to the product's main CPU, I chose National Semi's (San Jose, CA (408)
721-5000) Microwire serial interface. This design minimizes components on the display
board while offloading some processing from the product's main processor.
Code-domain problems
An interesting side effect of this decision is that it made creating the interface
essentially a programming exercise. No longer does the interface rely on specialized
circuitry or discrete logic. In fact, depending on the code it's executing, a
general-purpose processor driving a set of user-interface elements (LEDs, knobs and
switches) can produce a nearly infinite number of operational characteristics. Therefore,
the remainder of this column deals with software aspects. This concentration is also
appropriate because the highest risk in an embedded design is in software, which can
compensate for hardware deficiencies--while hardware can rarely correct for software
problems.
The process I follow for software development is fairly traditional. Its purpose is to
ensure that what I develop meets product requirements. The first step is to get down in
writing exactly what the product should be and how it should operate. Typically in the
course of this documentation process, I develop three documents before building anything:
a requirements document, a design document and a test document. I'll discuss the first two
this month and save the third for my next column.
Write we must
Most of you are probably groaning about writing anything, let alone documentation.
However, before you completely tune out this discussion, let me present my side of the
issue. I recall a client who wanted us to design a simple circuit board using a
microprocessor to implement some timing functions. I remember thinking, "Piece of
cake" as I signed a fixed-price contract. Unfortunately, even though I thought I knew
what the client required, it wasn't until many changes (and dollars) later that I
discovered that the client didn't know what he needed. This mistake forced me to find a
way to prevent this situation from arising in the future.
The fix I came up with is the requirements document. Every project I undertake now must
have one to make sure that both I and the client understand what's going to be developed.
A good requirements document is actually very simple to write. As someone once explained
to me, it must answer the question what. What is required? What should the device do? The
problem I see on lots of requirement documents is that they move beyond (or skip over) the
what and try to address the how. Unfortunately, you can't adequately answer how if you
haven't answered what.
In the case of the display controller, the requirements document was roughly 1000 words
long and took two hours to write. After finishing it, I sent it to the client for approval
so that we were both clear as to what I was designing for him. If he wanted to make any
changes to this agreement--no problem. We both knew that a requirement change results in a
change in the project's scope, yielding more work and increased cost. Personally, I think
investing two hours to ensure financial security is worth the effort.
Paper designs
Once the display controller's requirements were approved, I started working on the
software design document. The purpose of this paper is to help you focus on overall system
design without worrying about nitty-gritty details. Without a general understanding, your
software most likely won't form the integrated whole you need it to be. We've all seen
software that's bloated and bogged down with replicated functions and massive global
bandaids trying to patch over basic flaws.
However, a little forethought can pay tremendous dividends later when you're coding,
testing, debugging and maintaining code. Remember, every line of code, no matter how
insignificant, has a cost. Fewer lines of code equate to lower development and maintenance
costs. Just as you wouldn't think of wasting materials when building a house by putting in
extra studs in walls or joists in floors or ceilings, you shouldn't have extraneous or
redundant code in software.
A common trap to avoid when creating a design document is extreme levels of detail. I
consider such exercises, such as expressing the entire design in pseudocode, a waste of
time. A design document should confine itself to describing the system's major
architectural features, including the operating system, major data structures and logic
states. Software engineers are professionals and don't need to be spoon-fed how or what to
code.
For the display controller, the design document comprised 1200 words and again took two
hours to write. As with the requirements document, I sent this design overview to the
client for approval. While the client won't necessarily understand the software design,
his approval is a way to draw the client into the process and to show that I'm not going
off in some half-baked direction.
Up to this point I've invested four hours of time to complete two documents that
completely describe what I'm designing and how I'm going to design it. Next time, I'll
finish this project with a discussion of how to prove to a client that your design meets
the project's goals (the requirements). PE&IN
Adapted from an article that appeared in Personal Engineering & Instrumentation
News.
Return to the article index.
|
