You may redistribute this newsletter for non-commercial purposes. For commercial use contact jack@ganssle.com. To subscribe or unsubscribe go here or drop Jack an email.

• Editor's Notes
• Quotes and Thoughts
• Tools and Tips
• Freebies and Discounts
• On Requirements Documents
• More New Years Resolutions
• On E-Voting
• The Secret of My Success
• This Week's Cool Product
• Jobs!
• Joke for the Week
• About The Embedded Muse

Over 400 companies and more than 7000 engineers have benefited from my Better Firmware Faster seminar held on-site, at their companies. Want to crank up your productivity and decrease shipped bugs? Spend a day with me learning how to debug your development processes.

Engineering changes at an accelerating pace. The boss wants more bug-free code, today. Tomorrow he'll want even more in the same time-frame. Are you on top of the best ways to deliver it?

Some tell me they just don't have time to attend seminars. I'm reminded of this:

It is important to fight today's engineering battle. But the war will be lost if you don't find better ways to win.

This is what my one-day Better Firmware Faster seminar is all about: giving your team the tools they need to operate at a measurably world-class level, producing code with far fewer bugs in less time. It's fast-paced, fun, and uniquely covers the issues faced by embedded developers.

I'll present the Better Firmware Faster seminar in Melbourne and Perth, Australia February 20 and 26th. All are invited. More info here. The early registration discount ends today. As I noted in a recent blog, I'm cutting back significantly on travel, so this will be my last trip to Australia. It's a beautiful country with great people, but a long way from my homestead in Maryland.

Jack's latest blog: A Lack of Forethought

I never give anyone hell. I only tell the truth. They think it's hell. Harry S. Truman

Please submit clever ideas or thoughts about tools, techniques and resources you love or hate. Here are the tool reviews submitted in the past.

This month's giveaway is a Cypress CY8KIT-044 PSoC 4 M-series Pioneer kit.

Enter via this link.

Brian Cuthie reports that the schematic editor/simulation software Micro-Cap is now free. See this.

How long are your requirements documents? How complete are they?

Getting hard data is notoriously difficult in the software world. Capers Jones probably has more than anyone. He stresses the large standard deviation, but makes it clear that one can gain some insight from it. I view the data as an impressionist painting, where the outlines might be fuzzy, but one can still make out the general shape of things.

The following table is derived from data in Jones' The Economics of Software Quality. It shows how many pages of requirements are found for various-sized projects. The "Requirements Completeness" column illustrates all-to-pathetically how short those pages are of the delivered functionality.

Jones uses function points instead of lines of code. Most of us are uncomfortable with function points, so I've converted them to lines of C code using the generally-accepted average of one FP being 130 lines of C.

Playing with the numbers, for 100% completeness you'd need about one page of requirements documentation for every ten lines of code. It's not clear if a "page" means 500 words, or perhaps just a sentence or two, with perhaps each requirement standing proudly on its own page.

What do your numbers look like?

Vlad Z sent more New Year's resolutions:

Later this year the US will chose a new president. But who will make that choice?

I last wrote about electronic voting machines in the election year of 2008. Twelve years later little has changed.

Vermin the world over will exploit any computer weakness to extort tens of thousands of dollars from the unsuspecting populace. Those are pretty puny stakes compared with the presidential election, which will consume billions of dollars of campaign funds and will shape the direction of the most powerful nation on the planet for at least four years.

So how did we react? By acquiring voting machines with many known security flaws, developed without using best engineering practices, whose code is proprietary, and that use hacker-friendly operating systems. In effect, the government, by making these purchasing decisions, sanctioned a "we're the government, you can trust us" appeal to the electorate.

Ironically, the citizenry has never trusted the government less than in recent years.

We know how to build reliable software systems. We know how to build secure software systems. We decided not to. How dumb is that?

Democracy is hard. We citizens have to be involved. We need to hold our elected officials accountable, and toss them out when they fail to meet our standards. That requires we trust the integrity of the ballot box.

E-voting travails are not new; ballot-stuffing is as old as the Republic. The difference is that now it may be possible to stuff millions of votes with a few clicks.

I believe that e-voting holds the promise of eliminating compromised elections. But not with the approaches used now. I'm sickened to read of various commissions demanding that vendors add printers to their machines. That's does nothing to prove that each vote is recorded properly. The printer could show one candidate and record another. And the voting machine itself is not the issue: it's the entire system, including the computers that hold the databases, which are even more attractive targets for bad actors.

We citizens must demand a system that works. That requires the following:

• Open source both the software and hardware. Publish the code and schematics on the web. Sure, we can hire a private company to develop and manufacture the equipment, but the IP should be owned by those footing the bill. Us.
• A dead simple design with minimal features. Prune anything not completely necessary. That means no Windows or Linux.
• Use provably-correct components. No proprietary code is allowed.
• No changes may be made to the design within six months of an election, to give the community time to evaluate the proposed change. If the design is dead simple, few changes should be needed.
• Certify the code to DO-178B level A, the avionics standard..
• Certify the code to Common Criteria EAL7, the highest security standard.

Will this happen? I doubt it. Conspiracy theorists probably feel the overlords who control the government want to have hackable elections. But I suspect there's more truth in: Never ascribe to malice, that which can be explained by incompetence.

The blue light of the TV flickered on the blank wall, but it went unnoticed by me as I slumped in my old armchair.

It had been a bad week. She left on Monday, screaming that she couldn't take all of the equipment piled everywhere. Me, I thought that old Tek 545 was a collector's item, an antique. Sure, the dust was pretty bad, but you can bet we were the only couple in town with a living room populated by old scopes and CP/M machines.

Yeah, I do mess up some times, like that time my homebrew furnace controller burped and drove the house to 115 degrees when we were gone for the weekend. Hey, I never liked those pets anyway, and the smell did eventually come out of the carpets. Pretty much. I mean, it was just a little software bug; we all have those!

And there was the fire. Yeah, next time I'll put a bigger heat sink on the power supply. I admit it - I learned a lesson. The scorch marks on her dresses don't really look all that bad.

I reached for another bag of chips as the chair groaned a bit more. One of these days I'm gonna have to work off some of the excess pounds. A decade spent in the lab drinking Jolt and munching fries had taken its toll. Despite the flab I still know calculus and can program in C; surely a dream dude for any discerning woman. I bet I could wow them at the local watering hole with my great stories about TCP/IP!

Well, this is Silicon Valley after all, where relationships, jobs and careers are measured in milliseconds and loyalty doled out by the microgram. Electronics is a dog-eat-dog business and I'm an old hand at crawling out from the wreckage. Like that last startup I worked for. I told 'em we'd get that product out the door, eventually anyway. We woulda survived if that idiot president just got another couple of mil of venture capital. For a while at least.

Ya know, maybe it was losing that job that ticked her off. I figure, what's the big deal? She should be used to this by now. Check out my resume - it shows lots of experience at lots of places. No one can beat this!

I picked up the phone but heard only the accusing silence of a non-payment disconnection. No matter. Time to find another company looking for my embedded expertise. There's a startup a minute here, pigeons ripe for picking.

I clumped out of the trailer's front door and found Big Al, the usual wild look in his eyes, mouth working hard on this morning's sugar raised, the white powder spotting his beard.  "Al, buddy, you're outa work too, huh? How's the wife and kids?"

"Kids? Kids? Yeah, come to think of it I did notice some little people living with me. I wonder where they came from? Check this out." With that he shoved a coffee-stained fragment of the San Jose Mercury News into my hands. I quickly took in the circled want ad. "ENGINEERs – microprocessor savvy designers and programmers needed. C, FPGAs, assembly a plus. Exciting opportunity for a motivated developers in a new high-growth company."

A slow smile spread across my face. Here was our pigeon; I was already mentally spending the signing bonus.

That afternoon, T-shirts cleaned and pressed, with most of the donut detritus hurriedly wiped from Al's beard, we met with the president of Galaxar Enterprises. Yep, just as usual, this man was the typical harried executive desperate for people, so desperate he had neither the time nor resources to do much of a background check. Not that my background is so terrible; it's just that there's so much of it.

"You know C? Schematic capture? What's the last project you worked on?" he mumbled, looking at his watch while the cell pinged an urgent tune.

"We did that Internet cappuccino maker for Kitchen Services; you must have read about it in the press. Yep, that puppy had a RISC-V based coffee engine with 10 gigs of RAM…"

"Didn't they go Chapter 7?", he interrupted, interested  now.

"Trust me on this. The boss was an idiot. He just didn't understand how much compute power we needed to blend the perfect cuppa joe. That sucker could crank some coffee, believe me. If they hadn't been so stuck on the cost of goods we coulda cleaned up the cappuccino market. We were practically done with development when the SEC raided us."

"OK, OK, look, when can you start? Now? Don't you guys ever shave? Hell, just sit here and Bob will tell you what to do."

Bob, engineering VP, was one of those snotty-nosed brats with a degree and an attitude. "We're building a new marine VHF radio for the recreational boating market. That means there are three main design parameters. First, the unit must be totally sealed to ensure it's waterproof. Second, the sell price can't exceed $250. And obviously the unit must be simple enough that even the most casual boater can use it."

He went on to tell us how we were going to design the product. Us! Can you imagine? As if I don't understand project planning, structured design, discipline design, and all of that utter crap. Me, I prefer to skip all of that non-productive nonsense and just bang it out.

I zoned out, the drone of Bob's voice barely noticeable, nodding at the right time while planning my next move. Clearly it was time for the old end-run. Saturday night Al and I marched into the president's office. "Herb," I started, "we know you're running out of venture money and an IPO is at least a year away. Bob's planning to spend another three months just doing preliminary design. Whatdoya want, a design or a product? Trust me on this – we can pound out a design in a week, max, and then get the radio done in no time."

Herb's eyes gleamed. It seems that he, too, was frustrated by Bob's methodical approach to engineering. This valley is the land of Steve Jobs, where unbridled passion and hope fuels the dream of tomorrow's big score. Discipline? Bah. Just lemme at a problem and I'll get it done. With a bit more prodding Herb agreed that this project was so important he'd give it skunk-works treatment, get Bob off of our backs, and let us report directly to his president's office.

The week sped by like a read from cache memory. Al slouched into my cubicle, let out a long, satisfying-sounding belch, and asked "didn't we promise Herb a spec or something?" Right! Never let the boss, down, that's my motto. Unless there's a good reason, of course.

"Sure, look, just grab those header files we've been working on and edit a bit of descriptive stuff at the beginning. They'll never read it all anyway. If he complains we'll tell 'em not only is the spec done, we've incorporated it into the firmware. How can he get upset if he sees we're already coding?"

Herb swallowed our header files hook, line and sinker. He's thrilled that we're already cranking out software, and giddily reported our progress to the venture capitalists. I think they're already mentally spending their IPO profits. Bob is muttering vague threats, but he's been squeezed into the user-interface group.  He wants Al and I to take on that new college grad, Marty. We're supposed to show him how to get projects done. It's  not all bad; the kid has a car so can get us beers and carry-out.

The secret to success in this business is to look busy, keep a prototype in a state that looks like it has some level of functionality, and always agree with the boss.  And you can't act like you have a personal life when battling a schedule! Heck, after just three days on the job Marty asked if he could leave at 5 to celebrate his first anniversary. I straightened him out. "Kid, trust me on this. We all go through one or two starter marriages, you know, no kids, no property, no regrets. Don't take it too seriously. Now let's order a pizza and get back to work." It was probably a good thing that I turned off the switchboard that night, so he wouldn't get distracted by all of those frantic calls from home.

And that kid did need some attention. I caught him late one night doing a spell check on his comments! Somehow he missed the fact that a ship date loomed; comments are always the first thing to go. "Kid, trust me on this. Never include a comment that will help someone else understand your code. If they understand it, they don't need you." I think he gets the picture now.

As time moved on we started having trouble fitting the binary image into the CPU's address space. "This always happens", I reassured Herb, "them 16 bitters just can't handle the sort of code we're cranking out for you. Look, we'll just stuff a bigger part in there this afternoon. No problemo; I've done this a million times."

Big Al's eyes lit up when I suggested we look into a 64 bit processor. "I've got just the ticket. There's one I've been itching to try; it's totally reconfigurable, you can even define your own instruction set. Man, this is gonna look great on my resume!"

Ah, resume fodder, the grease of the industry. Herb didn't seem to concerned about the increased cost of goods – at least he wasn't asking any questions – so I set out trying to find some way to cool the sucker. With luck a big old heat sink and decent-sized fan might be adequate. Jeez, maybe I'll use the next size up; those burnt dresses still haunt me at times.

We optimized the instruction set on the CPU to play DoomStar III at awesome speeds. The best part of using a custom architecture was that I got to port the entire GNU toolchain to our chip. That compiler sure is tricky! First time I'd ever fiddled with a code generator, so it naturally took a bit longer than planned to get working – mostly – tools.

As the weeks passed Herb got noticeably more antsy, checking on our progress on a daily, and then hourly, basis. This always happens, and is a sign that the old cash reserve is evaporating. I started running to the bank the minute paychecks came out. No one's gonna stick me with bouncing paper! Been there, done that.

Bob – remember Bob? – strolled into the lab one afternoon to check on our progress. It seems the fool had actually invested his own money into the company! He's correspondingly annoying about what we do, even though my end-run had gotten him off the project months before. Oddly, he seemed upset about the cooling fan. "This thing has got to be totally sealed, so no water gets in!" he whined.

"Yeah, yeah, just mount it in a dry place or something", I replied. "I can't be bothered with that sort of stuff. You know how much power this sucker uses?" These company men are all stress puppies. Not me; I'll be going strong when he suffers his first mid-30s myocardial infarction.

Christmas rolled around – or was it Easter? I dunno, we were plenty busy chasing down bugs and making feature changes. Bob's paycheck bounced. I knew that Herb had been doing some fancy footwork to keep things afloat, but when everyone in accounting quit, complaining about insolvency or something, the standard exodus began. As usual, engineering remained untouched by the various rounds of layoffs. They needed the products we make to survive. I love this field!

This seemed like a great time for a two week vacation, though Marty seemed almost hysterical that I'd take off now. "Kid, trust me on this. Never complete a project on time. If you do, they will think it was easy and anyone can do it and they don't need you. Now I'm outa here for a while. Look busy and we'll sort it all out when I get back."

I got back, more or less sober but feeling great, to find the front door padlocked and a sheriff standing guard. Marty, skulking in a dark corner, grabbed my arm and moaned that he couldn't build the code at all while I was away. It seems he had trouble locating all of the source.

"Kid, trust me on this. Never archive all the sources necessary to build a binary. Always hide a few on your own disk. If they can build your binary, they don't need you. What do they teach you in college, anyway?"

He said the creditors got fed up and were demanding their money. Half the employees were suing because their paychecks bounced. A satisfied grin spread across my face as I recalled beating the rest of those idiots to the bank.

Marty shrieked that Herb was suing all of us in engineering for not meeting promised dates, specs, or features. "Kid, trust me on this. They always sue. That's why I own nothing. What do they think they'll get, my trailer? The bank owns that!"

Well, it seems my two week holiday might extend itself a bit. No worries there! After such a tough project I needed a break. It's time to sleep in for a while, build up those reserves.

Days later an awful booming interrupted my sleep. "My god, it's not even noon!" I shouted, "go away". The door slammed open and Big Al loomed over me. "Check this out." He unwrapped the newspaper from around his BLT and handed me a section from the want ads. Yep, old Al was right on top of things again. Another startup, as usual desperate for a pair of gurus like us, no doubt willing to hire at any price.

A harried president briefly interviewed the two of us, asking lots of questions about our most recent experience. We gave them the scoop on the VHF radio, but had to parry his request for references. "Sorry – they went out of business. Shame, that. There's no one there you can call. But we built a hell of a radio for those guys. It's too bad management was so screwed up they folded. Hey, it happens all the time in this industry."

"But trust me on this – you need a graybeard like me to mentor your young engineers, and to get this project out now! I'm ready to start coding today. What is it we're building?"

Bob Paddock sent in a link to an article about a new-fangled battery. The key specs:

It's SMT-compatible in an EIA 1812 package. The article doesn't list a price (a practice that is unacceptable), but Digi-Key lists these at $8.30 in small quantities.

While this is an interesting part, with only 100 µAh of capacity and the relatively high cost, I'm not sure where such a part makes sense.

Note: This section is about something I personally find cool, interesting or important and want to pass along to readers. It is not influenced by vendors.

Let me know if you’re hiring embedded engineers. No recruiters please, and I reserve the right to edit ads to fit the format and intent of this newsletter. Please keep it to 100 words. There is no charge for a job ad.

These jokes are archived here.

Tomislav Razov sent this:

Changing random stuff until your program works is "hacky" and "bad coding practice".

But if you do it fast enough it is "Machine learning" and pays 4x your current salary.

The Embedded Muse is Jack Ganssle's newsletter. Send complaints, comments, and contributions to me at jack@ganssle.com.

The Embedded Muse is supported by The Ganssle Group, whose mission is to help embedded folks get better products to market faster.