I have recently purchased two of those very sweet Olinuxino A13 boards for a new project I’m working on. I bought them directly from Olimex in Bulgaria, only to later discover that I could have ordered them from another website in the US. The prices are a bit higher, but shipping is lower so for small quantities it might work better.
I also bought two LCD Touch screens, two MOD-RS232, and some other boards that I plan to experiment with further down the road (for example to control higher voltage relays).
What this guide contains
In this guide I will show you:
- What hardware to purchase for your development kit
- How to build your own custom Linux Kernel
- How to build a bootable SD Card with Debian Wheezy
- How to get X11 working on the A13-LCD7-TS with Debian
- How to get the Touch Screen to work with X11
- How to start a locked-down, full screen web browser
By the end of this guide, you will hopefully learn how all the components work together, and as an added benefit you will also get a fully working development system that allows you to comfortably start working on your product, based on a very solid platform, with stable, reliable, and reproducible results. I believe learning is more important than doing, and this is why I’m making this guide as detailed as possible.
Another important aspect is the comments to this post, which come from pretty smart people who tried all this out, and had really important feedback. Without this feedback, this guide would certainly be lacking. I would like to thank all of you for taking the time to give feedback so that others may have a better configuration with their systems.
My initial impression
I was initially trying to purchase a Raspberry Pi, but supplies being non-existent I was forced to look for alternatives, and I’m very glad I did because the end result is that I have a more powerful platform to work with. It’s faster, has 3 USB ports with tons of gpio pins, has an on-board nand chip, wifi adapter, sd card reader, audio in/out, and the pretty useful UEXT connector. It runs very cool, and since there are no moving parts or fans it is naturally silent.
In addition to this specific product being quite amazing, feature wise, Olimex has a very talented team of engineers who crank out new boards and designs at a pace rarely seen. They are already working on an A10 board, which packs even more impressive hardware and features. Once in a while they even find the time to write a new guide or how-to, and post it on their blog.
Apart from the Olimex engineers who are obviously dedicated to their cause, there’s a good number of individuals working on the “ARM Netbook” project. The Olimex and ARM engineers, as well as the community of users, all hang out on the Freenode IRC Network, on channels #olimex and #arm-netbook (If you have an IRC client you can click those links to directly join the rooms). I strongly urge you to join those chat rooms if you have questions, or if you feel you can help others with your skills and knowledge.
And if this is not enough to convince you, consider this: All Olimex products are 100% open source hardware, which includes the CAD files for the boards, routing, etc. You can truly do whatever you want with the designs, and all the designs are fully available and downloadable from their github account. This is not the case with the Raspberry Pi where some parts are closed with strange excuses given by project members.
Important adjustment of expectations
I think that for a short while I was under the illusion that things will just work great out of the box. I was quickly disillusioned however, because the problems piled up and some of them proved quite a challenge initially. Thankfully, the Olimex hardware has quite a following; a mix of hardware enthusiasts as well as commercial entities purchasing the boards to include in their embedded linux projects. They all socialize and help each other on the Olimex forums.
On the other hand, the issues I encountered are all software related, and platform specific. This means that with some reasonable effort and enough reading, they can all be solved. I solved my issues within a week, and I am now very pleased with the results. I am by no means done – As of this moment, I still have a segmentation fault with the touchscreen driver, but I’m sure I will have this issue resolved within the next 24 hours.
So what I learned is something I should have known right from the start: This is not a mass market product. It is a very new product (May 2012!), and this means whoever utilizes this platform is pretty much on the bleeding edge of open source hardware technologies, and this is not without implications. On the other hand, this is what makes it fun. Reading data sheets, really understanding how the board functions, what components are on the board and why they were chosen, what each pin does in the various on-board connectors, and so on and so forth. This is a platform that forces you to take off your shirt and dive into unknown waters, but you get to swim with some pretty cool fish!
Simple challenges during my first order
No Power Supply: While ordering the boards, I needed to purchase power supplies separately. Olimex does not sell power supplies for America. A quick search on Amazon based on the power rating, polarity, and dimensions of the connector, and I found a pretty good power supply on Amazon. It arrived within a few days and I was able to power the boards.
No LCD Cable: This is when I realized the LCD comes without the cable that connects it to the board. Fortunately Olimex support (Tsvetan) replied that the cables are the same as IDE cables. Again Amazon to the rescue, and within 2 days I had two cables and the LCD was hooked up to the board. At this point I was able to boot the system, which comes preloaded with Android.
Wrong Screen Resolution: When Android booted I noticed the entire screen is offset some 20% to the right and some 10% to the bottom. The touch screen however was properly calibrated, so I had to touch the icons in the area where I thought they should be. This is pretty easy to resolve, as I found out later, but not from Linux or Mac. You need to install a program called LiveSuit on Windows. A port of LiveSuite for Linux exists, but it does not recognize the Android IMG file. I tell this to you now, but it took many days of trying and failing and talking to people online until I received a final confirmation that it only works on Windows, because of people at Allwinner, the company that produced the SOC (Systen On Chip).
Bad USB to Serial Strategy: I had a PL2303 at home, so I didn’t buy the USB to Serial cable sold by Olimex. This was a mistake because the one I had did not work very well. I should have just purchased it but I didn’t think I would need it. It ended up being very important, because it helps you login to the console and configure the OS to connect to the network, for example, or to see the output from u-boot while the system is booting. It’s just a good idea to have console access.
Which brings me to the next section for any person considering buying Olimex products, or any products in general since this does not apply only to Olimex but to any hardware project.
What to buy as a starter kit
I feel I have learned quite a lot about the platform because of all the mistakes I made and all the obstacles I encountered, so I am thankful that I made those mistakes. However if you are in a hurry to create a commercial product based on this platform, you will avoid all the mistakes I made by simply buying the correct products for your kit.
This is my recommended list of materials for any person trying to develop on this platform for the first time:
- From the Olinuxino A13 category:
- One of the Olinuxino Boards (based on whether you need 1 or 3 usb ports, wifi or no wifi, 512mb RAM or 256mb RAM on the Micro version, etc). I purchased the most expensive one A13-OLinuXino-WIFI
- One of the LCD products, without the touchscreen A13-LCD7 or with a touchscreen A13-LCD7-TS (that’s the one I have). I like having the LCD because it’s cheap enough and will not take away one of your monitors while you work with your kit. The size is perfect for development purposes and the resolution is high enough (800×480) which makes the fonts quite sharp and readable.
- One of the SD cards (A13-OLinuXino-MICRO-SD or A13-OLinuXino-SD), it comes preloaded with Debian Linux (Wheezy), and will save you a lot of time and efforts (and most of the mistakes I made).
- If you are getting an LCD, get this cable: CABLE-IDC40-15cm
- Get the following cables for sure:
- If you live in Europe or a country with European power sockets and voltage, definitely get this power supply: SY0612E
- If you plan on using an off the shelf USB to Serial cable with a DB9 connector, definitely get this UEXT adapter: MOD-RS232
Lessons about building and booting a Debian SD Card
The main lesson here is that if you want to be up and running as soon as possible, that you should not even focus on trying to build the Debian image yourself. Olimex sell you the SD Card with the Debian image already pre-built for you.
On the other hand, I do feel it is a great learning experience. And more importantly, I believe that if you are serious about the product you are building, you have to learn how the parts all fit together. Building your own Debian image is a great way to learn about that.
Remember how I said in the beginning that this is all very fresh technology? Some of the options I’m going to show you here, were only just committed into the Github repository of the sunxi-bsp project by techn_ from IRC.
Before we start – Installing Prerequisites
It’s important to have a correct system time, or you will get warnings about some dates being in the future. While we’re at it, let’s also install git, the compilers and other utilities required to build our packages:
# Install compilers and related utilities apt-get install build-essential git automake autoconf libtool ntpdate pkg-config # Let's make sure our system time is correct ntpdate pool.ntp.org
If you connect to your A13 over SSH (Like I do, which is way more convenient than working on the A13 directly), then it is quite possible the network will disconnect after you update the system time. I’m not exactly sure why this happens (I have some theories), but if you find yourself disconnected from your A13 after you update the system time, don’t panic, and don’t reboot your A13. Just connect to the console as root and type:
/etc/init.d/networking restart /etc/init.d/ssh restart
That’s it, your A13 will now be available again via SSH.
Quick start guide – Building the Kernel
Fortunately for us, this task has been made infinitely simpler by the good guys on #arm-netbook via the sunxi-bsp project, which is an umbrella project, as well as a set of scripts, designed to bring everything you need in order to build the kernel, u-boot, and the script.bin file, as well as tools that help you hack around with the AllWinner hardware.
# Let's fetch the sunxi-bsp project into /usr/src: cd /usr/src/ git clone git://github.com/linux-sunxi/sunxi-bsp.git # Now we configure it for the A13 Olinuxino: cd sunxi-bsp make ./configure a13_olinuxino # This time, make will build everything! make
Once this is done, you’ll have the kernel, as well as the modules and u-boot under the /build/ directory. You now have the latest supported kernel (At the moment 3.0.52).
Important step: Enabling sun4i-gpio
If you own the A13-LCD7-TS hardware, you will notice it doesn’t power on under Debian. It took me a while to figure out the reason behind this. Turns out the backlight is powered by pin 15 of the GPIO port to which the LCD is hooked up. Android has a PWM (Pulse Width Modulation) component that pulses this pin in various frequencies, to give you different levels of brightness.
Since Debian does not have a PWM module, all we can do is power the pin, and the display will always be stuck on maximum brightness. That’s fine by me anyway.
To set that pin to the On mode, we need two things:
- Enable GPIO in script.bin, set pin 15 to be On by default, and update that file in your boot partition (same place where uImage is).
- When Debian loads, we need to load the sun4i-gpio module, so that the settings will actually be in effect. But first we’ll need to build it with the kernel, since it’s not enabled by default.
Let’s enable the GPIO Kernel modules:
cd /usr/src/sunxi-bsp/ make linux-config
This will get you into the standard “menuconfig” option, except it will edit the correct .config for your setup (in our case: a13_defconfig). Navigate to Device Drivers —> Misc Devices and enable the following features as Module <M>:
<M> An ugly sun4i gpio driver
<M> Sunxi platform register debug driver
Exit back and save the settings, then run make again:
This time, make sure you see sun4i-gpio.ko in the list of generated modules. If you see it there, you have enabled the correct modules.
A word of caution about the Paranoid Android…
During my trial and errors with trying to activate the LCD, I experimented with a pre-built kernel that I extracted from the built-in Android OS that came with the A13. The theory was that it might have a PWM module to power the LCD.
It booted the OS just fine, but I discovered that non-root users did not have permission to create Network File Descriptors. Through some more research on google, I discovered this is a Kernel config flag called CONFIG_ANDROID_PARANOID_NETWORK. If enabled, the kernel will require users to be on a group with gid 3003 to be allowed network access, and that’s just one of the restrictions. This broke the xf86-input-tslib module with a segmentation fault.
So my warning to you is: Do not enable CONFIG_ANDROID_PARANOID_NETWORK unless you are prepared to deal with the implications (making code modifications in several modules, and configuring the system very carefully).
Preparing the bootable Debian SD Card
Coming soon. In the mean time, consult this guide on the A13 Olinuxino Wiki Page
In fact, that page contains ready made images, along with various tools that will help you tweak the script.bin file to your hardware configuration (VGA vs. LCD for example).
Building tslib and xf86-input-tslib
In order to support the A13-LCD7-TS we have to use a patched tslib and xf86-input-tslib. The way I understand the patches, they are designed to work around the multi-touch limitation in the hardware.
1. First download the 3 patch files from this github directory and place them in /usr/src/
2. Perform the steps below to patch, compile and install tslib in your system:
cd /usr/src git clone https://github.com/kergoth/tslib cd tslib patch -p1 < ../tslib.patch autoreconf -vi ./configure --prefix=/usr/local make make install ldconfig
At this stage, tslib will be installed on your system, and by running ldconfig we make sure that the libraries can be accessible immediately. Note that if you installed the libraries into a non-standard location, you should make sure to add that path to /etc/ld.so.conf and then run ldconfig again. To find out the touchscreen device number run “dmesg | grep sun4i-ts“. Sample output below:
[email protected]:/usr/src/tslib# dmesg | grep sun4i-ts [ 15.540000] sun4i-ts.c: sun4i_ts_init: start ... [ 15.560000] sun4i-ts: tp_screen_size is 5 inch. [ 15.560000] sun4i-ts: tp_regidity_level is 5. [ 15.570000] sun4i-ts: tp_press_threshold_enable is 0. [ 15.580000] sun4i-ts: rtp_sensitive_level is 15. [ 15.590000] sun4i-ts: rtp_exchange_x_y_flag is 0. [ 15.600000] sun4i-ts.c: sun4i_ts_probe: start... [ 15.620000] input: sun4i-ts as /devices/platform/sun4i-ts/input/input1 [ 15.640000] sun4i-ts.c: sun4i_ts_probe: end
As we can see in the output above (on my system), the device number is input 1.
To run ts_test and ts_calibrate, as well as run X11 with tslib support, we need to export the following environment variables:
export TSLIB_TSEVENTTYPE=raw export TSLIB_CONSOLEDEVICE=none export TSLIB_FBDEVICE=/dev/fb0 export TSLIB_TSDEVICE=/dev/input/event1 export TSLIB_CALIBFILE=/etc/pointercal export TSLIB_CONFFILE=/etc/ts.conf export TSLIB_PLUGINDIR=/usr/local/lib/ts
Note that in the TSLIB_TSDEVICE environment variable, the “event1” part corresponds to the “input1” device that we saw earlier. If your device is on “input4” then you should replace “event1” with “event4“.
I have placed this block of exports in /etc/environment so they are all set on system boot. I also erased /etc/pointercal and reran ts_calibrate to re-generate that file. ts_calibrate will guide you through the calibration process, and when done it will write the new values into /etc/pointercal. You can then run ts_test to make sure you are happy with the calibration. ts_test will allow you to draw on the screen, or drag a small block around, which is great because it gives you a good feel for the accuracy and responsiveness of the touch screen.
By the way, one small “visual bug” I noticed is that ts_calibrate and ts_test do not clear the screen when they exit, but don’t worry about that.
3. Perform the steps below to patch and compile the xf86-xorg-tslib module:
# Let's get some X11 dependencies first apt-get install xorg-dev xserver-xorg-dev x11proto-core-dev # Now we fetch the module's source code and unpack it: cd /usr/src wget http://ftp.de.debian.org/debian/pool/main/x/xf86-input-tslib/xf86-input-tslib_0.0.6.orig.tar.gz tar zxfv xf86-input-tslib_0.0.6.orig.tar.gz cd xf86-input-tslib-0.0.6/ # Apply the patches patch -p1 < ../1-xf86tslib-sigfault.patch patch -p1 < ../xf86-input-tslib-port-ABI-12-r48.patch # Finally, let's get this thing built and installed ./configure –prefix=/usr make make install
Now that we have the module compiled and installed, we need to tell X11 about the new device. We’ll do this by creating a new file under /usr/share/X11/xorg.conf.d/. I chose to call this file: 20-touchscreen.conf.
Here’s what my file looks like:
Section "InputClass" Identifier "Sun4iTouchscreen" Option "Device" "/dev/input/event1" Driver "tslib" Option "ScreenNumber" "0" Option "Rotate" "NONE" Option "Width" "800" Option "Height" "480" Option "SendCoreEvents" "yes" Option "Type" "touchscreen" EndSection
At this point you are ready to start X. Let’s start it with in Verbose mode so you can see the logging on screen:
If you did everything right, you should see a mouse cursor on the screen, and you should be able to properly click on screen items and even drag scroll bars to scroll around. Congratulations!