"I got words ..."
 -- Firefly 2002, S1:E2 The Train Job

Common Sense Coding

May 22, 2016

These ideas are neither new nor original. I mostly I put them down here so I can remember them myself.

"Code to test". Never expect that testing is just one phase of a project; expect there to be testing throughout the life of the product. Code in a style that is modular and testable as a module. Bugs will be found; requirements will change; code will be touched. And when the code is touched, something will break in unexpected ways.

Architect code as if it will be ported. If processor-specific concessions have to be made, make these areas clearly identifiable. Better yet, write the code so that it can easily be compiled and run under a simulated environment, such as a Windows thread. This can also go a long way towards modular testing and re-usability. This can also come in handy when you need to write a host application that may need to deal with data in a structure as it's defined for your embedded device; it's much easier and less error-prone if you can simply include the same header file.

Avoid generic variable types, unless the variable is truly generic. "Say what you mean, and mean what you say": if you mean to use an unsigned 16-bit variable, then declare it in a generic, size-specific fashion, as "uint16_t". This can avoid a tedious translation effort later on, when that "int" variable that just happened to be 16 bits in the last processor, now breaks because it's 32 bits when it's ported, or when you try to compile it for simulation under Windows.

Comment the why, not the what. Yes, I can see that you're incrementing the count value, but explaining to me that you're doing it because you're using it to reach a time-out is much more useful (and if you can tell me why you're checking for a timeout, all the better). And comment while you code. Don't wait until you have more time "later", because it either won't get done, or you'll forget the "why" part by then. Oh, and don't let auto-generated code be an excuse not to add comments. OK, so I'm guilty of that myself, especially for an IDE that generates a routine for every. single. event. At least go back and add a bit about "here are my event handlers".

I like Doxygen-style comments. Having documentation that can be directly derived from the code is much (much, much) more likely to be in synch with that code.

Document as if you'll be handing over the code to some other poor sot. Because, in a few months, that other poor sot will be you.

When using an IDE, name your routines category-first, such as "threadPollAdc(), threadMonitorTemperature()", so that they are ordered by this category in the routine drop-down list.

A Case For The Electric Car

May 15, 2016

There are all kinds of arguments out there for why we need electric vehicles, or why people will want to buy them or why they won't. The price of gas goes up, they say electric cars will succeed; the price of gas goes down and they say it will never happen. They argue about whether the source of the electricity used to power electric cars makes them less "green".

I say "they" are missing the point entirely. It's not about saving the planet or saving money.

It's about simplicity of design.

Imagine purposing the idea of a gasoline engine today, given the technology at hand. Let's imagine for a bit how this might go as an engineering project. Given the task of developing a form of personal transportation, the team comes up with the idea of using gasoline as a fuel to propel these things - we'll call them "cars" - down the buggy trail at high speeds.

"Should be pretty straight-forward", they think, and come up with a plan:

"Gasoline is readily available, and we can design an engine that converts short thrusts of linear motion into rotary to move the wheels, by injecting small amounts of the fuel, mixed with just the right proportion of air, into chambers, where it will be ignited by a carefully timed spark. The resulting explosions will cause the shaft, connected to the wheels, to turn. We'll make several of these, timing them so that they fire one after the other, to smooth out the motion."

They develop a prototype. It's very noisy, but it works, and they figure it's something they can deal with later, using baffles and sound-deadening materials. They get the go-ahead to develop a full-scale model.

Week one: while the prototype worked for the short period of the demonstration, they quickly realize that over time the engine tends to get quite warm, and they rig up a series of fans to keep it cool. Also, the excess heat from combustion makes it difficult to keep the parts near the combustion chambers lubricated. They develop a system to circulate oil which seems to solve this issue.

Week two: further testing shows that the extreme heat is degrading the oil. Further, it's causing stress fractures in the casing. "We'll have to find a way to keep it cool" says the lead engineer to the project manager. "It'll tear itself to pieces otherwise. Also, we'll want to use a thicker casing, and that's gonna add some weight". This sets the project back a few weeks, but at this point they have no choice, so they press forward.

Week six: "This looks a lot bigger than the prototype" says the project manager. "Well, we had to make the casing larger so we could circulate the oil and coolant liquid through it", says the engineer. "And we had to add a heat exchanger and fan to help keep it all cool". "What's this doohickey on the side" asks the manager, noticing the small electric motor. "I thought this thing ran on gasoline". "Oh, that's an added feature", the engineer explains, "we call it an 'auto-crank' (that was Frank's idea - good news by the way, his arm will be out of the cast next week)". "Well, what's the other motor for"? "That's not a motor, that's a generator. See, it hooks to the battery we use to power the motor, to keep it charged.".

"Look", says the manager, "this thing is getting out of hand. All these extra parts will put this way over budget, and we can't afford to slip schedule much more.". The lead engineer decides not to mention that they've started getting complaints from workers next door, on their smoke break, about the combustion fumes they've had to vent to the outside.

The project is eventually killed by the investors, and half the team let go, after it is discovered that the gasoline engine could only run without stalling or over-revving by adding a complex gear-changer, the project deemed too complex and costly by the investors.

Pogoplug Web Server

September 23, 2013

The Pogoplug Series 4 is, in itself, a very nice little device for storing pictures and whatnot from various computers and handheld devices. What makes it really interesting to me, however, is how it can also be used as a tiny little Linux box. Install Arch Linux and a few other open source packages on it and it becomes a small but surprisingly nimble web server. Not bad for under $50.

Besides the various connectors it comes with for its intended purpose as a network storage device, it has one advantage over a Rasberry Pi or Arduino board in that it comes in a very sleek black plastic case, ready to tuck away in an inconspicuous place on a desktop, table, or, in my case, alongside a DSL router on a makeshift wooden shelf in the closet of our neighborhood clubhouse. It’s also packed with connectors for attaching a number of storage devices, with one USB2 and one SATA connector accessible by removing the top cover, two USB3 connectors in the back and one SD slot in the side. I found that I could tuck a tiny Sandisk Cruizer Fit 8G drive into the top USB connector and still have room to replace the cover. Unfortunately, only the top USB 2 and SATA connectors allow for a bootable device.

The Series 4 comes installed with software that lets you bounce a variety of iOS and Android-based devices off a server to get access to all your music, files and photos on your own personal “cloud” server. For a fee, they also allow you (entice you?) to store some of this on their servers. I think a much more interesting, and, let’s face it, geeky use of this device, though, is to discard the pre-packaged software - and intended use - and simply use it as a Linux box. Fortunately, some very smart and generous people have already done the work of porting something called Arch Linux over to the various versions of Pogoplug, including the Series 4.

Now I’m not a Linux guru by any stretch, but, after much trial and error, I was able to set up the operating system, an Apache web server and a YaBB bulletin board for our neighborhood website. If you’ve been looking for a nice platform for playing with Linux, or you just need to set up a small server on the cheap, this could be a nice little solution for you. There’s a link at the end of this article to all the gory details, along with some useful sites, to hopefully save you the trouble of digging all of this up for yourself.

Oh, and if you decide you want to go back to using it as a cloud storage device (or you mess up the Arch Linux install the first time around), you can just replace the top USB device with a drive that has a file named “revert” on it, and it goes back to using the software it came with out of the box.

For all my detailed notes, follow this link to the PDF.


Phone: 919-961-1139
Email: Tom@BarefootSoftwareConsulting.com

Barefoot Software Consulting
421 Commons Walk Circle
Cary, NC 27519