Tools

Five Wire, a Portable Debugging Suite for Digital Engineers

Table of Contents:

  1. Introduction
  2. Feature Overview
  3. Unboxing
  4. Installing
  5. Documentation
  6. Five Wire in Action
    1. LiveLogic
    2. Protocol Tool
    3. Waveform Source
    4. Logic Analyzer
    5. Logic Source
  7. Design Motivations
  8. Comparing the Five Wire to My Current Toolset
    1. Price Point
    2. Capabilities
    3. Verdict
  9. My Five Wire Wish List
  10. Closing Thoughts on the Device

Introduction

As an engineer, I take my tools seriously. Our tools act as a force multiplier for our work, enabling us to accomplish increasingly complex tasks with reduced effort. The time we invest in selecting, learning, and maintaining our tools is time well spent.

One tendency that I regularly see, and that I've personally struggled with, is the tendency to become complacent with the current toolset. We become comfortable with our tools, especially after investing time in learning how to use them. We don't even consider other options, even when they promise a dramatic improvement. This effect is magnified by the time it would take to learn the new tool.

I recently encountered Five Wire, a tool that promises to condense most of my suite of embedded debugging tools into a single hardware and software package. I was excited at the feature set and possibilities, but the familiar feelings of new-tool-trepidation came to the surface:

  • Don't my current tools already provide most of these capabilities?
  • Will it really do everything it claims?
  • How much time will it take to reach fluency?
  • Is it worth the price?

I believe that engineers should invest in quality tools: they pay dividends by increasing our productivity and product quality. I decided to follow my own advice and check out the Five Wire. If you're on the fence about purchasing a Five Wire tool, I hope this review gives you a thorough look at the device, warts and all.

5 second summary: I think the Five Wire is an extremely powerful debugging tool that is well worth the price. I've spent an equivalent amount of money for all of my lab and debugging equipment, much of it used, and still can't match the capabilities that the Five Wire provides. It also greatly simplifies my travel debug kit.

 

The FiveWire debugging tool, freshly unboxed.

 

Feature Overview

The main draw of the Five Wire tool is that it combines five distinct hardware tools into a single package. Each tool is controlled through a single computer program. The five tools are:

  1. LiveLogic (a digital oscilloscope)
  2. Logic Analyzer
  3. Protocol Tool
  4. Waveform Source
  5. Logic Source

Each tool is implemented in hardware. The hardware is implemented in such a way as to avoid bandwidth issues. All five tools can be used simultaneously if needed.

All I/O pins on the Five Wire are rated to 0-5 V. This works well for modern embedded applications. If you need to analyze higher voltages, a proper oscilloscope is required.

The Five Wire software is essentially a display front-end for the hardware. Each of the five tools has its own window, and they can all be open at the same time. Each tool window also includes a convenient "copy window" button, which copies a screenshot of the current contents to the clipboard. This is especially convenient for capturing and sharing your results.

The Five Wire uses a "delta" storage format. Only signal transitions are recorded, allowing long time-spans to be captured. Each tool can save captured data into a CSV for post-processing. The data files can be shared with other team members. Captured data can be viewed in the Five Wire program without having a Five Wire device.

Each tool has an associated hardware button on the Five Wire device. These buttons may seem to be unnecessary since we can start and stop each tool in software. During my testing, I used the hardware buttons much more often than I thought I would. It turns out that it's much easier to coordinate pressing a physical button and starting software in tandem than trying to start two software programs.

The Five Wire can decode communication protocols such as RS232, I2C, SPI, and LIN. You can also write your own custom communication protocol decoders with the Five Wire's DCD Script language.

All of the tools have the ability to trigger events and wait for events. This enables complex behaviors, such as triggering the Waveform Source tool with a custom analog waveform whenever a GPIO trigger is received from the target device. These triggers and events can be configured in the application. You can write scripts to control the tool suite using the Five Wire's MBScript language.

The software currently runs only on Windows 10.

Unboxing

I dig deeper into the features below, but I figured that a $1795 tool deserves an unboxing ceremony.

The Five Wire ships in a nice sturdy box. The art is kept on a sleeve which slides off (product designers, take note - you don't need to add a fancy $15 custom foam-cut package to your BOM for attractive packaging).

 

The FiveWire ships in a nice sturdy box. The art is kept on a sleeve which slides off.

 

When you open the box, you are greeted by a one-sheet getting started guide. Underneath the guide is the Five Wire device and an oscilloscope probe.

There is also a box with accessories - many more than I was expecting to find! The Five Wire comes with:

  • Two 10x Oscilloscope Probes
  • Logic Analyzer probe with 10-wire connector
  • Pattern source probe with 10-wire connector
  • I2C Protocol Adapter with 3-wire connector (clock, data, and GND)
  • Power Adapter
  • USB Cable
  • USB drive containing the Five Wire software and user manuals

Greeted by the five wire and a scope probe.

I wasn’t expecting to see all of these accessories!

The Five Wire device itself is a sturdy metal product. The metal enclosure is a welcome touch - I'm growing weary of flimsy plastic products.

The Five Wire comes with a kickstand, which places the device at a much more convenient viewing angle. The left side of the device features a USB connector and power connector. Cables for both are provided in-box.

The FiveWire, free from its former restraints.

The FiveWire comes with a kickstand for easy viewing. Also note the USB and power port on the left side of the device.


Installing

Installing the software was straightforward, especially since the in-box USB drive contained an installer. You can also download the latest software from the Five Wire website.

The software is targeted for Windows 10, and it uses the .NET 3.5 Framework. If you don't have the .NET 3.5 framework installed, Windows will prompt you to download and install it when you first run the Five Wire application.

 

FiveWire uses the familiar Windows installer.

 

Documentation

If you're a long-time reader of this blog, you know how much I value well-documented products. The Five Wire is one such product.

The USB drive that ships with the Five Wire contains helpful reference documentation:

The Five Wire website has a series of Getting Started videos which helped me quickly become familiar with the tool. Currently the videos are focused exclusively on the LiveLogic and Waveform tools.

The Five Wire website also features a series of Application Notes which use the product in a variety of different scenarios. These caught my eye:

Of course, the User Manual is always a last resort, but I was extremely grateful for its detail. There were many questions I had which weren't covered by the introductory material, such as how to configure protocol analyzer triggers or how to use the protocol tool to talk to an I2C slave device. I highly recommend taking the time to read the manual if you find yourself stumped.

Five Wire in Action

Now that we're oriented with the device, let's look at each of five tools in greater detail:

  1. LiveLogic (a digital oscilloscope)
  2. Logic Analyzer
  3. Protocol Tool
  4. Waveform Source
  5. Logic Source

LiveLogic

The LiveLogic tool is meant to operate similarly to a two-channel digital oscilloscope. LiveLogic sports a 400 MHz sampling rate. Two channels is enough - most 'scopes I've used in my career, including the HM1507-3 that I own, only support two channels. Four-channel 'scopes are prohibitively expensive, and many larger companies only keep 1-2 on hand.

The capture button, zoom knob, and scroll knob give a familiar 'scope feel for capturing and navigating around a waveform. Having a hardware capture button is especially useful when coordinating multiple activities, such as starting software and triggering a capture at the same time. It also gives our debugging partner something useful to do. (Who hasn't been a part of a 'scope huddle from time to time?)

The display is continually updated and signals are auto-scaled. Like all auto-scaling 'scopes, the initial scaling probably needs to be tweaked a bit to get to the exact view you need.

Both continuous and single capture modes are supported, with a variety of trigger settings. Where LiveLogic excels over the traditional oscilloscope is the ability to easily specify complex triggering logic. It's a breeze to specify "trigger a capture when the line has been high for 10ms and then goes low for 15us", which would be almost impossible to implement on a traditional 'scope.

Another area where LiveLogic excels over traditional scopes is the potential capture duration. Because LiveLogic uses a delta capture format, where only signal changes are stored, the tool can support a much longer capture duration than a traditional oscilloscope.

A view of the Live Logic window. My trigger is set on a falling edge after logic ‘1’ has persisted for > 100 microseconds (100u).

Other familiar 'scope features are included in LiveLogic, such as reference markers which perform time calculations.

You can right click on the waveform to set marks. You can set a time reference, and additional time marks which calculate the durations relative to the reference mark. Time mark measurements have a 2.5ns resolution.

You can set time marks for waveform measurements, just like on a scope.

LiveLogic supports protocol decoding, so you can hook up an I2C clock and data signal and see the translated output. A variety of decoders are supplied with the tool. You can also write custom decoders using DCD script.

LiveLogic was used to capture and decode I2C traffic. Channel 1 is SCK, and Channel 2 is SDL.

The LiveLogic display features a digital voltmeter (DVM) on each channel, allowing you to get quick voltage readings. This feature is quite helpful since LiveLogic only operates as a digital scope - looking at the graph output doesn't give you any indication of the signal's voltage level.

Screen Shot 2019-04-25 at 12.19.44.png

Protocol Tool

The Protocol Tool is a complex one - accurately described as comprising multiple tools in a single package. The Protocol Tool automatically configures itself depending on the probe that you attach to the Five Wire.

A primary use for the Protocol Tool is emulating an I2C/SPI master or slave device. This is extremely useful for exploring the behaviors of a new slave device, debugging slave devices in-system, or mocking a slave device to validate your embedded system. The Five Wire ships with an I2C Protocol Adapter, but the SPI Protocol Adapter must be purchased from the Five Wire store.

The Protocol Tool also supports the "Trigger Protocol", which provides 3 trigger signal inputs and 3 trigger signal outputs. This protocol is used for automation and coordination purposes. Trigger inputs can be used to generate an event and kick off another tool, and trigger outputs can be set when a trigger event is supplied by another tool. Your imagination is the limit for using triggers. The Trigger Protocol adapter must be purchased from the Five Wire store.

The only downside of this powerful Protocol Tool is that you really must read through the User Manual to understand it. I tried poking around to see if I could figure it out. I quickly gave up. Once I read the manual, I was up and running in no time.

To test out the Protocol Tool, I used the I2C probe and attached it to a proto board populated with a VL53L1X time-of-flight sensor. I programmed a simple transaction which reads the model ID (held in register 0x010F) from the device (the value 0xEA shown in the image is correct).

For most I2C purposes, this tool works well. However, each write transaction can only send a maximum of 8 bytes. This can be limiting for some systems. For example, I have an OLED driver which takes a 384-byte screen buffer payload. But these scenarios are fairly uncommon.

The I2C exchange shown in this image reads the model ID from the ST VL53L1X time-of-flight sensor. The read value (0xEA) is the correct model ID.

Waveform Source

The Waveform Source can program an arbitrary analog voltage waveform with an output range of [0V, 5V]. The tool can handle up to 1020 sequential voltages with 10 bits of amplitude resolution. Waveform durations can span 5 microseconds to 5000 seconds with up to 0.2 microsecond resolution. A preview window is provided so you can see the waveform that will be produced.

The tool provides a variety of built-in waveforms:

  • Sine
  • Square
  • Triangle
  • RC curve
  • Battery discharge curve, with multiple profiles:
    • Alkaline
    • Ni-Cd
    • Li-ion
    • Ni-MH
    • LiPo
  • DC Output

You can also specify an arbitrary waveform profile using a CSV file. With MBScript, you can use looping and conditional branching to generate complex waveforms.

The Waveform Source can also be used as a power supply. The Five Wire can source up to 100mA through the Waveform Source leads. Coupling the power supply capability with configurable waveforms enables hardware designers to evaluate supply-related behaviors, such as simulating brown-outs.

The Waveform Source can be used to configure a battery discharge profile.

Logic Analyzer

The Logic Analyzer sports 9 channels, each with a 100 MHz sampling rate. The Logic Analyzer comes with an associated "Logic Analyzer Probe" that terminates with 9 individual signal wires and 1 ground wire.

The Logic Analyzer supports protocol decoding, and you can enable multiple decoders for a single capture. A variety of decoders are supplied with the tool. You can also write custom decoders using DCD script.

Captured data is displayed in timing diagram format. User-defined labels, protocol data, and time measurements can be superimposed on the signal capture. The display order of the signals can also be modified in the software.

The most powerful feature of the Logic Analyzer is triggering logic. The analyzer supports up to three levels of sequential triggering. You can specify multiple trigger levels at once to create complex triggering logic; each condition must be true in the specified order to trigger a capture. The trigger levels also control the position of the capture (triggering "middle" will capture samples before and after the trigger event, while triggering "start" will only capture samples after the trigger event). Like LiveLogic, the Logic Analyzer also supports time-qualified triggers.

Timeouts can be configured to stop a capture in the event that the triggering condition doesn't occur. You can also manually stop the capture by pressing "Stop" in the application or the Logic Analyzer's "Capture" button on the Five Wire device.

To test the logic analyzer, I connected it to a proto board with a VL53L1X time-of-flight sensor and a SSD1306 OLED display driver. The SCK signal was connected to wire #3, and the SDA signal to wire #4. I then enabled the I2C decoder.

Configuring the I2C decoder is easy: just tell it the position of the SCK and SDA signals.

Configuring the I2C decoder is easy: just tell it the position of the SCK and SDA signals.

I then started a program which reads values from the ToF sensor, updates the OLED screen buffer with a printout of the distance measurement, and writes to the OLED display.

Capturing at a random point in this cycle revealed our I2C data, with decoded values superimposed on the captured waveform.

Our waveform capture with decoded I2C data superimposed.

Zooming in shows the captured output in greater detail.

Here we’ve zoomed in on a specific transfer to see it in greater detail.

A really interesting use case for debugging RTOS thread execution using a custom decoder protocol is presented in this app note: Using the Five Wire Toolset for Real-time Trace of RTOS Execution. This will definitely come in handy in the future.

Logic Source

The Logic Source tool is a pattern generator. Logic Source supports 9 output IO with programmable high/low drive levels.

The tool allows you program up to 1020 vectors with durations in the range of [30ns, 40ms]. Times can be specified in 10 ns increments. Looping and conditional branching support allows for complex logic patterns to be generated. Logic Source output can be single-shot or continuous, and output can also be triggered by an event.

Here I’ve made a 4-bit “counting” pattern which repeats on a loop.

Comparing the Five Wire to My Current Toolset

I think the fairest evaluation of the Fire Wire is in comparison to the suite of tools I have that provides the equivalent functionality. I shared some of them when reviewing my portable embedded travel kit. We'll also compare it to my oscilloscope and benchtop DMM, which do not travel with me.

Here are the items I will be comparing to the Five Wire, with the prices I paid for them:

Price Point

The total price I paid for my equivalent equipment suite is $1570. If you count the original price of the Tektronix DMM, that jumps to $2295. I don't have a signal generator in my lab, which would increase the equipment cost even further.

The Five Wire's price point is right in the ballpark for what I paid for my equivalent toolset. Had I bought all of my equipment brand new, the Five Wire would come in much cheaper. Don't let the Five Wire's price tag scare you away. The value is there.

Capabilities

Now, price isn't the fairest comparison: the Five Wire and my current toolset both provide capabilities not found in the other.

Five Wire provides a Waveform generator, as well as a programmable digital logic output generator (Logic Soure). I don't have any tools in my lab that provide these functionalities.

Oscilloscope Comparison

Now, technically the Five Wire's LiveLogic tool is not an oscilloscope. But since it provides similar capabilities, I will be evaluating it against my HMS1507 oscilloscope.

Five Wire holds several advantages over my HMS1507. Most obvious, my Five Wire's 400MHz frequency beats my HMS1507's 200MHz. My HMS1507's frequency has limited my scoping of high-speed digital signals before, so I am grateful for the higher frequency of the Five Wire. The Five Wire also holds the advantage with protocol analysis and triggering capabilities. Time-based triggering has been especially helpful for honing in on scenarios of interest.

My HMS1507 beats my Five Wire because it can probe analog signals. However, I am primarily a digital engineer working on digital systems, and my analog debugging sessions are extremely rare. When I need the analog capabilities of a 'scope, it's usually to confirm the suspicion of noise on signal causing erroneous digital readings.

DMM Comparison

DMM accuracy varies across measurement devices. To check the Five Wire's accuracy, I used the Waveform Source to generate a 3.3V DC signal. I then took measurements with each DMM. My Tektronix DMM 4020 is the most accurate of the bunch, so we'll use it as the reference.

  • Tektronix DMM 4020: 3.291 V
  • Five Wire DVM: 3.26 V (0.94% error)
  • Mastech MS8268 DMM: 3.286 V (0.15% error)

We can't expect the Five Wire to be as accurate as the Tek DMM 4020, and < 1% error satisfies this engineer. The Five Wire appears to be more accurate when reading a 5V DC waveform, as it reports 4.98 V (0.4% error, assuming the output is 5.0 V exactly). You won't be calibrating power supplies with the Five Wire, but you don't need to carry around a DMM to serve as a voltmeter.

That isn't to say that the Five Wire eliminates my need for a DMM. I frequently use my DMM's continuity mode to check for shorts. Resistance and capacitance readings are also useful.

Logic Analyzer Comparison

The Five Wire and Salae logic analyzers operate very similarly. Both enable you to decode multiple protocols. Each one holds a slight advantage over the other in different areas.

The Five Wire has superior triggering capabilities, which can be quite helpful when attempting to capture a tricky scenario. The time-based triggering has already proved useful to me, and being able to set multiple trigger conditions before executing a capture is immensely helpful.

The Salae wins in terms of maximum duration of capture. The Five Wire capture maxes out at 2048 samples. Since the Five Wire only records signal deltas, this is sufficient for most debugging. However, I tried to capture a 384-byte I2C transfer using the Five Wire, and the logic analyzer capture ends before the transfer completes. The Salae can capture that transaction with no problem. That being said, the Salae logic does have a limited device-side buffer, and we have had our device complain that it was not able to keep up with the sample rate. The Five Wire will not report such a problem during capture.

As a purely personal preference, I find it more natural to use the Five Wire's physical knobs to navigate the captured waveform. Even after 8 years of using a Salae logic analyzer, I haven't gotten use to the app's click/zoom behavior.

Protocol Comparison

From a debugging perspective, the Five Wire and Aardvark I2C/SPI debug adapter provide almost equivalent functionalities. The Aardvark has the advantage over the Five Wire in two aspects:

  1. The ability to send larger payloads (the Five Wire is limited to 8 bytes per write)
  2. The API and library which allows you to interact with the Aardvark adapter from a program

These features aren't crucial for in-field debugging. I could safely leave my Aardvark adapter at home and accomplish everything I need with the Five Wire.

From a test automation perspective, the Five Wire has greater potential, especially because we can use events to script complex behaviors.

From a system bring-up perspective, however, the Aardvark APIs have been invaluable. When I need to write a new driver, I put the slave device onto a proto board and connect the I2C/SPI signals to the Aardvark adapter. I can write and test my slave driver by talking to actual hardware using the APIs. When the driver is complete, I can port it over to the target platform with little-to-no modifications.

Luckily, I have another tool in my kit which can be used for this purpose: the TUMPA debug adapter. While I normally use it as a JTAG device, the TUMPA can also interface to I2C and SPI devices. Technically the Aardvark has won over on the Five Wire due to the APIs, but I can make up for that with another tool.

Portability

Having a portable toolkit has been important to me throughout my career. As an employee, I frequently travelled for field testing and to support manufacturing builds. As a consultant, I regularly travel to my client's offices. On many trips, debugging tools aren't available on-site, so having a toolset I can travel with is crucial.

Five Wire handily beats my current toolset in terms of portability. I currently need to travel with 4 different devices and a USB hub, and those tools don't match the capabilities provided by the Five Wire.

Five Wire augments my current travel kit's capabilities with a digital oscilloscope and waveform generator. My new kit can be reduced to two USB devices: the Five Wire and the TUMPA debug adapter. The Five Wire and its accessories do increase the physical size of my current kit, but that is offset by the additional capabilities. The Five Wire is also slightly heavier than the replaced tools, but the weight is still negligible.

Verdict

The Five Wire is a worthy tool and has a new home in my toolset. It will reduce the number of devices I travel with, while simultaneously increasing my debug capabilities.

The Five Wire provides great value for the price point. I spent the equivalent amount on my current tools and still don't have all of the capabilities that the Five Wire provides. I rarely need the capabilities that are not covered by the Five Wire. I think it's a valuable debugging tool for developers.

My Five Wire Wish List

I think the Five Wire is a powerful device, but I promised to share the warts too. Here is my Five Wire wish list:

  • • I am able to use this tool with my Mac via Parallels, but I really wish the program also ran on OS X and Linux.
  • • The LEDs are too bright, and thus distracting. They should be tuned down. I've taped over them for now.
  • It's not immediately obvious that "update waveform" doesn't change the waveform output if the tool is already is running. If you click "Update" while a waveform is running, the graph updates but the output does not. You have to stop, update, and start. It would be great if the output would automatically update.
  • I really like the grabbers that come with the Salae Logic Analyzer, and I think they would be a great addition to the Five Wire. The wire leads on the connectors are the same type as the Salae so luckily, I can use the ones I have.
  • I wish there was an API like the Aardvark provides, so I could use the Five Wire as a I2C/SPI master from a program.
  • I wish there was a way to execute scripts from the command line, so I could use the Five Wire for hardware-in-the-loop tests with my CI server when I don't need it for debugging.

Closing Thoughts on the Device

There's always trepidation and resistance to learning new tools, but I surprised myself with how much I enjoyed using the Five Wire. I have my wish list of features and modifications, but that is true of every tool that I use. I think that the value provided by the Five Wire significantly offsets my wishlist.

I really enjoy using the Five Wire because of the combined hardware-software interaction. It's extremely satisfying to press buttons and turn knobs. It's also extremely useful when coordinating activities; it can be quite difficult to start two different software programs in tandem. I've barely scratched the surface of its capabilities, especially with automating hardware tests through triggers and events.

I think the Five Wire is a valuable debugging tool that is worth the price.

Further Reading

A Look at My Portable Embedded Toolkit

Embedded systems developers rely on a variety of tools: debug adapters, power supplies, multimeters, oscilloscopes, logic analyzers, spectrum analyzers, and more.

Much of the equipment we use lives in our offices or labs, since it's too bulky to move around. But for engineers who travel frequently, it's quite helpful to have a portable toolkit. You never know when you'll be stuck in an emergency debugging situation, and having familiar tools on hand is a blessing.

If you're an engineer who travels frequently, or if you're just simply looking for useful tools, I hope you can find inspiration from my kit.

My Portable Embedded Toolkit

I've slowly built my portable embedded toolkit over the past ten years, and I've managed to pack a lot of debugging power into a small load. My kit is always on hand when I'm visiting a client, and its travelled with me to multiple manufacturing builds in China.

My kit consists of the following:

  • Digital multimeter
  • Aardvark I2C/SPI Host Adapter
  • Saleae Logic Analyzer
  • TIAO USB Multi-Protocol Adapter
  • USB Hub
  • A grab bag of wires and clamps
  • Spare jumpers

Most of the kit packs down into a first-edition Saleae Logic 8 case, which was made with a much sturdier shell. I carry the DMM and Aardvark adapter separately in my bag.

Let's take a deeper look at each piece of my kit and the roles they serve.

The major pieces of my embedded toolkit, packed for transport.

The unpacked contents of my Saleae case.

DIGITAL MULTIMETER

Digital multimeters (DMMs) are an essential tool for anyone working with electronics. I regularly need to measure voltage/current/resistance/capacitance and check continuity between signals.

My portable DMM of choice is the Mastech MS8288, which costs around 30 USD. I purchased my multimeter ten years ago and have yet to find a single cause for complaint.

For low-power tasks, the Mastech MS8288 performs admirably and produces accurate measurements. Once voltages and currents start to rise, you’ll notice inaccuracy (I've seen 3% error while measuring a 48V power supply). With that in mind, this isn't a DMM you'd use for tuning your power settings. For tasks which require precise measurements, you'll need to turn to a higher-precision DMM.

When selecting your own multimeter, make sure it has the following features:

  • Measurement Capabilities:

    • DC voltage 

    • AC voltage

    • Current

    • Resistance

    • Capacitance

  • Continuity check with audible beep

  • Selectable measurement range

  • Kickstand

  • Screen backlight

Everybody needs a multimeter, but you don’t need the most expensive one available.

Everybody needs a multimeter, but you don’t need the most expensive one available.

Aardvark I2C/SPI Host Adapter

The Aardvark I2C/SPI Host Adapter is the newest addition to my toolkit. The Aardvark has been tremendously helpful in tracking down I2C/SPI problems and validating I2C/SPI interfaces. The adapter can operate as both a master and slave, and you can script sequences of commands to send to the device.

Total Phase also supplies libraries that you can use to interact with the adapter programatically. I’ve written I2C and SPI drivers for the Aardvark adapter, which enables me to write device drivers from the comfort of my host machine. Once the drivers are working, I can quickly port them to the target platform.

The newest addition to the toolkit. Useful for debugging I2C/SPI problems and for writing drivers on your host machine.

The newest addition to the toolkit. Useful for debugging I2C/SPI problems and for writing drivers on your host machine.

Saleae Logic Analyzer

When I first started my career, logic analyzers were giant pieces of equipment which lived permanently in the lab. You would spend hours carefully getting set up and configuring the device, and you were chained to the analyzer until you were finished.

When Saleae released their amazingly compact USB logic analyzer, I immediately jumped on board. The Saleae Logic 8 is my favorite tool in my kit. Saleae’s logic analyzer software supports a variety of trigger conditions and data resolutions, and it can also decode a common communication protocols such as JTAG, SPI, I2C, CAN, and UART.

I'm still using my first edition Saleae Logic 8, but they’ve since overhauled their design and released both 4-channel and 16-channel versions.

I think that eight channels is the sweet spot for a portable analyzer. I’ve rarely needed to monitor more than eight channels at once, and in those rare cases I can usually work through signal groups in stages. I also find that I regularly use more than four channels, especially when I need to analyze both control signals and a bus (e.g. SPI).

The  Saleae Logic 8  is my favorite tool in the toolkit.

The Saleae Logic 8 is my favorite tool in the toolkit.

TIAO USB Multi-Protocol Adapter

The TIAO USB Multi-Protocol Adapter (TUMPA) has been another invaluable tool in my kit.

TUMPA is built around FTDI’s FT2232H chip. Between OpenOCD and FTDI libraries, you can use the TUMPA as an adapter for SWD, JTAG, SPI, I2C, UART, and digital I/O. The board also sports on-board voltage translation, which can be enabled/disabled through software or with a jumper.

TUMPA allows me to use a single debug adapter across most of my projects. If you work on a variety of projects, having a single debugging adapter can drastically simplify your development environment.

The  TUMPA  board enables me to carry a single debug adapter for a variety of scenarios.

The TUMPA board enables me to carry a single debug adapter for a variety of scenarios.

USB Hub

My laptop doesn't have enough ports to support all of my debugging devices, so I’m always carrying around a small USB hub.

I use Sabrent’s 4-port USB Hub without an external power supply, which I love for its small size and toggle buttons. If you’re working with high-current devices, I recommend purchasing the 4-port hub with a 5V power adapter.

You can use any USB hub you like, but I highly recommend picking one with toggle buttons. Being able to selectively enable and disable ports has been helpful when working with embedded devices. I frequently find myself cutting power to a USB device, using the buttons to reset devices, and to force USB disconnect/connect conditions.

All these USB devices mean that I need to carry a hub in my kit.

All these USB devices mean that I need to carry a hub in my kit.

Wire Grab-Bag

All of these debug tools need to be hooked up to the target system, so I keep a mixed bag of wires and clips in my kit. I have a mix of male-male, female-male, and female-female jumper wires to handle any manner of connector. I also keep a few pieces of scrap wire for emergency soldering needs.

The clips you see come with the Saleae logic analyzers, but they are just generally useful for clipping pins and boards. You can find all manner of useful clips by searching for “test probe hook clip”.

You can never have enough wires.

You can never have enough wires.

Spare Jumpers

Because I keep finding myself in situations where I don’t have enough jumpers, I decided to keep a little baggie of 2.54mm standard jumpers in my kit. These come in handy when you lose a jumper, or your local EE can’t seem to find enough for that new dev board.

There are never enough jumpers when you need them.

There are never enough jumpers when you need them.

What’s in your kit?

I’d love to hear from my readers about the tools you frequently carry around. Leave me a note in the comments!

GitNStats: A Git History Analyzer to Help Identify Code Hotspots

GitNStats is a cross-platform git history analyzer. GitNStats is used to identify files within a git repository which are frequently updated. High churn can be used as a proxy for identifying files which may have poor implementation quality, lack tests, or are missing a layer of abstraction.

Below I will provide basic instructions for getting and using GitNStats. We'll also look at two of my projects to review high-churn files and their git history. By reviewing the history of these files, we can identify potential problem areas, refactoring projects, and development process improvements.

Table of Contents:

  1. Getting GitNStats
  2. Usage
  3. Client Project Analysis
  4. Jenkins Pipeline Library Analysis
  5. Further Reading

Getting GitNStats

Best place to download the software is the repository Releases Page. Pre-packaged 64-bit releases are provided for OSX 10.12, Ubuntu 14.04, Ubuntu 16.04, and Windows.

To install GitNStats:

  1. Download one of the pre-packaged releases
  2. Create a home for GitNStats, such as within /usr/local/share or your home directory.
  3. Unzip the release package to the target directory
  4. Link the gitnstats binary to a location in your path, such as /usr/local/bin or /bin.
    1. Alternatively, you can add the target directory to your PATH variable

Example workflow included in the README:

# Download release (replace version and runtime accordingly)
cd ~/Downloads
wget <archive-for-your-platform.zip>

# Create directory to keep package
mkdir -p ~/bin/gitnstats

# unzip
unzip osx.10.12-x64.zip -d ~/bin/gitnstats

# Create symlink
ln -s /Users/rubberduck/bin/gitnstats/gitnstats /usr/local/bin/gitnstats

Usage

The primary method of using gitnstats is simply to run it in a repository without arguments. You will see the repository path, the branch, and a list of file & commit pairs.

$ gitnstats

Repository: /Users/pjohnston/src/ea/templates
Branch: master

Commits    Path
3    oss_docs/CONTRIBUTING.md
3    oss_docs/PULL_REQUEST_TEMPLATE_CCC.md
3    oss_docs/PULL_REQUEST_TEMPLATE.md
3    oss_docs/ISSUE_TEMPLATE.md
2    oss_docs/CODE_OF_CONDUCT.md
1    README_template.md
1    PULL_REQUEST_TEMPLATE_example.md
1    PULL_REQUEST_TEMPLATE_CCC.md
1    Jenkinsfile
1    ISSUE_TEMPLATE_example.md
1    CONTRIBUTING_template.md
1    CODE_OF_CONDUCT_template.md
1    CI.jenkinsfile
1    .github/PULL_REQUEST_TEMPLATE.md
1    .github/ISSUE_TEMPLATE.md
1    oss_docs/README.md
1    jenkins/Jenkinsfile
1    jenkins/CI.jenkinsfile

You can also supply the repository path as a command-line argument, allowing you to invoke gitnstats from outside of a repository:

~$ gitnstats /Users/pjohnston/src/ea/templates
Repository: /Users/pjohnston/src/ea/templates
Branch: master

…

You can specify a branch name to analyze using the -b or --branch arguments:

$ gitnstats -b avoid-failing-when-delete-a-branch
Repository: /Users/pjohnston/src/ea/scm-sync-configuration-plugin
Branch: avoid-failing-when-delete-a-branch

…

You can also limit the search to all commits after a certain date using the -d or --date arguments:

$ gitnstats -d 1/1/18
Repository: /Users/pjohnston/src/ea/embedded-framework
Branch: master

Commits    Path
8    docs/development/libraries.md
5    docs/development/tools.md
4    docs/architecture/architecture.md
3    docs/development/testing.md
2    docs/development/quality.md

Those are the basic operations supported by gitnstats, and they can be combined together:

$ gitnstats ~/src/ea/libc -b pj/stdlib-test -d 10/30/17
Repository: /Users/pjohnston/src/ea/libc
Branch: pj/stdlib-test

Commits    Path
1    src/stdlib/strtof.c
1    src/stdlib/strtod.c
1    src/gdtoa
1    premake5.lua
1    .gitmodules
1    src/stdlib/strtoll.c
1    src/stdlib/strtol.c

For further instruction, refer to gitnstats --help

Client Project Analysis

I recently worked on a short-term project for a client, so let's take a look at that project and see how the file churn maps to problems I encountered along the way.

10:38:13 (master) power-system-fw$ gitnstats
Repository: /Users/pjohnston/src/projects/power-system-fw
Branch: master

Commits    Path
34    src/lib/powerctrl/powerctrl.c
34    src/main.c
33    Makefile
29    README.md
26    src/lib/commctrl/commctrl.c
19    src/_config.h
18    src/drivers/i2c/i2c_slave.c
17    src/drivers/can/can.c
13    src/lib/powerctrl/powerctrl.h
13    src/drivers/bmr456/bmr456.c
11    src/drivers/gpio/gpio_interrupt_handler.c
11    src/lib/commctrl/commctrl.h
10    src/drivers/i2c/i2c.c

There are 8 files that have been changed a significant number of times, and the top 3 files were changed 3 times more than the files below the top 10.

That's a pretty huge gap, so let's look at the history to see what's going on with our top three files:

  • main.c was updated every time a new library or driver was added and required initialization.
    • The abort and error handling functions are included in main.c and received multiple functionality updates (stopping threads, sending a UART message, LED error code)
      • These handlers should be split into a different file
    • Static functions received doxygen updates in separate commits - I can clearly be better about documenting WHILE writing a function
  • powerctrl.c is the library which provides power control abstractions and power-state management
    • Timing parameters have been updated multiple times after validation efforts
      • These values should be configurable and moved into _config.h - churn should happen there
    • Due to timing problems, the library was overhauled to add in a thread which managed power state changes
      • Significantly less churn happens after this change
    • As new parts and drivers were brought up, they were added into the power control library individually
  • Makefile was updated every time a new source file was created.
    • Significant churn happened when bringing up the project on Linux, as differences between gcc versions and case-sensitive file systems identified a series of changes that needed to be made
      • These changes weren't made on a branch, but instead committed and tested with a new build on the build server.
      • This is terrible development practice on my end. I should have been testing locally in a VM or by using a branch.

By looking at the statistics, I can uncover some design work and refactoring efforts that will improve the project. I also see the results of some expedient choices I made, resulting in terrible development practices and unnecessary file churn. Now these facts are logged in git history forever.

What About Recent Changes?

The project was officially delivered on 6/1/18, so let's see what modifications have been made after client feedback:

$ gitnstats -d 6/2/18
Repository: /Users/pjohnston/src/projects/power-system-fw
Branch: master

Commits    Path
1    src/drivers/gpio/gpio_interrupt_handler.c
1    src/lib/powerctrl/powerctrl.c

Not too bad after all, though both gpio_interrupt_handler.c and powerctrl.c are in the high-commit list in the overall history analysis. If these libraries continue to show edits, I know I need to spend more time thinking about the structure and interfaces of these files.

Jenkins Pipeline Library Analysis

The Jenkins Pipeline Library is an open-source library for use by Jenkins multi-branch pipeline projects. I use this library internally to support complex Jenkins behaviors, as well as with some client Jenkins implementations.

Let's see what the highest-churn files for this project are:

10:41:59 (master) jenkins-pipeline-lib$ gitnstats
Repository: /Users/pjohnston/src/ea/jenkins-pipeline-lib
Branch: master

Commits    Path
15    vars/sendNotifications.groovy
11    vars/gitTagPreBuild.groovy
10    vars/slackNotify.groovy
5    vars/gitTagCleanup.groovy
4    vars/gitTagSuccess.groovy
4    vars/setGithubStatus.groovy
4    vars/emailNotify.groovy
4    vars/gitBranchName.groovy

…

Wow, the top three files have been edited more than 10 times.

Clearly there is a problem, which is made even worse by the fact that sendNotifications.groovy was split off into two separate functions: slackNotify.groovy and emailNotify.groovy. The fact that sendNotifications.groovy was managing two separate notification paths was cause for the initial churn on that file, and certainly caused overly complex logic. Splitting the file into two separate functions was A Good Thing.

Diving into the slackNotify.groovy changes, I can see that I was very thoughtless in my initial implementation and committing strategy.

Two commits were actual feature extensions:

  1. Add an option to use blueOcean URLs for slack notifications
  2. Improve output for builds with no changes or first-builds: The commit that was built will be indicated in the message

The rest of the changes were formatting errors, typos, and other fixes for easily-identified errors.

There are some clear lessons here:

  1. I can identify and address problematic files long before 25 total changes (sendNotifications.groovy + slackNotify.groovy)
  2. To avoid high-churn on a file, follow good development processes. Expediency creates terrible history and higher-than-necessary churn. I would be embarrassed to do this on a professional project, so why did I take the expedient route on a personal (and public!) project?

Further Reading