A complete beginners guide to Cubieboard 2

I just got my hands on a cubieboard, and all the potential that it comes with.  Like making your own portable play-any-video-game system!



Holy cow!  Write a program, plug it in, and BOOM amazing awesome stuff happens!

Well, not quite.

I had a hard time getting going with my cubieboard, so here is a quick guide on cubieboard programming.

First off, what is a cubieboard?  I had never heard of it before, and could have used a brief explanation.  Basically it is the computer that drives tables and smartphones.  Its a tiny programmable computer with hardware pins you can hook up to anything.  Maybe you have heard of its smaller cousin, the Raspberry Pi.  There is a google book on the topic, well written for complete beginners.  Check it out here.

So a cubieboard is a computer, right?  So I did what you do with any new computer: I eagerly plugged it in and looked for the power switch.  Or tried to.  Let me tell you right now, it doesn’t come with a power cord and there isn’t a power switch.  It goes on when you connect a power source.  Fortunately my laptop power supply worked (if you don’t have one, try here).  Unfortunately, my cubieboard did not come with any operating system.

It’s supposed to come with android pre-installed.  Mine didn’t, for whatever reason.  Turns out it didn’t matter, because you are supposed to install a different operating system no matter what (apparently android sucks?).

Install an operating system??  Don’t panic!  It wasn’t that hard.

Back in the old days, you had to load a CD with an operating system, fiddle with BIOS settings to load the CD on boot, reset your computer, and go through a several-hour long process.  A cubieboard is simpler and faster.

First you need a “MicroSD” card and a way to connect the MicroSD card to your regular computer.  I didn’t have one.  I had to run to walmart and picked up both for a total of $12.96.  Plug in the MicroSD card to your computer and follow these instructions to copy Cubian to it.  Cubian is an operating system specifically for cubieboards.  It is a modified version of Linux.  If you plan on doing any programming on a cubieboard you WANT Cubian.  Do not follow other tutorials saying you should install Debian, or Ubuntu, or BootBerry.  I tried those.  Debian produced a devious flicker, and Ubuntu, while it looked very pretty and was easy to use, kept crashing after an hour.  BootBerry, while written for Raspberry Pis, worked well, but did not provide an option to install Cubian.  Cubian has everything preconfigured.  You won’t need to muck around with FEX files or kernels (more on this later).

This guide assumes you are going to use the pins on the cubieboard, to hook them up to buttons or sensors or whatever (thats where the true power of a cubieboard lies).  There are a few things you need to know about the pins on the cubieboard, things that took me a while to figure out.

First, pins are NOT GPIOs.  Pins are the physical bits of metal sticking out of the board.  GPIOs are abstract things that must be created.  They CAN be pins, but for the cubieboard you have to assign a pin to a GPIO.  (Click here for info on GPIOS).

Second, there are 96 pins (count em) but you can only use 60-some of them.  Why?  I’m not sure.  Some pins carry pure voltage, or connect to ground, which is why they cannot be used as inputs/outputs, but that only explains about 5 pins.  The other 25+ I have no idea about.

Third, pins and GPIOs have a different numbering system.  Pin 1 is NOT the same as GPIO 1.  In fact, Pin 1 on the cubieboard is a direct connection to the power supply, so you cannot use it as a GPIO no matter what.

Fourth, you must assign pins to GPIOs, by something called a “Fex” file, sometimes referred to as “script.fex” or “script.bin”.  This is done automatically if you installed Cubian.

Fifth, the pins (and by proxy, the GPIOS) have weird messed-up names.  Pins, while numbered, have names like “CSI1”, “DEF”, “VCC-1”, etc.  Usable pins, pins you can assign to GPIOs, have names like “PG3”, “PD5”, “PE9” (they all start with P).gpio_defination_large[1]

Sixth, you need to know all the previous 5 steps.  Sorry, it’s true.  You need to know the names of the pin, the pin numbers, and what pin corresponds to which GPIO.  Fortunately, there is a handy chart found here.



The bottom line is, Cubieboards are DUMB.  They cannot detect their own pins.  They don’t know which pins are inputs or outputs.  They know nothing.  You need to install an operating system just to get a cubieboard to do anything, and the only free operating systems (Linux, Android) are not meant to work with physical pins.  If you don’t use Cubian, you would have to install special software (called a Kernel) to get the Operating System to access the pins, then you need to install special software to access the files that access the pins, then you need to edit the files – its a pain.  If you really want to know more, click here and here.

All this was backround information to the big secret: pins on a cubieboard are accessed via files.  Edit the file on the operating system, and the voltage on the cubieboard changes.  Or, if its an input, change the voltage and the file changes.

This took me a day to realize, so I’m going to repeat it.  All those tutorials on programming GPIOS and code snippets are about one thing, and one thing only – someone has invented a way to access each GPIO on a cubieboard by modifying a regular file.

Try it yourself, right now.  Assuming you have cubian installed, type in
echo timer > /sys/class/leds/blue:ph21:led2/trigger
and your cubieboard should start blinking (the blue light).  Here is the full article.  If you don’t have cubian you will have to install a package called sunxi-leds.

What’s going on here?  Well, if you know Linux, you know that “echo” just outputs some text – “timer” is a special code word – and the “>” symbol just means ‘write (or “pipe”) to this file’.  The file is called “trigger” and is in the /sys/class/leds/blue:ph21:led2 directory.  Yes, that is a valid directory name in Linux.  So we are putting the word “timer” in the file called “trigger” and the cubieboard automatically starts blinking!  It’s brilliant, and works for every GPIO on the cubieboard.

Unfortunately, these special files do not automatically exist.  They do for the above example, the blue blinking light, and the green light, but for everything else you must create them for each pin or GPIO.  So here are the steps to enable a hypothetical GPIO #1:

In your linux command prompt, type:

echo 1 > /sys/class/gpio/export

(Note that echo 1 corresponds to the number of the GPIO you want to use.  If you want to create, say, GPIO #21 you would type ‘echo 21’ instead).

This is the command that creates the magic files that connect to the pins.   If you type ‘ls’ in the command prompt, you will see a new directory created.  Unfortunately, the new directory is named after both the GPIO you created and the name of the physical pin.  So the new directory will be called something like “gpio1_pg3” where the first part is the name of the GPIO (which you created) and the second part is the name of the pin (which you have to memorize from the chart).  It’s stupid, but what can you do.

Now decide if this GPIO is going to be an input or output.  That is, do you want the voltage going to this pin changing based on what a computer program is telling it what to do (output), or is the pin going to receive voltage from some external source and a computer program detects it (input)?

If it is input, type
echo “in” > /sys/class/newdirectory/direction
or for output,
echo “out” > /sys/class/newdirectory/direction

Now you can either set the value of the pin/GPIO directly (if it is output) or detect it using the cat command (if it is input).

To test this you will need an LED/diode and a small jumper cable.  Connect pin #1, which is a direct connection to the power supply, with your now GPIO pin#1 (named ‘pg3’, fourth from the top, right-most row.  See diagram.)  Connect the short end of the LED/diode to pin 1 (the direct voltage) and the long end to pin ‘pg3′(again, 4th from the top right)

.  2015-09-01 23.19.52

Then in the command prompt, type
cd /sys/class/gpio/gpio1_pg3
echo 1 > value
and the LED/diode should light up.  (Picture)2015-09-01 23.23.27

Amazing, right?  By now you should realize that
echo 0 > value
will turn it off.

If you’ve made it this far, and understood everything up to this point, all you need to do is understand how to do everything programmatically.  I’m trained in the C language, so I’ll do my examples in C.  Most examples out there are in Python.  Use whatever programming language you prefer.

You’ll need to know how to create and compile a program in C.  So install the C compiler, then using your preferred text editor (I prefer the simple nano) create your C program ( called it ‘test.c’), then compile with the command gcc test.c, then run it by typing ./a.out.  Here is my complete program to turn on the LED:

#include <stdio.h>
#include <string.h>
#include <stdlib.h>

int main(){

FILE * fp;

if((fp = fopen("/sys/class/gpio/gpio1_pg3/value", "w")) == NULL){
printf("File not found");


return 0;

The key is using the fprintf() command.

To detect if a pin voltage has changed (meaning the pin is an input) you do a similar process – Open the file, and check if the value is 0 or 1.  You can do this in linux by going to the directory/file and typing in cat value  (See video).  1 is the default, and when you hook up the pin to ground (which is something like pin #20) the value will change to 0. (note this is different for output – output you attach the pin to VCC (pin #1), not ground).

In C, use the fgetc() command:

     int ch;
     fd = open(filename, O_RDONLY);
	ch = fgetc(fd);

	if (ch != '0') {
	} else {

Hope that helps beginners with cubieboard.  Good luck!


EDIT: turns out there are stability problems with cubieboard2 and cubian. Read about my adventures here in part 2.

Leave a Reply

Your email address will not be published. Required fields are marked *

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