Idiot's Guide to OpenWrt on the BR-6104K

Introduction

Not wanting to insult anyone, but there are enough books out there with such titles, and quite popular at that so this is hopefully a good starting point for 'les nuls' as they say.

If you are a Linux beginner then you have hopefully come to the right place.

Instructing people on the intricacies of OpenWrt compilation, especially for partially supported platforms (like BR-6104K) is somewhat challenging. No point posting config files, since the developers have a habit of changing formats on a daily (or at least weekly) basis. Also, a list of instructions is time-consuming to write up, and soul-destroyingly quickly out of date.

So here I present a series of Flash movies to guide you through the process. I am basing these on a Vmware Server host (http://www.vmware.com). This is a virtual machine emulator, which means my instructions can concentrate on what you do with OpenWrt, instead of details of how to configure SuSE, RedHat or Mandrake etc... to support OpenWrt. I have chosen Slackware version 12.0, because that's my platform of choice. If you don't like it, feel free to use something else, but as far as I am concerned you might just as well stop reading here. If you want something that's (fairly) sure to work, bear with me and read on.

Hardware Requirements

If you have no router to begin with, you could do worse than purchase one of the Omnima boards (http://www.omnima.co.uk/kp). This is actually the BR-6104KP model (USB included). Alternatively, a Sweex LB000021 can be had a bit cheaper but without the USB ports. A similar board is sold as the Edimax BR-6104K(P). The main board, and most importantly the bootloaders are all compatible on these boards, although the PCBs can be slightly different. For hacking, the Omnima comes with an 8-pin serial port header supplied, which saves some time, but the price does not include the case.

You will need a serial level shifter to connect to the serial port on the board. Wiring details can be found at http://www.linux-mips.org/wiki/BR6104, so I won't cover this here. It's best to simply purchase a level shifter from your nearest mobile phone/set top box hacking store. In the UK try http://jabsplace.co.uk. I don't recommend the guy 100% since he doesn't respond very quickly to queries, but he does send the goods.

Installing VMWare

Grab the emulation software from http://www.vmware.com. You will need to get a registration key. I won't cover installation here, please refer to the instructions at the site, there is plenty of documentation there. VMWare installs cleanly on any of the supported platforms (many versions of Windows, and quite a few versions of Linux too). If you are trying to run VMWare itself on Slackware you can make it work, but this is not for beginners. Please chose a supported platform, or take a detour and read someone else's guide!

Obtaining the Slackware DVD

You will need to download a rather large DVD image called slackware-12.0-install-dvd.iso (It's almost 4GB!), hopefully that won't be much trouble for most people. There is no need to burn it to a DVD or anything, we will make vmware use it directly. It can be found at some of the slackware mirrors at http://www.slackware.org/getslack/ - be careful because not all sites carry DVD images. One site which does is the Finnish mirror: ftp://elektroni.phys.tut.fi/slackware-12.0-iso.

Create a virtual machine

In the vmware menu, create a new machine, with 'typical configuration'. When prompted for the operating system chose 'Linux' and then 'Other Linux 2.6.x kernel'. In the next dialog give it the name 'slackware' or 'openwrt' or something. Then in the following dialog select 'bridged networking'. Subsequently, the default 8GB should be more than enough space, however uncheck the 'allocate all disk space now' option if you're a bit low on disk space. It won't make too much difference to VMWare's performance.

Configure the virtual machine

Having created the virtual machine you will need to point it at the downloaded DVD image, otherwise it won't boot. Go into the settings for the virtual machine (VM->Settings) and select the CD-ROM drive. Select 'Use ISO image' and browse to the DVD image you previously downloaded.

Powering on and installing Slackware

Now it's time to power on the virtual machine. You should see a BIOS screen followed by the slackware boot prompt. You can just hit ENTER here because the default kernel is fine for running under VMWare. You can then sit back and follow the flash of the Slackware install: Slackware configuration (1). There follows a fairly lengthy period where the installer is installing packages, which has been cut.

Following the installation of the packages, there's some extra per-package configuration that needs to be done: Slackware configuration (2). My network has an ADSL router, so I've chosen DHCP network configuration. If you want to give your virtual machine a static address, you'll need to use your imagination, but it shouldn't be too hard.

First boot and initial configuration

OpenWrt quite rightly refuses to run as root, so on the first boot we create a user to run the compile, and log in as that user: First boot.

Obtaining and configuring OpenWrt

I've configured the i2c modules, USB and a jffs so you can store stuff across reboots. I've removed PPP and some other network functions. This configuration is more suited to hobbyist electronics and home automation than routing: Extract from SVN and configure. Once you've got it working, re-configure to taste.

Compiling OpenWrt

Nothing much to see here: Compiling.

Adding a serial port to VMWare

Power off the virtual machine (from within the virtual machine, not from the vmware menu!), by typing (as root) 'poweroff'. Go to vmware settings and add a serial port, assuming you have one on your host machine. If you're lucky enough to have a 'real' serial port, you can skip the next paragraph.

In my case I have a USB->Serial converter, so I must add a USB host controller instead. It's necessary to explicitly connect any USB devices from the 'VM' menu, which is the 'virtual' equivalent of plugging the device in, at which point the hotplug system running inside Slackware should kick in and detect the device. The converter should appear as device /dev/tts/USB0 inside the virtual machine, so anywhere you see /dev/ttyS0 in the following documentation please substitute /dev/tts/USB0. I recommend inserting the converter into your physical USB port after the virtual machine has powered up. I believe this avoids the host machine taking control of the device.

Obtaining the firmware upload utility

You need to obtain pexpect and adm_upload.py. I will make slackware packages for these at some point, but for now you can download them using the Lynx web browser. It's a text-based browser (we didn't install X windows in Slackware, remember!). You use the up and down arrows to select links, then press enter to follow them. Left-arrow goes back, 'q' quits. Here's the video: adm_upload.

Uploading via xmodem

Uploading requires access to the serial port, and must be done as root, so use the 'su' command to become root. I've cut the rather long and tedious upload sequence down to just a few seconds for brevity. Note the device name given to adm_upload.py - it will vary depending on whether or not you have a real serial port - for real ports use /dev/ttyS0, for USB converters use /dev/tts/USB0. Here is the Xmodem movie

That's All...

So that concludes the introduction. I will create future guides covering use of the i2c ports to do something useful (you will need to desolder the LEDs to make the relevant connections) in further guides.