"Boomerang 1.0" Home Automation Board
for NSLU2

This electronic board is intended to be connected to a Linksys NSLU2. The NSLU2(also known as "slug") is an NAS (Network Attached Storage) device. The NSLU2 embeds an unused TTL serial port and an I2C bus it uses to communicate with its RTC(Real Time Clock). The Boomerang 1.0 board uses them to provide additional functionalities. This association of devices already permits me to control several electrical devices remotely, either manually or in an automated way. Everything but the 1-wire has been working successfully for months at home. This doesn't mean I can certify that the hardware and software described below is guaranteed as free of defects. The informations and downloads following are provided "as is" for those who'd like to build, use, and improve their own board. Documentation needs a lot of time to be written. I'll try to improve it as often as possible. Many thanks to those who provide free open-source software and documentation. Documentation, tips, and add-ons for the NSLU2 I have used to design this board can be found on the excellent web site: http://www.nslu2-linux.org

Hardware

--> Synoptic

The I2C bus drives four PCF8574 chips to control an HD44780-based LCD display, 8 opto-isolated triac switches, and 16 additional I/Os.

The serial port is made available through a TTL to RS232 adapter, or is used to control a 1-wire port(not working yet).

Finally, as the NSLU2 embeds 3 fully functional but not wired USB ports, the Boomerang board provides a double USB socket and pads for a quick wiring of 2 of these ports.



--> Diagram, PCB

The Boomerang 1.0 board has been designed with the excellent, open-source, and free software Kicad. It has been designed to be easily build: single-sided printed circuit board(PCB), widespread components.
Download the Diagram
Download the PCB



--> I2C

Connection to the embedded I2C bus of the NSLU2 is made directly on the RTC X1205 chip. The red wire is SDA the other SCL. The wires come from an IDE cable. It's held with a thin wire soldered between two ground pads.

The I2C addresses used by the 4 PCF8574 are the following:

0x20 : LCD display
0x21 : Triac switches
0x22 : I/O port 1
0x23 : I/O port 2

Software



--> LCD display

The LCD display is a HD44780 chip based. The wiring is made easier as the 16 pins on the display are in the same order as on the Boomerang board. Do check with the diagram if yours is identical. Pins 7 to 10 are unused. Backlight is controled by pins 15 and 16. Some displays without backlight haven't these pins. Adjust brightness with RV1.

Software



--> Switches

Triac switches are driven and isolated from the mains using MOC3043. On power up, all switches are OFF. Each switch sucks 5mA. If you reboot the NSLU2 without putting OFF the Boomerang board, the swiches state doesn't change.

Wiring on the mains side is made simple using a row of 9 terminal blocks and pieces of copper wire directly soldered on the PCB. Triacs are protected with fuses. No coolers on triacs are needed for small current sucking devices (<1A) such as routers, light bulbs, external hard disks. But if you intend to drain more current from the triacs (for a water heater or radiators etc..) you'll have to put coolers on triacs or use relays

Software



--> Serial port

The NSLU2 serial port is located between the battery and the flash memory. In addition to the data lines, two pins bring ground and 3.3V. An audio connector from a motherboard or a sound card perfectly fits. Never leave open-ended wires on the NSLU2 data lines as they will act as an aerial and might perturb the boot of the NSLU2. A resistor and a zener protect the TTL serial input on the NSLU2 from receiving more than 3.3V. This link, once connected to the Boomerang board, can be used as a 1-Wire port or as RS232 by setting up JP1 and JP2 jumpers simultaneously. Do poweroff the NSLU2 and the Boomerang board before any action on the jumpers



--> RS232

RS232 serial line adapter can be a MAX3232(3,3V expensive) or a MAX232(5V much cheaper). I had a problem with the latter and terminal emulation softwares. With both Linux Minicom and Windows HyperTerminal it is better to run your terminal emulation software after powering up the NSLU2 to get round this problem. You must setup the appropriate voltage for the MAX you use with JP3 before supplying the board with power.



--> 1-Wire(not working yet!)

The 1-wire port uses a dedicated chip DS2480B. ESD protection is due to the recommended DS9503 but as i didn't find any yet at my retailer's, i have added pads for a 7,5V zener diode and a Schottky diode in replacement for the DS9503.

Software



--> Power Supply

The Boomerang board is power supplied from the 5V of the NSLU2. The 3,3V from the NSLU2 is used for the optionnal pull-up resistors R31 and R32 of the I2C bus and for the MAX3232 in case you decide to use it instead of the MAX232. It is highly recommended to insert a fuse or a fusible resistor in the +5V wire between the NSLU2 and the Boomerang board. The advantage of the resistor (0.1 ohm is a good choice) is to permit the measuring of the current sucked by the Boomerang. Be careful not to overload the USBs as the NSLU2 power supply is given for 2A max.



--> Autostart

I've added a digital transistor DTC124 in order to force power always on. Soldered directly on U15(74HC74, pin 1 and 4) and the ground. Other means are described on the nslu2-linux.org web site, see http://www.nslu2-linux.org/wiki/HowTo/ForcePowerAlwaysOn. My solution is a simplified version of the alternative 11 which uses an ordinary NPN transistor and a 10k resistor. Use of a DTC124 digital transistor simplifies the wiring.



--> Extra USBs

In order to use the extra USB ports you need to solder wires on SMD resistors. Again, a piece of wire soldered on the ground on the edge of the board will help maintaining the wires. As for the I2C, the wires I used come from an IDE cable. Red wires are for D+, others for D-. On the Boomerang, wires are connected using DEL connectors from a junk motherboard.

Software



--> Useful Links

http://www.nslu2-linux.org/wiki/HowTo/AddASerialPort
http://www.nslu2-linux.org/wiki/HowTo/EnableExtraUSBPorts
http://www.nslu2-linux.org/wiki/HowTo/AddATextDisplayOnI2CWithLCDproc
http://www.nslu2-linux.org/wiki/HowTo/ForcePowerAlwaysOn



Firmware

As the original firmware of the NSLU2 is GNU/Linux based, it can be easily adapted to fulfil the board needs. Different firmwares can run on the NSLU2. One of them is "OpenWRT". It's the one I've chosen in order to control the Boomerang board.

--> Install OpenWRT:

If your NSLU2 comes with the original Linksys firmware, the first installation can be made using the web interface. The latest stable firmware from "OpenWRT" is this one:
http://downloads.openwrt.org/backfire/10.03/ixp4xx/openwrt-nslu2-squashfs.bin
After downloading:

  • Shutdown your slug
  • Remove all USB devices
  • Boot it
  • Login to its Web Configuration Interface
  • Click on "Administration", "Upgrade"
  • Browse for the correct file, and Start Upgrade
  • While waiting, read the following...

OpenWRT's firmware is a very small firmware. It occupies only a part of the flash memory. The remaining flash memory is available in read-write mode for adding and updating software. After flashing, the slug reboots and during the first boot it formats this area of memory. It can take a few minutes. Be very patient. Once done, it mounts this read-write flash memory on "/overlay" which is itself mounted over "/".

At the end of this first boot:

  • The NSLU2's IP address is now 192.168.1.1 whatever it was before.
    If your DSL Box or your router use this address, change it immediately.
  • The LEDs' behaviour has changed: only the Ethernet LED is lit(if the Ethernet cable is plugged in).
    Even if you connect an USB storage device, DISK LEDs will remain off.
  • The power button is inactive.

Configuration

--> Configuration tools:

If you're not familiar with command line interface, use the Web interface: "LuCI". Open in your Internet browser:
http://192.168.1.1
Login without password. It has to be defined. Click on the right: "Administration" to get more detailed options in left menus.

Another web interface is available and can be installed: "webif". I use this one because the crontab editor is much more friendly than LuCI's and there is an embedded file editor. Additionaly it uses "haserl" which is needed by the switches control web interface I made.

The commande line interface is available with 

telnet 192.168.1.1
or with a terminal or a terminal software using the serial port(115200,8,N,1)

An editor, "vi", is installed so you can edit all configuration files. To someone unused to it, "vi" can be disconcerting. Other editors are availables and can be installed. Among them: "nano", "mc". These editors take some 200k bytes in flash memory for nano and more than 500k bytes for mc, which is far more than a simple editor.

--> Password:

First thing to do is to set the super-user(root)'s password:
  • Web : System > Admin Password
With a terminal:
telnet 192.168.1.1
then :
passwd
Type twice the same password and remember it

This achieved, you have to access to the NSLU2 with "ssh", which is much safer than telnet:
ssh -l root 192.168.1.1

--> Hostname and Timezone:

  • Web : System > System
  • fichier : /etc/config/system
Here you choose the name and the timezone for the slug itself.

--> Network:

  • Web : Network > Interfaces > Lan
  • file : /etc/config/network
Unless you know very well what you are doing, it's better to use the Web interface than to edit the config file. If you don't choose to use DHCP, it is mandatory to setup a gateway and a valid DNS in order to install softwares easily. The file might look like this: 
# do not modify
config 'interface' 'loopback'
	option 'ifname' 'lo'
	option 'proto' 'static'
	option 'ipaddr' '127.0.0.1'
	option 'netmask' '255.0.0.0'

# network interface configuration
config 'interface' 'lan'
	option 'ifname' 'eth0'
	option 'type' 'bridge'
	option 'proto' 'static'
	option 'netmask' '255.255.255.0'
	option 'ipaddr' '192.168.1.77'
	option 'defaultroute' '0'
	option 'peerdns' '0'
	option 'gateway' '192.168.1.254'
	option 'dns' '212.27.40.240'

--> Hostnames:

  • Web : Network > Hostnames
  • fichier : /etc/config/dhcp
Here you choose the name and the IP addresses for known hosts or machines on your network.
It is recommended to set at least the hostname and the IP address for the NSLU2. If you intend to use Samba, in particular.
NSLU2, 192.168.1.77, in this case. 
# extract from /etc/config/dhcp
config 'domain'
	option 'name' 'NSLU2'
	option 'ip' '192.168.1.77'
Add similar sections for each known host.



--> Reboot:

  • Web : System > Reboot
Once having made the first settings, it is recommended to reboot:
reboot
After reboot, if you have changed the IP address of the NSLU2, you'll need to open:
http://192.168.1.77
in your browser or:
ssh -l root 192.168.1.77
in a terminal.

Install/Remove Software, Drivers, Modules

Out of the box, OpenWRT doesn't include much drivers and softwares. Fortunately it's very customizable. Installing and uninstalling software can be done through the Web interface or with a command line tool: "opkg". Softwares are downloaded as packages from the Internet and installed automatically by opkg. So you have to configure the network connection first. Don't forget to setup a DNS and a gateway if you don't use DHCP. Softwares may need one or more packages. Packages with names starting by "kmod-" are kernel modules(drivers).

- Web interface:

  • Web : System > Software
Click on "Update package lists" to download or refresh the available softwares'list. To have menus in other languages, install one of the following packages: 
luci-i18n-french
luci-i18n-german
luci-i18n-greek
luci-i18n-italian
luci-i18n-japanese
luci-i18n-portuguese_brazilian
luci-i18n-russian.

- Command lines:

# before every packages installation,
# refresh the available softwares'list:
opkg update

# install a package:
opkg install package_name

# remove a package:
opkg remove package_name

# remove a package and orphaned dependancies:
opkg remove --autoremove package_name

# get the list of available packages:
opkg list

# get the list of installed packages:
opkg list_installed

# list a package content:
opkg files package_name

# more help on opkg :
opkg
Hint: Use the command lines below to install the softwares or drivers you need

--> USB storage

Use of USB storage devices with OpenWRT needs some additional software packages.
- USB packages (kmod-usb-...) are indispensable.
- Filesystems packages (kmod-fs-...) depend on how are formatted the disks you intend to use.
- Codepages packages (kmod-nls-...) are necessary in order to the system to display the correct filenames.
# for OpenWRT Backfire.
# useless for Kamikaze.
opkg install block-mount
opkg install block-hotplug

# usb
opkg install kmod-usb-core
opkg install kmod-usb-ohci
opkg install kmod-usb2
opkg install kmod-scsi-core
opkg install kmod-usb-storage

# ext2/3/4 (Linux) filesystems
opkg install kmod-fs-ext2
opkg install kmod-fs-ext3
opkg install kmod-fs-ext4

# Microsoft filesystems
opkg install kmod-fs-vfat
opkg install kmod-fs-ntfs

# Apple filesystems
opkg install kmod-fs-hfs
opkg install kmod-fs-hfsplus

# codepages
opkg install kmod-nls-base
opkg install kmod-nls-cp437
opkg install kmod-nls-cp850
opkg install kmod-nls-iso8859-1
opkg install kmod-nls-iso8859-15
opkg install kmod-nls-iso8859-2
opkg install kmod-nls-utf8

# other codepages
# Codepage 1250 (Eastern Europe)
opkg install kmod-nls-cp1250
# Codepage 1251 (Russian)
opkg install kmod-nls-cp1251
# KOI8-R (Russian)
opkg install kmod-nls-koi8r

--> I2C

The default Linux kernel coming with OpenWRT has already the appropriate module to control the I2C bus as it uses it to talk with the RTC 
root@NSLU2:/# ls -l /dev/i2c*
crw-r--r--    1 root     root      89,   0 Feb 21 01:05 /dev/i2c-0

--> Switches

In order to put ON/OFF the switches or to write/read the I/Os on the Boomerang board it's necessary to install some software: 
# install i2c tools
opkg install i2c-tools

# i2c detection
root@NSLU2:/# i2cdetect -l
i2c-0   i2c             i2c-gpio0                               I2C adapter

# scan the i2c addresses used on the bus
root@NSLU2:~# i2cdetect -y 0
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:          -- -- -- -- -- -- -- -- -- -- -- -- -- 
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
20: 20 21 22 23 -- -- -- -- -- -- -- -- -- -- -- -- 
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- UU 
70: -- -- -- -- -- -- -- --                         

# play with the switches..
root@NSLU2:/# i2cset -y 0 0x21 0xaa 0xaa
No size specified (using byte-data access)
Value 0xaa written, readback matched

# read the switches status
root@NSLU2:/# i2cget -y 0 0x21
0xaa
In order to operate the switches more easily, I've coded a Web interface and a command line interface. I have made a package of these utilities. This software package is called "domus" and is available in the Downloads. Both interfaces use a unique configuration file in which you can set a name, an icon and allow or deny actions for each switch or I/O. Three actions are available: on, off, and reboot. The delay for reboot is adjustable up to 99 seconds. Default is 7.

- Installation of domus on the NSLU2

Installation can be performed with these command lines: 
cd /tmp
wget http://berlioux.com/electronique/boomerang/downloads/domus_0.0.1-1_ixp4xx.ipk
opkg install domus_0.0.1-1_ixp4xx.ipk
Details of the installed files : 
# config file
/etc/domus/switches.conf

# startup script to set/recall the switches position after a power failure
/etc/init.d/domus

# command line interface
/usr/sbin/domus
# translations for the command line interface
/usr/share/domus/domus.en
/usr/share/domus/domus.fr

# web interface
/www/domus/index.html
/www/domus/css/angles.css
/www/domus/css/sw.css
/www/domus/js/sw_ajax.js
/www/domus/js/sw_display.js
/www/domus/js/sw_vars.js
/www/cgi-bin/switches/index.sh
/www/cgi-bin/switches/switches.sh
# translations for the web interface
/www/cgi-bin/switches/en.lng
/www/cgi-bin/switches/fr.lng
# images for buttons and switches
/www/domus/images/off.gif
/www/domus/images/on.gif
/www/domus/images/reboot.gif
/www/domus/images/default-64-cyan.gif
The post-install script adds two lines for user/password protection of the Web interface in the uhttpd config file: 
/etc/httpd.conf

- Configuration

Edit the configuration file 
vi /etc/domus/switches.conf
each switch or I/O line has its configuration stored on a single line. Syntax:

i2c-address-in-hex;line-number;switch-name;switch-icon;default-startup-position;options

options:
no_all : denies all actions on the switch or the I/O line
no_on : denies the "on" action
no_off : denies the "off" "action"
no_reboot : denies the "reboot" "action"

example:
0x21;2;Disk;hdd-64.gif;off;no_reboot

icons are stored in /www/domus/images and they are supposed to be in 64x64 pixels. As some old web browsers don't like PNGs'transparency it's better to use GIF format for images instead.
Once configuration made, store the default position for switches with:
/etc/init.d/domus reload
then recall the last stored position for all switches: 
/etc/init.d/domus start
to enable the switches status recovery at startup: 
/etc/init.d/domus enable
then reboot or restart uhttpd with: 
/etc/init.d/uhttpd restart

- Usage: manual controls

Web interface: http://192.168.1.77/domus



Command line interface: 
usage   : domus switch-name action [delay] # (action=on|off|reboot)
example : domus Router reboot 10
or      : domus i2c-address line-number action [delay]
example : domus 0x21 7 off

- Usage: automated controls

To perform automated actions, use "crond" and the command line interface. In crontabs, it's always better to use the full path:
55 23 * * * /usr/sbin/domus Router reboot 10
The previous crontab line will reboot the Router every day at 23h55 with a OFF delay of 10seconds.

--> LCD

An lcd4linux package for OpenWRT is available but it doesn't have the necessary driver for the HD44780 through I2C. I had to build a specific package. To make the HD44780 driver appear in the OpenWRT buildroot interface (make menuconfig > Utilities > lcd4linux), you have to edit the file: 
feeds/packages/utils/lcd4linux/Config.in
Find the HD44780 driver section and insert a '#' at the begining of the lines 'depends BROKEN' as shown below. 
config LCD4LINUX_DRV_HD44780
        bool
        prompt "HD44780"
        select LCD4LINUX_HAS_AT_LEAST_ONE_DRIVER
#       depends BROKEN

config LCD4LINUX_DRV_HD44780-I2C
        bool
        prompt "HD44780-I2C"
        select LCD4LINUX_HAS_AT_LEAST_ONE_DRIVER
#       depends BROKEN
The file: 
feeds/packages/utils/lcd4linux/files/lcd4linux.conf
contains the default configuration for the driver. Replace the default I2C address (Device '70') in the HD44780-I2C Display's section. Addresses are in dec, not in hex. This is what works for a two lines, 16 chars display connected to the Boomerang board: 
Display HD44780-I2C {
    Driver 'HD44780'
    Model 'generic'
    Bus 'i2c'
    Port '/dev/i2c-0'
    Device '32'
    Bits '4'
    Size '16x2'
    asc255bug 0
    Icons 1
    Wire {
        RW     'DB5'
        RS     'DB4'
        ENABLE 'DB6'
        GPO    'GND'
    }
}
As it is somehow tedious, you can download below a modified lcd4linux package including the driver and a stripped configuration file.
Download lcd4linux with the HD44780-I2C driver
Another thing to know is that lcd4linux won't work if its configuration file "/etc/lcd4linux.conf" is set to be readable/writable by all. Once you have modified it, change its permissions: 
chmod 600 /etc/lcd4linux.conf
and restart lcd4linux or reboot.

--> 1-Wire

As i said above i didn't succeed in using the 1-wire yet. When I try to use it, the slug hangs. The problem is not with the hardware I made, but with the serial port. The bootloader(RedBoot) uses it. Then the Linux kernel. If it's easy to change the command line for the Linux kernel to avoid the use of the serial port, for Redboot it's more complicated and you loose the benefit of the serial console for easy flashing new firmwares, troubleshooting, etc. So I gave up trying to use the serial port for the 1-wire interface. I'm working on a hardware patch to make the 1-wire interface use the I2C bus instead. This will be described as soon as I have the money to purchase the parts and the time to make it work. Stay tuned.

Donations

This design work has been made with free software and runs free software. I give it for free and with no limitations. But things have a cost. Testing new hardware needs to buy spare parts, writing and translating a clear and readable documentation is long and tedious. It's why I added the splendid Paypal buttons below for those who find this work useful and can't refrain from offering me a coffee, a beer, or a pizza. Trough Paypal donations you can also contact me and get a quick reply. Thanks.

€

Some good people from the U.S.A might also want to give some of their unused dollars:

$

All the money I can't drink or eat will be reinvested in the project(hosting, new hardware hacks etc...)

Downloads

Download the Diagram
Download the PCB
Download the modified lcd4linux package for Boomerang
Download the domus package for Boomerang