This page describes how to get libpruio working on your system. At the bottom you'll find a step by step guide to install the complete system. Eager users may skip the theory and jump to Installation directly.
libpruio depends on the prussdrv library (from am335x_pru_package) to control the PRU subsystems. A further package might be required, depending on what you intend to do:
Executing Binaries | Compiling C code | Compiling FB code (and customizing libpruio) |
---|---|---|
am335x_pru_package | am335x_pru_package | FB prussdrv Kit |
any C compiler | BBB-FBC |
The original am335x_pru_package contains libprussdrv, some examples and the PRU assembler (pasm). It's designed for C compilers. In contrast the FB prussdrv Kit contains the FreeBASIC headers and a modified pasm that can output FB header files.
The BBB-FBC package contains a minimal configuration of the executable and some essential libraries. Find the complete compiler package including the source code, lots of library bindings and examples in the GIT repo.
To execute software based on libpruio you have to ensure that
/dev/uio5
system interrupt.The first and second preconditions can be reached at once by loading an appropriate device tree overlay. Either prepare, install and load a customized overlay with fixed pin mode configurations (created by the dts_custom.bas tool, see section Pin Configuration for details). Or install and load the universal overlay (file src/config/libpruio-0A00.dtbo ust get copied to folder /lib/firmware) shipped with the libpruio package by executing
It's also possible to activate one of the prepared operating systems device tree overlays, ie. by executing
All these device tree overlays start the PRUSS and also load the kernel driver. The kernel driver allocates external memory for the PRUSS, which is a default of 256 kB. (See section ERam on how to customize this.)
When your operating systems comes with capemgr you can use it to load the overlay at system startup by adapting the configuration file
to make it look like
Item 3 of the initial list (privileges) can either be reached by running the software as user root
. But the prefered method should be preparing privileges for the related users:
addgroup pruio
)Then you can apply these group to the interrupt device and activate read / write privileges for it (execute with admin privileges)
It's best to auto-execute these commands at startup (ie. in the /etc/rc.local script).
Beaglebone hardware contains a TI AM3359 CPU, which includes lots of subsystems with different connectors like analog or digital lines. The number of subsystem connectors is greater than the number of connectors at the CPU housing (= CPU balls), in order to keep the housing small. That's why digital lines (ie. like GPIO or PWM) have to get configured (pinmuxed) before they can be used (in a non-default configuration).
Pinmuxing means to connect a CPU ball to
When a digital line should get used, libpruio checks first if the pinmuxing matches the required configuration. If this is not the case, libpruio tries to re-configure the CPU ball. This may fail and the API function returns an error message
To avoid such a failure
During development, the later might be advantageous (although it requires admin privileges), since a feature can easily get switched from one pin to another. In contrast, changing a customized overlay mostly requires re-booting the system, since unlaoding and reloading a device tree overlay doesn't work reliable (effective September, 2014). When you finished testing and start to use a PCB with fixed wiring, it's time to install your customized device tree overlay and further on work with user privileges.
Internaly, libpruio uses the CPU ball number to identify a connector. That's why you can access all connectors, even those which are not connected to a header pin. The (optional) header pruio_pins.bi includes convenience macros to refer to a ball number by its header pin position (as seen from the user point of view).
The universal device tree overlay can also get used to pre-configure the pins before executing the program. Therefor echo
the desired hexadecimal value to the state file in the approprite pin folder. Ie. to configure pin P9_14 as PWM output execute (with admin privileges)
where x0E
is the hexadecimal value for the Control Module pad register and the number after pruio-
is the hexadecimal number of the CPU ball. Both hexadecimal values must have two digits. See ARM Reference Guide, chapter 9 for details on the pad registers.
To compile your C source code against libpruio you need the am335x_pru_package and from the libpruio package the library binary and the header files
It's recommended to install by
See file src/c_wrapper/pruio.h for the documentation and find examples in folder src/c_examples.
To compile your FreeBASIC source code against libpruio you need the FB prussdrv Kit and from the libpruio package library binary and the header files.
In order to avoid naming conflicts in the headers folder (/usr/local/include/freebasic) place the Beaglebone stuff in a subfolder called BBB. It's recommended to install by
In that case you've to adapt the INCLUDE ONCE "..."
lines in your code
becomes
Find example code in folder src/examples.
To customize libpruio itself, you must observe this order
Find the command line to invoke the compilers at the top of each file.
Here's a step by step guide for a complete libpruio installation on a vanilla Debian (Ubuntu) system, based on a Rafael Vega post (find the original text here ).
apt-get ...
ldconfig
mkdir ... /usr/...
cp ... /usr/...
cp ... /lib/...
echo ... /sys/...