Networking a Balloon over USB

The standard method of connecting a Balloon to the world without adding any extra hardware is using USB to connect it to a PC and running a network connection over this cable. This page describes how to set this up and use it. The details depend on which hardware you have (balloon3 or balloon2) whther the PC end is Linux or Windows, and which kernel version you have on the balloon and the host (because the names of modules and interfaces change).

Note there are also many other ways of connecting up the balloon - USBserial, USB<->Ethernet adaptor, CF ethernet or wireless adaptor, zigbee, and plain serial. See BalloonConnectivity. This networking method is not particularly fast (nominal 1Mb/sec) but it's simple - all you need is a suitable socket/cable and a bit of config. For faster networking that loads the CPU less plug a CF ethernet card into the CF slot, or include an ethernet chip on your expansion board.

How it fits together

The way this all works is a bit complicated so here is an explanation of what is going on (very helpful if it isn't working).

The usb-client side of the interface (the Balloon) exists as soon as the necessary modules are loaded (and it is configured). The USB-host side of the interface (normally a PC) does not exist until the cable is connected, even though it is configured with a static address. A much simpler set-up is possible with both side being statically configured, but the problem there is that something needs to do 'ifup usb0' (or 'ifup usbf' on kernel 2.4) on the balloon end, and unless you have a serial connection, or a keyboard and display login, there is no way to do that. Using dhcp the interface is prodded to configure itself as soon as the cable is plugged in.

The host-side config is set to run the dhcp server as soon as the usb0 interface comes up, and to dish out exactly one address to each usb'n' interface. So this is effectively static configuration using DHCP. The max lease time is set low so that that address is always available; the downside being that the balloon asks to renew its address very often. Each time the balloon powers up its usb-client interface has a different MAC address because there is no real hardware, so it is randomly generated - this means that the PC-side thinks it is a new machine each time so won't hand out the same IP address unless the previouslease has expired.

The dhcp client on the balloon side will give up some time after power-up (15 mins?) so you may need to reboot if plugging the usb cable in a long time after powering-up.

If you want to support multiple balloons being plugged into one host then you need to configure multiple usb interfaces (usb0, usb1, usb2 etc) and corresponding dhcp-server stanzas. You also need to enable each one in /etc/default/dhcp3-server.

Wiring

Balloon 3

You cannot connect a USB cable directly to a balloon 3: a socket and terminator chip (or at least resistor) is required. Normally a CUED or Balloonz IO board is required. We are using the slave socket in the mechanism described on this page.

Balloon 2

The cable is normally supplied with your Balloon, but if you haven't got one, or have lost it BalloonUSBCable will tell you how to make your own.

The balloon has both host and slave USB sockets. For this scheme we need to use the slave socket [(J7) | http://www.balloonboard.org/hardware/205/con/usbs.html] (the one that's next-but-one to the serial/jtag socket). The other end (type A plug) goes in your PC or hub.

Software Setup

This page tells you all about the usbnet driver and what it can do, including configuration, but here's the potted version for the Balloon. Resort to the above page if this info doesn't do it for you, and you might also find the [BalloonUSBDebugging] page helpful, where people record their problems and solutions - put yours here if you had trouble.

Note that kernel 2.6 is different kernel 2.4 due to changes in names of modules and interfaces. You can have a 2.4 kernel balloon and a 2.6 kernel PC and it will still work - just choose the right instructions.

kernel 2.6

PC side config

Your kernel must support the ethernet gadget interface. This was true from the 2.6.16.5 balloon port for balloon3. This only ever worked on the 2.6.12 port for balloon2, (and needs updating).

The usbnet module must be loaded:
```
 modprobe usbnet
```

The usb0 network device must be configured. Add this to your /etc/network/interfaces file (Debian-based machines):

allow-hotplug usb0

mapping udev
    script grep
    map usb0

iface usb0 inet static
    address 10.1.1.1
    netmask 255.255.255.0
    network 10.1.1.0
    broadcast 10.1.1.255
    post-up /etc/init.d/dhcp3-server restart
    down /etc/init.d/dhcp3-server stop

The allow-hotplug line enables the dhcp-server lines to be run when the usb0 interface comes up (even when using udev).

The last two lines are to support the fully automatic DHCP configuration. For this to work you need to configure DHCP on this interface, as follows.

Note that the usb0 interface will not appear until the cable is plugged into a properly configured balloon (because there is no real interface until that connection is made).

This requires that dhcp-server (or dnsmasq) is installed:
```
apt-get install dhcp3-server
```

IMPORTANT You must configure it to make sure it is only operating on usb0 otherwise you can cause huge problems on your subnet. Edit /etc/default/dhcp3-server:

INTERFACES="usb0"

Then add the following to /etc/dhcp3/dhcpd.conf:

subnet 10.1.1.0 netmask 255.255.255.0 {
  range 10.1.1.2 10.1.1.2;
  option routers 10.1.1.1;
}

You need to set standard info for your network in here, and a short lease time can be helpful, e.g.:

option domain-name "balloon";
option domain-name-servers 192.168.10.3;
option subnet-mask 255.255.255.0;
default-lease-time 600;
max-lease-time 120;

Balloon side config

Balloon3

The modules pxa27x_udc (usb slave driver) and g_ether (gadget ethernet device) must be loaded:
```
modprobe pxa27x_udc
modprobe g_ether
```

Balloons are normally configured to load either this or g_serial by default in /etc/modules. This modules brings in pxa27x_udc too.

The usb0 interface should now be shown by ifconfig -a

And the interface should be configured to use dhcp:
```
  iface usb0 inet dhcp
  hostname balloon
```

Use

Once it is set up then as soon as the USB cable is plugged into the balloon the g_ether module brings up the usb0 interface on the balloon side, and the usb0 interface on the PC end is created and also brought up, at which point the dhcp server starts and provides an IP address and config to the balloon. If for any reason stuff was not working (e.g. the DHCP timed out) then replugging the USB cable once the config is fiddled with should make it all try again.

If you have trouble check these things:

* modprobe g_ether on balloon should produce output like this:

usb0: Ethernet Gadget, version: May Day 2005
usb0: using pxa27x_udc, OUT Bulk-out-5 IN Bulk-in-4 STATUS Interrupt-in-6
usb0: MAC 66:31:da:44:94:64
usb0: HOST MAC 2a:24:eb:8d:2b:6b
usb0: RNDIS ready
udc: registered gadget driver 'ether'

Plugging in the USB cable should produce this sort of output on the balloon:

usb0: full speed config #1: 100 mA, Ethernet Gadget, using CDC Ethernet Subset

kernel 2.4

PC side config

* Make sure the usbnet module is loaded on the host PC:{{{

modprobe usbnet}}}

* Add this to your PC's network config (/etc/network/interfaces on Debian, /etc/sysconfig/<something> on RedHat):

 iface usb0 inet static
 address 10.1.1.1
 netmask 255.255.255.0

* If you install the ipmasq package on the host and then do:

 ipmasq

after the usb0 conection come up then so long as your kernel is capable of doing IP forwarding (which it almost certainly will be these days), it will automatically set things up so that your balloon can see the world via the PC net connection.

Balloon side config

* Applying 5V to the balloon should make the interface come up. If not, do ifup usb0. If the host PC is running hotplug, it should be possible to get it to bring up usb0 automatically: on Debian, check that NET_AGENT_POLICY in the file /etc/default/hotplug is set to 'auto' rather than 'hotplug', and that usb0 is marked as auto in /etc/network/interfaces.

* You may need to unplug the USB cable from the PC and then plug it in again to get the computer to find the board.

* The balloon will be 10.1.1.2 and the host will be 10.1.1.1.

* You can use DHCP to assign an address to the balloon. You'll have to set up dhcpd on the host pc and tell it to point at interface usb0. On Debian, this is conveniently done in /etc/default/dhcp as INTERFACES="usb0". Because dhcpd isn't happy about managing interfaces which are currently down (as usb0 is before the balloon is connected), you'll need to add some lines to /etc/network/interfaces under usb0. Add

 post-up /etc/init.d/dhcp restart
 down /etc/init.d/dhcp stop

to tickle the DHCP server when the balloon is connected and disconnected.

* to enable DHCP on the balloon, edit /etc/network/interfaces thus:

iface usbf inet dhcp
hostname balloon