I like to believe that this is a reasonably complete guide on how to get a reasonably old revision of OpenWRT running on your Bifferboard. I wrote this mostly for myself, I know that if I don't I will have forgotten everything by the next time I need to do it.
I started working with the Bifferboard around August 2010, playing around with it and trying to make it do what I wanted for a project. After that I didn't do much work on the Bifferboard again, until now. However, dusting off the old Linux-installation I used for building the software and trying to remember exactly what I had done the last time, I realised that I really needed to write the complete process down. So, after once again scurraging the net trying to dig out all the info I had forgotten, and learning quite a bit of new things in the process, I decided to compile it all in a handy little "walkthrough". Of course, this handy little walkthrough then started ballooning to rather large proportions as I added things in ...
Note that while I do believe everything in here to be mostly accurate and have tested it all, I will not take any responsibility for any problems or damage you may or may not cause to yourself, your hardware, your loved ones or really anything at all by following, or not following as the case may be, this guide.
If you do run in to any problems, however, I will gladly try to help you to the best of my ability. Any questions, comments or suggestions can be sent to bifferboard@heavyconsulting.net.
Also, if you find my usage of the English language to be erroneous or peculiar, that is probably just because I'm crazy. Or Swedish. I get those two confused sometimes. Anyway, please do point out any mistakes so that I may at once correct them.
Big thanks to Fredrik Björeman for proofreading and spell checking the original draft. I have probably caused more errors since then though.
--
Niclas Lardh
Heavy Consulting
Sweden, January 2011.
The serial cable is not strictly necessary unless you are having trouble flashing the board over ethernet. It is also useful if you need to change BIFFBOOT config-paramters, although there is a way to set the parameters over ethernet as well. Please see the Bifferboard Wiki for more info on that.
I believe any Bifferboard purchased since at least summer 2010 already has the correct BIFFBOOT config parameters set on delivery, so chances are good you don't really have to alter them.
Note that unless you remove the firewall or change its configuration when building OpenWRT, it will not allow you to log in with telnet or SSH from the network. This is because the Bifferboard network port is treated as the WAN-port on a router and firewalled by default. If you build OpenWRT with the firewall like that you need a serial cable to get access to the console to change the settings to allow you to log in.
The cable can also help quite a lot if something goes wrong during boot. Without it it may be difficult at best to see what the board did, or more likely did not, do when it tried to start.
Note that you do not have to be root to do anything in this file, except if you need to install anything on your computer with apt or use the ethernet-flasher script. Commands are prefixed with # to illustrate the command prompt. That character should not be typed. As always, please take time to understand what commands do before typing anything into you system. I have tested these instructions thoroughly and believe them to be accurate, but there could always be some mistypes or errors lurking.
First you need to make sure your Linux system has all the necessary software installed to compile the build environment. Probably something like build-essential subversion asciidoc autoconf binutils bison bzip2 flex gawk gettext libncurses5-dev libz-dev patch unzip zlib1g-dev cmake. If you get errors during the make-process, that is probably because you lack some component. Install by running "sudo aptitude install name" (At least on Debian/Ubuntu and other systems that use apt. Please see your distributions' manual for more info).
Create a working directory somewhere, perhaps inside you home folder. This is where we will store everything, including the cross compile tools, all the built files and all the downloaded archives and extracted code. Everything. You need at least 3 GiB of space. Probably more.
# cd ~
# mkdir bifferboard
# cd bifferboard
For convenience, I have gathered a few things you need in a single archive. It contains a few patches and Bifferos tools to flash the Bifferboard.
Download and extract it to the current directory. (Don't forget the - at the end of the command)
# wget -O - http://heavyconsulting.net/bifferboard/bifferboard-openwrt.tar.gz | tar xvzf -
Using subversion, check out the trunk, revision 22979 and store it in a directory called openwrt.
# svn co -r 22979 svn://svn.openwrt.org/openwrt/trunk openwrt
Enter the openwrt directory and apply the bb-r22979.patch
# cd openwrt
# patch -p0 < ../bb-r22979.patch
The bb-r22979.patch changes the /etc/config/network for the Bifferboard to remove the LAN-interface since the Bifferboard only has the WAN-interface (The RDC-chip has two interfaces, but only one is connected). It also adds a hostname to the wan-interface.
Edit the file before applying the patch if you want to change the name from the default "bifferboard".
This can of course also be changed after you have installed everything to the Bifferboard.
Copy the two other patch-files included in the archive to the linux kernel patch-directory so they will be used in the build-process.
# cp ../016-pit_tick_rate.patch target/linux/rdc/patches-2.6.32
# cp ../017-set_rtc_mmss_disable.patch target/linux/rdc/patches-2.6.32
The pit_tick_rate-patch changes the tick-rate in the file build_dir/linux-rdc/linux-2.6.32.20/include/timex.h to make the real time clock run with correct speed. Without this it will be slowing down with approximately 7.5 seconds every minute.
The set_rtc_mmss-patch disables the set_rtc_mmss-function in the file build_dir/linux-rdc/linux-2.6.32.20/arch/x86/kernel/rtc.c to avoid getting a lot of "can't update from 2 to 5x" warnings in the log if you are running ntpd. The Bifferboard does not have any real time clock and the minute field always reads as 2. This causes set_rtc_mmss to always fail with that warning if it is not run at the right time of the hour.
This is optional since all the base functionality is included in what we already downloaded, but will give you access to a whole lot more packages in the menuconfig.
# scripts/feeds update -a
# scripts/feeds install -a
The first of the two commands will use svn to download package-trees from the svn-servers and then generate some indexes and collect some package info. The svn-servers are specified in the feeds.conf-file. If you wish to edit it to add other package repositories, copy the feeds.conf.default-file to feeds.conf and edit it with a text editor. Everything downloaded will be stored in the feeds-directory.
The second command installs everything by linking it into the package/feeds-directory so the build-process can use them.
Note that the packages you download here will always be the latest versions, even though the rest of the system and kernel is from trunk revision 22979. In other words, the packages will differ in the future and even if you set everything the exact same when you build at a later point in time, the software not included in the base system may very well be later versions.
As i write this, it checks out the following revisions, but these numbers are growing by the minute:
Now we are ready to create the configuration
# make menuconfig
This will first check dependencies and alert you if anything is missing from your Linux system. If so, just install it with aptitude or whatever.
It will also run through all the packages and add them to the configuration-menu which you will then be presented with.
Here you can select exactly what you wish to include on your Bifferboard, but first you need to select the correct target.
Under Target System, choose RDC321x.
Target Profile should then be set to Bifferboard.
Select all packages you want. Deselect the ones you do not want. It may be a good thing to remove the Base system/Firewall as it will be in the way when you try to connect with telnet or SSH later. While you are there, also remove dnsmasq since you probably will not have any use for it.
Notice that OpenWRT includes Busybox. Busybox takes care of a lot of things and implements most common Linux tools in a single file. This saves a lot of space and means you do not normally have to explicitly install anything already present in Busybox. You may optionally enable or disable parts of Busybox in the config menu. Just go into Base system, move down to Busybox and press enter, move down to Configuration and press enter again, and so on. To walk up from a submenu, tab to highlight Exit at the bottom and press enter. There are a lot of compile options for Busybox available in this menu.
Busybox includes vi, the text editor, by default. If you don't like vi you can always add nano or some other simple editor from Utilities/Editors.
If you plan on using USB-serial adapters, go into Kernel modules/USB support and select kmod-usb-serial and any serial drivers you need. Probably FTDI (Arduino and other things) and/or pl2303 (many USB-serial cables). Also include kmod-usb-serial-option if you plan to use Huawei or Option 3G-modems (see my other how-to on how to use your Huawei E1550 3G-modem with the Bifferboard).
If you want to use USB-memories or other mass storage devices, go into Kernel modules/Filesystems and add any filesystem you wish to use. By default only ext3 is selected.
Select things by pressing space. "M" indicates the package will be built but not installed to the Bifferboard image. "*" indicates that it will be built and included in the image.
Packages built but not included can be installed to the Bifferboard at a later time by downloading the ipk-files the build produces to the Bifferboard and installing them with "opkg install". This way you can always make more packages at a later time and install them without the need to re-flash the entire Bifferboard.
Exit by pressing tab to highlight Exit at the bottom and press enter. Choose to save the configuration when asked.
Now, build it.
# make
Wait for an hour or so while everything downloads and compiles. This will first download and build the actual tools and compilers that will be used to compile the software for the Bifferboard. Then those tools will be used to compile the Linux kernel and all packages. The packages will be "installed" into a directory and then it will be packed up as a filesystem-image. That image is appended to the kernel to create the image-file we will later flash to the Bifferboard.
If something goes wrong you might want to use verbose output and save all output (both stdout and stderr) to a file so you can examine it later.
# make V=99 2>&1 | tee ../build-log.txt
This will run make with V set to 99 to display all output and then redirect stderr to stdout and pipe stdout to tee, which is a program that saves stdin to a file and at the same time sending it to stdout.
Long story short, it gives you all output on screen as-well as in a file.
If there was something that did go wrong, look through the build-log.txt to find where the error occurred, fix it, and just run make again.
If everything runs through without error you should now have a bunch of image files in bin/rdc.
For the kernel to boot properly you need to have some specific settings in your BIFFBOOT config on the Bifferboard.
Connect the serial cable and launch a terminal program like minicom. Set the program to use your serial port, probably something like /dev/ttyUSB0 if you use the USB-serial adapter, at 115200 bps 8 bit, no parity, 1 stop bit (8N1), no flow control.
If you are using minicom you can run "sudo minicom -s", set all parameters and save the setup as default to have it load the next time you run it with "minicom". Remember to go to the Modem and dialling section of the config and remove everything from A to I and K.
Once you have a working serial connection to the Bifferboard, apply power to the board and press ESC as soon as you see <ESC> on the terminal. You will then be dropped into the BIFFBOOT command interface.
These BIFFBOOT-instructions are for version 3.0 or newer.
Check your current config with "showconfig" to see if it matches what you need. If not, use "set" to set values as needed. Finish with "save" to save them. There is built in help by typing "help".
The kernelmax parameter specifies how many 64 KiB blocks should be loaded to RAM by the bootloader. These are the blocks that contain the Linux Kernel. 0x10*64 KiB = 16*64 KiB = 1024 KiB = 1 MiB. The OpenWRT-kernel will probably be around 700 KiB.
The cmndline can be used to pass parameters to the kernel when it starts, but OpenWRT have all the needed parameters already in the kernel. Therefore, cmndline should be blank.
It is also possible to change the parameters in BIFFBOOT over ethernet. Please see the Bifferboard Wiki for more information about that.
Flash the jffs2-64k-image to the board (JFFS2 is the file-system used in the image and 64k is the block size) with the scripts that was included in the archive downloaded before. The scripts are written by Bifferos in the language Python, which needs to be installed if it is not already (it probably is).
To flash using the serial cable is reliable and simple, but you need the cable, and you need to open the Bifferboard case (if you have it inside the case) to attach the cable. It also takes quite some time.
# ../bb_upload8.py /dev/ttyUSB0 bin/rdc/openwrt-rdc-jffs2-64k-bifferboard.img
Replace ttyUSB0 with the name of the serial port the Bifferboard is connected to. To figure that out you can run the command "dmesg" after plugging in your USB-serial cable.
Run the bb_upload8.py-command and then apply power to the Bifferboard when it asks you to do so. If all goes well, the flash will be erased and the raw image will be flashed to it, 8192 bytes at a time.
This will take several minutes.
When it's finished the upload tool works as a simple serial terminal, allowing you to boot the Bifferboard (by pressing 4) and checking everything out without starting a separate terminal. To exit the upload tool while it is in terminal mode, check what the process ID (PID) is, for example with "ps ax | grep bb_upload", and send it a kill from another terminal (such as "kill 1234").
If you wish to flash over ethernet, just connect the Bifferboard to the same network switch as the computer. The protocol is not routable, so they have to be on the same ethernet network. If you get any problems you could also try a cross-over cable (or a straight cable if your computer automatically senses that it is connected to another device instead of a switch).
The network flashing script needs to be run as root to work. Replace eth0 with the network interface name (check with "ifconfig") and the hex-numbers with the MAC-address of the Bifferboard. The MAC-address is written on the sticker on the flash-chip (the top line if there are two lines of numbers). It is also sent out on the serial port by BIFFBOOT every time the Bifferboard is powered up (unless console is disabled in BIFFBOOT config).
If your Bifferboard is inside a closed case and you do not wish to open it, you could, provided that there already is a bootable Linux installed on it, start it up and try to connect with telnet or ssh to run the ifconfig-command and get the MAC-address that way. It may also be possible to check the MAC-address in your routers logs.
Run the following command and switch the power on to the Bifferboard within 10 seconds, or it will time out.
# sudo bb_eth_upload8.py eth0 12:34:56:78:9a:bc bin/rdc/openwrt-rdc-jffs2-64k-bifferboard.img
Newer versions of BIFFBOOT also includes ways of flashing and booting over the ethernet with TFTP, but you generally still need the serial cable to activate those procedures.
Once flashing is complete you should now have a working Bifferboard running OpenWRT.
The first boot will take slightly longer since the kernel have to expand the filesystem to fill all the available (almost 7 MiB) flash.
By default, the system has no password so you can not use SSH to log in. Telnet will however let you in without even asking, and you can always use the serial cable to get to the command prompt (see the instructions for using minicom above).
Use the command "passwd" to set a password for the root-user. This will automatically disable telnet, since the start-script for telnetd checks if the root-user has a password and does not start it if it has. One the password is set you will have to use SSH if you wish to log in from the network. Change the IP-address in the following command to the one your Bifferboard uses. If you are unsure about what address what assigned to the Bifferboard, you can usually find it in your routers DHCP-logs, or use a serial connection to the Bifferboard and chech it with "ifconfig".
# ssh root@192.168.10.10
Note though that by default, unless you deselected the firewall at menuconfig (or edited the rules before building) it will block both telnet and SSH on the Bifferboard network port. This is because it is the WAN-port and OpenWRT expects to be running on a router with both WAN and LAN ports. You can use the serial console to get into the Bifferboard and turn it off by running:
BIFF# /etc/init.d/firewall stop
BIFF# /etc/init.d/firewall disable
The first command stops it temporarily. The second disables is so it won't start again when it reboots. Check with "ls /etc/rc.d/" that the firewall init-file is really gone.
Or you could update the firewall settings to allow connections to port 22 from the WAN.
That's it. Welcome to the wonderful world of OpenWRT on the Bifferboard.
Please stay on the lookout for more "walkthroughs", "how to's" and "tutorials" from me as I learn more about the subject in the future at http://heavyconsulting.net/bifferboard/.
Niclas