Josef “Jeff” Sipek

In the late 90s, I messed a little bit with electronics but I stopped because I got interested in programming. This last January, I decided to revisit this hobby.

I went through my collection of random components and found one 555 timer chip—specifically a TS555CN. I played with it on a breadboard and very quickly concluded that I should have more than just one. Disappointingly, sometime over the past 25 years, STM stopped making TS555 in DIP packages, so I ordered NA555PE4s thinking that they should be similar enough.

When they arrived, I tried to make use of them but I quickly noticed that their output seemed…weird. I tweeted about it and then tweeted some more. I concluded that precision 555s just weren’t fundamental enough to most circuits using DIP packages, and that I would have to make do with the NA555 parts.

Fast forward a few months, and I noticed ICM7555IPAZ on Mouser. The datasheet made it look a lot like the TS555…so I bought one to benchmark.

I went with a very simple astable multivibrator configuration—the same one that every 555 datasheet includes:

The TS555 datasheet suggested 0.01μF for C2, and it didn’t seem to harm the other two chips so I went with it.

The NA555 datasheet suggested 0.01μF for C3. That cleaned up the rising edge slightly for TS555 and ICM7555. NA555’s rising edge actually became an edge instead of a huge mess, however it still seemed to be limited so I went with a bigger decoupling capacitor—namely 10μF. That didn’t seem to harm the other two chips.

Finally, note that the output is completely unloaded. I figure that this is reasonable since there are plenty of high input impedance loads that the 555 output could feed into. (A quick sanity check with a 1kΩ resitor to ground shows that the output voltage drops by about a volt, but the general shape of the wave doesn’t change.)

I assembled it on a breadboard with plenty of space for my fingers to swap out the chip:

The orange and red wires go to +5V and the black one goes to ground. All 3 are plugged in just right of the decoupling capacitor (off image).

Looking at the three datasheets, they all provide the same (or slightly rearranged) formulas for the frequency and duty cycle. Since I used 1kΩ for the two resistors and 220nF for the capacitor, I should be seeing:

$f=\frac{1.44}{\left(R_A+2*R_B\right)*C}=2182\mathrm{Hz}$

and duty cycle:

$D=\frac{R_A+R_B}{R_A+2*R_B}=\frac{2}{3}$ or 66.67%

Because I used a breadboard, there is some amount of stray capacitance which likely shifts the frequency a bit. Based on previous experience, that shouldn’t be too much of an issue.

I supplied the circuit with a power supply set to 5V and 0.2A. (It operated in constant-voltage mode the entire time.)

Unlike some of my previous experiments, I actually tried to get a nice clean measurement this time. I used the probe grounding spring to get a short ground and measured between pin 1 and 3 (ground and output, respectively).

Let’s look at the amplitude, frequency, duty cycle, and rise time of the three chips. I took screenshots of the scope as I was performing the various measurements. To make it easier to compare them, I made combined/overlayed images and tweaked the colors. This makes the UI elements in the screenshot look terrible, but it is trivial to see how the chips compare at a glance. In the combined images TS555 is always yellow, NA555 is cyan, and ICM7555 is magenta.

Amplitude, frequency, and duty cycle

(Individual screenshots: NA555, TS555, ICM7555)

It is easy to see that the output of both TS555 and ICM7555 goes to (and stays at) 5V. The NA555 spikes to 5V during the transition, but then decays to 4.5V. More on this later.

Similarly, it is easy to see that the TS555 and NA555 have a very similar positive cycle time but different enough negative cycle time that their frequencies and duty cycle will be different.

TS555 got close with the frequency (2.20 kHz) while NA555 got close with the duty cycle (65.75%). ICM7555 was the worst of the bunch with 2.28 kHz and 63.23% duty cycle.

Rise time

(Individual screenshots: NA555, TS555, ICM7555)

The NA555 has a comparatively awful rise time of 74.88 ns. The TS555 appears to be a speed demon clocking in at 18.69 ns. Finally, the ICM7555 appears to split the difference with 41.91 ns.

I still think that it is amazing that a relatively inexpensive scope (like the Siglent SDS 1104X-E used for these measurements) can visualize signal changes on nanosecond scales.

Revisiting amplitude

In a way, looking at the amplitude is what got me into this evaluation—specifically, the strange output voltage on the NA555 chip. Let’s take a look at the first microsecond following a positive edge.

(Individual screenshots: NA555, TS555, ICM7555)

After the somewhat leisurely rise time of ~75 ns, the output stays near 5V for about 200 ns, before dipping down to about 3.75V for almost 200 ns and then recovering to about 4.5V over the next 400 ns. The output stays at 4.5V until the negative edge.

This is weird and I don’t have any answers for why this happens. I tried a handful of the NA555s (all likely from the same batch), and they all exhibit this behavior.

NA555 decoupling

As I mentioned in the introduction, I didn’t follow the NA555’s decoupling capacitor suggestion. I wasn’t planning on writing this section, but I think that it is interesting to see just how much the output changes as the decoupling capacitor is varied.

As before, I made combined/overlayed images for easier comparison. This time, yellow is no decoupling capacitor, magenta is 0.01μF (suggested by the NA555 datasheet), cyan is 0.1μF, and green is 10μF (used in chip comparison circuit).

(Individual screenshots: no cap, 0.01μF, 0.1μF, 10μF)

As you can see, not having a decoupling capacitor makes the output voltage go to nearly 7V in a circuit with a 5V supply. Adding the suggested 0.01μ certainly makes things better (the peak is at about 5.8V) but it looks like the chip is still struggling to deal with the transient. Using 0.1μF or more results in approximately the same waveform with a peak just around 5V.

The suggested 0.01μF has another problem in my circuit. It makes the NA555’s output ring:

(Individual screenshots: no cap, 0.01μF, 0.1μF, 10μF)

Neither the TS555 nor the ICM7555 have this issue. They are both quite happy with a 0.01μF capacitor. Without any capacitor, they have a little bit of a ring around 5V (1.2Vpp for TS555, 200mVpp for ICM7555) but it subsides promptly. The ICM7555’s ringing is so minor, that it probably isn’t worth it to even use a decoupling capacitor.

Summary

I’ve collected the various measurements from the screenshots and put them into the following table:

So, what does this all mean? Ultimately, not a whole lot. The 555 is a versatile chip, but not a magical one. Despite what the NA555 datasheet says, the 555 is not a precision device by modern standards, but it is still an easy way to get a square(-ish) wave around the desired frequency.

With that said, not all 555s are created equal.

The NA555 with all its flaws still works well enough and has a low price. So, for any sort of “crude” timing, it should work well. If, however, the circuit making use of the timer output requires a cleaner signal, then I’d reach for something better.

The ICM7555 is very good. It produces a nice clean output with reasonably fast edges, but not as fast as the TS555. Unfortunately, the performance costs extra—an ICM7555 is about twice the cost of a NA555.

All things being equal, the TS555 and ICM7555 are on par. One has a faster edge, the other has less ringing (and is still actively manufactured). I’ll save the TS555 for future benchmarks. Depending on the application, I’ll either use a NA555 or ICM7555.

This post is about two of the  fox hunts organized by the Bristol County Repeater Association in 2021. (Information about the last/next fox hunting event.)

July 31st, 2021

This was my first fox hunt of any kind. To improve the chances of success I teamed up with KM1NDY and AA1F. They participated in at least one BCRA fox hunt before, so they knew what to expect. (You can read KM1NDY’s thoughts about the hunt on her blog.)

The “parameters” of the hunt were simple: find the transmitter transmitting every 5 minutes from somewhere within 5 miles of exit 13 on MA 24.

Everyone likes to talk about gear, but at least in my opinion it is much more important to have a good strategy than to invest in specialized gear. That idea, combined with not knowing whether I’d like fox hunting or not, meant that I was going to use what I already owned. That meant WA5VJB’s cheap yagi and an Alinco DJ-G7 handheld. As far as non-radio gear is concerned, I brought my iPad to use for an annotated map.

I already talked about the antenna in my ARRL June VHF contest writeup, so I won’t repeat myself here. I got the Alinco handheld because I wanted a handheld with a third band. That narrowed my options down a lot. Since I heard good things about the Alinco and having a 1.2 GHz capability seemed cool, I went with it, even though the Boston area doesn’t have any sort of 1.2 GHz activity.

We decided to meet up at  Massasoit State Park. That made it easy for me to do a POTA/WWFF activation after the hunt.

My co-conspirators were running a bit late, so I got to make the first “measurement” from the park parking lot alone. You can see it on the map labeled as #1:

As you can see, I went relatively low-tech on the map annotation. I just took a screenshot of a reasonably zoomed map and hand-drew the 5 mile circle. Then, during the hunt itself, I just eyeballed the direction of each measurement and noted it down.

When KM1NDY and AA1F arrived at the park, I shared with them my measurement. After a brief discussion about where to go next, I hopped into their car and we headed west to get back to the highway.

I won’t bore you with turn by turn retelling of the whole trip. I will, however, mention a few observations. In no particular order:

1. Even the eyeballed arrows on the map are more than sufficient to get an idea where the transmitter is.
2. The built-in attenuation in the Alinco handheld is super convenient, and pretty much all that I needed.
3. Knowing the fox can help a ton—E.g., Skip (KB1CNB), acting as the fox, is known to like coffee shop parking lots, so looking there first is wise.

October 23rd, 2021

Between this and the previous BCRA fox hunt, I got a chance to do some on-foot fox hunting thanks to K1MJC who hid a fox several times in nearby  Waltham. This time, I decided to try the hunt by myself (well, with Holly) and left KM1NDY and AA1F to fend for themselves—or “once our partner and now our competitor” as KM1NDY put it in her writeup.

This was a bigger hunt. The radius was 10 miles centered on the Veterans Memorial Bridge in Fall River and there were two transmitters!

Given the size, I decided to make a better blank map. I stitched together a couple of screenshots and then drew 5 mile and 10 mile circles. This turned out to be mostly useless since both foxes were within the 5 mile circle and we hadn’t even picked them up before entering the inner circle. Just look at the annotated map:

I didn’t even bother to try to capture all the information on this map because of how close everything was. When I got home, I ended up redrawing the map to show all the detail based on the above map, notes I made on the side, and what I remembered.

As you can see, we started off getting measurements for both foxes, but soon afterwards thought that we were relatively close to the blue fox. After driving between the two banks of the river far too many times, we gave up on the blue fox and tried our luck with the red fox.

Hunting the red fox was pretty straightforward, and before long we found Skip (KB1CNB) in his car playing the role of the fox. Skip told us that the other fox (blue on our map) was on the other side of the river. This sort of helped. So, we headed across the river.

Looking at the map now, it is clear which measurements were real and which were erroneous, but it is much harder to sort it all out when you are driving around not knowing where the fox is. :) We got really close at stop #20 where we got two equally promising directions. Sadly, we followed what turned out to be the reflection instead of the real one because we assumed that the blue fox was, much like Skip’s, a car in a parking lot. It wasn’t. The fox was on a step ladder in someone’s yard. We were clued in to this when someone mentioned it on the BCRA repeater.

I should know better, but I’ll promise anyway to write about my fox hunting strategy at some point in the future.

hamwaves.com — A cornucopia of amateur radio content.

Software type content — Assorted (mostly DSP) software by Jonti.

Dad Jokes — US government’s dad joke API.

Second IC :) — Sam Zeloof’s second home-made IC.

10 tips for academic talks

USB Cheat Sheet — Fabien Sanglard’s very nicely done summary of the USB standard naming mess.

Every so often, I have a need to dual-boot Windows with a Unix-y operating system. In the other OS (e.g., FreeBSD), I like to keep the hardware clock set to UTC (the only truly sane setting). Windows does not expose any user-visible setting to keep the hardware clock in UTC but there is a registry key one can set to make Windows behave sanely. Specifically, in:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation

you want to set RealTimeIsUniversal to a dword 1.

That’s it. After this, Windows will no longer adjust the hardware clock during DST changes.

I’ve used this a number of times on Windows 7.

This concludes today’s edition of Note To Self.

Last summer I ended up getting licensed as a  radio amateur. (Yes, it took me 11 months to mention it here.) Since then, I’ve been keeping myself busy trying out various aspects of the hobby. A week and a half ago, I got to combine a few of these aspects and participate in the ARRL June VHF contest. Namely, I wanted to try combining: contesting, roving, operating from a park, and antenna building.

I’ve been meaning to try roving for the past 7 months, but every time there was a good opportunity (in other words a VHF contest), life got in the way and I couldn’t participate.

Since I first got the idea, I’ve emailed with a number of people about a variety of radio-related topics. Speaking specifically of VHF contest roving, WB8LYJ and WW7D provided me with plenty of information. As a matter of fact, they gave me so much roving info I didn’t even use it all—yet. Thank you!

Location Planning

Every rove starts with planning of the route. In order to be a rover, one must make contacts from at least two  grid squares during the contest. Given that this was going to be my first rove, I decided to do the bare minimum and visit only two grids to get some experience for the next time.

I live in FN42, so I went with a location I knew would work—the Middlesex Fells Reservation. I’ve been there a couple of times, so I knew exactly which hill I wanted to use. This requires a 200 m hike with about 15 m of elevation gain to get to from the parking lot.

Living pretty much in the center of FN42, I have three equally annoying options for the second grid—FN32 to the west, FN43 to the north, and FN41 to the south.

I looked for parks just outside FN42 to operate from and eventually settled on Wells State Park in Sturbridge, MA in FN32.

At VHF and UHF frequencies, the elevation of the antennas matters quite a bit, so I was happy to see that Wells State Park has a decent hill—Carpenter’s Rocks. The peak is at about 260 m while the parking lot at the bottom of the park is at 190 m—or about 70 m of elevation gain over 1.1 km of distance. Hiking up the hill with the necessary radio equipment didn’t seem like too crazy of an idea while sitting at my computer.

Finally, both Wells and Middlesex Fells are in the Parks on the Air and World Wide Flora & Fauna databases. Wells is K-2462 and KFF-2462, while Middlesex Fells is K-8414 and KFF-5690, respectively. So, not only do any contacts made there count toward the contest, I can also use them to get credit for activating the parks. (Well, I didn’t realize that Wells was a WWFF park until after the contest.)

To keep the timing simple, I was going to spend Saturday at Wells and Sunday at Middlesex Fells.

Antenna—2 m

The plan for a few months was to build  yagis for 2 m and 70 cm bands and some (weakly) directional antenna for the 6 m band. Somehow, I ran out of time and only managed to build the 2 m yagi the day of the contest.

I went with WA5VJB’s cheap yagi design. I used a 2 inch by 1 inch wooden furring strip for the boom and 1/8 inch aluminum tubes for the elements.

Here’s the antenna after the contest. The elements are beaten up and slightly misaligned.

Boom

I bought an 8 foot long furring strip and cut it in half, which gives plenty of space as the 4-element “cheap yagi” design requires 40.5 inches between the reflector and the second director. I placed the reflector about 5 inches from the end of the boom which leaves enough room to act as a hand grip. This left about 2 inches extra on the other end.

Because I didn’t have time to figure out how to attach it to a mast, I drilled 3/8 inch holes about 1 inch from both ends of the boom to let me suspend it on a rope from a tree branch.

Elements

The aluminum tubes I found come in 3 foot sections. Unfortunately, three of the four elements in the design are longer than 3 feet, so I had to splice them together to make the longer lengths.

At the hardware store, I noticed that the 3/32 inch aluminum tube fit nicely (but loosely) inside the 1/8 inch tubes. So, the plan was to use bits of the smaller diameter tube as a stub to hold the sections together.

At first, I tried to solder the sections together, but the solder just wasn’t sticking to the aluminum. After nearly giving up on the build, I realized that I can crimp the pieces together. The 0.100 hex die I have for coax crimping works perfectly for this.

So, whenever I needed to do a splice, I’d insert a 1 inch section of the 3/32 inch aluminum tube between the two section of 1/8 inch tube to be joined and I’d crimp each side. This provides decent mechanical and electrical connections.

Completed splice on the driven element:

Fragility

Unfortunately, the aluminum tubes themselves are rather fragile. While carrying the fully built yagi up and down a hill, it was far too easy to bump one of the elements and bend it immediately next to the boom. It didn’t take many bumps for metal fatigue to result in a break. Thankfully, the one and only break happened on the way home. I still had to fix it in order to use the antenna on the second day of the contest.

I would not recommend 1/8 inch aluminum tubes for 2 m yagis. The elements stick out a bit too much. Combine that with the softness of aluminum, and you have an antenna that’ll break far too easily. A yagi for 70 cm might be narrow enough that these aluminum tubes would work well, but I haven’t tried. I plan to repurpose the tubes from this build for a 10-element 1296 MHz yagi. With the widest element being only 4.3 inches, it should be relatively robust. And if one of the elements breaks, it is simple enough to just cut a new one instead of having to splice things back together.

Antenna—6 m

For the 6 m band, I reused my 1/4 wave vertical that I’ve been using for Parks On The Air activations over the past two months. (I plan on making a separate post about my 1/4 wave verticals.)

Antenna—70 cm

I don’t have a dedicated 70 cm antenna. However, I have an Ed Fong DBJ-1, which is a 2 m/70 cm wire  J-pole antenna. It only really works on the 440-450 MHz part of the band, but it is better than nothing.

Contest Itself

Unsurprisingly, not everything went according to plan.

Suspending the yagi from a branch worked, but it was a bit fiddly. Specifically, it was far too easy to tilt it up or down instead of keeping it level. It was also a bit difficult to aim the antenna in a specific direction since the coax hanging down constantly tried to turn it back to where it started.

Saturday

The contest started at 18:00Z. I planned to leave early enough that I could drive over to Wells State Park, grab all the gear, hike up the hill, set up, test everything, and then have a few minutes to relax before the start.

Well, I ended up leaving late because of last minute antenna building. I planned to leave about two hours before the start of the contest, but managed to leave only 5 minutes before the start.

I arrived at the park, and it became obvious that I wasn’t quite sure how to get to the top of the hill. Instead of roaming aimlessly around the forest with all the gear, I did a quick hike to the top to find a reasonable way. This extra hiking added another 30 minute delay to my start.

When I got back to the car, I grabbed everything and headed up again. The second ascent was much harder because of the ~16 kg (~35 lbs) of radios, coax, battery, water, etc. Having my hands literally full also made it harder to defend myself from mosquitoes on the way up. Thankfully, the top of the hill didn’t have any.

Once back at the top, I took a few minutes to reduce my heart rate and then I started setting up. That’s when I discovered that even though I brought three antennas with me, I hauled only two coaxes up the hill. I left the third (and spare fourth) in the car. There was no way I was going to go back to the car, so I resorted to moving one of the coaxes between the Ed Fong and the 6 m 1/4 wave. During the first coax swap, I realized that I also forgot a coax switch.

Anyway, at least the view was nice. (You can see the Ed Fong antenna hanging in the tree on the left.)

At 00:00Z, about 20 minutes before sunset, I called it a day, packed up, and descended through the mosquito territory once more to get to the car. During the descent, I managed to break off one of the elements on the yagi.

Sunday

The first thing I did Sunday morning was fix the yagi. This took extra effort because the break happened at a crimped joint. So, the first step was to remove the broken inner aluminum tube. Once removed, re-crimping took very little time.

After that, eating breakfast, repacking everything, and so on, I headed out to Middlesex Fells. I hiked up the hill, set up the three antennas, and started working stations around noon (16:00Z).

I’m not sure what happened, but I think the repair I did on the yagi or something else messed up its pattern. It seemed as if the pattern rotated 20-30 degrees.

I planned to stay about 8 hours—from noon to 8pm (16:00Z–00:00Z), but about half way through the breeze died down enough that the mosquitoes started biting. It was nowhere near as bad as during the hikes at Wells, but enough that by 5pm (17:00Z) I decided to call it quits. I packed up and headed home. On the way home, I realized that I could use my handheld radio to catch a few more FM contacts by going to Robbins Farm Park. It is near home, has good elevation, and overlooks Boston, Cambridge, etc. — in other words, places with people and therefore hams.

I made it up to Robbins Farm Park about an hour later. I called for good 25 minutes before I got a response. The person that got back to me happens to be a new-ish ham. We chatted for about half an hour about antenna building, portable operations, ham radio in general, software (we’re both software developers), and programming languages. After that contact, I decided that I wanted dinner and went home.

Preliminary Results

So, how did I do? I ended up with a score of 832 points. Not great, but not bad either.

In more detail, I…

• worked in 2 grids (FN32 and FN42)
• worked 7 unique grids (EL98, FN31, FN32, FN33, FN41, FN42, and FN43)
• made 49 SSB/FM contacts (3 on 70 cm, 32 on 2 m, and 14 on 6 m)

Improvements For Next Time

I definitely learned quite a bit about about VHF contesting and roving. None of it is ground breaking, and I’ve heard some variant of each of my conclusions before, but I can confirm that they are valid ideas. :)

1. I should have a beam for every band I plan to use.
2. I should remember to ask the other person which bands they can use.
3. I should visit more grids.
4. I should share the itinerary with people in the area that are interested in the contest.
5. I should avoid (long) hikes.
6. I should make antenna setup as fast as possible.
7. I should use a mast instead of suspending antennas from trees.

The next relevant contest is the CQ World Wide VHF Contest in July. Which means that I have a month to rebuild the 2 m yagi, construct something directional for 6 m that is still easy enough to transport, and figure out a mast. I should also start scoping out locations. Finally, I need to subscribe to some mailing lists so I have a place to announce my intentions.

Results

This section has been added in November 2021. The results for the contests are out.

With 864 points, I placed 3rd in the New England division. This sounds impressive, but there were only 4 limited rovers in New England. More impressively, I placed 36th out of 62 limited rovers in all of US.

On several occasions, I expressed opinions about what I consider good and bad ideas as far as sysadmin-friendly interfaces are concerned. Recently, I had a reason to try to organize those thoughts a bit more, and so I decided to write them down in this post.

You may have heard me say that I don’t like “magical behavior”. Instead, I want everything system software does to be explicit. The rest of this post is going to be about words and my mantra when designing sysadmin friendly interfaces.

First of all, explicit does not mean manual. Explicit behavior is simply something the sysadmin has to ask for. A manual behavior is something the sysadmin has to do by hand.

The opposite of explicit is magical. That is, something which has a varying behavior depending subtle differences in “some state” of something related.

The opposite of manual is automatic. That is, repetitive actions are performed by the computer instead of the human operator.

For the tl;dr crowd:

explicit & automatic = good

magical & manual = bad

To “prove” this by example, let me analyze the good ol’ Unix rm command.

By default, it will refuse to remove a directory. You have to explicitly tell it that it is ok to do by using the -d flag (either directly or implicitly via the -r flag).

The command does not try to guess what you likely intended to do—that’d be magical behavior.

At the same time, rm can delete many files without manually listing every single one. In other words, rm has automation built in, and therefore it isn’t manual.

Makes sense? Good.

What does this mean for more complicated software than rm? Well, I came up with these “rules” to guide your design:

1. Avoid Magical Behavior
2. Error Out when Uncertain
3. Provide Interfaces and Tools
4. Create Low-level Primitives
5. Avoid Commitment
6. Be Consistent

Let me go through each of these rules and explain what I mean. I jump between examples of APIs and user (sysadmin) interfaces. In many ways, the same ideas apply to both and so I reach for whichever is easier to talk about at the time.

1. Avoid Magical Behavior

Avoid magical behavior by not guessing what the user may have intended.

Just like installing a second web browser shouldn’t change all your settings, installing a new RDBMS shouldn’t just randomly find some disk space and reformat it for its use. Similarly, when a new host in a cluster starts up, the software has no way of knowing what the intent is. Is it supposed to go into production immediately? What if it is Friday at 5pm? Would it make sense to wait till Monday morning? Is it supposed to be a spare?

The software should give the sysadmin the tools to perform whatever actions may be needed but leave it up to the sysadmin to decide when to do them. This is very similar to the idea of  separation of mechanism and policy.

So, won’t this create a lot of work for the sysadmin? Glad you asked! Keep reading to find out why it doesn’t ;)

2. Error Out when Uncertain

Err on the side of caution and error out if the user’s intent isn’t clear.

Error out if you aren’t sure what exactly the user intended. This is really a form of the first rule—avoid magical behavior.

It is better to be (slightly) annoying to use, than to misinterpret the user’s intentions and lose data. “Annoying to use” can be addressed in the future with new commands and APIs. Lost data cannot be “unlost” by code changes.

3. Provide Interfaces and Tools

Provide interfaces and tools to encapsulate implementation details.

If the installation instructions for an operating system included disk byte offsets and values to store there, you’d either think that it is insane or that you are living in the 1970’s and you just got a super fancy 8-bit computer with a (floppy) disk drive.

Any modern OS installer will encapsulate all these disk writes by several layers of abstractions. Disk driver, file system, some sort of mkfs utility, and so on. Depending on the intended users’ skill level, the highest abstraction visible may be a fully functional shell or just a single “Install now” button.

Similarly, a program that requires a database should provide some (explicit) “initialize the database” command instead of requiring the user to run manual queries. (Yes, there is software requiring setup steps like that!) Or in the “new host in a cluster” scenario, the new host should have a “add self to cluster” command for the sysadmin.

With these interfaces and commands, it is possible to automate tasks if the need arises. For example, since the cluster admin already has some form of provisioning or configuration management tool, it is rather easy to add the “add self to cluster” command invocation to the existing tooling. Whether or not to automate this (as well as when exactly to run the command) is a matter of policy and therefore shouldn’t be dictated by the developer.

4. Create Low-level Primitives

Err on the side of caution and create (reasonably) low-level primitives.

Different tasks benefit from different levels of abstraction. The higher the abstraction level, the less flexible it is, but the easier it is to use—but only if that’s exactly what you want to do. If what you want to do is not quite what the level of abstraction provides, it can be very difficult (or outright impossible) to accomplish what you are after.

Therefore, it is better to have a solid lower-level abstraction that can be built on rather than a higher-level abstraction that you have to fight with.

Note that these two aren’t mutually exclusive, it is possible to have a low-level abstraction with a few higher level primitives that help with common tasks.

Consider a simple file access API. We could implement functions to delete a single file, delete a set of files, delete recursively, and so on. This would take a lot of effort and would create a lot of code that needs to be maintained. If you are uncertain what the users will need, do the simplest thing you expect them to need. For example, give them a way to delete one file and to list files. Users are clever, and before long they’ll script ways to delete multiple files or to delete recursively.

Then, when you have some user feedback (“I always end up writing the same complicated command over and over”), you can revisit the set of provided primitives, and add or modify as needed.

It doesn’t matter if you are providing a file API, a cluster management API, or something else, providing some form of  create, read, update, delete, and list API for each “thing” you expect the users to operate on is sufficient to get going. Of course the type of object will dictate the exact set of operations. For example, better command names may be add/remove (cluster node) instead of a create/delete.

5. Avoid Commitment

Err on the side of caution and do not commit to support APIs and other interfaces.

It is essentially impossible to predict what APIs or other interfaces will actually end up being useful. It can become a huge maintenance burden (in time and cost) to maintain seldom used interfaces that have only a handful of users. Unfortunately, users like being able to rely on functionality not going away. Therefore, for your own sanity, make it clear:

1. Which interfaces are supported and which may change or disappear without any warning.
2. When supported interfaces may change (e.g., major versions may break all APIs).
3. What behavior of a supported interface is supported and what is merely an implementation detail.

The first two items are self-explanatory, but the last one requires a few extra words.

It is tempting to say that “function foo is supported”, but that is the wrong way to do it. Rather, you want to say “function foo, which does only bar, is supported”.

For example, suppose that we have a function which returns an array of names (strings). Let’s also assume that it is convenient to keep track of those names internally using a balanced binary search tree. When we implement this get-names function, we are likely to simply iterate the tree appending all the names to the output array. This results in the output being sorted because of the tree-based implementation.

Now, consider these two possible statements of what is supported. First, a bad one:

Function get-names is supported. The function returns all names.

And now a better one:

Function get-names is supported. The function returns all names in an unspecified order.

Using the first (bad) description, it is completely reasonable for someone to start relying on the fact that the returned names are sorted. This ties our hands in multiple ways.

The second (better) description makes it clear that the order of the names can be anything and therefore the users shouldn’t rely on a particular order. It better communicates our intention of what is and what isn’t supported.

Now, say that we’d like to replace the tree with a hash table. (Maybe the tree insertion cost is too high for what we are trying to do.) This is a pretty simple change, but now our get-names output is unsorted. If we used the first description and some major consumer relied on the sorted behavior, we have to add a O(n log n) sort to the end of get-names making everyone pay the penalty instead of just the consumers that want sorted output. On the other hand, the second description lets us do this hash table change.

So, be very explicit about what is and what isn’t supported.

I used a function in the above example, but the same applies to utilities and other tools. For example, it is perfectly reasonable to make the default output of a command implementation dependant, but provide arguments that force certain columns, values, or units for the consumers that care.

Real World Example

A project I worked on a number of years ago had very simple rules for what was supported. Everything was unsupported, unless otherwise stated.

In short, we supported any API function and utility command that had a manpage that didn’t explicitly say that it was a developer-only interface or that the specific behavior should not be relied upon.

Yes, there have been a few instances where our users assumed something was supported when it wasn’t, and inevitably they filed bugs. However, we were able to tell them that there was a better (and supported) way to accomplishing their task. Once they fixed their assumptions, their system became more robust and significantly less likely to break in the future.

6. Be Consistent

Finally, make your interfaces consistent.

Not only internally consistent (e.g., always use the same option name for the same behavior) but also consistent with the rest of the system (e.g., use the same option names that commonly used software uses). This is a rephrasing of the  principle of least astonishment.

Summary

There are other ways of approaching interface design, but the only one I’ve seen that doesn’t turn into a mess (or doesn’t cause a user revolt) is what I tried to outline here. Specifically, start with a small, simple, consistent, and explicit interface that you barely support and evolve over time.

This was a long post with a lot of information, but it still barely scratches the surface of what could be said. Really, most of the rules could easily turn into lengthy posts of their own. Maybe if there is interest (and I find the time), I’ll elaborate on some of these.

The Confusing World of USB

Amateur Radio License Map

Topographic maps

VHF/UHF Line of Sight Calculator

Hey What’s That — Line of sight calculator

Radio Mobile Online — RF coverage estimator

Telnet Access to DX Clusters and Reverse Beacon Network

FCC M3 Map of Effective Ground Conductivity in the US for AM Broadcast Stations

The Official U.S. Time

It took me about 3 years to write this post. Partly because I had other things I wanted to work on and partly because I hoped that it wouldn’t be needed. Well, I finally decided that I really need to write this.

In short, I’m officially stopping work on guilt.

Practically speaking, I haven’t touched it (as a developer) in over two years and as a user in about as long. So really, nothing will change.

What is guilt?

I started writing Guilt in fall 2006 because I was working on unionfs and needed to maintain patches on top of the Linux kernel git repository—much like what the mq extension did with Mercurial repositories.

It all started with:

commit 664e5a7d7f8d2c2726f03a239de11fa00127cf84
Author: Josef Sipek <jsipek@thor.fsl.cs.sunysb.edu>
Date:   Mon Nov 6 13:08:30 2006 -0500

    Initial commit

That’s right, 14 years to the day.

Technically, the first few versions were called “gq” (which stood for “git quilt”) until someone pointed out that “GQ” was a well established GTK-based LDAP client.

Artifacts

If anyone wishes to resurrect this project, then by all means go for it. If not, the old content will remain online for as long as I have a web server. :)

Specifically, you can find everything up to and including the last release (v0.37-rc1) at the following locations:

• HTML manpages: http://guilt.31bits.net/man/
• Source tarballs: http://guilt.31bits.net/src/
• Git repository: https://repo.or.cz/guilt.git (mirrored at https://github.com/jeffpc/guilt)

Users

I know that Guilt has served a number of people quite well over the years. It’s been quite stable and mostly feature complete since at least 2008, so I haven’t really been hearing from people short of the occasional patch or an occasional “oh yeah, I use that”.

To those users: I hope the last release works well enough for you until someone starts to maintain Guilt again or you find a different tool that suits your needs.

TL;DR: Just because email is decades old doesn’t mean that it cannot serve a vital role in modern project management, research, development, and support.

Ultimately, working on a project requires communication—and lots of it. Communication with peers, with managers, with other departments within the company, and even with customers. It is tempting to grab the Tool du Jour and add it to your ever-growing arsenal of tools believing it will make communication easier. Often, it does not.

For example, let’s consider these tools: Jira, Confluence, Slack, Zoom, GitHub/GitLab, phone, and email.

Does your company use these tools or their equivalents? Isn’t it a bit overkill to have 7 different channels of communication? Sure, often one tool is better at a particular mode of communication than the others but there is a significant overlap.

Do you want a video chat? Do you use Slack or Zoom?

Voice chat? Slack, Zoom, or phone?

Do you want to ask a question related to a bug? Do you use Jira, Slack, or just set up a call? Voice or video? Or would email be best?

Do you keep track of your project via high-level Jira issues? Or do you use a set of Confluence pages where you include various semi-autogenerated plots?

 Decision fatigue is real. Do you want your (rather expensive) employees to waste their cognitive capacity deciding which tool to use? Or do you want them to make the product better?

It is painful how many times over the past ten years I’ve witnessed conversations that went much like this:

A: Can you answer the question I left in Jira?
B: <B reads Jira question> Oh, that is answered on the ABC123 Confluence page.
A: Ah. Can you make a note of that in Jira? Thanks.

This example involves three communication channels—Jira, Confluence, and some chat system.

This sort of communication fragmentation is really bad. Not only does it waste a lot of time with exchanges like this example, it also makes searching for information essentially impossible. Who in their right mind would search half a dozen tools (with various degrees of search capability) for something? It is simply easier to just ask your coworkers. After all, their time is less valuable to you than your own time and sanity.

So, what can be done to improve things?

Well, if at all possible do not use tools that have duplicate functionality. If you have to, hopefully you can disable the duplicate functionality. If there is no way to disable it, then you must make it painfully clear where such communication should go. Hopefully this can be done via automated hooks that somehow notify the user. For example, automatically closing issues opened in the wrong bug tracker (e.g., opened in GitHub instead of Jira), or automatically responding to wiki commenters directing them to the proper medium for wiki discussion. Finally, if all else fails, have someone (ideally manager or team lead so the notification has some weight to it) manually make sure that anyone that uses the functionality is told not to.

This reduction in the number of tools should also help with responsiveness. It is no secret that  the average human can hold only about 7 things in working memory at the same time. How many of those do you want to dedicate to tooling? If I have to remember to check 7 different tools periodically, one of two things happens: either I manage to check them all but accomplish nothing else, or I get things done but only remember about 2 or 3 tools.

That should help with quite a bit of the fragmentation. Now “all” that’s left to do is decide which communication channel is used for what.

I have concluded that there are four major levels of communication:

1. important, synchronous
2. important, asynchronous
3. unimportant, synchronous
4. unimportant, asynchronous

I’m using the terms “synchronous” to mean that you want the back-and-forth latency to be low, and “important” to mean that that you must have an answer. Note that “unimportant” does not mean off-topic, but rather lower priority.

Why make the synchronous/asynchronous distinction? For multiple reasons. First of all, being interrupted in the middle of something is costly. It takes a significant amount of time to get back “into the zone” but only a fraction of a minute to get out of it. Would you rather pay your employees to try to work or to actually work? And second, asynchrony makes communication across time zones easier. Not easy, but easier.

So, let me go through the four major levels of communication one by one and share my opinion about what works and why.

important, synchronous

If you want to have a (relatively) rapid back-and-forth, you pretty much have to use an in-person meeting or a voice/video call. A one-to-one (i.e., non-group) chat can also possibly work, but there will be temptation to multi-task. This desire to multi-task implies that the chat isn’t actually that important.

important, asynchronous

When you don’t require having the answers immediately or when it simply isn’t possible to get everyone in the same “room” at the same time for a meeting (in person, voice, or video), email is probably the best communication method. Each person can read it and possibly reply at a the most convenient time for them.

unimportant, synchronous

This is the form of communication that includes various chit-chat, sanity checking polls (e.g., “would anyone object if I tried xyz?”), and so on. It lets you quickly get bits of information, but in a way it is unreliable. Not everyone is reading the chat when you say something and when it scrolls off the screen it is as if you never said it. In other words, do not expect anyone to read the group chat messages from when they were away. If you want someone specific or even everyone to see a particular message, it is not an unimportant message. One-to-one chat is a little different since it is more “reliable”, but usually anything substantial that is important will end up with a call instead.

unimportant, asynchronous

Finally, all the things you’d like others to see at some point in the future should be sent as an email. The recipients will read it when they get to it, and since it isn’t important it probably doesn’t even require a reply.

These four levels are, of course, not set in stone. It is possible (and I’d even encourage it) to upgrade or downgrade your communication as needed. For example, it is perfectly reasonable to ask in chat if there are objections or obvious issues with a particular approach, function, or workload. Then, if the responses don’t make it obviously a terrible idea but a more definitive discussion is desired, a similar (but more detailed) version can be sent via email. In essence, upgrading it from “unimportant synchronous” to “important asynchronous”. (Caution: don’t overdo these upgrades/downgrades.)

As you can see, I think that email is a good choice for any asynchronous communication. That’s for good reasons. Everyone has an email address, everyone knows how to use it (at least a little), and the free-form format allows you to use the most appropriate content type to get your point across—be it ASCII art, images, or even Excel spreadsheets. In other words:

Email is ubiquitous.

Email works remarkably well.

Email is extremely flexible.

As a real world example, consider that pretty much every company-wide announcement (important or not) has been made either in a huge meeting or via email. Often the meeting-time announcements are followed up by an email anyway! It’s not a chat message. It’s not a Confluence page. It’s not a Jira issue. It’s an email.

Before I conclude, I’d like to address two slightly more specific cases.

First, what about issue tracking? How does that tie into my email-centric world? Well, you can keep your issue tracker, but in my opinion, the comments feature should not be used. If a ticket needs to be discussed, send an email, set up a conference call, whatever works for your—just don’t use the comments on the issue. If you look at any issue in your issue tracker, the comments will fall into one of two categories. Either there are none or there are many, and it is painfully clear that people don’t read them and ask the same questions over and over. Instead of burying progress reports or updates to the understanding of the issue in a comment that nobody will ever read, that information should be used to reword the issue description. The same largely applies to other tools’ comments sections as well.

Second is a concern that people will not read all those emails. I think this is only a problem if there are too many tools and email isn’t viewed as an important one. If (unrealistically) all communication happens through email, then right after communicating with someone, the person is already in the right tool to handle the next communication. If code reviews, support requests, and everything else were to go to the same place, there is nearly zero context switching cost. Even if the person goes to use a different tool (e.g., a text editor or an IDE), when that work is done, they’ll return to their email client. In other words, if you make the email communication channel important, your emails will get read. If you don’t make it important, then you (individually) are better off using a channel the recipient considers important. In an environment with too many tools, each recipient may have a different preference.

Just to make it painfully clear, I am not advocating killing off everything except email. Instead, I’m advocating killing off tools that duplicate functionality, and shifting all asynchronous communication to a single medium. In my experience, the most efficient (and least disruptive) asynchronous communication medium is email. And therefore it should not only be one of the tools that survives the culling, but it also should be the one that is embraced afterwards.

That’s it for today. In the next post, I’ll talk about what I consider the ideal code review workflow.

Sound in FreeBSD is somewhat complicated because of the various portability and compatibility shims. Last week, I hit an annoying to diagnose situation: I plugged in a USB sound card and while the kernel and some applications detected it just fine, other applications didn’t seem to notice it at all.

At first, I thought it was a Qt issue since only Qt applications appeared broken. But then, mere minutes before emailing a FreeBSD mailing list, I managed to find a hint that it was likely an ALSA on FreeBSD issue. Some searching later, I learned that in order for ALSA to see the device, it needed a mapping to the actual OSS device.

So, after adding the following to ~/.asoundrc, any ALSA application (and therefore any Qt application) that tries to list the sound devices will see a “ft991a” device:

pcm.ft991a {
	type oss
	device /dev/dsp3
}

To make it more explicit, without adding the above stanza to .asoundrc:

1. OSS applications work fine.
2. PortAudio applications work fine.
3. ALSA applications did not see the device.

With the stanza, everything seems to work.