The systems you want to be debugging are the ones you can reason about

This is a little story that I want to cast as a parable for considering the state of software engineering.

So for an AxesXplained post, I was soldering up the restoration project with an interim lash-up as part of the process of deciding what the final wiring should be, as the old wiring setup was not great back in the 1990s.

It’s not a grade II listed building

We’ll be discussing this technique:

I wire it up, and the switch half works.

Oops

Image for post
Image for post
to be fair, always looking at the last installed component first…

So naturally, I plan to go took a thorough look at my handiwork, but first, is it possible to characterise this issue?

Review: what was intended?

The switch was meant to flip the electrical combination of the coils from the common series combination to that of parallel combination.

Review: What happened?

The pickup only worked in the parallel combination

Current hypotheses:

  • coil is borked due to use of ham fist (unrecoverable fault)
    - only requires one fact
  • switch is half borked due to ham fisted soldering (unrecoverable fault)
    - needs theory of how switch could break that way
    - and see below
  • connections are borked due to ham fisted soldering (fixable fault)
    - see below
  • *below*
    Now, the reason I downloaded a wiring diagram is because switching diagrams is one of my blind spots — I never had the training course, and frankly, I’m too pig-headed to stick to the simple circuits I can’t get wrong.
    Hence I don’t have the ability to instantly discount the possibility that one fault could be the origin of the observed behaviour.

One might argue reasonably that a badly wired wiring diagram would fail in both positions, for example. It may do so, but it need not do so.

Keep looking

So, there are some more things I can do before going back to the soldering iron.

In the working position, is it really working?

  • no buzz — check
  • sounds right tonality / strength
  • passes the tap test to show both coils are active

So, yes, oddly, the fault exactly keeps one side working and the other … not

In the broken position, how broken is it?

  • absolutely no signal (not just massively attenuated)
  • no buzz /hum
    - see later

*later* typically open circuit issues can inject noise signal into the circuit, giving a strong clue. Sadly my vastly more through approach to shielding the circuits from noise has somewhat mitigated this rule of thumb. That’s progress for you!

in other positions, what effect does the fault have?

  • Aha — in “working” position, the pickups are all working, and the “in-between” settings work as expected.
  • In the “broken” position, the other pickup settings all work, except for the absence of the bridge pickup signal.

This means parallel combinations are not affected by the issue.

Ok, now we know the pickup is open circuit in that position.

I *don’t* know if that is the parallel or the series combination, although from the sound I would guess it’s the series that’s affected. There is also a more general point that series circuits only need one open circuit anywhere and they all fail that way, whereas (again I have yet to consult the diagram, because “bloke” and it’s a 4 metre walk) for parallel, one would have to choose more carefully where to place the faulty wiring.

Review: let’s look at the diagram and the handiwork

I take a look and line them side by side.

I have of course, picked wire colourings and placement so that the diagram and the piece can be placed side by side.

Whoops, I missed out a whole link wire: that would do it.

Solder in the link

And the same issue again, same symptoms

Review (again)

So, my initial hunch would have been a bad joint, as I do in fact, eyeball pieces after making them.

New hypothesis:

There was a dozy oversight and the obligatory bad joint.

You can only test for one open circuit at a time

Inspect the new link and then the original wires

I gave one of them a light tug and it was loose: either I completely missed it or the original attempt at the fiddly connection was no good.

Re-solder — and we’re good!

The tap test shows both coils are always connected both positions.

The sounds are good, and match what is expected.

So what have we learned?

In this simple enough system, with a light dusting of high school electronics, and some reasoning about likelihoods, my first assumption “ah, bad joint” was close to being the first cause and was the second.

In my defence, the missing link wire and bad joint were electrically indistinguishable without getting very deep.

The second thought “did I finish all the steps off correctly?” was the correct place to start and the logical first fix.

This illustrates the power of systems that are amenable to being reasoned about

There is a never ending lesson for system designers, which that if humans are not presented with a figurative or literal Gordian knot

they may well be able to rapidly fault-correct.

So, are we making progress?

https://en.wikipedia.org/wiki/Agile_software_development#Common_agile_software_development_pitfalls”, “Move fast and break things”: I’m looking at you.

I don’t think my minor electrical engineering issue is trivial, if we take a step back. The net outcome of the project is quite impressive for little net effort, guided by an insight into how the system works. This of course, follows from the properties of the components and the features of how they are combined.

That last recasting is sounding a bit more generic, is it not?

Perhaps if software engineering were to focus even more on systems that produce strong guarantees that can be combined in ways that have easily understood outcomes we will see some benefits?

WAIT THAT’S

Perhaps this is a failing in my projects, but I observe that more often than not, we fail to produce a well thought through system that meets the above precepts.

Conversely, it’s a common consequence that systems organically accrete features and amendments and bug-fixes and re-purposing end up being the kind of system you really don’t want to spend too much time doing more of the prior.

And to return to the original parable, they become the kind of system where I can’t simply think “ah, bad joint”

Written by

Person. blah blah about me ... WAIT CLIMATE CANCER WE CAN BEAT IT PEOPLE ... all opinions my own

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store