My Fretlight Guitar As a Binary Clock

With a little research and some USB tracing, I wrote a Windows program — and an Android app — that turns my Fretlight guitar into a BCD mode binary clock!

(Update: I now also have a Raspberry Pi version.)

What Is a Fretlight Guitar?

A Fretlight guitar is a teaching aid for guitarists. It has LEDs embedded in the fretboard. The LEDs are controlled by software on a computer, which is connected to the guitar through a USB cable. The software lights the LEDs to show scales, chords, and songs. Check out this demo if you want to learn more about it.

Why Did I Turn It Into a Binary Clock?

I wanted to know the guitar’s API because I thought it would be cool to control it (not that I knew what I wanted to do with it). When searching I found demos of unconventional uses of the Fretlight: the LED Fretboard Light Show and Conway’s Game of Life on FretLight Guitar. I immediately thought of a binary clock, realizing the six columns of LEDs were a perfect match.

Researching The Fretlight Interface

Optek Music Systems has a Fretlight SDK that’s available by application, but I found open source software that implemented interfaces: Fretlight Animator (the code behind “Conway’s Game of Life”) and TuxGuitar Light Plugin. Fretlight Animator is written in C#, but I wanted something in C++. Nonetheless, the code was well documented, so I had all that I needed to write my own implementation. TuxGuitar Light Plugin, written in Java, was also a good reference, confirming what I learned from Fretlight Animator.

To verify everything, I decided to “sniff” the USB traffic to my guitar. I wrote a “song” in Guitar Pro 6 to play all 132 notes on the guitar in sequence; here is a screenshot of the first few lines:

(If you are not familiar with guitar tablature, the lines correspond to the six guitar strings, with the thick string at the bottom and thin string at the top. The numbers are the frets, with fret 0 meaning the open string.)

The USB traffic confirmed what was encoded in Fretlight Animator and TuxGuitar.

The Fretlight Interface

The Fretlight is a simple USB HID. The host controls the status of the LEDs by sending reports to the guitar’s interrupt OUT endpoint. Each report is 8 bytes, with a one-byte report ID (0) and a 7-byte packet. Each packet contains a one-byte packet ID and 6 bytes of LED data. Each LED is specified by one bit: a 1 turns the LED on, and a 0 turns the LED off. With 48 bits per packet, you need three packets to specify the status of all 132 LEDs.

Packet ID 1 controls the LEDs in frets 0 through 7, packet ID 2 controls the LEDs in frets 8 through 15, and packet ID 3 controls the LEDs in frets 16 through 21. Each bit in each packet corresponds to a unique combination of fret and string. Fret numbers range from 0-21, and string numbers range from 1-6, with 1 being the high E (thinnest string). Here is the layout of the LEDs, with ‘f’ standing for fret, and ‘s’ standing for string:

(The unused bits in packet ID 3 are marked with ‘x’s.)

Overview of My Windows Code

I wrote my program in Visual C++ (Visual Studio 2013). I used hidapi as my USB API because it was extremely simple (I turned to it after trying to wade through Microsoft’s HID examples.) I created a project, included files hidapi.h and hid.c, and changed a few compile and link options.

I used calls hid_init(), hid_open(), hid_write(), hid_close(), and hid_exit(). I used hid_open() to open the Fretlight HID, using its vendor ID (0x0925) and product ID (0x2000). (I don’t know why the vendor ID is 0x0925 — that is assigned to Lakeview Research!). I used hid_write() to send packets to the guitar (hid_write() automatically knew to send to the guitar’s interrupt OUT endpoint).

I initialized local variables to represent the current time on my computer, and then set a one second timer. Each time the timer popped I incremented the time, created the packet (packet ID 3), and sent it to the guitar. I used 19 LEDs: f21s6, f18s5, f19s5, f20s5, f21s5, f19s4, f20s4, f21s4, f18s3, f19s3, f20s3, f21s3, f19s2, f20s2, f21s2, f18s1, f19s1, f20s1, and f21s1.

I picked those frets for several reasons:

• The LEDs are spaced about as closely as on my real binary clock.
• The clock is easier to read being up against the last fret (there can’t be any hidden “off” LEDs below it).
• The LEDs are all in the same packet.

I only implemented BCD mode, and only for 12-hour time.

Overview of My Android Code

After writing and debugging my Windows program I wrote an equivalent Android app to run the Fretlight as a binary clock. I wrote it in Java, using Android Studio. I used the Android USB Host API, classes UsbManager, UsbDevice, UsbInterface, UsbEndpoint, and UsbDeviceConnection. I used the bulkTransfer() method of the UsbDeviceConnection class to send HID packets to the guitar. (I modeled my USB code on the USB HID Terminal app.)

To use an Android device as a USB host, it must support USB OTG; this support is in Android 3.1 and higher. You also need a female USB to male micro USB adapter to connect the Fretlight cable to the device. When writing the app, I enabled wireless debugging, since the device’s USB slot was connected to the guitar.

On Reflective Fret Markers

The Fretlight has reflective, circular, LED-sized fret markers, which is a poor design; sometimes they look like a lit LED! See how that plays out in my binary clock by watching the last few seconds of my video (watch when the time turns 10:30:00).