Tinkering with OpenWrt

Introduction

You probably already have wireless router at home. Typically, it will be running software specific to the vendor but this tends to limit the ability of its hardware. Fortunately, you have the option on some routers to change its firmware. Instead of modifying my home wifi router, I ended up buying a ASUS WL-520gU for the purpose of my robotics experiments. Why did I decide on getting this model? Well, it is OpenWrt compatible, reasonably compact, has a UART, and importantly has a USB port. This page describes some of the experiments I've carried out on my ASUS WL-520gU (running OpenWrt). Note that the WL-520gU has been discontinued by ASUS, but you can still find places that stock them.

Setting up OpenWrt

Before you begin, it would be wise to check if there is support for your router (see the OpenWrt supported devices page). Even if there is OpenWrt support, it is also a good idea to check if there is support for your particular needs. For instance, with the WL-520gU, a slightly limitation is that OpenWrt firmware does not properly with the 2.6 kernel. This limited the list of supported USB devices that I could use, namely webcameras.

It is common with open-source projects (such as OpenWrt) for you to compile software from source. This can be off-putting and daunting, particularly for non-savvy Linux users. Fortunately, if your router model is popular with other OpenWrt enthusiasts, odds are you can download a pre-built image. If you also have a WL-520gU, you are in luck! Head over to the MightyOhm blog and follow the fantastic Wifi radio project write-up.

Customisation

After you've got OpenWrt running on your router, I suggest you download and install the following packages: kmod-usb-core, kmod-usb-ohci, kmod-video-core (to install a package, type 'opkg install XX', where XX is the name of the package(s)). If you require more than one serial port, you might also want to install kmod-usb-serial and kmod-usb-serial-ftdi packages so you can use USB to UART bridge devices.

Another useful thing to have on your router is dropbear. After installing it, you can then get a terminal via ssh. To do so, get a terminal via the router's serial port, and run 'opkg install dropbear'. Following that, setup the root password (on a terminal from the router, type 'passwd', then set the password). You should now be good to log onto your router via ssh. In Windows, you could use teraterm (then New connection -> TCP/IP, enter in your router's IP). In Linux, run 'ssh XX', where XX is your router's IP.

It might also be useful to know that after installing dropbear you can now copy files via wifi, using scp. An example of using secure copy is 'scp file-to-copy root@XX:~/', which transfers file-to-copy to the home directory (i.e., ~/) of the root account of the router at the IP of XX.

During customisation you'll probably have to modify configuration files on the router using the basic editor vi. If you haven't used this before, essentially it has two modes: edit and command. When you edit a file, i.e., run 'vi file', it starts up in command mode. To change to edit mode, type 'i' first, then begin editing. To get out of edit mode, press the escape key. Useful commands when in command mode are: ':q' (quit), ':w' (write), and ':wq' (write and quit).

Wireless video

I wanted to add computer vision (CV) capabilities to my robotics projects. However, anything CV more sophisticated than blob finding tends to require laptop/PC computing power to run in real-time. Since the target robot of mine is small, it would have been expensive to buy a small form factor PC. Instead, I decided to stream the robot's video feed to a host computer to run the computationally demanding algorithms.

The main challenge of getting this to work on the WL-520gU was finding a suitable webcamera and driver (and compatible video server). In the end, I got a Logitech QuickCam Communicate STX (vendor ID: 0X046D, product ID: 0x08AD). Note that this is the matte black coloured with a blue LED one; I also tried the newer one (grey with lens cap), but it did not work. As for the driver, which needs to be taken into consideration at the same time when looking at webcams, I used the spca5xx driver and the spcaserv video server

Once you have sourced a suitable webcamera and put on OpenWrt firmware (follow the Wifi radio project tutorial) on your WL-520gU, you'll need to download and install the spca5xx webcamera driver and a video server. If you have got a WL-520gU running (I think this will also work for a WL-500g), transfer to the router: the driver (to /lib/modules/2.4.35.4/) and the video server (to /usr/bin/).

Insert the driver module into the kernel (run 'insmod /lib/modules/2.4.35.4/spca5xx.o'), plug in your webcam. Hopefully your driver and webcam are now working together happily. To test this, read through the kernel messages (run 'dmesg', or to see the last few, run 'dmesg | tail'). My router prints out:

...
usb.c: registered new driver spca5xx
spca_core.c: spca5xx driver 00.57.08LE registered
hub.c: new USB device 00:03.0-1, assigned address 2
spca_core.c: USB SPCA5XX camera found. Logitech QC Communicate STX

Provided that your driver and webcam are working, proceed to testing out the video server. If you encouter errors when inserting the driver, perhaps there are some dependencies that your router lacks? In that case, track down and install those packages. On my router, the webcamera appears under /dev/v4l/video. I wanted it to appear as /dev/video0, so I made a symlink to fix this (run 'ln -s /dev/v4l/video0 /dev/video0'). Then start the video server: '/usr/bin/spcaserv -d /dev/video0 -f jpg -s 320x240 &'. Note that the ampersand at the end which puts the task in the background (and returns you your terminal!). Finally, view the video from your router's webcam remotely on your PC. Use the spcaview program, which you can find versions that run on both Windows and Linux. I have also made a custom Player plugin to have the video accessible within the The Player Project (a popular open-source robotics framework).

Note that if you have followed the Wifi radio writeup and also tried to get USB audio going, you could encouter some issues with the streamed video image. For me, I found that having the kmod-usb-audio module on my router at the same time messed up the video frames that I got from my router. Uninstalling it seemed to fix the problem, and I did not need audio anyway.

Remote serial port

Having access to a serial port on the router is quite useful for robotics. This is because with some software, you can have a nice wireless serial port setup. In my robotics projects, I typically have the router's serial port connected to a microcontroller that interfaces to low level hardware (motors, LEDs, buttons, sensors, etc). This leads to a cost-effective telerobotics setup.

Prior to using the WL-520gU's serial port for communication with another device, you need to free it from being used as a terminal. First, make sure you can get a terminal via ssh. This is important! Next, I followed the steps of Wifi radio writeup. In essence, edit /etc.inittab and comment out the lines containing 'ttys/0' and 'ttyS0'. Next, edit /etc/sysctl.conf and add the line 'kernel.sysrq = 0'. Save and reboot your router. Confirm that you've freed up the serial port - it will still send out the initial boot messages, but it will no longer act as a command shell. Login to the router via ssh, and try sending out something from the serial port by setting up the port 'stty 9600 -echo < /dev/tts/0' and then running 'echo "Hello World!\n" > /dev/tts/0'.

After you have confirmed that you're serial port is not being used by another application, install ser2net. This is a reasonably common program, and you can install it on your router via opkg. Edit the ser2net configuration file, which is likely found at /etc/ser2net.conf. It comes with a lot of example configurations. The one I used was '2000:raw:600:/dev/tts/0:115200 NONE 1STOPBIT 8DATABITS XONXOFF LOCAL -RTSCTS', which makes the router's internal serial port (/dev/tts/0) accessible on port 2000 and sets it up with a baud rate of 115200 and standard configurations.

A simple test to check if things are working is to hook up a USB-UART adapter to the router's serial port and startup a serial port program. On Linux, also fire up netcat (run 'nc XX YY', where XX is the IP of the router, and YY is the port you assigned to ser2net). Try sending commands from the serial port program and see if they come up in netcat. Make sure you also try the other way around! If you want to send and receive data from your router's serial port in a cleaner manner, you'll need to write a program that makes use of TCP/UDP sockets. An example on how to do this: linux_remote_serial.zip

Startup scripts

It would be annoying having to manually setup programs that you want to run each time you rebooted your router. Instead write a startup script. I did this when setting up wireless video on my router, so let's use this as an example. Refer to this handy link pertaining to startup scripts on OpenWrt.

In order to get wireless video automatically initialised when the router reboots, create a file called webcamera in /etc/init.d/. Add the following to this file you have just created: 

#!/bin/sh /etc/rc.common
# Webcamera initialisation script
# Robert Tang
# 10/6/09
START=41
start() {
        echo start
        #insert spca5xx module into kernel
        insmod /lib/modules/2.4.35.4/spca5xx.o
        #create simulink to deal with different webcamera path
        ln -s /dev/v4l/video0 /dev/video0
        /home/scripts/webcamera-start.sh &

#!/bin/sh /etc/rc.common
# Webcamera initialisation script
START=41
start() {
    echo start
    #insert spca5xx module into kernel
    insmod /lib/modules/2.4.35.4/spca5xx.o
    #create simulink to deal with different webcamera path
    ln -s /dev/v4l/video0 /dev/video0
    #start spcaserv
    /usr/bin/spcaserv -d /dev/video0 -f jpg -s 320x240 &
}

Save the file, and change its permissions by running 'chmod ugo+x webcamera'. Next, enable the script by running '/etc/init.d/webcamera enable'. Confirm it has been enabled by checking if there is now a symlink to it in /etc/rc.d/. If so, reboot the router and hopefully you will now have wireless video automatically setup!

Share |