Friday, January 31, 2014

OpenWRT for WEMO - Part 3 - Cross compilation and remote debug with Eclipse

Being able to compile and remotely debug applications on the WEMO is very useful in creating custom applications for remotely switching the power, or adding functionality to the WEMO. For remote debugging the WEMO must be connected to the wifi network that the cross compilation machine is on and the machine must be able to ssh into the WEMO. 

Here are some example settings to get the WEMO connected to a typical WPA-PSK wifi network. These settings can be modified over the serial terminal.
  • Edit /etc/config/network with vi and comment every line with # then add the follwing.
    config interface 'lan'
        option ifname 'wlan0'
        option proto 'dhcp'
        option hostname 'WEMO'

  • Edit /etc/config/wireless with vi and change it to the following, note change the SSID and password to that of your Wifi network.

    config wifi-iface
        option device 'radio0'
        option network 'lan'
        option mode 'sta'
        option ssid 'SSID'
        option encryption 'psk2'
        option key 'password'

  • Reboot the router and check over the serial terminal that the wlan0 interface has been assigned an ip address.

Using the custom compiled firmware from part 1 the required packages for remote debugging will be installed. If using the base image use the following command to install the required packages.  
opkg update
opkg install gdb-server openssh-sftp-server

The following steps setup Eclipse to cross compile a simple c project.

  1. Start Eclipse and navigate to "Help" menu and select "Install New Software...". In the install wizard select "--All Available Sites--" from the drop down menu next to "Work with:" at the top. This will load all available software packages that can be install in Eclipse and will take while.
  2. If your version of eclipse does not have CDT installed use the guide here to install it. Navigate to the "Mobile and Device Development" in the tree view and select "C/C++ GCC Cross Compiler Support", "Remote System Explorer End-User Runtime", and "C/C++ Remote Launch" as shown below.

    Click "Next >"  and follow the prompts in the wizard to install the packages. Eclipse may need to restart afterwards.
  3. In this example we will be creating a "C Project" that will cross compile C code only. Select "File" then "New" and finally "Project..." to bring up the "New Project" wizard. Choose the "C/C++" option in the tree view and then select "C Project" as shown below.

    Click "Next >" to proceed.
  4.  Select an "Empty Project" from "Executable" under "Project type:" and "Cross GCC" under "Toolchians:" as shown below.

    Choose a name for the project and enter it at the top then click "Next >" to proceed.
  5. In the final stage of the wizard (the "Finnish button" shown appear) click the "Advanced Settings" button. This will bring up a dialogue to edit the project settings, which can be accessed by right clicking on the project and selecting "Properties". The next steps deal with this dialogue and show the parameters that need to be added to configure the cross compiler.
  6. The staging directory in the openwrt folder contains the cross compiler and gdb for remote debugging. The first step is to configure the cross compiler, and this is under "C/C++ Build" then "Settings" on the left. Choose "Cross Settings" as shown in the image below.

    The toolchains directory depends on the architecture and gcc version. Locate the toolchain directory by looking in the staging directory of openwrt and set it to the path. The prefix is an appended string for the cross compilation tools such as gcc, this can be found by looking in the bin directory of the toolchain. Note all directories must be absolute and directories like "~/openwrt/..." will not work.
  7. The include directories can be specified to enable better code completion by selecting Includes as shown in the image below.

    Select the add button (upper right in the image) and locate the include directory in the toolchain directory.
  8. An environment variable "STAGING_DIR" is required by the cross compiler and can be set by navigating to "C/C++ Build" then "Environment" on the left as shown below.

    To add the environment variable click the "Add" and set the name as "STAGING_DIR" and the value as the path to the OpenWRT staging directory.
  9. Finnaly click "OK" to save the project settings and finally "Finish" to create the project.
  10. To test the cross compiler create a "main.c" file in the project by right clicking the project and selecting "New" then "File". Use the following code as a simple hello world.

    int main()
        printf("hello world\r\n");
        return 0;

  11. Save the main.c file then right click the project and select build. The output of the build (in the "Console" tab down the bottom) show a successful build, for example:

    **** Build of configuration Debug for project hello_world ****

    make all
    Building file: ../main.c
    Invoking: Cross GCC Compiler
    mipsel-openwrt-linux-gcc -I/home/sean/openwrt/openwrt/staging_dir/toolchain-mipsel_24kec+dsp_gcc-4.6-linaro_uClibc- -O0 -g3 -Wall -c -fmessage-length=0 -MMD -MP -MF"main.d" -MT"main.d" -o "main.o" "../main.c"
    Finished building: ../main.c

    Building target: hello_world
    Invoking: Cross GCC Linker
    mipsel-openwrt-linux-gcc  -o "hello_world"  ./main.o  
    Finished building target: hello_world

    **** Build Finished ****

    If there are any problems with the build, check to ensure the paths to the tools are correct. If the path to the build tools requires changing then change the "PATH" environment variable, as changing the setting in step 6 will not update the environment variable.
To remotely debug a cross compiled project use the steps below.
  1. Ensure the "main.c" file in cross compiled project is selected in the "Project Explorer" then open the debug configuration by clicking the arrow next to the debug button and then selection "Debug Configurations..." as shown below.

    This will open the Debug configuration dialouge.
  2. Create a new "C/C++ Remote Application" configuration by clicking the button shown in the image below.

    This will create a new debug configuration in the left pane.
  3. Set the "Remote Absolute File Path for C/C++ Application:" to a simple path such as /tmp/hello_world. It is better to use the tmp directory as it resides in ram making upload faster and decreases wear on the flash.
  4. Click the "New..." button next to the combo box for "Connection:" to add a connection to the WEMO. Select a "Linux" connection in the wizard as shown below, then click "Next".

  5. Give the the IP address of the WEMO on your WiFi network for the "Host Name:", and optionally a friendly "Connection name:" as shown below.

    Do not click "Finnish", instead click "Next".
  6. Select "ssh.files" from the "Configuration" check list as shown below.

    Proceed by clicking "Next".
  7. Select "" as shown below then click "Next".

  8. Select "ssh.shells" as shown below then "Finish" to complete the wizard.

    This creates a new option in the combo box next to "Connection:" for the WEMO in the debug configuration.
  9. Select the newly created connection from the "Connection:" comb box. Select "Enable auto build" to enable building before debugging.
  10. Navigate to the Debugger tab (at the top), click "Browse..." next to the "GDB debugger" option and select the cross compiled GDB debugger in the toolchains bin dierctory. The GDB debugger is cross compiled as a part of the toolchain, and is located in the bin folder of the toolchain directory used earlier. The GDB executable is prefixed like all the other tools.
  11. Click the "Debug" button in the right hand corner to intiate a remote debug session. A prompt for the ssh login will appear if the connection is successful. After logging in the executable will be uploaded and debugging session started. The program should stop on a break point on the first line of code.
The console tab provides access to the remote shell session but must be selected by clicking the arrow next to the console button and selecting the remote shell option as shown below.

If you step through the hello world program, hello world will appear in this console.

If an "Error during file upload" occurs this can mean an existing debug session has not terminated correctly. This requires the termination of the gdbserver process, which can be done in the "Remote Systems" tab. To enable the "Remote Systems" tab, open the "Window" menu and select "Show View" then "Other...". In the dialogue use the search button to find the "Remote Systems" tab. The gbdserver process can be terminated by selecting the connection to the WEMO in the "Remote Systems" tab, then selecting processes. Find the gdbserver process in the treeview, right click, and select "Kill..." as shown below.

That completes a guide to cross compiling and remote debugging in eclipse. Next I will show how to interface with the gpio pins to switch the relay in the WEMO.

OpenWRT for WEMO - Part 2 - Flashing Firmware

So the WEMO arrived, and the first thing I did was set it up with my iPhone. After checking it worked I voided the warranty to attach serial lines. The serial port is used to issue commands to flash firmware onto the WEMO and requires soldiering onto the board. There are pads for RX and TX, but the pad for ground proved tricky to heat sufficiently so I used the ground pin of the header in fear of damaging the board. There is also conveniently placed via to put the ground wire through, I refrained from soldering to the via for the same reason as the ground pad.

The location of the pads and various other information about the hardware can be found here and here. I attached the ground, rx, and tx to Sparkfun FTDI XBee explorer to give access to the serial terminal. Powering on the WEMO gave a very verbose boot log.

The flash memory partitioning on the WEMO can be determined from the boot messages.

Creating 10 MTD partitions on "raspi":
0x00000000-0x00050000 : "uboot"
0x00050000-0x007c0000 : "A - Kernel and Rootfs"
0x00150000-0x007c0000 : "A - Rootfs"
0x007c0000-0x00f30000 : "B - Kernel and Rootfs"
0x008c0000-0x00f30000 : "B - Rootfs"
0x00fe0000-0x00ff0000 : "Nvram"
0x00ff0000-0x01000000 : "User_Factory"
0x00040000-0x00050000 : "Factory"
0x00f30000-0x00fd0000 : "Belkin_settings"
0x00030000-0x00040000 : "Uboot_env"

The stock firmware allows for updating from Belkin, so to increase reliability there are actually 2 firmware images stored in flash. From the partitions above you can see where they reside in flash. Uboot uses the environment variables "bootstate" and "check_boot" for switching between which images to boot from (more info can be found on the OpenWRT site).

When I first uploaded the firmware onto the WEMO I assumed that OpenWRT would either override this or nicely work with their redundancy scheme. Unfortunately it didn't quite work out because the partitions OpenWRT expected to see weren't there as it was put into the "B - Kerenel and Rootfs" partition.

Using the fwupgrade tool in the stock firmware I flashed my compiled firmware image in, but at boot it would not mount the rootfs partition. Setting the uboot "bootarg" variable with different mtdblock numbers did not remedy the situation. So I booted back into the stock firmware (changed "bootstate" to 0) and dd'ed the stock firmware to overwrite openwrt using:

dd if=/dev/mtdblock1 of=/dev/mtdblock3
This overwrites the kernel and rootfs. The intial state of the flash memory appears to have identical contents of a and b firmware partitions. To flash the OpenWRT firmware requires that a stock firmware version of less than WeMo_WW_2.00.2176.PVT. To find the firmware version use this command in the serial terminal

cat /etc/ver.txt

The contents of my ver.txt is:

02/19/2012 06:35:50 AM

If you have an upgraded WEMO it may be possible to still boot into the stock firmware, you can check if the stock firmware is in the b partition by using step 4 and 5 below.

To write the OpenWRT firmware to the WEMO use the following steps:

  1. Ensure the WEMO is connected to your WIFI network by setting it up, DO NOT UPGRADE THE FIRMWARE if prompted.

  2. This step is optional - if you want to used a custom compiled image. Install apache or any other web server. This is needed to download the firmware image. Place the compiled firmware image in the in root web server directory and ensure it is accessible.

  3. Open a terminal for the serial port, I used PuTTy, the buad rate is 57600.
  4. While in the terminal hold down "4" and then boot the WEMO, uboot only has a 1 second wait time.
  5. In the uboot command line set it to boot from the b firmware image using:
    set bootstate 2
    set boot_check 0
    set bootargs 'console=ttys1,57600n root=/dev/mtdblock4'
    After the boot command the WEMO will reboot into the stock firmware image from the b firmware partition.
  6. Wait for about 10 seconds for a prompt, the serial terminal is the default output for some of the log messages so messages will appear sporadically. To stop these log messages use:

    killall sh
    killall wemoAPP

    This kills the Belkin applications that enable remote switching and log to the serial port.
  7. Now we can download the firmware image into the tmp (this is for a firmware image from, change the url accordingly):

    cd /tmp

    The tmp directory resides in RAM, all other directories are in flash so the image will not fit. I have given the URL to the trunk snapshot on, if you are using a custom image give the url to webserver that has the image.
  8. The image is now in the tmp directory and it can be flashed using:

    fwupgrade openwrt-ramips-rt305x-belkinf7c027-squashfs-sysupgrade.bin
  9. Reboot the router using the "reboot" command and then hold "4" to enter the uboot command menu. The "bootstate" and "boot_check" variable need to be set in order to prevent uboot reverting back to the stock firmware.
    set bootstate 0 
    set boot_check 0

    The WEMO will now reboot and hopefully boot into OpenWRT. The nice thing is that the stock firmware can be reverted to by changing the boot variables using step 5.
In the next part I will show how to use Eclipse to compile and remotely debug software for the WEMO using the toolchain compiled in part 1.

Thursday, January 30, 2014

OpenWRT for WEMO - Part 1 - Compiling firmware

While waiting for a Belkin WEMO to arrive in the mail, I decided to at least get the firmware and development tools ready for its arrival. The Belkin WEMO is a power socket switch that can be turned on and off via the internet. It runs an embedded form of linux, with 16 Mb of storage and 32 Mb of ram. The embedded processor it uses (RT5350F) is part of the ralink mips embedded processor line for networking devices such as routers. OpenWRT is embedded linux for routers and many ARM and MIPS based devices. The ralink MIPS processor is supported by OpenWRT, so I will show how to install OpenWRT on the router and develop software for it.  This will enable development of custom applications to run on the device for switching appliances not restricted to Belkins proprietary software. Alternatively you could use the uPnP protocol with the stock firmware to control the unit (here), but that's a messy solution that requires a computer!

There are some prerequisites for putting OpenWRT on the WEMO, which are:

  • You must have Linux, preferably Ubuntu
  • The WEMO must be running stock firmware (pre 2.00.2176), due to an exploit Belkin locked access to the device (see here).

The following steps show how to create the toolchain for cross compilation, create tools for remote debugging, and create the firmware image for the WEMO.

  1. Install the latest build tools for linux.

    sudo apt-get install subversion build-essential libncurses5-dev
    sudo apt-get install git-core python2.7-dev
  2. Checkout the latest OpenWRT.
    mkdir ~/openwrt
    cd ~/openwrt
    git clone git://
  3. Update and download the feeds, the feeds are source code for building packages to install in the firmware image.

    cd ~/openwrt/openwrt
    ./scripts/feeds update -a
    ./scripts/feeds install -a
  4. Start the menu configuration for OpenWRT, this will check for dependencies required for cross compilation.

    make menuconfig
  5. The menu configuration configures which cross compilation tools are to be compiled for creating a firmware image for a specific platform. For the Belking WEMO select the Target System as "Ralink RT288x/RT3xxx" and select the Subtarget as "RT3x5x/RT5350 based boards"
  6. This step enables options to build a toolchain for cross compiling and tools for remote debugging in eclipse (tutorial how to do this here). To build a toolchain and remote debugging tools select the following options:
    • Enable "Advanced configuration options (for developers)" (press space  bar), and from this menu (press enter to open once enabled) select "Toolchain Options --->" and ensure "Build gdb (NEW)" is enabled.
    • Back in the main menu, enable "Build the OpenWRT based Toolchain"
    • Select the "Development --->" menu and enable the "gdbserver" option, To select the option press space bar twice until an * appears next to the option, when M appears next to an option the package will be built but not installed in the firmware image.
    • Back to the main menu, then select "Network --->", "SSH --->" and enable the package "openssh-sftp-server"
    These options will allow for compilation and remote debugging using Eclipse, guide will be [here]
  7. Exit menu configuration and when prompted save the configuration.
  8. Begin the build processing with:
    This can take several hours, if there are problems use the option V=99 to get a more verbrose output. 

This completes the build of the firmware image, which can be found in:


The next step (here) is to connect serial lines to the Wemo, prepare the uboot environment, and finally flash the firmware image.