I love the Raspberry Pi. Sure it has its warts, but overall it is very well suited to an amazingly large range of uses. What I’m not so keen on, though, is the Python. Not that I have anything against the programming language (or John Cleese, Eric Idle et al., come to that), but it’s just not how I want to write software right now.

I have plenty of experience in a load of other programming languages, including C, C++, Java, Ruby, FORTH, APL, BASIC and so on. I’m even getting more familiar with Javascript and node.js. These are all general-purpose programming languages, in one form or another available on the Raspberry Pi, and would be perfectly suitable for writing Raspberry Pi software and controlling Raspberry Pi hardware.

Except that (mostly) you can’t easily use these languages to control off-the shelf third-party Raspberry Pi hardware.

This limitation is nothing to do with these programming languages, nor with the Raspberry Pi, nor its operating systems. It’s to do with the software and documentation provided with the hardware.

Most recently I have bumped into this with the PiFace Control and Display. I think the board and its features are great, and the supplied example programs do show some of the things it is capable of. But the supplied code is all Python. And, try as I might, I can’t find any documentation about the actual hardware which might enable me to use it with anything else. I can tell from examining the board that it has a MCP23s17 port expander on an SPI port with a HD44780 LCD driver and some switches connected to it, but to make sensible use of the hardware using anything other than the supplied Python code I need to know details such as which GPIO pins are connected to what, and whether they are inputs or outputs, which SPI device numbers are used, whether the display is in “4 bit” or “8 bit” mode, and so on. I spent several hours yesterday poking through the PiFace CAD Python code and trying things out in a C program, but so far I have not managed to successfully even clear the LCD display or switch the backlight on or off, let alone write any characters.

I’m really not trying to single out the PFCAD, here. Over the last year or so I have bought a large proportion of the available Raspberry Pi expansion boards, and I think its fair to say that most of them had this problem in one way or another. It almost seems as if the promotion of Python as an introductory Raspberry Pi programming language in schools (a role I’m sure it suits quite well) has obscured the fact that what we actually have is a flexible platform which can and should also be used for everything from for hobbyist tinkering, follow-on education in wider computer topics, product prototyping, and embedded use. And it could so easily be.

Everyone who makes an electronic component provides a datasheet. That datasheet gives enough information, in a mostly standardised form, for anyone with some experience to have a go at using the component. When I tried interfacing an MCP3002 ADC chip to a Raspberry Pi, I made use of such datasheets to understand what I needed to do. If the manufacturer had only produced software examples, I’m pretty sure they would not have made them for my hand-made board plugged into a Raspberry Pi! Without a datasheet, nobody will buy or use your component.

My plea is this:

If you produce add-on hardware for a Raspberry Pi, it is vital that you document and make available enough hardware details that anyone with a bit of understanding can use your hardware from any language or operating environment. Let the growing community of skilled developers help you out by writing libraries, drivers, examples and tutorials for languages and uses you don’t have time, skills or inclination to do. Don’t assume everyone will use only your software!

If you want to also provide some sort of language-independent kernel driver, and/or libraries and examples in multiple languages, good on you, but it’s still no substitute for the raw information. As I found out almost a year ago, it can be surprisingly hard to rebuild drivers even on a stock Raspbian Linux system.

My hope is that if everyone tries to do this we will (soon?) begin to see the familiarities between devices and start to standardise on how things are documented. A pool of developers could then form, able to pick up and work with any add-on hardware based on a quick examination of its datasheet. This in turn could help the production of general-purpose software tools which can ease the development of libraries, drivers, examples and tutorials. At the moment everything seems unique and puzzling, the simplest of details are tedious or even impossible to find out, and hardly any extension hardware gains enough momentum to escape the orbit of the original developers. This is crazy, and must be limiting hardware and software sales.

So, am I missing something? is this kind of documentation and developer pool available already? Can someone point me at some sort of datasheet for The PiFace Control and Display board, or for any of the dozens of other add-on boards and devices which have been produced so far?