Last Update: Preliminary information, subject to change.
All Decaf boards are fully supported under Windows, both via the PiXCL app builder language and the PiXCL Decaf SDK. This application note describes some of the issues is getting Decaf boards to work under linux. Work is progressing with Raspbian Stretch on the RaspberryPi 3 and 4, Ubuntu 20.04, and on an Intel mini-box. In the following,”linux” refers to all of the above, unless specifically indicated otherwise.
Decaf board being controlled from Ubuntu 20.04 LTS on an Intel host. App is a utility from hidapi libraries that allows command reports to be issued and received. The same code also works on Raspbian with all RaspberryPi hosts.
USB support in linux
The USB device end-user libraries libusb (from libusb.info) are already present in all, and in at least two versions or builds.
The console command $ dpkg -l libusb*
will list all the installed or available packages. You should see something like
ii libusb-0.1-4 // This is the obsolete version, only for older apps that need it.
ii libusb-1.0-0 // This is the current version, and is the one you should use.
and several others that are not relevent at present. “ii” means ‘It should be installed and it is installed’. The last number is (AFAIK) a build number.
Adding developer support
Our intent is to create apps, not just run an executable, so the libusb developer package has to be installed. Looking around the net for advice, you’ll find libusb-dev, looks like the right one. Maybe…will it install? If you try
$ sudo apt-get install libusb-dev
it runs to completion and issuing
$ dpkg -l libusb* reports
ii libusb-dev
Trying to compile (see below) a simple libusb-1.0 test app fails miserably with all sorts of “file not found” errors, starting with the first code line #include <libusb.h>
In fact, libusb-dev is not the one you want, and refers to libusb-0.1 (see below to find out how). The correct command is
$ sudo apt-get install libusb-1.0-0-dev
This installs the latest required files.
Where are these dev package files installed?
Good question! The apt-get install command does a lot of stuff in the background, and finding where an installed package ends up can be challenging, at least initially. Here’s how to do it:
$ dpkg -L libusb-1.0-0-dev
which produces a directory list of all the paths and files installed by the package, including the Rules file libusb-1.0.pc, see below.
If you installed libusb-dev by mistake and want to remove it, here’s how:
First, it’s important to verify EXACTLY what files are going to be removed.
$ dpkg -L libusb-dev
On Debian, Ubuntu and Debian, this lists the files. There’s another check coming.
$ sudo apt-get remove libusb-dev
This will list the package(s) that will be removed. In this case, it is libusb-dev only. It asks if you REALLY want to remove the listed package files.
Answer Y to do it.
Removing libusb-0.1 is more problematic, as there is a large list of dependent packages that use it as well, including Python3. You may want to leave it alone.
$ sudo apt-get remove libusb-0.1-4
is a typical command. Use it at your own risk, when you are SURE (seriously, ABSOLUTELY certain!) you know what will be removed. On our copy of Debian 9 on the Pine A64+, this command wanted to also delete all the apt* files and other dependencies (reason unknown at present), which was NOT wanted, and resulted in a compromised installation.
Compiling and building an app executable
Here’s where it gets quite complicated until the linux obscurity is cleared away.
When a <package> is installed, there is usually a package.pc file written to one of several possible locations. Use the man pkg-config command for more info on this.
pkg-config can report the contents of the .pc file, including the paths to libraries and includes, into the compiler tool gcc. For libusb-1.0, this is libusb-1.0.pc.
Let’s say we have a source named listdevs.c that should build an executable called listdevs. The simplest command might be …
gcc listdevs.c -o listdevs
and will most likely fail because it cannot locate the libraries and includes needed to build. The better command …
gcc listdevs.c $(pkg-config --cflags --libs libusb-1.0) -o listdevs
This will work, and listdevs will run. The $(pkg-config…) inserts the needed includes and libraries paths into the gcc command line. Note here that the -o listdevs has to be the last part of the command, as it needs the --libs paths, and creates the app executable.
This command has been successfully tested on Raspbian, Ubuntu and Debian.
udev Rules : what are these and why are they necessary?
The linux udev module controls how devices are accessible to applications. You can read about it via the $ man udev pages, though more than likely you’ll find these pages present many more questions than answers. Rules files are primarily stored in /usr/udev/rules.d and in several other directories.
For example, the listdevs.c app code can read (via libusb functions) some information about attached usb devices, including the important VendorID and ProductID. A device can also report a set of descriptor strings for Manufacturer, Product, Serial_Number and others depending on the device firmware. To do this, it’s necessary to call libusb_open(…) which fails with a ACCESS_ERROR code, even if we use $ sudo ./listdevs The failure happens because no rule file exists.
What’s needed is something like this, as /usr/udev/rules.d/55-decaf-permissions.rules
# Decaf USB Human Interface Devices
SUBSYSTEM==”usb”,ENV{DEVTYPE}==”usb_device”,SYSFS{idVendor}==”0483″, SYSFS{idProduct}==”5750″,MODE=”0666″
This lists the VendorID and ProductID, and that MODE=”0666″ means anyone can access the device. The filename is arbitrary and always ends with .rules.
If we again use $ sudo ./listdevs the Manufacturer, Product, Serial_Number descriptor strings are accessible from the target device firmware.
Installing apps and libraries to linux: some clarification
Installing to linux is very different (and less intuitive for the new user) to Windows. A lot of things happen as if by magic, and require some searching for the explanation.
There’s many sites that describe the methods and techniques.
Porting PXLusbdevs.DLL Source to linux
PXLusbdevs.DLL is the library that PiXCL uses to access all the Decaf boards. Since this is a Windows library, it is built for Intel-type processors.
For initial versions of linux, the target is ARM processors, and build a shared library (or SO, extension .so) using the gcc compiler tools.
PiXCL DLLs export the function name list, so the SO has to do the same.
In the DLL there are some Windows API specific calls, mainly related to file handling, which have to be switched to the gcc equivalents.
How will this new Shared Library be tested?
Since there is not at present linux version of PiXCL 20, we’ll create two types of test apps, the first using gcc as a console app that exercises the Decaf command set, and second using GTK as a windowed app.
< More to come, check back again soon. >
Copyright © 2024 PiXCL Automation Tech Notes, Canada. All Rights Reserved.