SLTF Consulting
Technology with Business Sense



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

Copyright © 1998-2012 SLTF Consulting, a division of SLTF Marine LLC. All rights reserved.