Introduction to libpibox

PiBox is many things: a core development platform, a media center, a UI, and a learning tool.  It’s also an infrastructure for application development. Most platforms have infrastructure support.  Android has an array of Java and C/C++ librariesTizen has a build environment, but for the life of me I can’t find the basic APIs.  In general these are full featured infrastructures for every possible application.  PiBox is much simpler.  It doesn’t really do a lot for you.  It lets you figure out what libraries you want installed and build your C apps on top of those.  But it does provide some basic infrastructure libraries for C apps.  While it’s not quite a suckless philosophy, the goal is still be to simple and small.

The two main components of the PiBox infrastructure are libpibox and libpnc.  Both libraries are included in the core development platform.  These libraries contain functions for dealing with common application features from debugging to networking to touchscreens.  Applications within the media center, for example, make extensive use of both libraries.  We’ll examine libpnc in another article.  Let’s take a deeper look at libpibox.


There are six API namespaces within libpibox:  pibox, piboxLogger, piboxMsg, rpi, touchProcessor and Parson.  The pibox functions include useful utility functions such as trimming white space or newlines from a string.  This functional area is small as many libraries exist for handling utility functions.  But to avoid loading multiple larger general purpose libraries just for their utilities, pibox functions allow sticking to a single lightweight library that includes other functional areas specific to PiBox.  If you need a fully featured utility library with all the bells and whistles I recommend glib.

The piboxLogger functions are used for debugging code.  The logging facilities allow for output to the console or to a file, provide up to 8 levels of detail and include support for optional timestamps.  Logging can also be enabled or disabled at compile time.  If the library is disabled at compile time the library calls in the app are simply ignored by the compiler.

The PiBox protocol is used for messaging between apps and daemons.  Apps can send messages to daemons using piboxMsg() which wraps the protocol and message passing in a single function call.  Future development of this functional area will include receiver management for inbound messages.  While the PiBox protocol is well defined, this functional area of libpibox is still under heavy development in order to provide easy-to-use APIs for message passing.

The Raspberry Pi project supports the use of a text configuration file, called config.txt, that can modify the bootloader operation at boot time.  This includes features like loading overlays or setting the screen orientation.  The rpi functions are provided for reading, modifying and writing config.txt entries.  This allows apps to implement their own interfaces for changing the boot configuration.

A recent addition to libpibox is generalized support for touchscreens.  This support is a wrapper around the ts library making it possible to map a touchscreen to 9 regions or absolute screen coordinates.  Mapping the screen to 9 regions makes it easier to implement a consistent usage strategy for a touchscreen across multiple apps while having absolute coordinates allows apps to map a screen location to a specific action like activating a function for an icon.  The new kiosk mode of VideoFE (a media center app) uses the region mode for fast forward, rewind, next video, prev video and so forth.

Finally, the Parson library has been integrated into libpibox.  Early development of PiBox focused on XML configuration files.  During development it was discovered that JSON was a much simpler format and more easily integrated using a much smaller library (Parson is one C module and one header file).  Parson provides an easy to use function set for managing JSON objects, including support for setting alternative malloc and free functions appropriate for embedded applications.  Unlike the PiBox developed APIs, the Parson library uses the json prefix for all of its functions.

What’s next

There is still plenty of work to be done with libpibox.  All PiBox APIs are described with function headers in the source code and each includes a header file with the list of available functions at the end.  The Parson library is easier to decipher by reading its header file or by visiting the project web site.  But I still need to add meaningful documentation.   A bunch of man pages would be the Linux way.  I can then convert them to web pages as needed.

Extending the library is an obvious chore – there are always more features that could be added, but I want to keep the library as small as possible.  An import  extension will be to the messaging APIs and to thread management.  Apps will often want to exchange data with other apps.  They can do it using the simplistic PiBox protocol.  But they need senders and receivers.  And they need generic parsers to place the data into usable structures (lists of data) for use by the apps.  I have all of this done in one place or another but they need to be consolidated into general purpose functions.

None of this is hard to do.  It just takes time.  And isn’t that the hardest resource to acquire!


Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.