Bluetooth garage door opener

Today I made a Bluetooth garage door opener. Now I can open my garage from my Android phone. There’s a short how-to YouTube video from Lou Prado. Lou also made a website btmate.com that has more information, and you can watch an earlier howto video as well.

The project itself was pretty simple:
- Acquire a Samsung HM1100 bluetooth headset (the Samsung HM1800 also works). You can buy these cheap from Fry’s or eBay. I got mine on eBay for $10-$15.
- Crack open the earpiece on the Bluetooth headset and solder one of the earpiece wires to the base pin of a transistor. Solder red and black wires to the other pins of the transistor.
- Connect the red and black wires to the garage door opener. It turns out that most garage door openers are built to allow easy insertion of wires, which is nice.

That’s more or less it. My soldering was ugly as sin–too ugly for me to even post a picture. And rather than leave the house for some heat shrink tubing, I just left bare wires on the transistor, but everything works fine.

Lou wrote a nice Android app that’s free to install and then pay-what-you-want for a license. Then it’s just a single button to open or close the garage door. In theory, I could use Tasker to open the garage door automatically when I get home.

It’s not quite as sexy as Brad Fitzpatrick’s Android garage door opener, but it was a fun little project for a day.

The heart of a computer is now the network connection

Back in the 90s, the heart of a computer was the CPU. The faster the CPU, the better the computer was–you could do more, and the speed of the CPU directly affected your productivity. People upgraded their computers or bought new ones whenever they could to take advantage of faster CPU speeds.

I remember the point when computers got “fast enough” though. Around 1997 or 1998, computers started hitting 166 MHz or 200 MHz and you could feel the returns diminishing. At some point, the heart of a computer switched from being a CPU to the hard drive. What mattered wasn’t the speed of your Intel or AMD chip, but the data that you had stored on your computer.

The era of the hard drive lasted for a decade or so. Now I think we’re shifting away from the hard drive to the network connection. Or at least the heart of a computer has shifted for me. In 2006 I contemplated a future where “documents sat in a magic Writely [note: now Google Docs] cloud where I could get to them from anywhere.” Sure enough, I keep all my important files in Google Docs now. At this point, if I have a file that sits only on a local hard drive, I get really nervous. I’ve had local hard drives fail. By 2008, I was spending 98% of my time in a web browser.

Don’t get me wrong. Local hard drives are great for caching things. Plus sometimes you want to run apps locally. But for most people, the heart of a computer will soon be its network connection. Ask yourself: could you get by with a minimal hard drive? Sure. Plenty of people store their files on Dropbox, Box, Google Drive, iCloud, or SkyDrive. Or they back up their data with CrashPlan, SpiderOak, Carbonite, or Mozy. But would you want a computer that couldn’t browse the web, do email, or watch YouTube videos? Not likely.

Playing with a USB Missile Launcher

This is the last half-finished “hairball” blog post about USB devices on Linux. I actually did manage to get a working program that controlled a USB foam missile launcher. Unfortunately, I didn’t document all the steps, so this blog post just sort of stops at some point.

I got a USB Missile Launcher for Christmas. The manufacturer, Dream Cheeky, provides software–but only for Windows XP. And I thought to myself, “wouldn’t it be fun to practice some USB reverse engineering skills?” Because another Christmas present was a USB protocol analyzer from Total Phase. I should note that plenty of other people have apparently already written drivers/software for USB missile launcher toys, but I wanted to poke around myself.

Total Phase makes a high-speed USB 2.0 protocol analyzer for $1200, or a regular-speed USB protocol analyzer for $400. Here’s a trick someone mentioned: if you get the cheaper protocol analyzer and need to work with a high-speed USB device, you may be able to plug the high-speed device into a low-speed USB hub to slow the device down.

I decided to start with ladyada’s excellent guide to hacking a Kinect by reverse engineering USB packets. So here’s what I did.

Step 1. Make sure the device works. It would suck to attempt to reverse engineer a broken device. I keep a Windows XP computer lying around, so I downloaded the software for it, installed the program, and plugged in the USB rocket launcher. After the install, XP wanted to restart, so I restarted the XP computer (unplugging my USB rocket launcher after the computer was off), then started the rocket launcher software back up, then plugged in the USB device. Sure enough, everything worked fine. The controls are: pan left/right, tilt up/down, and fire. Tip: the rocket launcher uses bursts of air, so don’t jam the foam rockets down hard on the launcher.

Step 2. Probe the device. I plugged the USB rocket launcher into a Linux machine running Ubuntu 10.04 (Lucid Lynx). I ran the command sudo lsusb -vv and the relevant info from the list of USB devices on my system was this:

Bus 002 Device 045: ID 0a81:0701 Chesen Electronics Corp. USB Missile Launcher
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               1.10
  bDeviceClass            0 (Defined at Interface level)
  bDeviceSubClass         0 
  bDeviceProtocol         0 
  bMaxPacketSize0         8
  idVendor           0x0a81 Chesen Electronics Corp.
  idProduct          0x0701 USB Missile Launcher
  bcdDevice            0.01
  iManufacturer           1 Dream Link
  iProduct                2 USB Missile Launcher v1.0
  iSerial                 0 
  bNumConfigurations      1
  Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength           34
    bNumInterfaces          1
    bConfigurationValue     1
    iConfiguration          0 
    bmAttributes         0xa0
      (Bus Powered)
      Remote Wakeup
    MaxPower              100mA
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        0
      bAlternateSetting       0
      bNumEndpoints           1
      bInterfaceClass         3 Human Interface Device
      bInterfaceSubClass      0 No Subclass
      bInterfaceProtocol      0 None
      iInterface              0 
        HID Device Descriptor:
          bLength                 9
          bDescriptorType        33
          bcdHID               1.00
          bCountryCode            0 Not supported
          bNumDescriptors         1
          bDescriptorType        34 Report
          wDescriptorLength      52
         Report Descriptors: 
           ** UNAVAILABLE **
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x81  EP 1 IN
        bmAttributes            3
          Transfer Type            Interrupt
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0001  1x 1 bytes
        bInterval              20
Device Status:     0x0000
  (Bus Powered)

Note that my Vendor ID = 0x0a81 and my Product ID = 0×0701. Also note that bNumEndpoints = 1. An endpoint is a channel for USB data communication. Then we get the Endpoint info:

      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x81  EP 1 IN
        bmAttributes            3
          Transfer Type            Interrupt
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0001  1x 1 bytes
        bInterval              20

According to ladyada’s write-up, the “IN” means that data goes IN to the computer from the device, and the “Interrupt” transfer type is good for sending large amounts of small data quickly (e.g. a USB mouse).

Step 3. Prepare your Linux system to talk to the device. First, let’s review ladyada’s steps, which is for Windows. She installs libusb-win32 and then runs a program called inf-wizard to make a driver shell. Then plugging the device into Windows will attach the LibUSB-win32 device driver. Next, she installed Python and PyUSB.

I wanted to stick with Linux. I didn’t need libusb-win32 or inf-wizard.exe, and I already had Python installed. So my next step was to download PyUSB, extract the zip into a directory, change into that directory, then run sudo python setup.py install in that directory to install PyUSB. Since you’re installing PyUSB system-wide, you do need to run that command with “sudo” to run it as root.

Step 4. Write a short program on your Linux machine to talk to the device. I made a file missile-launcher.py and executable access with “chmod ugo+rx missile-launcher.py” next. Here’s the short program I ended up with:

#!/usr/bin/python

import usb.core
import usb.util
import sys
 
# find our device
dev = usb.core.find(idVendor=0x0a81, idProduct=0x0701)
 
# was it found?
if dev is None:
    raise ValueError('Device not found')

# Linux kernel sets up a device driver for USB device, which you have
# to detach. Otherwise trying to interact with the device gives a
# 'Resource Busy' error.
try:
  dev.detach_kernel_driver(0)
except Exception, e:
  pass # already unregistered
 
# set the active configuration. With no arguments, the first
# configuration will be the active one
dev.set_configuration()
 
print "all done"

Note that my “idVendor=0x0a81, idProduct=0×0701″ parameters use the values I found from lsusb -vv. If you compare against ladyada’s short program you’ll notice one major difference. My code has these lines:

# Linux kernel sets up a device driver for USB device, which you have
# to detach. Otherwise trying to interact with the device gives a
# 'Resource Busy' error.
try:
  dev.detach_kernel_driver(0)
except Exception, e:
  pass # already unregistered

Ladyada’s PyUSB program for Windows didn’t have anything like that. But when I ran the program under Linux, I got the error message “usb.core.USBError: Resource busy”. It turns out that the Linux kernel tries to use a default kernel driver, and that prevents my program from talking to the device. Detaching the kernel driver lets me talk to the device just fine. I picked up this tip Ken Shirriff’s post about a USB panic button with Linux and Python. In theory you could also unbind the USB device from a command-line, but I prefer to do it right in my PyUSB program directly.

Note that you will need to run the python program as root, e.g. “sudo ./missile-launcher.py” or else you’ll get a warning message like “usb.core.USBError: Access denied (insufficient permissions)”.

At this point, you have a small working program that opens up a connection to the USB rocket launcher. If the USB rocket launcher isn’t plugged in, you’ll get a “Device not found” error, and if the USB device is plugged in, you’ll get an “all done” message and the program exits gracefully.

Step 5: Try to read from the USB device. In ladyada’s guide, she tried sending 0b11000000 = 0xC0 (“Read Vendor data from Device”) to a Kinect. I got no response from that, but I did get a response sending 0b10000000. That corresponds to sending:
- a ’1′ to read from the device
- a message type of ’00′ = standard. Ladyada got a response sending to ’10′ = vendor
- ’000′ (reserved bits, so always 0)
- ’00′ to say the recipient of the message is the device.
Then sending a request of 0 got back a result of two zero bytes:

bRequest  0
array('B', [0, 0])

Interestingly, running the same program again would get a “usb.core.USBError: Unknown error” response. At that point, I would unplug the USB device and then plug it back in to reset it. I didn’t get any other responses from trying to send message types of class or vendor (as opposed to standard), nor did I get any responses from try to send messages to the interface or endpoint (as opposed to the device). See ladyada’s guide for more details about fuzzing the device and what all the various bit fields mean.

Step 6: Set up the Linux computer to use the Total Phase Beagle. The CD worked nicely with HTML documentation on it. First, you copy some udev rules so that the device is writable by anyone when the Beagle is plugged in:


cd /media/Total Phase/drivers/linux/
sudo cp 99-totalphase.rules /etc/udev/rules.d/
sudo chmod 644 /etc/udev/rules.d/99-totalphase.rules

If you’ve already plugged in the Beagle, you’ll need to unplug it and plug it back in for these rules to fire. Next, you’ll need the Data Center software. You can get it off the CD, but I’d recommend downloading the latest software and user’s manual from the website instead. My CD had software version 4.20 for example and the website was up to 5.01. Extract the software zip file (either from online or the CD). Then follow the directions in the online manual (or user manual PDF). The directions according to the manual are

  1. Install the USB drivers and Data Center software. Copying the udev rules is enough for USB drivers on Linux. Unpacking the zip is all you need for the Data Center software, because the executable is self-contained.
  2. Plug the Beagle analyzer into the analysis machine. This was my Linux machine.
  3. Plug the Beagle analyzer into the bus to be analyzed. In this case, this was my XP computer. Don’t plug the USB missile launcher in yet though.
  4. Start the Data Center software. Run the program “Data Center” in the directory you extracted from the .zip file. Follow the rest of the instruction in the Quick Start section.

Linux USB device driver info

What, *another* half-finished blog post about Linux USB drivers? Yup.

Suppose you have a device and want a Linux device driver for it. There are a few steps you’ll need to take. One of the heroes in this area is Greg Kroah-Hartman. Greg wrote USBView, which is a Linux tool to enumerate a list of USB devices. He’s also done a massive amount of documentation as we’ll see below. One of his more eye-catching tricks is to walk a classroom through the process of writing a Linux driver for a USB thermometer live and in real-time. In addition to all the work he does for Linux in general, he recently announced a program to work with manufacturers and provide Linux drivers for new devices for free. That’s right, manufacturers get a free driver. From the original announcement:

All that is needed is some kind of specification that describes how your device works, or the email address of an engineer that is willing to answer questions every once in a while. A few sample devices might be good to have so that debugging doesn’t have to be done by email, but if necessary, that can be done.

In return, you will receive a complete and working Linux driver that is added to the main Linux kernel source tree. The driver will be written by some of the members of the Linux kernel developer community (over 1500 strong and growing).

That is majorly good karma for Linux and Greg. But if you’re not a manufacturer, here are the steps that you’d look into.

1. Get documentation of the USB protocol, or reverse engineer the protocol. It’s far easier if you can get documentation of the protocol. If you do need to reverse engineer the USB protocol, here are some tools that might help:

Windows tools: USB Snoopy let you do actions with your device and log the stream of USB information going downstream/outbound to the device, or upstream/inbound back to your computer. Snoopy Pro is a variant of the same code that evidently has some improvements. It appears that the preferred location for Snoopy Pro is here.

Linux tools:
- The previously mentioned USBView will show you devices that are currently plugged in.
- The usbutils package includes a bunch of handy console tools for USB, including lsusb, which shows you the USB devices that are currently plugged in. The output of lsusb looks like this:

Bus 001 Device 006: ID 2222:3061 MacAlly
Bus 001 Device 002: ID 0557:7000 ATEN International Co., Ltd
Bus 001 Device 003: ID 045e:00db Microsoft Corp.

2. Write the driver.

- It seems that the process of writing drivers in Linux is getting easier over time. The Linux Journal has documented this well. Compare this 2001 article by Greg Kroah-Hartman to Greg’s 2004 article on controlling a simple USB lamp device. Then see Greg’s follow-up article on writing a linux driver in user space. It turns out that you can use the libusb library to read/write with USB devices without ever mucking around in the kernel. This is possible because Linux provides a USB filesystem (called USBFS) that automatically mounts USB devices into the Linux directory tree. Note that libusb also works on BSDs, Mac/OSX computers, and that there is a Windows libusb port.

If you really want to delve into this deeply, there’s an O’Reilly book on Linux device drivers that you can buy as well.

Reverse engineering a Windows USB driver

For a while, I was really into reverse-engineering USB drivers. Don’t ask why. The heart wants what the heart wants. I didn’t finish this “hairball” post, but it has some info in it that still might be good.

I recently stumbled across this post and it inspired me. I decided to try to reverse engineer the USB protocol for my Omron pedometer, which can upload your step data, but only to a Windows computer.

There are two parts to writing a Linux driver for a new USB device: reverse-engineering the USB protocol, and writing the Linux program.

Reverse-engineering the USB protocol

Typically your problem is that a device only runs under Windows. Like it or not, that means that you’re going to need something that runs Windows. It can be a Windows computer, or you can get fancy and run Windows as a “guest” operating system using something like VMWare to do virtualization. That is, you’d install Linux, then install VMWare, then install Windows to run under VMWare. But let’s start simple.

Step 0. Find the Vendor ID and Product ID of your device

Every USB device should have a Vendor ID plus a Product ID (sometimes called a device ID) that identifies it. You’ll need to discover this information before you can talk to the device. I plugged my Omron pedometer into a linux machine and typed “lsusb”. You’ll get a lot of information back. I saw a line like

Bus 002 Device 018: ID 0590:0028 Omron Corp.

That tells me that the vendorid is hexadecimal value 0×0590 (which is 1424 in decimal) and the productid is hex value 0×0028 (which is 40 in decimal). For other operating systems, this post tells you how to find your vendor id and product id under Mac and Windows. For Windows XP, it looks like you can run “msinfo32.exe” and then look under “Components” and then “USB” and look for “VID_” (vendor id) and “PID_” (product id).

1) The simple approach: a dedicated Windows computer

In the beginning, it’s easiest to just use a Windows computer and run some software to sniff on the USB packets as they go back and forth. The wild part is that the best open-source/free program I found is five years old (SnoopyPro). It still worked fine on Windows XP though. SnoopyPro is the program you want. There’s a whole long history of how it forked from USBSnoopy (evidently also called “sniff-bin“), and there’s another program called sniffusb which is related but different (I think both sniffusb and SnoopyPro are forks off of the original USBSnoopy/sniff-bin program). It’s all very confusing. I went with SnoopyPro and it worked fine for me.

Further reading on SnoopyPro and related USB sniffer programs:
Some documentation on how to use SnoopyPro
If you’re willing to shell out for a book, it looks like USB Complete, now in its third edition, is one of the best.
http://www.piclist.com/techref/usbs.htm – mentions all the different sniffers
http://hackspire.unsads.com/USB_Protocol#USB_traffic_analysis – talks about how to convert SnoopyPro (and SniffUsb) logs/traces into hexadecimal data.

Are there other options? Sure. USB Monitor from HHD Software is $85 and runs on Windows. Or you could spend $850-950 to buy a hardware USB protocol analyzer. Since I have only a casual interest, that’s a bit steep for me.

One last option is to run Windows as a virtual “guest” on a Linux system running something like VMWare. VMWare can let programs interact with USB devices. As the virtual version Windows interacts with the USB device, the Linux computer gets to see everything that happens, because it sits between Windows and the USB device. In fact, Eric Preston presented a method that could log all the the output of the Linux usbmon program as binary data. Eric changed usbmon to use relayfs so that large amounts of data could be quickly relayed from kernel space to user space, then wrote a user space program to dump that binary data to disk. Eric also wrote a dissector for ethereal so that he could view the USB data in real-time. Unfortunately the PDF of his slide presentation have disappeared from http://download.linuxmontreal.com/projects/usb/reveng/ where they used to be. In fact, all of linuxmontreal.com appears to be gone now. :(

By the way, Ethereal is now known as Wireshark, and it is a protocol analyzer that runs on many platforms and apparently supports USB traces. It looks like Wireshark has supported USB since version 0.99.4:

Wireshark now supports USB as a media type. If you’re running a Linux distribution with version 2.6.11 of the kernel or greater and you have the usbmon module enabled and you have a recent CVS version of libpcap (post-0.9.5) installed you can also do live captures. More details can be found at the USB capture setup page on the wiki.

Follow the link in the quote to find Wireshark’s USB wiki page.

On Ubuntu 7.10 (Gutsy Gibbon), I was able to do these commands:

sudo mount -t debugfs none_debugs /sys/kernel/debug
sudo modprobe usbmon
ls /sys/kernel/debug/usbmon
0s 0t 0u 1s 1t 1u 2s 2t 2u

General USB Reading:
USB in a NutShell is a pretty good overview of how USB communication goes.
This Java and USB tutorial starts with a good overview of USB.
This USB and Linux tutorial starts to get into the nitty gritty of USB on Linux.

css.php