# Outlet software

Posted on Mon 22 Feb 2010 by wedge

A client/server software system to control a modified remote outlet system via a USB Bit Whacker board.

This is free software, and is released under the terms of the GNU General Public Licence.

outlet-1.0.3 (24 Feb 2010)

• [win32] Fix bug which prevented COM ports > 9 to be accessed.

outlet-1.0.2 (22 Feb 2010)

• Tidied up.
• Included BitWhacker firmware modifications in package.

## Updating the BitWhacker firmware

Changes need to be made to the firmware running on the BitWhacker board to allow it to send and receieve encoded data packets for controlling remote outlet systems.

The modifications are all contained in the user.c file, which is included in the distribution package in the bitwhacker/ directory. It is based on the "D v1.4.3" version firmware from http://www.schmalzhaus.com/UBW/.

To apply this modification, download the "D v1.4.3" firmware source: http://www.schmalzhaus.com/UBW/FW/D_143/D_143.zip, and replace the file user/user.c with the user.c file contained in this package. A diff file is also included, which shows the differences between my version and the original. This may be used to apply the changes to a later version of the BitWhacker firmware, if required.

Build hex file and program the UBW device as normal using the bootloader (see documents supplied with the UBW for instructions). You will need the Microchip USB Framework and MPLAB C Compiler for PIC18 devices.

## Using the software (Windows)

### Installing

Prebuilt binaries are supplied in the above package, though these can be rebuilt if required by opening the outlet.dsw project in MSVC.

No specific installation required - simply find outletctl.exe and outletsrv.exe in the win32/out/ directory, and copy them to a convenient location on your machine.

### Running

Make sure the modified remote control is plugged into the computer via USB. The USB bit whacker should appear to the computer as a serial port. To find the name of the port, go to Control Panel > System > Hardware tab > Device manager. The USB serial port should be listed under the Ports node, on my machine it is "COM6".

The server program (outletsrv.exe) should be running. You can launch this manually, or make this run every time your computer boots by dragging a shortcut into the Start Menu > Programs > Startup folder. Right click the shortcut and select "Properties". The "target" box should contain the name of the executable, to this you will need to append a space followed by the name of the COM port which corresponds to the USB bit whacker, which you determined in the previous step.

You should see a grey outlet icon in the system tray indicating the server is running. The icon flashes yellow to indicate activity, and turns red in the case of an error.

Right click and drag the client executable outletctl.exe and select "Create shortcut here". Rename the shortcut to indicate what you want it to do, e.g. "Switch light off". Right click the shortcut and select "Properties". You will need to append three arguments to the executable name in the "target box", each separated by space. Firstly, the identifier (a unique number between 0 and 65535 to identify the set of outlets), then the button (A,B,C,D or ALL), then the state (ON or OFF). So you might end up with something like:

c:\path\to\program\outletctl.exe 12345 A ON


Press the "change icon" button to choose an appropriate icon for the shortcut. Several standard ones are supplied, but you can also create your own if required using a suitable icon editor.

Once you have created the "ON" shortcut, you will also want to create a corresponding "OFF" shortcut, in a similar way.

You can make a command run at a particular time or in response to certain events by dragging a shortcut into the "Scheduled tasks" folder (found under Control Panel). Right click the shortcut in the scheduled tasks folder and select properties, you can then specify when you want the command to run.

## Using the software (Linux)

### Installing

You'll need the c++ compiler and make installed (e.g. on Ubuntu run "sudo apt-get install build-essential").

From a command shell, go into the linux/ directory under the distribution and run "make".

To install the binaries, run "make install" as root - this will copy them to /usr/local/bin.

### Running

Make sure the modified remote control is plugged into the computer via USB. The USB bit whacker should appear to the computer as a modem, which should be called something like "/dev/ttyACM0". Run "dmesg" from the command line after plugging in the device to determine the name of the device.

The server program (outletsrv) should be running. You can launch this manually, or make this run every time your computer boots by running it from /etc/rc.local (there may be a more suitable way of doing this, depending on your Linux distribution, but this is usually the simplest). The comm port can be specified on the outletsrv command line using the '-c' option. For example, you might use the following line in /etc/rc.local:

/usr/local/bin/outletsrv -c=/dev/ttyACM0


Create shortcuts to the outletctl program using your desktop environment, appending the required command line arguments (see the running on Windows section above).

Task scheduling on Linux is usually done using cron. You need to add the task(s) you want to run to crontab (the file cron uses to decide which tasks to run). To edit the crontab file, run the command "crontab -e" at the command line. This should bring up the crontab file in your selected editor. For example:

0 9 * * * /usr/local/bin/outletctl 12345 A ON
0 17 * * * /usr/local/bin/outletctl 12345 A OFF


This would switch outlet set 12345 button A on at 09:00 every morning, and off at 17:00. See your user manual for cron for an explanation of how the date and time is specified in crontab files.

## Assigning shortcuts to outlets

To assign a shortcut to an outlet, plug in the outlet and press the "learn" button (LED should flash). Then run one of the shortcuts you created, the LED should stop flashing to indicate the outlet has learnt this identifier and button combination.

## How it works

The firmware modification implements two new commands which are described below:

COMMAND: ZO,[z1][z2][z3][z4]

Encodes and transmits a data packet to control remote outlet systems.
[z1]...[z4] are bytes in hex format.
[z1] = Counter value (not significant, can be left as 00)
[z2] = First part of identifier
[z3] = Command
[z4] = Second part of identifier

COMMAND: ZI

Starts listening for incoming packets.

Received packets are decoded and sent to the computer in the following format:

ZI,[z1][z2][z3][z4]

[z1]...[z4] are bytes in hex format, with meanings as described for the ZO command above.