contrib/barry_freebsd/barry_freebsd.txt

   1
   2 This document explains how to tether FreeBSD to a Blackberry smartphone
   3 via USB using the Barry library and pppob utility.
   4
   5 It should be noted that I developed these instructions using my own
   6 phone, which is a Blackberry Curve 8230 running OS 4.5.0.81. I use
   7 T-Mobile as a carrier. Some of the setup, particularly the chat script,
   8 will need to be modified if you use another carrier.
   9
  10 First you will need the Barry package. Barry is targeted mainly to
  11 Linux, but can be built and used on FreeBSD as well. There is no FreeBSD
  12 binary distribution however, so you'll need to build it yourself. You
  13 can obtain the sources from here:
  14
  15 http://sourceforge.net/projects/barry
  16
  17 There are a few caveats that should be noted before attempting to
  18 build Barry on FreeBSD:
  19
  20 - Make sure that libusb is installed. This is available from the FreeBSD
  21   ports/package collection.
  22
  23 - Make sure gmake is installed. This is available from the FreeBSD
  24   ports/package collection.
  25
  26 - If you build the latest sources from CVS, make sure aclocal and friends
  27   are also installed.
  28
  29 - Barry uses some fairly new C++ features and will not build successfully
  30   unless you have GCC 4 or later installed. If you use FreeBSD 7.0 or later,
  31   then you already have a new enough version of GCC. If you use FreeBSD 6.x,
  32   you will only have GCC 3.x installed by default. You will need to build or
  33   install a later verision of GCC/G++ to build Barry on such a system. (This
  34   is fairly easy to do as recent GCC distributions will built out of the
  35   box on FreeBSD.)
  36
  37 To build Barry, unpack the sources and run the configure script. If you
  38 build from CVS (which I recommend that you do), run the buildgen.sh
  39 script first to create the configure script and other autogenerated
  40 files. At bare mininum, you need the pppob binary to be built. Once
  41 everything is compiled, do a gmake install.
  42
  43 The following caveats should be noted before using pppob with FreeBSD:
  44
  45 - Barry is designed to work with pppd 2.4.x, which is what is available
  46   with Linux. FreeBSD still has pppd 2.3pl5. The difficulty here is that
  47   the sample pppd configuration files included with Barry use options
  48   that are only available with the newer version of pppd. In particular,
  49   the "pty" keyword is not supported.
  50
  51   Consequently, the instructions here show how to use Barry with the
  52   FreeBSD user-mode ppp(8) utility instead.
  53
  54 - The pppob utility is designed to redirect the Blackberry's internal
  55   modem interface directly to stdin and stdout. The ppp(8) utility
  56   expects to operate on a specific device under /dev instead. The simplest
  57   way to deal with this is to run pppob with a script that redirects its
  58   stdin and stdout descriptors to a pseudo-terminal. A perl script called
  59   ptyexec is included here which does just that.
  60
  61 - The Blackberry provides access to its internal micro-SD flash device
  62   by pretending to be a USB mass storage device. As a result, the FreeBSD
  63   umass(8) driver will claim the Blackberry when it's plugged in. But to
  64   use Barry, the Blackberry must be used in conjunction with the ugen(8)
  65   driver instead, since that's the driver interface used by libusb. The
  66   problem is, the GENERIC kernel included with FreeBSD has the umass(8)
  67   driver compiled in, and there's no easy way to disable it.
  68
  69   To deal with this, you must compile a custom kernel that does not
  70   have the umass(8) driver compiled it. (You can re-use the GENERIC
  71   kernel configuration file and just comment out the "device umass"
  72   line near the bottom.) You can still use USB mass storage devices
  73   with the new kernel: you just need to kldload the umass.ko driver
  74   module first.
  75
  76 - The ppp(8) utility uses the tun(4) kernel driver instead of the ppp(4)
  77   kernel driver. If tun(4) is not compiled into the kernel, ppp(8) will
  78   automatically load it on the fly.
  79
  80 Instructions for using Barry's pppob utility with FreeBSD:
  81
  82 1) Install a kernel that does *not* have umass(8) compiled in
  83
  84 2) Copy the ppp.conf file included here to /etc/ppp.
  85
  86 3) Copy ptyexec to /usr/local/bin, or whereever the pppob binary is
  87    installed. Both should be in your path.
  88
  89 4) Run pppob as follows:
  90
  91    # ptyexec pppob
  92
  93 5) Note which pseudo-terminal device the ptyexec script selected for
  94    use with pppob
  95
  96 6) Edit /etc/ppp/ppp.conf and change the device specified in the
  97    "set device" line to match the device noted above.
  98
  99 7) Launch ppp(8) with the following command:
 100
 101    # ppp -background barry
 102
 103 You can check /var/log/ppp.log to monitor ppp(8)'s progress. If all goes
 104 well, it should negotiate a link with the Blackberry and configure the
 105 tun0 interface accordingly.
 106
 107 Note:
 108
 109 - The chat script in the ppp.conf file is especially messy due to the
 110   presence of double quote characters in one of the AT commands required
 111   to set up the link. The chat script syntax makes escaping the quote
 112   characters very awkward.
 113
 114 - There was a bug in the IP modem code in Barry which was only recently
 115   fixed which could cause the attached Blackberry device to crash and
 116   reboot. The bug was fixed in rev 1.18 of src/m_ipmodem.cc. The bug
 117   is that part of the startup handshaking was being skipped in the case
 118   no username/password is needed to communicate with the device. (This
 119   is the case with the Curve 8320 and T-Mobile.) The tethering still
 120   appeared to work, but in reality each packet sent to the device was
 121   causing an extra notification to be returned to the host. This caused
 122   the device to become unstable, and it would reset itself at random
 123   times (though for me at least the crash occured mainly during periods
 124   of heavy traffic).
 125
 126   For this reason, it is strongly recommended that the latest CVS version
 127   of Barry be used for tethering.