
This document explains how to tether FreeBSD to a Blackberry smartphone
via USB using the Barry library and pppob utility.

It should be noted that I developed these instructions using my own
phone, which is a Blackberry Curve 8230 running OS 4.5.0.81. I use
T-Mobile as a carrier. Some of the setup, particularly the chat script,
will need to be modified if you use another carrier.

First you will need the Barry package. Barry is targeted mainly to
Linux, but can be built and used on FreeBSD as well. There is no FreeBSD
binary distribution however, so you'll need to build it yourself. You
can obtain the sources from here:

http://sourceforge.net/projects/barry

There are a few caveats that should be noted before attempting to
build Barry on FreeBSD:

- Make sure that libusb is installed. This is available from the FreeBSD
  ports/package collection.

- Make sure gmake is installed. This is available from the FreeBSD
  ports/package collection.

- If you build the latest sources from CVS, make sure aclocal and friends
  are also installed.

- Barry uses some fairly new C++ features and will not build successfully
  unless you have GCC 4 or later installed. If you use FreeBSD 7.0 or later,
  then you already have a new enough version of GCC. If you use FreeBSD 6.x,
  you will only have GCC 3.x installed by default. You will need to build or
  install a later verision of GCC/G++ to build Barry on such a system. (This
  is fairly easy to do as recent GCC distributions will built out of the
  box on FreeBSD.)

To build Barry, unpack the sources and run the configure script. If you
build from CVS (which I recommend that you do), run the buildgen.sh
script first to create the configure script and other autogenerated
files. At bare mininum, you need the pppob binary to be built. Once
everything is compiled, do a gmake install.

The following caveats should be noted before using pppob with FreeBSD:

- Barry is designed to work with pppd 2.4.x, which is what is available
  with Linux. FreeBSD still has pppd 2.3pl5. The difficulty here is that
  the sample pppd configuration files included with Barry use options
  that are only available with the newer version of pppd. In particular,
  the "pty" keyword is not supported.

  Consequently, the instructions here show how to use Barry with the
  FreeBSD user-mode ppp(8) utility instead.

- The pppob utility is designed to redirect the Blackberry's internal
  modem interface directly to stdin and stdout. The ppp(8) utility
  expects to operate on a specific device under /dev instead. The simplest
  way to deal with this is to run pppob with a script that redirects its
  stdin and stdout descriptors to a pseudo-terminal. A perl script called
  ptyexec is included here which does just that.

- The Blackberry provides access to its internal micro-SD flash device
  by pretending to be a USB mass storage device. As a result, the FreeBSD
  umass(8) driver will claim the Blackberry when it's plugged in. But to
  use Barry, the Blackberry must be used in conjunction with the ugen(8)
  driver instead, since that's the driver interface used by libusb. The
  problem is, the GENERIC kernel included with FreeBSD has the umass(8)
  driver compiled in, and there's no easy way to disable it.

  To deal with this, you must compile a custom kernel that does not
  have the umass(8) driver compiled it. (You can re-use the GENERIC
  kernel configuration file and just comment out the "device umass"
  line near the bottom.) You can still use USB mass storage devices
  with the new kernel: you just need to kldload the umass.ko driver
  module first.

- The ppp(8) utility uses the tun(4) kernel driver instead of the ppp(4)
  kernel driver. If tun(4) is not compiled into the kernel, ppp(8) will
  automatically load it on the fly.

Instructions for using Barry's pppob utility with FreeBSD:

1) Install a kernel that does *not* have umass(8) compiled in

2) Copy the ppp.conf file included here to /etc/ppp.

3) Copy ptyexec to /usr/local/bin, or whereever the pppob binary is
   installed. Both should be in your path.

4) Run pppob as follows:

   # ptyexec pppob

5) Note which pseudo-terminal device the ptyexec script selected for
   use with pppob

6) Edit /etc/ppp/ppp.conf and change the device specified in the
   "set device" line to match the device noted above.

7) Launch ppp(8) with the following command:

   # ppp -background barry

You can check /var/log/ppp.log to monitor ppp(8)'s progress. If all goes
well, it should negotiate a link with the Blackberry and configure the
tun0 interface accordingly.

Note:

- The chat script in the ppp.conf file is especially messy due to the
  presence of double quote characters in one of the AT commands required
  to set up the link. The chat script syntax makes escaping the quote
  characters very awkward.

- There was a bug in the IP modem code in Barry which was only recently
  fixed which could cause the attached Blackberry device to crash and
  reboot. The bug was fixed in rev 1.18 of src/m_ipmodem.cc. The bug
  is that part of the startup handshaking was being skipped in the case
  no username/password is needed to communicate with the device. (This
  is the case with the Curve 8320 and T-Mobile.) The tethering still
  appeared to work, but in reality each packet sent to the device was
  causing an extra notification to be returned to the host. This caused
  the device to become unstable, and it would reset itself at random
  times (though for me at least the crash occured mainly during periods
  of heavy traffic).

  For this reason, it is strongly recommended that the latest CVS version
  of Barry be used for tethering.
