October 6, 2016

Getting started with Kyu on the ARM platform for the BBB

I do all of my Kyu development on a linux system (at this time Fedora 24, but the linux distribution should not matter). If you want to try Kyu development on some other system (such as OS-X) I won't be able to help, but I would be quite glad to hear from you and add any information about doing this that you might provide.

Getting Kyu

You need to get and build the source distribution. This is best done by cloning from github: A command like the following should do the trick. 
git clone https://github.com/trebisky/Kyu.git
This will place Kyu into the directory "Kyu", but if you prefer something else, give the clone a target like: 
git clone https://github.com/trebisky/Kyu.git kyu

Hardware

You will need two things, a BBB and an appropriate USB to serial gadget. You can buy a BBB for about $55 these days from Sparkfun, Adafruit, or perhaps even Digikey. However, I prefer the BBG (Beaglebone Green). It sells for only $39 and omits the HDMI video that you will probably never want or need. The last time I checked, Digikey had them or you can get them from Seeed Studio. I have done most of my development on a BBG. Any statement I make about a BBB applies equally to the BBG.

Serial console

It is essentially impossible to do anything on a BBB without a serial console. If you don't already have one, rush out and buy some kind of USB to serial gadget. The BBB uses what is commonly referred to as the "arduino pinout" (or so I am told). Just make sure that it is configured to use 3.3 volt logic levels or you will damage your BBB. I like the Sparkfun FTDI basic. See this article: Then on my linux system, I use picocom, typically something like this works: 
picocom -b 115200 /dev/ttyUSB0
Type control-A control-X to exit.

Compiler

You will need a cross compiler that targets the ARM. Actually you need a whole toolchain, but your linux package system should give it to you. On Fedora, I do this: 
dnf install gcc-arm-linux-gnu
This installs several packages (I believe four, including binutils) and is all that you need. If you are on another distribution you will have to work things out and perhaps change the compiler name in "Makefile.inc". I am currently building with the 6.1.1 version of the compiler. Note that if the compiler version changes, you will need to tweak a setting in Makefile.inc.

There is another compiler available in the fedora package set, namely "arm-none-eabi-gcc-cs". This is the code sourcery spin on the GCC compiler. I have never worked with it, but odds are it would work just fine. If you use it and have comments to make, let me know.

Once you have the compiler installed, you should be able to build Kyu as follows: 

cd Kyu ; make
The final step in the make process is to copy the binary image to the tftpboot area as follows: 
cp kyu.bin /var/lib/tftpboot/kyu.bin
This will probably yield an error (unless you already have a tftp server set up). We will get to this in the next section.

Network booting -- setting up a server

This may seem like a lot of fuss, but once it is all set up, it is wonderful and absolutely worth it.

First, set up a TFTP boot server. These instructions are for a Fedora 24 system in late 2016. This boils down to installing a package, starting the server, and making sure the necessary ports are open on your firewall. On fedora, the package to install is "tftp-server". But the service to start is "tftp-socket". What are these guys smoking? Notice also that this is no longer under xinetd as it used to be, but is "stand-alone" as its own thing. 

dnf install tftp-server
systemctl start tftp.socket.
systemctl enable tftp.socket.

TFTP uses UDP port 69, so you need to do whatever you need to do to open up this port on your firewall (if you have one). I just hack a line like this into my iptables file, but there are definitely other ways to do this. 

-A INPUT -s 192.168.0.0/24 -m state --state NEW -p udp --dport 69 -j ACCEPT

You probably will not need to set up DHCP. My home router does just fine, but if for some reason you need to run a server on your linux system, the game is much the same (except you need to edit the config file). 

dnf install dhcp-server
systemctl start dhcpd.service.
systemctl enable dhcpd.service.
Starting it will probably fail (or do nothing) until you add entries to /etc/dhcp/dhcpd.conf. You will also need to fiddle with firewall ports. Open up UDP ports 67 and 68.

Details will likely differ on different systems and distributions. You will need the MAC address of your unit, which you can get from the serial console output, or wireshark.

Network booting -- setting up the BBB

As shipped, your BBB will probably boot some version of linux. These instructions tell you how to modify the uEnv.txt file so that the boot loader (U-boot) will boot Kyu from the network rather than linux.

How all this works when the smoke clears

Once all of this is set up, I typically work with two windows involved. One is running picocom and showing me the BBB console. The other is in the Kyu source directory. I type "make" in the source window, change windows to view the console and either press the reset button or type "R" to the Kyu prompt, which should look like this: 
Kyu, ready>

Have any comments? Questions? Drop me a line!

Kyu / tom@mmto.org