In order to better keep track of reported bugs and submitted patches, we've set up a bug tracking system:

Please use this to report bugs found in any sigrok project. Attached bugfix patches are most welcome, of course, as are patches that add a new feature. However, feature requests should be directed to the mailing list or IRC channel. We want to keep the list of open bugs as small as possible.

A matter of parsing

Supporting a new piece of hardware in sigrok entails writing a driver for libsigrok. As a bare minimum, the driver consists of a C source file with a struct sr_dev_driver in it. That struct contains the name of the driver and a set of callbacks libsigrok will do when that driver is used — things like initializing the device, starting acquisition and so on. libsigrok provides an internal API which drivers can use to send data across the "session bus" — something which the frontend application listens on.

However, writing code is the last thing you do. When you get started, first make a page on the wiki for that device. Check out the page for a similar device, and copy its source over. This will get the page structure and categories down. Take some pictures of the device, particularly of the insides. It may well help you with the driver later on. Some guidelines for taking good PCB pictures are here.

Next, take a look at the protocol. Generally this involves running a copy of Windows in a VM (Virtualbox or VMware will do nicely) on a Linux host. When you use the device through the vendor-provided Windows software, you can sniff the USB (or whatever) traffic on the Linux host. There are many techniques to reverse engineering protocols, but essentially it involves staring at hexdumps until you understand the connection between what the vendor software sends to the device, and what the device does in response.

Whatever you find out about the protocol, document it! You want to be able to pick up where you left off, even if there's a couple of weeks between working on this. By all means, use the wiki page you created as a working document — it's not just a place to put finished protocol docs. If you get stuck, somebody else might see something in your notes that you missed.

For some devices you might even skip the VM + Windows step. Some low-end multimeters and other measurement devices don't really communicate with the vendor software: they just send data out periodically — usually a few times per second — and don't even have an input channel on which to take commands. These are generally devices with a keypad or similar controls, and a display. By simply listening to what it puts out, verifying this against what you see on the display, and putting the device through its various modes and options with the controls, you have everything you need to grok the protocol.

Once you're satisfied you've got the whole protocol documented, it's time for the driver. Creating the driver's various source files and integrating it into the build is quite a bit of work, and requires a lot of fiddling around with autotools. So to make things easier, we have a tool to do all this for you. It's called, unsurprisingly, "new-driver", and can be found in the sigrok-util repository.

Clone the repository, and run it from the source directory:

$ git clone git://
$ cd sigrok-util/source

Let's say your device is called the "Magic Widget S15". Invoke new-driver like this:

$ ./new-driver Magic Widget S15

This will show some output as it works, and leave behind a single file when it's done: 0001-magic-widget-s15-Initial-driver-skeleton.patch

Apply this to your libsigrok tree:

$ cd /path/to/libsigrok
$ git am /path/to/0001-magic-widget-s15-Initial-driver-skeleton.patch

That's it! The configure script will now know about your new driver, and doing the usual configure/make steps will build it. You'll find it in your source tree in the hardware directory:

$ ls -l hardware/magic-widget-s15
total 16
-rw-rw-r-- 1 bert bert 3692 Nov 13 02:49 api.c
-rw-rw-r-- 1 bert bert 1035 Nov 13 02:49
-rw-rw-r-- 1 bert bert 1157 Nov 13 02:49 protocol.c
-rw-rw-r-- 1 bert bert 1919 Nov 13 02:49 protocol.h

The file api.c contains the struct sr_dev_driver which registers it with libsigrok. An overview of the struct and the callbacks it contains is on the hardware driver API page. All the callbacks have a stub function in api.c, with a TODO comment marking the spot where you come in. Take a look at another driver for a similar device to see how various callbacks might be implemented. The protocol.h file is included from both C files, and contains mostly the device context struct. This is specific to your driver, not shared across libsigrok. The protocol.c file is where you implement the protocol parser for your device. It has a single stub function defined:

SR_PRIV int magic_widget_s15_receive_data(int fd, int revents, void *cb_data)

This function gets called whenever your device sent some data. The stub grabs your device context, which will have a device handle you can use to read the data and send libsigrok the results.

Everything else is just a matter of parsing.

git repositories moved

Just a quick public service announcement: we've moved the sigrok related git repositories from SourceForge to (for various reasons).

While we were at it we also did the long-overdue "repo split". Every sigrok-related subproject (libsigrok, libsigrokdecode, sigrok-cli, sigrok-gtk, sigrok-qt, and so on) now has its own git repository, as opposed to all of these unrelated subprojects being mangled into one big repository.

There were also a few smaller renames and git rebase actions on some repos, so please make sure you clone the new repositories from their new locations for any further usage or development. Thanks!

The new clone URLs for the repositories look like this:

 $ git clone git://

(replace "libsigrok" with your desired subproject)

All the repositories also have their own source code browser (and git changelog) at now.

Please let us know in case you experience any issues with the new repository setup.

fx2lafw 0.1.0 released!

We're happy to announce the initial release of the open-source fx2lafw firmware for FX2-based logic analyzers.

See the "About fx2lafw" blog post for more information about the fx2lafw subproject.

This firmware must be used with libsigrok >= 0.1.1. Previous versions of libsigrok did not yet have support for fx2lafw.

The code was tested to build fine on Linux, Windows (using MinGW), and FreeBSD, using both sdcc 2.9.x and the newer sdcc 3.x.y (which contains various API changes that need to be handled properly in fx2lafw).

You can get the firmware source code tarball from SourceForge. Alternatively, you can also download pre-built firmware files, if you don't want to build them from the source code yourself.

This firmware package should hopefully also be available in your favorite distribution soon, a Debian package is already in the works (which will usually be automatically installed when you do "apt-get install sigrok" or even just "apt-get install libsigrok0").

This release supports 8-bit and 16-bit digital sampling (i.e., logic analyzer usage) on the Saleae Logic, CWAV USBee SX, Braintechnology USB-LPS, and many, many other devices. Support for analog signal acquisition (on those devices which have hardware support for that) is in the works, but not yet available in this release.

See the fx2lafw wiki page for the full list of currently supported and/or tested devices — and some devices we assume would work, but which have not yet been tested; test reports are always welcome!).



Since the sigrok project started, we’ve focused on logic analyzers. They were the initial inspiration for the project, and were at that time just getting affordable — at least compared to the bad old days when such gear cost thousands of dollars. Since then, prices have continued dropping and capabilities have increased; the Openbench Logic Sniffer is just $50, and will happily sample at 100MHz. Cheap FX2-based boards can be had for as low as $15. But logic analyzers were never the limit of our ambition. sigrok groks your signals for you — ALL your signals! We consider any kind of test and measurement equipment in scope of the project; if it can be queried or controlled, we’ll take it on.

To that end, we’ve recently merged in support for processing analog data, as well as the first driver using it. The driver is hantek-dso, and supports the Hantek DSO-2090 USB oscilloscope. It’s part of a series of five similar models, all of which we plan to support. The only output module supporting analog data for now just outputs voltage levels as text, suitable for importing into other tools.


Capture from a DSO-2090, before postprocessing, as plotted by qtiplot

We will, of course, also support saving analog data in .sr files. If you know of any other file formats that are commonly used for transferring oscilloscope output, do let us know! We’re always happy to put it on our TODO list, and even happier to take patches.

We also have a Hantek DSO-5200A, a higher-end model in the same series, so it will be supported quite soon. We can’t buy every device out there, however, so we will need help if we’re going to support the DSO-2150, DSO-2250 and DSO-5200. If you own one of these, you can help! Opening up your device and taking pictures of the internals for the wiki is already a great step forward; helping us to test the driver on a model we don’t own ourselves is even better.

Detailed pictures of the PCB and components should also help us to determine what exactly the difference is between these models. We know the 2xxx series share the same firmware and most of their specifications, for example, so the difference is likely in the analog frontend only. But is it possible to do a simple upgrade from one model to another? This is not unheard of; in the case of the Rigol DS1052E and the Hantek 5062B bench oscilloscopes the hardware is identical to higher-end models.

Next on the agenda are drivers for the Link Instruments MSO-19 and the PoLabs PoScope. The MSO-19 in particular is a very popular device, and both are interesting for us in that they’re Mixed Signal Oscilloscopes (MSOs): they can output both analog and digital signals. We can handle both separately, but getting them at the same time — and keeping them in sync — is another challenge entirely.

Several of the FX2 boards we support also have analog frontends; we plan to add support for these to the fx2lafw firmware and driver both.

We’re also in the planning stages of support for other devices that output various kinds of analog data. More on that later, watch this space!

About fx2lafw

At the end of May we released libsigrok 0.1.1. It had various fixes and improvements, but the main reason we released it was to get a release out the door before merging in the work on analog data I’d been doing in another branch.

But there was one major feature in that release which I think deserves a bit more attention. It was the first time we’ve included a driver that communicates with a device which runs firmware we ALSO wrote. This firmware is called fx2lafw, and I think it’s absolutely fantastic.

The all singing, all dancing FX2

Some of the first generation of inexpensive logic analyzers, i.e. within reach for non-megacorporation budgets, were the CWAV USBee SX and the Saleae Logic. That is to say, they’re under $200. But when you look at what’s inside, as we inevitably do, it becomes apparent that there’s really very little there. Essentially, these boards are based on a Cypress EZ-USB FX2LP chip — the FX2, for short — and a small number of components to support it. The FX2 is a generic USB interface chip, based around an 8-bit 8051 microcontroller core. It runs quite slowly, nowhere near enough to keep up with a modern high-speed USB bus. But it has some built-in peripherals which allow it do fully automated transfers from GPIO pins to the USB bus, without ever touching the 8051 core. You basically tell it which pins to sample, and which USB endpoint to send the results to, and off it goes — leaving the CPU core idle. This feature is intended for transferring data from external devices, such as hard disks, onto a USB bus.
A Cypress FX2 chip
But of course that data doesn’t have to come from a device that’s getting clocked to send data to the FX2. It takes whatever appears on the digital I/O pins, which is what a logic analyzer does. So this can be used as a simple single-chip logic analyzer. There’s a bit more to a full product than that, of course — you have to provide some sort of analog frontend, probes, a USB connector, and an enclosure. You’d also have to invest in a website/store, arrange manufacturing, and provide support. But you could sell it without all of that if you really wanted to provide something cheap that will mostly work. Enter the Chinese clones.
If you pare it down to its bare essentials, the FX2 needs an 24MHz oscillator, a small EEPROM chip, a USB connector and a few passives. Connect your own probes to broken-out GPIO pins, and you have a basic logic analyzer. So that’s what happened: various FX2 boards started showing up on Taobao, Alibaba and Ebay. There are well over a dozen different designs, some for as low as $15. Some of the clones appear to be copying other clones.
Writing logic analyzer software is not so quickly done however, as we’ve noticed here at sigrok. These people aren’t exactly going to spend the time and effort to write great software for it; so they just sell it as “Saleae/USBee compatible”, and tell you to go download software from those companies. That’s not only the PC software, but also the firmware for the FX2, which that software talks to. It’s fundamentally wrong, of course. You might make an argument that if a bare-bones FX2 board will do the job, there’s nothing wrong with making them cheap and shovelling them out the door via Ebay. But using somebody else’s firmware and software without permission is not OK.

Doing the right thing

We’ve long supported the Saleae Logic in sigrok of course; it was our very first driver. But we used the Saleae firmware. We couldn’t distribute it legally, so we published a procedure that showed people how to extract the firmware from their own, hopefully legal, driver installation.
That’s fine as it goes, but we thought we could do one better. This is where fx2lafw comes in. It’s firmware for the FX2, written from scratch, that implements the automatic sampling mode. It uses our own protocol, and communicates with our own driver, and is 100% free and open source software. It was very much a team effort: the firmware was written jointly by Uwe Hermann and Joel Holdsworth, and the sigrok driver it talks to is based on my original Saleae driver.
The fx2lafw page on the wiki currently lists some 37 FX2-based devices we know of. We've verified many to work with fx2lafw, but we know the rest will work as well. If you have one that's not listed as 100%, please do try it out and let us know!
Some of the clone makers are already linking to sigrok; we’d like all of them to do that. If and when we get a good logic analyzer GUI for sigrok, we hope they’ll stop the shenanigans altogether. But the most important thing is that you can now have a very inexpensive basic logic analyzer that uses only 100% free software. And that is a good thing indeed.


Subscribe to RSS - blogs