BRIStuff Documentation
======================
Tzafrir Cohen <tzafrir.cohen@xorcom.com>
$Revision: 5200 $, $Date: 2008-01-01 00:29:05 +0200 (Tue, 01 Jan 2008) $

BRIStuff is a distribution for installing and / or patching
http://asterisk.org[Asterisk] with several extra features written and
maintained by http://junghanns.net[Junghanns.NET Gmbh].

This document is written in http://www.methods.co.nz/asciidoc/[AsciiDoc]
format, and should be readable as text as well. It is based on the
original documentation from the bristuff package.

Compiling/installing
--------------------
=== Short Version
  wget http://updates.xorcom.com/astribank/bristuff/1.4/bristuff-current.tgz
  tar xvzf bristuff-current.tgz
  # change into the directory. May vary by between versions:
  cd bristuff-0.4.0-test4

  # Install prerequirements. At the moment only works on Debian and
  # CentOS: 
  ./prereq.sh install

  # downloads, builds  and installs everything:
  ./install.sh
  # Alternatively, use ./compile.sh to just repeat build phase.

  # Two optional steps:
  # 1. If you have not installed asterisk and Zaptel on that system yet
  #    set it up:
  ./config.sh
  # 2. Generate Zaptel configuration to match your system. If you have
  #    an Astribank, connect it to your system first:
  genzaptelconf -svdM

NOTE: If you have a CentOS 5 system and install a Xorcom Astribank, you
also need fxload from http://updates.xorcom.com/astribank/fxload/[] .

NOTE: If you have Trixbox: that won't install you kernel-devel. You may
get an error from yum for the kerenl package. Get kernel-devel or
kernel-smp-devel from
http://updates.xorcom.com/astribank/trixbox/repo[]


=== Prerequirements
==== Kernel Source / "Headers"
- Building zaptel requires a kernel build tree.
- This should basically be at least a partial kernel source tree and
  most importantly, the exact kernel .config file used for the build as
  well as several files generated at kernel build time.
- KERNEL_VERSION i sthe output of the command `uname -r`
- If you build your own kernel, you need to point to the exact kernel
  build tree. Luckily for you, this will typically be pointed by the
  symbolic link /lib/modules/KERNEL_VERSION/build which is the location
  zaptel checks by default.
- If you use a kernel from your distribution you will typically have a
  package with all the files required to build a kernel modules for your
  kernel image.
  * On Debian Etch and above and any Ubuntu this is
    +++ linux-headers-`uname -r` +++
  * On Fedora RHEL and compatibles (e.g. CentOS) this is the
    kernel-devel package. Or if you run kernel-smp or kernel-xen, you
    need kernel-smp-devel or kernel-xen-devel, respectively.
  * On SUSE you seem to need the package kernel-source .
- If the above still does not apply to you please contact me.
  (I need to update the document here at this point. Setting up
  /usr/src/linux may actually be the wrong thing to do).

==== Required Packages
- Besides the kernel sources you need a properl build system. You 
  also need ncurses (for zaptel's zttool, optional on 1.4), bison, zlib
  and openssl.
- For the Xorcom Astribank you'll also need libusb, usbutils and the fxload
  firmware loader. 

  * On Debian and Ubuntu: 
  
  apt-get install build-essential bison libncurses-dev libusb-dev usbutils fxload
  
  * On Fedora, Redhat, and CentOS:

  yum install gcc gcc-c++ bison libncurses-devel newt-devel openssl-devel usbutils libusb-devel

  * On RHEL4 / CentOS4 and Fedora up to 5 fxload is part of the package.
    hotplug-utils that is installed by default
  * On newer versions it is not yet available. You may need to get it
    from http://updates.xorcom.com/astribank/fxload
  * On SUSE: 

  yast --install gcc bison ncurses-devel openssl-devel libusb usbutils fxload

  * Other distributions?
  
'This section needs some feedback. Specifically: names of packages.'

==== prereq.sh
On several distributions (currently Debian and CentOS) the following
script can show you what needs to be installed in order to build
bristuff, or even install those packages on its own.

To show what needs doing:

  ./prereq.sh test

To go ahead an install those packages:

  ./prereq.sh install

==== Building
- Just run:  ./install.sh

If you have all the pre-requirements, it should download, patch, build
and install everything. But it will leave the system unconfigured.

System Setup
------------
In this section we will try to give basic instructions on the setup of
an Asterisk system with the BRIStuff patches. See the References section
in the end for other sources of information, as this docuemtn can not
serve as a complete Asterisk setup guide.

The *install.sh* script above will not set up a complete system. If you
don't have have a system 

This may be what you want if you have already configured Asterisk. If
not, see the following section.

- If you have not installed Asterisk and Zaptel before on the system,
  you should also run:  
  
  ./config.sh

- For automatic zaptel hardware detection and setup, you can run (for
  any combination of cards / drivers):

  genzaptelconf -sdMv


=== BRI Zaptel Setup
I would generally recommend you to use genzaptelconf for initial setup
of your Zaptel hardware.

==== Tweaking genzaptelconf
genzaptelconf has a few command-line switches. It is also possible to
affect it behavious through environment variables. But the most
effectivce way to affect its behaviour is through the *zaptel init
configuration file*.

genzaptelconf has two major modes:
1. Without the option -d, it will try to detect configuration from the
   currently-loaded modules.
2. With the option -d it will unload all loaded modules and probe to see 
   which of them needs loading.


The zaptel init configuration file is either */etc/default/zaptel* if it
exists (typically on Debian / Ubuntu) or */etc/sysconfig/zaptel*
otherwise (typically used on Redhats, SUSE and some other 
distributions). 

The syntax of that file is of a shell script: 'VAR=VALUE' . It is also
being read by the zaptel initialization script (/etc/init.d/zaptel).
genzaptelconf sets many variables on its startup and they can be
overriden by setting them in the zaptel init configuration file.

Any changes here will only apply when you re-run genzaptelconf.

A few select variables:
- *lc_country*: the country to use. Default: 'us'. The country to use 
  for tonezones in zaptel.conf . Also may affect a number of settings 
  where we found it useful to have country-dependent defaults.
- *context_lines*: The context into which FXO channels (and BRI TE
  channels) will be directed. Default: 'from-pstn'.
- *context_phones*: The context into which FXS channels (and BRI NT
  channels) will be directed. Default: 'from-internal'.
- *context_manual*: If set to 'yes', genzaptelconf will not set
  contexts, as you probably know better. Default: unset.

This is just a small example. For a complete list, look at the
begionning of genzaptelconf, up to the comment line "# read default
configuration from /etc/default/zaptel".

==== Manual Zaptel Setup
Alternatively, you can use the sample zaptel.conf and zapata.conf 
files provided for various cards. Chances are you will need to edit them:
* Set your country name in zaptel.conf
* Set the proper groups, extension etc. in zapata.conf.conf .

For a Xorcom Astribank you'll need to dig in into xpp/README.Astribank
to find example zaptel.conf, zapata.conf and minimal extensions.conf .

==== Manual Drivers Loading
'The following section is added unmodified from the original document.
I don't really agree with it, though.'

Junghanns quadBRI:

    cd qozap
    modprobe zaptel
    insmod qozap.o (for kernel 2.4)
    insmod qozap.ko (for kernel 2.6)
    ztcfg

Junghanns octoBRI:

    cd qozap
    modprobe zaptel
    insmod qozap.o ports=X (kernel 2.4, for X see below)
    insmod qozap.ko ports=X (kernel 2.6, for X see below)
    ztcfg
    
- 'X' is a bitmap representing the port configuration (TE or NT mode) 
  of the octoBRI card.
- S/T port 1 starts at the LSB of the bitmap.
    
Junghanns octoBRI Example:

- S/T 1,2 in NT mode, S/T 3,4,5,6,7,8 in TE mode
- X (binary) = 00000011
- X (decimal) = 3
    insmod qozap.o ports=3 (kernel 2.4)
    insmod qozap.ko ports=3 (kernel 2.6)


Junghanns singleE1, doubleE1:

    cd cwain
    modprobe zaptel
    insmod cwain.o (kernel 2.4)
    insmod cwain.ko (kernel 2.6)
    
HFC-s:

    cd zaphfc
    make load   # for TE mode, or:
    make loadNT # for NT mode


IMPORTANT NOTE:

if you have any other zaptel device in your machine then make sure that
ztcfg is only run once!

(or run ztcfg -s and after that ztcfg again...)


=== Kernel Module Parameters
Some zaptel modules have optional parameters. For instance, qozap has 
a parameter called 'ports' as explained above. The following section
explains how to get the loaded automatically when kernel 2.6 is used.
For kernel 2.4, see the documentation for /etc/modules.conf .

The following configuration can be added to either /etc/modprobe.conf
(if it exists) or to any file under /etc/modprobe.d .

  options MODULENAME param=value

for example:

  options qozap ports=3
 
If you want to add several options, you should do that in a single line, 
such as:

  options xpp prefmaster=0 zap_autoreg=0


Special Build Options
---------------------
Instead of simply running ./install.sh , there are some variations.

Only download and patch:

  ./download.sh

Only build and install:

  ./compile.sh

(./install.sh simply calls those two)

To build bristuff without any annoying requests in the middle to press
Enter, set the variable 'BRISTUFF_CONFIRM' to 'no':

  BRISTUFF_CONFIRM=no ./install.sh

To build zaptel for a different kernel version (but still with sources
in standard location) use the variable 'KVERS':

  KVERS=2.6.18-5-686 ./install.sh

To provide a custom kernel source tree set 'KSRC' as well:

  KVERS=2.6.18.Custom KSRC=/home/tzafrir/linux-2.6.18 ./install.sh

To install everything to a separate subtree, use the variable
'BRISTUFF_DESTDIR'. It must be an absolute path, or else Zaptel modules 
installation would fail. This is generally only useful for testing:

  BRISTUFF_DESTDIR=$PWD/tmp ./install.sh


=== Patching with Quilt
The single patches under patches/ have been replaced with subdirectories
of patches that are managed with quilt. To avoid making quilt a build
requirement, I have added a simple wrapper script, 'apply-patches.sh',
that applies patches from a quilt directory. I have also provided a
wrapper script to quilt: to list all the patches on asterisk, use:

  ./quilt.sh asterisk series

This runs `quilt series` for asterisk. If you encounter some conflicts
with patches with a certain subdirectory, it is recommended to start
from cratch and use quilt.sh instead of apply-patches.sh, as quilt is
more robust and has bookkeeping of applied patches.


Links
-----
For more information:

* link:CHANGES[Changelog]
* http://BRIstuff.org/[] - more information about BRIstuff.
* http://asterisk.org/[] - Updates, links and some documentation.
* http://voip-info.org/[] - a.k.a "the wiki". Has much useful information.
  A bit not well-organized.
* http://www.oreilly.com/catalog/asterisk/[] - _Asterisk - The future of
  Telephony_. A very good Asterisk book. Published under a CC-NC license,
  which is even better (see under http://www.asteriskdocs.org/[] ).
* http://junghanns.net/[] - who maintain this patch. Site has a few good
  bits. Latest downloads from there:
  http://junghanns.net/downloads/?C=M;O=D[]
* http://zaphfc.florz.dyndns.org/[] - florz's patch to zaphfc. Useful if
  you have more than one HFC-s card. Included with this installation.
* http://zaphfc.florz.dyndns.org/[] - florz's patch to zaphfc. Useful if
  you have more than one HFC-s card. Included with this installation.
* http://xorcom.com/[] - who maintain this document :-)

