Configuring the GPIO and UART on the Cubieboard

In the previous post I had mentioned how you can customize the way you use the Cubieboard’s pins by changing the script.bin file. This post will be expand on that thought further.

Fex files, bin files and sunxi-tools

Every chipset has a human-readble file which sort of acts like a metadata file for the I/O pins of the board, this file is called the fex file.  It is of no use to the chip itself. It needs to be parsed and converted into an equivalent binary file, named script.bin, like the one we saw in the previous post while installing our OS on the board.

Thankfully the tools for converting fex to binary and vice versa for the A10 boards already exist. You will need to get the source files for the same and compile them in order to use them. Run the following command to get the source files:

home@user:~$ git clone git:// 

This should clone a copy of the sunxi-tools repository in your folder. The tools provided here are exclusively for AllWinner A10 based boards. They won’t work for generic devices. Now that we have the source files, we can proceed to build the tools:

home@user:~$ cd sunxi-tools
home@user:~$ make fex2bin
home@user:~$ make bin2fex 

This will spit out two executables, fex2bin and bin2fex. These executables do exactly what they are named. Next step would be to transfer both these executables to the folder where you want to keep your script.bin files.

home@user:~$ cp /path/to/sunxi-tools/fex2bin /path/to/script/files

Now we use our existent script file, the one we downloaded from the git repo here, and get it’s equivalent fex file like this:

home@user:~$ ./bin2fex script.bin cubieboard.fex 

If it executes (and it should) successfully, it shows the following lines in the terminal:

fexc-bin: script.bin: version: 0.1.2
fexc-bin: script.bin: size: 44104 (79 sections) 

Now use your favourite text editor to open the cubieboard.fex file. You will see a lot of things that may seem gibberish at present.

Each line consists of a key = value pair combination under a [sectionheader]. All three [sectionheader], key and value are case-sensitive. For comments a semi-colon (;) is used and everything following a semi-colon is ignored.

Configuring the GPIO pins in the fex file

Now since we intend to use some of the GPIO’s here, go to the [gpio-para] section header. You should see the following under this section header :

gpio_used = 1
gpio_num = 4
gpio_pin_1 = port:PG00<1><default><default><default>
gpio_pin_2 = port:PB19<1><default><default><default>
gpio_pin_3 = port:PG02<0><default><default><default>
gpio_pin_4 = port:PG04<0><default><default><default>

The first line has the parameter gpio_used which is initialized to 1. This parameter basically denotes if the functionality described by the section header is enabled(1) or disabled(0). Thus in this case, it seems like the GPIO functionality is enabled for 4 pins (gpio_num). The properties of each pin are given in the subsequent lines.

Description of the GPIO configuration in the form:

port:<port><mux feature><pullup/down><drive capability><output level>


<port> is the port to configure (ie. PH15)
<mux feature> is the function to configure the port for, mux 0 is as input, mux 1 as output and for 2-7 see A10/PIO for details.
<pullup/down> is 0 = disabled; 1 = pullup enabled; 2 = pulldown enabled (only valid when port is an input)
<drive capability> defines the output drive in mA, values are 0-3 corresponding to 10mA, 20mA, 30mA and 40mA.
<output level> sets the initial output level for the port; 0 = low; 1 = high (only valid for outputs)

The <pullup/down> <drive capability> and <output level> can be set to <default> which means don’t change. Any trailing <default> options can be omitted.

You can refer to the following image to see the I/O pins on the Cubieboard:

Cubieboard GPIO

Cubieboard GPIO

Configuring the UART ports

The Cubieboard supports a total of 8 UART ports, apart from the TTL connection provided. To configure them, you can check under the [uart_para$] section header, where the $ stands for a number from 0-7. These are the configuration parameters for UART1 (ttyS1):

uart_used = 0
uart_port = 1
uart_type = 8
uart_tx = port:PA10<4><1><default><default>
uart_rx = port:PA11<4><1><default><default>
uart_rts = port:PA12<4><1><default><default>
uart_cts = port:PA13<4><1><default><default>
uart_dtr = port:PA14<4><1><default><default>
uart_dsr = port:PA15<4><1><default><default>
uart_dcd = port:PA16<4><1><default><default>
uart_ring = port:PA17<4><1><default><default>

Since the uart_used parameter here is initialized to zero, this particular UART (ttyS1) is disabled and cannot be used. To enable it, you need to set it’s value to 1 just like we discussed for gpio_used in the previous section. This particular UART allows for the full 8 pin connection (uart_type = pin connections allowed). In case you are not familiar with it, these are the functions of each of the pin:

TX Transmit Data
RX Receive Data
RTS Request To Send
CTS Clear To Send
DSR Data Set Ready
DTR Data Terminal Ready
DCD Data Carrier Detect
RING Ring Indicator (Modem ring)

To interface this UART, you will just have to connect wires from the pins mentioned in the section header above to the appropriate pins on the slave device.

Generating the modified script file

Once we are done making all the modifications and customization we want, we need to generate the chip-readable script.bin file. To do that, we shall use the second executable that was taken from sunxi-tools earlier, the fex2bin.

home@user:~$ ./fex2bin cubieboard.fex script.bin

Succesful execution of this command will generate the new script.bin file which you can now transfer to the appropriate folder of your bootable SD card. On booting up your Cubieboard again, you will be able to use the modified pins just as you configured them in the fex file. To use your newly configured GPIO and UART pins, read ahead!

GPIO: After booting up the Cubieboard, do the following to use the GPIOs:

cubie@board:~$ echo 2 >  /sys/class/gpio/export
cubie@board:~$ ls /sys/class/gpio
export  gpio2_pb19  gpiochip1  unexport

Thus activating the second pin in your GPIO config (PB19) by generating a special file by the name gpio2_pb19. Similarly echoing 1,3 or 4 will activate the appropriate pins.  You can then write/read values from these files thus fulfilling the I/O function.

UART : For UARTs, you need to make the proper connections and then use some serial program like minicom. Or you can write your own code in Python or C to do it. In my next post, I will be writing a C program to perform a UART communication with an Arduino board, this will enable your Cubieboard to make more complicated tasks.

  1. Dimi Henri said:

    Sorry if my question is stupid but i have a cubieboard 2 and i would like use the UART. i have tried to follow the first step
    home@user:~$ git clone git://
    but the cubieboard send bash: git: command not found.

    How can i resolu this probleme please?

    • abhinavgupta said:

      Hey sorry for the late reply. I think you have figured this out already given the new comment.

      • Dimi Henri said:

        yes thank you and i have already resolute this problem.


  2. Fer Cubie said:

    I got a dumb question, when i try to execute the command ./bin2fex script.bin cubieboard.fex i get error message script.bin no such file or directory. Any idea what im missing?

    • Dimi Henri said:

      meaby you are not in the directory /boot.
      You must be on the file boot for execute this command.

      • Fer Cubie said:

        Y i got confused, didnt saw the previous post, i was using a dif kernel version. Now ill use the one from the first post. thanks

  3. Hi im trying to follow this tutorial but i got some errors… in first … i didnt find the directory when you put this:

    —-home@user:~$ cp /path/to/sunxi-tools/fex2bin /path/to/script/files

    but… i find the Script.bin file here /boot/
    and then … the following steps was good until the final step… when i use this line:

    —–cubie@board:~$ echo 2 > /sys/class/gpio/export

    i got this error:

    -su: echo: write error: Invalid argument

    • abhinavgupta said:

      —-home@user:~$ cp /path/to/sunxi-tools/fex2bin /path/to/script/files

      This path was on your host computer no t on the Cubieboard. Also when I wrote /path/to/sunxi-tools and /path/to/script/files; they weren’t the actual paths, you need to know the path where the sunxi-tools and the fex/script files actually lie.

      Regarding the echo error: Where exactly did you encounter this error? On the Cubieboard? Because your error seems to be asking for a super user (su). So try sudo echo 2 > /sys/class/gpio/export

  4. i have cubiuntu in sd of cubieboard… and i want to use the GPIOs of this cubieboard…. and i try to configure it on the cubie… and yes… im a super user when i try the echo 2 > /sys/class/gpio/export

    • abhinavgupta said:

      Sorry for the late reply, have been busy with some stuff.

      It might be that the pin is just not declared in the fex file. Did you initialize some pins in the fex file?

      • George said:

        (these are for a cubieboard2)

        gpio_used = 1
        gpio_num = 12
        gpio_pin_1 = port:PH20
        gpio_pin_2 = port:PH21
        gpio_pin_5 = port:PA10
        gpio_pin_6 = port:PA11
        gpio_pin_7 = port:PA12
        gpio_pin_8 = port:PA13
        gpio_pin_9 = port:PA14
        gpio_pin_10 = port:PA15
        gpio_pin_11 = port:PA16
        gpio_pin_12 = port:PA17


        uart_used = 1
        uart_port = 1
        uart_type = 8
        uart_tx = port:PA10
        uart_rx = port:PA11
        uart_rts = port:PA12
        uart_cts = port:PA13
        uart_dtr = port:PA14
        uart_dsr = port:PA15
        uart_dcd = port:PA16
        uart_ring = port:PA17

        have you actually managed to use the UART this way? not theoretically, has it actually worked, did you manage to speak to the cubieboard via this method? What is your gpio_para and uart_para1 sections?

      • abhinavgupta said:

        I have tried and tested talking to an Arduino board using the UART on the cubieboard. However it the uart_port was 3 which was a 4 pin type UART. The uart_para section looked like this:

        uart_used = 0
        uart_port = 3
        uart_type = 4
        uart_tx = port:PH00
        uart_rx = port:PH01
        uart_rts = port:PH02
        uart_cts = port:PH03

        The GPIO para doesn’t matter as long as you are not initializing the same pins under a different mux selection in the GPIO para

  5. I think you have a type at the end where you describe how to use the GPIO. Your line:
    export gpio2_pb17 gpiochip1 unexport

    should have gpio2_pb19 not gpio2_pb17

    You use both pb17 and pb19 in the next statement

    • abhinavgupta said:

      Ah damn, thanks for pointing it out! Shall change it,

      • It’s a very nice write up, thanks for sharing it!

      • abhinavgupta said:

        Hey thanks man! I have been working on a GPIO interrupts for quite some time and planning to write an article on sysfs-GPIOs as well, lets hope I get some time to finish that off.

  6. Hadi said:

    where is script.bin on Linaro 13.09 ? i search a lot but got nothing.

    • abhinavgupta said:

      You can either check in the /boot folder. Is this a working Linaro rootfs? As in did you boot your Board once with it or this is just a downloaded tarball?

  7. i wonder if you have tried to connect nRF24L01 sensor to cubieboard and receive any message, i am highly interested in some related information

    • abhinavgupta said:

      Nope, not really. It would be interesting to do so, but since it uses a standard SPI interface, it *should not* be technically not that difficult.

  8. Elizeu said:

    Your information has been very important for beginners in the world of Cubieboard.

    You should also put this information to users of Linaro.
    for the file is script.fex necessáio mount the nand partition
    $ mount / dev / nanda / mnt
    $ cd / mnt
    $ bin2fex script.fex script.bin
    $ vi script.fex or nano script.fex

    done this

    fex2bin script.fex script.bin

    graciously .

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: