path: root/kernel/xpp/README.Astribank

Xorcom Astribank Documentation
==============================
Xorcom Team <support@xorcom.com>
$Revision$, $Date$

This file documents the Zaptel drivers for the Xorcom Channel Bank.
The drivers reside in a separate subdirectory, kernel/xpp/ .

It is generally a more technical document than the 
http://www.xorcom.com/documentation/manuals/[Astribank User Manual]

An HTML version of the latest version of this document could be found at 
http://zaptel.tzafrir.org.il/README.Astribank.html[]

Building and Installation
-------------------------
Building and installation is basically like the normal procedure of 
installing Zaptel with some additions.

Building drivers
~~~~~~~~~~~~~~~~
Apart from the standard Zaptel build requirements, you also need libusb
development headers to build the fpga_load firmware loader. This is
typically the package libusb-dev on Debian (and derivatives like Ubuntu)
or libusb-devel on RedHat (and derivatives like CentOS/Trixbox).

On Zaptel 1.2 you will need to run the following extra step to build the
user space utilities, apart from the standard 'make; make install':

  make -C xpp/utils install

Though this should be done automatically on Zaptel >= 1.4.1 .


Sample Configurations
---------------------
We generally recommend to generate the configuration by using utility
genzaptelconf or zapconf which are included with Zaptel. Nevertheless,
the following can serve as reference configurations for a system where 
Astribank devices are used.


Zaptel Init Configuration File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The zaptel init.d script, genzaptelconf and the XPD init scripts uses the 
parameters located in file /etc/default/zaptel (on Debian) or 
/etc/sysconfig/zaptel (on RedHats). There is a number of useful parameters 
that may be defined there:

-----------------------------------------------------------
# Lines beginning with '#' are considered comments and ignored.

# A two-letter country code. genzaptelconf uses it to better guess 
# the configuration it generates. E.g: the signalling of E1 spans, and 
# a few other country-specific settings.
#lc_country=us

# See genzaptelconf(8) and the script itself for a longer list of 
# variables.

# Equivalent to the parameter opermode to the module wctdm: country-specific
# settings to the FXO lines. For a complete list of possible values, see
# /usr/share/zaptel/init_fxo_mode .
#opermode=FRANCE

# xpp_sync runs with the value of 'XPP_SYNC' as its parameter to set the
# synchronization source. The default is 'auto' that selects the best
# Astribank. 'ZAPTEL' gets synchronization from the Zaptel sync master
# span. Or a specific XBUS number.
#XPP_SYNC=ZAPTEL

# Disables hot-plug firmware loading
#XPP_HOTPLUG_DISABLED=yes
#

# Disables udev hook called when an Astribank is added and ready
# or removed.
#ASTRIBANK_HOOK_DISABLED=yes

# Setup for the Astribank PRI module:
# All the ports in the unit connected to the USB port 0000:00:1d.7-1
# will be NT and E1. Ports no. 1 and 3 of all the other Astribanks will 
# be NT and E1 (and thus ports 0 and 2 will be TE and E1).
#XPP_PRI_SETUP='
#	CONNECTOR/usb-0000:00:1d.7-1/XPD-01=NT,E1
#	NUM/*/XPD-0[13]=NT,E1
#	'
-----------------------------------------------------------

/etc/zaptel.conf
~~~~~~~~~~~~~~~~

Astribank 8
^^^^^^^^^^^
    fxoks=1-14

Astribank 6FXS/2FXO
^^^^^^^^^^^^^^^^^^^
    fxoks=1-12
    fxsks=13-14

Astribank 16: 8FXS/8FXO
^^^^^^^^^^^^^^^^^^^^^^^
    fxoks=1-14
    fxsks=15-22

Astribank 4 BRI
^^^^^^^^^^^^^^^
    # Assumed ports settings:
    # Ports 1,3: TE
    # Ports 2,4: NT
    span=1,1,1,ccs,ami
    span=2,0,1,ccs,ami
    span=3,2,1,ccs,ami
    span=4,0,1,ccs,ami
    bchan=1-2,4-5,7-8,10-11
    dchan=3,6,9,12

Astribank 4 PRI E1
^^^^^^^^^^^^^^^^^^
    # Assumed ports settings:
    # Ports 1,3: TE (CPE)
    # Ports 2,4: NT (Net)
    span=1,1,1,ccs,hdb3,crc4
    span=2,0,1,ccs,hdb3,crc4
    span=3,2,1,ccs,hdb3,crc4
    span=4,0,1,ccs,hdb3,crc4
    bchan=1-15,17-30,31-45,47-60,61-75,77-90,91-105,107-120
    dchan=16,46,76,106

Astribank 4 PRI T1
^^^^^^^^^^^^^^^^^^
    # Assumed ports settings:
    # Ports 1,3: TE (CPE)
    # Ports 2,4: NT (Net)
    span=1,1,1,esf,b8zs
    span=2,0,1,esf,b8zs
    span=3,2,1,esf,b8zs
    span=4,0,1,esf,b8zs
    bchan=1-23,25-47,49-71,73-95
    dchan=24,48,72,96
  

/etc/asterisk/zapata.conf
~~~~~~~~~~~~~~~~~~~~~~~~~
Astribank 8
^^^^^^^^^^^   
    [channels]
    signalling=fxo_ks
    ; The real analog ports:
    context=from-internal
    echocancel=yes
    ; echocancelwhenbriged=yes
    ; echotraining=no
    channel => 1-8

    ; output ports:
    context=astbank-output
    channel => 9-10
    ; input ports:
    immediate=yes
    context=astbank-input
    channel => 11-14
    immediate=no

Astribank 6FXS/2FXO
^^^^^^^^^^^^^^^^^^^   
    [channels]
    signalling=fxo_ks
    ; The real analog ports:
    context=from-internal
    echocancel=yes
    ; echocancelwhenbriged=yes
    ; echotraining=no
    channel => 1-6

    ; output ports:
    context=astbank-output
    channel => 7-8
    ; input ports:
    immediate=yes
    context=astbank-input
    channel => 9-12
    immediate=no

    ; FXO ports
    signalling=fxs_ks
    context=from-pstn
    callerid=asreceived
    channel => 13-14

Astribank 16: 8FXS/8FXO
^^^^^^^^^^^^^^^^^^^^^^^   
    [channels]
    signalling=fxo_ks
    ; The real analog ports:
    context=from-internal
    echocancel=yes
    ; echocancelwhenbriged=yes
    ; echotraining=no
    channel => 1-8

    ; output ports:
    context=astbank-output
    channel => 9-10
    ; input ports:
    immediate=yes
    context=astbank-input
    channel => 11-14
    immediate=no

    ; FXO ports
    signalling=fxs_ks
    context=from-pstn
    callerid=asreceived
    channel => 15-22

Astribank 4 BRI
^^^^^^^^^^^^^^^    
    ; Assumed ports settings:
    ; Ports 1,3: TE
    ; Ports 2,4: NT
    [channels]
    switchtype = euroisdn
    callerid = asreceived
    
    ; TE ports:
    signalling = bri_cpe_ptmp
    ;signalling = bri_cpe
    context = from-pstn
    group = 1,11
    channel => 1,2
    
    group = 1,13
    channel => 7,8
    
    ; NT ports:
    signalling = bri_net_ptmp
    ;signalling = bri_net
    context = from-internal
    group = 2,12
    channel => 4,5
    
    group = 2,14
    channel => 10,11

Astribank 4 PRI E1
^^^^^^^^^^^^^^^^^^ 
    ; Assumed ports settings:
    ; Ports 1,3: TE
    ; Ports 2,4: NT
    [channels]
    switchtype = euroisdn
    callerid = asreceived
    
    ; TE ports:
    signalling = pri_cpe
    context = from-pstn
    group = 1,11
    channel => 1-15,17-30
    
    group = 1,13
    channel => 61-75,77-90
    
    ; NT ports:
    signalling = pri_net
    ;signalling = pri_net
    context = from-internal
    group = 2,12
    channel => 31-45,47-60
    
    group = 2,14
    channel => 91-105,107-120

Astribank 4 PRI T1
^^^^^^^^^^^^^^^^^^ 
    ; Assumed ports settings:
    ; Ports 1,3: TE
    ; Ports 2,4: NT
    [channels]
    switchtype = national
    callerid = asreceived
    
    ; TE ports:
    signalling = pri_cpe
    context = from-pstn
    group = 1,11
    channel => 1-23
    
    group = 1,13
    channel => 49-71
    
    ; NT ports:
    signalling = pri_cpe
    ;signalling = pri_net
    context = from-internal
    group = 2,12
    channel => 25-47
    
    group = 2,14
    channel => 73-95


/etc/asterisk/extensions.conf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sample dialplan (extensions.conf) for all the above:

-----------------------------------------------------------
[phones-zap]
; 6001 will dial to channel 1, 6020, to Zaptel channel 20, etc.
exten => _6XXX,1,Dial(ZAP/${EXTEN:1})
; Useful for debugging trunks. Will potentially allow users to
; bypass context limitations.
;exten => _6XXX.,1,Dial(ZAP/${EXTEN:1:3}/${EXTEN:4})

[trunk]
; A number that begins with 9: dial it through a trunk
; (we put FXO channels and TE channels in group 0).
; The leading 9 is stripped.
exten => _9.,1,Dial(Zap/g0/${EXTEN:1})
; dialing a number that begins with 83 will dial it through
; span 3, and so forth. The two leading digits are stripped.
; (Each digital span is also added to group 10+span number).
exten => _8X.,1,Dial(Zap/g1${EXTEN:1:1}/${EXTEN:2})

[from-internal] 
; The context of FXS ports: analog phones.
; They are allowed to dial to all other phones 
include => phones-zap 
; They are also allowed to call through the trunk: 
include => trunk
; some simple tests:
include => astbank-test

[from-pstn] 
; Calls from the PSTN enter here. Redirect calls to an IVR 
; or a default extension in the s context here. In this case we  
; redirect calls to Zaptel channel 1: 
exten => s,1,Dial(Zap/1) 

; Alternatively, the following will redirect you to the demo IVR 
; from the sample extensions.conf of Asterisk:
include => demo

; An extra context with some simple tests
[astbank-test]
; 200: echo test
exten => 200,1,Answer
exten => 200,n,Wait(1)
exten => 200,n,Echo()
exten => 200,n,Hangup

; 203: say extension number. Will only work if caller ID 
; is properly set in zapata.conf / zapata-channels.conf
exten => 203,1,Answer
exten => 203,n,Wait(1)
exten => 203,n,SayNumber(${CALLERID(num)})
exten => 203,n,Hangup

[astbank-input] 
exten => s,1,Set(ZAP_CHAN=${CUT(CHANNEL,-,1)}) 
exten => s,n,Set(ZAP_CHAN=${CUT(ZAP_CHAN,/,2)}) 
; 11 is the number of the first input port. At least in the sample 
; configuration below. 
;exten => s,n,Set(INPUT_NUM=$[${ZAP_CHAN}-11)]) 
; The sample below just logs the signal.  
exten => s,n,NoOp(Got signal from Zaptel Channel ${ZAP_CHAN}) 
; Alternatively: 
;exten => s,n,System(run something) 

; No. We did not forget the context astbank-outputs. Output 
; ports only get calls from the PBX. Thus they don't need a context 
; of their own. Sending them to a context of their on makes 
; 'zap show channels' in the CLI provide useful display, though.
-----------------------------------------------------------




Troubleshooting
---------------
The following commands provide useful information for debugging:

lsusb Test
~~~~~~~~~~
Check USB level status. You can use one of the following utilities for it:

  zaptel_hardware -v
       or
  lsusb | grep e4e4

- Look for the USB Product ID (the second number after e4e4).
- If you see *11x2* (e.g: 1152)- the FPGA firmware has been loaded.
  Move on.
  zaptel_hardware will also show you some more details if the driver
  is loaded while the lsusb will just list the device.
- If it shows something as product ID *11x0* - the USB firmware is not
  loaded. Maybe you need to run fxload. Or maybe just unplug and plug again
  the device. Also make sure that you have fxload installed.
- If lsusb shows the Product ID as *11x1* - only the USB firmware is loaded 
  and not the FPGA firmware is loaded. If this is still the case after 
  a while - either the firmware loading has failed or you don't have
  fpga_load. Make sure you have libusb-dev(el) installed when
  building Zaptel. After you have installed it, you may need to re-run
  ./configure .
- It should list all of your Astribank devices. If it doesn't (for
  more than period of time needed for the initial firmware
  loading) - Check that the Astribank is connected indeed.


Zaptel Registration
~~~~~~~~~~~~~~~~~~~
Check if the Astribank spans are registered in Zaptel

  zt_registration

- This should give useful results after the drivers have identified
  and your devices are initialized.
- It should list all Astribank XPDs. For each of them it should write
  "on" or "off". If the registration status is "off", then it means that
  the span has not been registered in Zaptel and therefore can not be used
  yet.
- Registration is normally done as part of `/etc/init.d/zaptel start`.
  If you want to register the spans manually, then run command:
  `zt_registration on` .
- Disabling of the automatic Astribank spans registration give you full
  control on the order of Zaptel spans. See the module parameter
  **zap_autoreg** for the further details.


Zaptel Level Information
~~~~~~~~~~~~~~~~~~~~~~~~
You can get some information regarding Zaptel channels by running one of the
following commands:

    lszaptel
       or
    cat /proc/zaptel/*

- Those two are almost the same. The lszaptel produced more correctly sorted
  output if you have more than 10 spans, and also make the output listing
  looks a little bit nicer.
- You can see if your Zaptel spans and channels were loaded, if
  they were configured by ztcfg and if they are in use (typically by
  Asterisk).
  For example:
  Not configured Astribank FXS channel will be displayed as:

     42 FXS

- When a channel has been configured with *ztcfg* (that applies
  /etc/zaptel.conf), you will see an extra column for the signalling
  type of the channel. The same channel after it has been configured:

    42 FXS        FXOKS

- If a program (which is typically Asterisk) uses it, you'll see:

    42 FXS        FXOKS      (In use)



Asterisk Level Information
~~~~~~~~~~~~~~~~~~~~~~~~~~
  asterisk -rx 'zap show channels'

- If you get error "Unable to connect to remote asterisk" then it
  means that the Asterisk is not running. It is possible that Asterisk
  has failed to start due to misconfigured zapata.conf or whatever reason.
  Check /var/log/asterisk/messages or /var/log/asterisk/full .
- If you get the error that "there is no such command" then it means that
  chan_zap.so is not loaded. There are two reasons for such problem:
  * chan_zap.so is not even built. Check if the file exists:

       ls -l /usr/lib/asterisk/modules/chan_zap.so

  * the chan_zap.so file exists but it is not loaded. Try to load it manually:

       asterisk -rx 'load module chan_zap.so'

- You see "pseudo" channel only. It means that you have not configured any
  channels. If you have configured channels in zapata.conf, you may
  need either to restart the Asterisk or unload/load chan_zap.so manually.
  You can use the following Asterisk CLI commands for it: `unload chan_zap.so` 
  and `load chan_zap.so`


Known Issues
~~~~~~~~~~~~
Empty /proc dir
^^^^^^^^^^^^^^^
.Symptoms:
- Error message:

  "ERR-xpd_fxo: XBUS-00/XPD-00: Failed initializing registers (-22)"
  
- Likewise for all XPDs. 
- The directory /proc/xpp exists but is empty (not even the files 
  'xbuses' and 'sync').

.Cause:
The driver failed to recreate the procfs directory /proc/xpp and hence
everything under it. This is because it has already existed. And it
existed because a process still uses it. This is typically because you
have a shell whose working directory is /proc/xpp or somewhere under
it:

  # lsof /proc/xpp
  COMMAND  PID USER   FD   TYPE DEVICE SIZE       NODE NAME
  bash    2741 root  cwd    DIR    0,3    0 4026532684 /proc/xpp

.Fix:
Move that process from that directory, or close the file it uses from
under /proc/xpp and reload the zaptel / xpp drivers.


Bad Firmware Version
^^^^^^^^^^^^^^^^^^^^
.Symptoms:
- An Astribank finishes initialization quickly, the /proc/XBUS-nn
  directory has no XPD-mm subdirectories.
- Error in the kernel logs about:

  NOTICE-xpp: XBUS-00: XPD at 00: type=6.0 has bad firmware revision 2.6 

.Cause:
This is normally caused by an Astribank with an older firmware connected
to a 

The protocol version supported by the firmware will typically be the same 
one as in the device initialization scripts installed to 
/usr/share/zaptel . Hence if this version installed 
`/usr/share/zaptel/init_card_3_29` it will probably include firmware of 
protocol version 29.

.Fix:
Reset the firmware:

  /usr/share/zaptel/xpp_fxloader reset

Or disconnect the Astribank from the power and reocnnect. On some older 
versions of the USB firmware resetting the firmware (or any operation of 
fpga_load) would fail if the driver is loaded. Hence you would need to 
run `rmmod xpp_usb` . In the end, reload the drivers.


USB Errors at Shutdown
^^^^^^^^^^^^^^^^^^^^^^
.Symptoms:
You see USB-related errors similar to the following whenever you shut
down the drivers of the Astribank or disconnect its drivers:

  ERR-xpp_usb: XBUS-00: Failed to submit a receive urb

.Cause:
This is a normal part of the shutdown of the USB connection. 

.Fix:
Ignore them. Unless the USB should not have disconnected at that time.


BRI Layer 1 Down
^^^^^^^^^^^^^^^^
.Symptoms:
With the BRI module only, and not in the middle of an active call, you
notice that suddenly the line goes down. The LED of the port stops
blinking, layer1 not listed as "active" in the bri_info file in
/proc/xpp, and the span is in RED alarm in Zaptel.

You may also see an error message such as:

  NOTICE-xpd_bri: XBUS-00/XPD-02: D-Chan RX Bad checksum: [2A:01=FC] (252)

from the exact time of the disconnecting.

.Cause:
This is expected with most european BRI PtMP providers. If they support
PtMP, they are normally also expected to support ISDN phones, that get
the power from the provider. And thus they shut down the line whenever
there's no active call. 

Sometimes the line is shut down in the middle of a layer 2 message. In
the BRI driver the HDLC decoding/encoding is done in the card. In that
case we may get the above error.

.Fix:
Normaly this is not a problem. The driver will re-establish a connection
once a new call needs to be made.


Both default and sysconfig Exist
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.Symptoms:
The firmware fails to load. Manually running xpp_fxloader gives:

  Both '/etc/default/zaptel' and '/etc/sysconfig/zaptel' exist

Alternatively: an initialization script fails and gives the error

  An '/etc/default/zaptel' collides with 'etc/sysconfig/zaptel'

.Cause:
/etc/default/<service name> is the place used in Debian-based 
systems for initialization scripts. /etc/sysconfig/<service name> is
used in Redhat and similar for the same purpose. For historical reasons
many of our programs read configuration from there: either from
/etc/default/zaptel or from /etc/sysconfig/zaptel .

The problem is what to do if both of those exist. Selecting an arbitrary
one can lead to unexpected results. Likewise sourcing both of them.
Therefore we prefer to fail in a noisy and expected way. In the future
we will probably me to reading configuration from a file under /etc/zaptel .

.Fix:
Remove one of those two. There should be no reason to have both on the
same system.


Astribank not initialized: Premature packet end
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.Symptoms:
After upgrading to Zaptel 1.4.12 / 1.2.25 the initialization of the
Astribank times out. In the logs you see:

  kernel: NOTICE-xpp: XBUS-00(00): FIRMWARE: ERROR_CODE CODE = 0x3 (Premature packet end) 

.Cause:
When an Astribank is detected, the driver asks it what is its version
and what components it has. Normally if the version of the firmware and
of the driver does not match the driver gives an ugly message and fails
the initialization.

However in the change of the protocol between versions 2.9 (29) and 3.0
(30), the response that the new driver recieves from a device with the
old version is now considered to be an illegal packet and gets
discarded. As a result, the Astribank waits till time-out for the
initilization to end.

.Fix:
Reset the firmware of the Astribank by either:

  /usr/share/zaptel/xpp_fxloader reset

or disconnecting it from the power and reconnecting it.


Reference
---------
LEDs Indication
~~~~~~~~~~~~~~~
The Astribank has 4 global indication leds and one or two per-port leds.
On some of the models the LEDs are located on the left side on the front
panel. If there are no separate LEDs there, then the red LEDs of the
upper left-most ports of the device are used as the indication LEDs. Don't 
confuse them with green port status LEDs.

The first led is the "Power" led. It is on if the unit gets power.
The second led is the "Active" led, which is on when there is at 
least one "active" port (in a call / off-hook, though the meaning of this is 
different in BRI).
The last led is called "Hardware OK", but is actually only is on in case of  
the hardware failure.

The third led is the "Sync" led. If it blinks, the device is synchronized 
with the driver on the computer. If the device is selected to be the  
synchronization source for all of the Astribank devices then it will blink
a quick single blink.
If the device gets synchronization from the driver, it will blink in a 
more steady frequency.

"Double blink" indicates that the unit has an FXO module, and still is
getting synchronization from the computer, and is not the synchronization
source.

The per-port green led on analog (both FXS and FXO) indicates that the
port is off-hook.

On the BRI, the green led indicates a TE port whereas an orange led
indicates an NT port. If the led is solid, the port is down (not even
layer-1 connection is up). If it is blinking a double blink, layer 1
is up. A slower single blinking indicates that layer 2 is up as well
(which means that Asterisk is driving the port).


PRI Ports Configuration
~~~~~~~~~~~~~~~~~~~~~~~
Astribank PRI module has two RJ-45 sockets for each PRI port. The lower
socket provides typical PRI CPE side wiring: Rx- pins 1,2; Tx - pins 
4,5. The upper socket provides typical PRI Network side  wiring: Rx- pins
4,5; Tx - pins 1,2. The both sockets are permanently active and you can 
use any of them regardless of any configuration parameters (Both
connectors are live. And connecting both of them with a flat 8-wire
ethernet cable is a simple way to do a loop test for the port).


For each port there are two optional parameters that define its
behavior:

Each port in the PRI module can be configured either as E1 or T1. The
port type defaults to E1 and can be changed to T1 in the Zaptel Init 
Configuration File.

The Astribank xpp driver uses that information for correct hardware
initialization that is performed before the Zaptel span registration
process takes place. Because of that, xpp driver can't use the 
information from file zaptel.conf.

Another parameter that also can be defined in the Zaptel Init
Configuration File is the function group TE (CPE) or NT (Network). This
parameter is used for (a) building correct Zaptel & Asterisk
configuration by genzaptelconf and (b) control RJ-45 sockets LEDs for 
better visual port control:

A port in the PRI module can be either E1 (default) or T1. It can also be 
either "TE" (default) or "NT".

TE::
  Green LED of the lower socket will light. Hint that this is a TE
  (CPE) port. This is the default.

NT::
    Orange LED of the upper socket will light. Hint that this is an
    NT (network) port.

To set them to a non-default value, you should use the variable
XPP_PRI_SETUP in the 
xref:_zaptel_init_configuration_file[Zaptel Init Configuration File]
(/etc/sysconfig/zaptel on Redhats, /etc/default/zaptel on Debians).
This value is a whitespace-separated list of conditions. When a port is 
initialized it checks those conditions and uses the first one that 
matches.

Match expressions may be:
- CONNECTOR/usb..../XPD-nn	To identify by physical connector
- NUM/XBUS-mm/XPD-nn		To identify by bus number

Match expressions may contain "wildcards":

- * matches zero or more characters.
- ? matches one charater
- [xyz] - any of 'x', 'y', or 'z'.

For each line you should define both if it is E1 or T1 and if it is NT
or TE.

The list implicitly contains an 'NUM/*=TE,E1' catch all default, appended
to its end.

A number of useful examples. Note that you should use just one of them.
---------------------------------------------
# All ports are E1 and CPE
#XPP_PRI_SETUP=  #no need to set it

# All ports are T1 and CPE:
XPP_PRI_SETUP='NUM/*=T1,TE'

# Now you want to test a loop between ports 1 and 2 and between 
# port 3 and 4. So let's make ports 2 and 4 network:
XPP_PRI_SETUP='NUM/*/XPD-0[24]=E1,NT'

# The same with T1. In this case we also need to set the default of all 
# the others to T1. Note that we can use more than one item and the
# first one that matches counts:
XPP_PRI_SETUP='
  NUM/*/XPD-0[24]=T1,NT
  NUM/*=T1,TE
'

# Actually, there is an implicit 'NUM/*=E1,TE' added to the end of the
# value and set as the value if there is none. This is how the default
# is set.

# If you have more than one Astribank and you wish to configure
# different Astribanks differently, you can use the CONNECTOR option:
# e.g: set one specific Astribank as E1 network. The others default to
# E1 CPE:
XPP_PRI_SETUP='CONNECTOR/usb-0000:00:10.4-4/*=E1,NT'

# Theoretically you could use: XPP_PRI_SETUP='NUM/XBUS-01/*=E1,NT'
# but the XBUS number depends on the specific load order and is thus
# might differ in a manual load and a system boot.
---------------------------------------------

This is currently implemented by writing a value to the 
xref:_proc_xpp_xbus_nn_xpd_mm_pri_info[pri_info file in procfs], but
that may change in future versions.


Device Startup
~~~~~~~~~~~~~~
This section describes in great depth the initialization of the Xorcom
Astribank. Normally it would not be really needed, as the standard
installation of Zaptel should put everything in place.

Terminology
^^^^^^^^^^^
There are some technical terms that are used in this document and in the
driver / zaptel.

span:
Zaptel breaks the channels it knows about to logical units called
"spans". A port in a E1/T1/ISDN card is usually a span. An whole
analog card is also a "span". You can see the list of spans as the list
of files under /proc/zaptel directory or in output of the zttool
utility.

XBUS:
A funny way to call an Astribank device.

XPD:
Basically this is a logical unit of the Astribank. It will be registered in
Zaptel as a single span. This can be either an analog (FXS or FXO)
module or a single port in case of a BRI module.


Loading Firmware
^^^^^^^^^^^^^^^^
Normally this is done using the script /usr/share/zaptel/xpp_fxloader.
If it works fine, you don't need to bother reading this section.
Once the firmware is loaded the USB Vendor ID and Product ID of the Astribank
became to be e4e4 11x2, and now the driver can pick it up.

First and foremost: the simplest and most useful tool to debug problems
is lsusb. The output of lsusb should show you if the device is connected
if its firmware is loaded. 

The firmware files are named *.hex. They are presented in the text
hexadecimal format The files are copied from xpp/utils to /usr/share/zaptel
folder during the Zaptel installation.

The Astribank needs a firmware loaded into it. Without the firmware, 
the device will appear in lsusb with Vendor ID e4e4 and Product ID 1130.
The firmware loading process consists of two stages. In the first stage the
"USB" firmware is loaded by using program fxload. When the first stage is
completed the Vendor ID is e4e4 and the Product ID is 1131.

You can use the following command in order to load the "USB" firmware
manually:

  fxload -t fx2 -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/USB_FW.hex

where,

fxload::
  A standard program that is typically part either of package 'fxload' 
  or 'hotplug-utils' . 
/proc/bus/usb::
  The mount point of the USB file-system (usbfs).
MMM::
  the first number (bus number)
NNN::
  the second number (device number) you see for the device in lsusb

If the loading process has been completed successfully, the device 
disconnects and then connects again itself with USB Product ID 1131 
(and a new device number).

In the second stage, the "FPGA" firmware is loaded.
The second-stage firmware loading is performed by using program fpga_load, 
which is built in the directory xpp/utils and then copied to folder 
/usr/sbin during Zaptel installation.

The command syntax is similar to the syntax of fxload. You can use the 
following command in order to load the FPGA firmware manually:

  fpga_load -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/FPGA_1151.hex

Please note, that  NNN value differs from that that was used for the 
fxload command due to the fact that device has "reconnected" itself 
with another Product ID number. So you need to run lsusb again and get 
the new NNN value. Usually, the new value is equal to the old value 
incremented by 1.


Firmware Loading with Hotplug
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Hotplug framework was popular for hot-plugging different devices and 
usually also for automatic device drivers loading. If Hotplug is used in 
your system, you'll see many files in folder /etc/hotplug. Hotplug will 
automatically load the most relevant USB and PCI kernel modules according 
to the USB and PCI IDs provided by devices. Please note, that if the 
Hotplug framework is in place and the correct configuration files are 
located in the right place, then the firmware should be loaded automatically.

In order to get the Hotplug framework to load the firmware into the 
Astribank automatically, the configuration file xpp_fxloader.usermap and
the script xpp_fxloader should be copied into /etc/hotplug/usb/ . This is 
done by 'make -C xpp/utils install'.

File xpp_fxloader.usermap includes a map of USB IDs and the command to run 
when such devices are encountered. It instructs the Hotplug to run the script 
xpp_fxloader from that directory. This is also done by 'make -C
xpp/utils install' .

When xpp_fxloader is run without any parameters it assumes that it was
run by the hotplug scripts. Then it will check if the "add" event was 
accepted and if so, xpp_fxloader will install the required firmware file. 
The xpp_fxloader will be called twice, as after the load of the USB 
firmware the device will re-enumerate itself and thus "unplug" and 
"replug" in order to load the FPGA firmware.


Firmware Loading with UDEV
^^^^^^^^^^^^^^^^^^^^^^^^^^
The UDEV framework has replaced Hotplug in most recent systems. If you
have a recent 2.6 system without Hotplug and with many files in folder
/etc/udev, then there are good chances that are you using udev.
As in case of Hotplug, if your udev framework is configured properly
then the firmware should be loaded automatically.

In order to get udev to automatically load the firmware into the Astribank, 
the configuration file xpp.rules should be copied into folder /etc/udev/rules.d 
and the script xpp_fxloader should be copied into folder /etc/hotplug/usb/ . 
This is done by 'make -C xpp/utils install' during Zaptel installation.

File xpp.rules instructs the udevd daemon to run xpp_fxloader script with
the option "udev" and with the Astribank USB ID obtained from the 
device when it is plugged in.
Please note, that exactly like in case of Hotplug, the xpp_fxloader will be
called twice by the udevd. First time for the USB firmware loading and the 
second time for FPGA firmware loading.


Firmware Resetting
^^^^^^^^^^^^^^^^^^
Newer versions of the USB firmware can now be reset using 'fpga_load -r'.

Also you can try the following:

  /usr/share/zaptel/xpp_fxloader reset
  # if asterisk was running: you may need to stop/restart it now. 
  # if there are some "disconnected" spans in /proc/xpp/xbuses
  # wait a while, until you see the 1152 IDs again, and then:
  /etc/init.d/zaptel start
  # and start/restart asterisk.


Loading The Modules
^^^^^^^^^^^^^^^^^^^
Here is what should happen:
In short: you should plug the Astribank device(s) or have them plugged in at
the boot time. Then all the modules should be loaded automatically.
You will see xpp_usb , xpd_fxs and, possibly, xpd_fxo in the modules list
(the output of lsmod).

After the module xpp is loaded, you'll also be able to see the directory
/proc/xpp. For any Astribank device discovered, you will see there a 
directory /proc/xpp/XBUS-n (where n is a number: typically 0). Once a unit have
been discovered you'll see subdirectories: /proc/xpp/XBUS-n/XPD-m (where
m may be another number: 0, 1 ,etc).

Now to the ugly details:

The driver of the Astribank is composed of several modules: 

* xpp     - the basic module, that communicates with Zaptel and provides
            some common services to other modules.
* xpd_fxs - the module for controlling FXS modules.
* xpd_fxo - the module for controlling FXO modules. 
* xpd_bri - the module for controlling BRI modules. 
* xpd_pri - the module for controlling E1/T1 modules. 
* xpd_usb - the module that holds the functionality needed to connect to the
            USB bus.

All modules depend on xpp, and modprobing them will install xpp as well.
However the xpd_* modules are installed on-demand: no need to install
the xpd_fxo if you have only Astribank FXS.

Once an Astribank device connected and the firmware is loaded, the
Vendor-ID/Product-ID of the device will be  e4e4/1132 . The handler for that
combination is listed as the kernel module xpp_usb. Therefore, the system
runs 'modprobe xpp_usb' if that module is not already loaded.

The module xpp_usb depends on the zaptel and xpp modules. Both of them 
are loaded before xpp_usb. As usual, parameters and rules form
/etc/modprobe.conf and/or from /etc/modprobe.d/* will be applied to 
the module.

When command 'modprobe xpp_usb' returns, the span type specific modules
(e.g., xpd_fxs, xpd_fxo) may or may not have been loaded yet.

At this point the xpp driver "asks" the box about its software
(firmware) version) and the type of telephony modules it has. According 
to the answers it receives, the xpp driver will "modprobe" the required 
xpd_* modules. 


Device Initializations Scripts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The chips in the device need to be initialized. This requires sending a
bunch of values to certain registers in those chips. We decided that
hardwiring those values in the driver code is not a good idea.
Before registering a XPD as a span in Zaptel, we run an initialization
script: /usr/share/zaptel/init_card_N_MM (
where,

* N  - is 3 for an FXS span and 4 for an FXO span, and 6 or 7 for BRI.
* MM - is a version number. Currently it equals 26

Those scripts must be executable. Funny things happen if such a script
exists but is not executable.

If because of some reasons this fails (the script is not in the place, or the
file doesn't have the executable permissions), then you will get an error 
message in the logs and the XPD will then be removed (you won't see directory
for that XPD under the corresponding /proc/xpp/XBUS-* directory) and will not
be registered in Zaptel.

As the XPD is initialized, you'll see the green LEDs of the ports steadily 
turn on and later off ("a train of lights"). This is a bit slower than the 
faster "blinking" when the XPDs register as Zaptel spans. The initialization 
of an FXS XPD may take a few seconds.


Registering in Zaptel
^^^^^^^^^^^^^^^^^^^^^
The XPDs will not automatically register as Zaptel spans. This is
intended to allow you to set the registration order (and hence the order
of Zaptel spans and channels) among multiple Astribank devices,
or between an Astribank and a different Zaptel device.

When the XPD registers to Zaptel, all the green LEDs will be lit for a
short while. 

Spans are normally registered with the utility zt_registration. Simply
running 'zt_registration' shows the available XPDs and whether or not
they are registered. To register: 

  zt_registration on

For a system with several spans you'll see a "fast train of lights".

If you have multiple Astribank devices, zt_registration will register
them by the order of the "connector" field. This means that as long as
the same Astribank is connected to the same port, the order of plugging
is not important..

zt_registration checks if a span is registered or tries to register a
span using the file /proc/xpp/XBUS-nn/XPD-mm/zt_registration . Reading
from that file returns 0 if the span is unregisters or 1 if it is
registered. You can register a span or ask to unregister it by writing 1
(register) or 0 (unregister) to that file. Registration should
generally always succeed. Unregistration may fail if a span is in use.

You may choose to register the XPDs in Zaptel automatically. This may
make the startup sequence a bit simpler, but is generally not
recommended on a system with more than one Astribank or an Astribank and
a different Zaptel device. This behavior may be defined by setting 
parameter zap_autoreg in the modprobe configuration file (A file under 
/etc/modprobe.d or /etc/modprobe.conf):

  options xpp zap_autoreg=1


Zaptel And Above
^^^^^^^^^^^^^^^^
From here you get a standard Zaptel span. It still needs to be
configured by ztcfg and used by a program such as Asterisk like any
other Zaptel device. In order for you to get a dial-tone in a phone
connected to the FXS port or a fully synchronized BRI port (layer 2
activated, as signalled by a more steady blink) you will actually need
both the span configured by Zaptel and the channels configured in
Asterisk.

You should generally refer to the general Zaptel documentation on how to
configure those levels. e.g, the README file in the top-level directory,
and

  http://voip-info.org/wiki/view/Asterisk+config+zapata.conf[]


Zaptel now includes a utility called genzaptelconf (written as a big
ugly shell script) to configure Zaptel automatically as good as
possible. For analog channels it works quite well (because, IMHO, the
"configuration" level on Zaptel should be optional there - there are
already sane defaults). For digital spans - BRI and PRI , it may take
some tuning.

Alternatively, write you own configuration, based on the sample from the
"Sample Configurations" section.


/proc Interface
~~~~~~~~~~~~~~~
The Astribank drivers provide their own /proc interface under /proc/xpp.
Here we review the more useful details of the procfs interface. There
are many other debugging details that are exposed through the procfs
interface. 

Also note that those details are subject to changes. Generally the
recommended stable interface are the Zaptel-perl utilities from the
xpp/utils directory.


/proc/xpp/xbuses
^^^^^^^^^^^^^^^^
File /proc/xpp/xbuses lists the connected Astribank devices (one line 
per device).

A device is normally has status "connected". The status "missing" means that
the device has been disconnected, but Asterisk still holds channels from it
open.


/proc/xpp/sync
^^^^^^^^^^^^^^
A read/write file. It contains information about current synchronization 
source. You can change the synchronization source by writing special 
command to the file. For example, command
   echo SYNC=01 > /proc/xpp/sync

Possible values are:

<number>::
  Make the Astribank XBUS-<number> the sync source for other Astribanks.

ZAPTEL::
  Make the Astribanks synchronize with the Zaptel timing master span.
  You probably need this to get faxes from a non-Astribank adapter to an
  Astribank.

Though you'll normally use xpp_sync(8) for that.

For each Astribank device there is folder /proc/xpp/XBUS-nn and for each device
module (span in the terms of Zaptel) there is folder /proc/XBUS-nn/XPD-mm.


/proc/xpp/XBUS-nn/waitfor_xpds
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Reading from this file only returns when the Astribank has finished
initialization of the XPDs or in case of a timeout. It prints the number
of XPDs to initialize, and the number initialize. Unless something went
wrong, those two numbers are the same. Once the span was initialized,
reading from this file returns immediately:

  XPDS_READY: XBUS-00: 3/3


/proc/xpp/XBUS-nn/XPD-mm/zt_registration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
is a read/write file. Reading from it gives 0 if the span is
unregistered, or the span number if it is registered.

Writing to it allows manual registration / unregistration from Zaptel:
writing 1 registers a span (if it wasn't already registered) and writing
0 attempts to unregister it (if it is registered.  Span unregistration 
will fail if some channels from the span are used  (e.g: by Asterisk).

A more convenient interface to this is the command zt_registration that
registers or unregisters all the spans at once with a predefined order,
and this is what you should normally use.

Alternatively you can use the parameter zap_autoreg to register spans
automatically. But this is only recommended on a system with a single
Astribank and no other Zaptel device.


/proc/xpp/XBUS-nn/XPD-mm/summary 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Contains detailed information about port statuses of the device module 
(off-hook, on-hook etc.) For example, you can run the following command
in order to monitor the port statuses in the real time:

  watch -n1 cat /proc/xpp/XBUS-00/XPD-00/summary


/proc/xpp/XBUS-nn/XPD-mm/slics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Provides direct read/write interface to the registers of each chip. 
Reading from the file shows the result of the last read request. To make
either a read request or a write request you need to write to that file.

It is mainly used by the initialization scripts (card_init_*).

Incorrect usage of this file is one possible way of damaging the
Astribank.


/proc/xpp/XBUS-nn/XPD-mm/fxo_info
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Only for FXO modules. Apart from showing the status of the LEDs, it also
shows for each FXO port if it is connected to a provider: look for the
value of "battery" for that specific port, and a bunch of other
characteristics of the port.


/proc/xpp/XBUS-nn/XPD-mm/bri_info
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In addition to the usual information about the LEDs, this file also
provides useful information regarding ISDN Layer 1 and Layer 2 status.
For example, you can run the following command in order to monitor
the Layer 1 port statuses for all BRI devices in the real time:

  watch -n1 -d 'grep "Layer 1:" /proc/xpp/XBUS-*/XPD-*/bri_info'

For the status of the D channel of the ports on all BRI spans, run:

  watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/bri_info'


/proc/xpp/XBUS-nn/XPD-mm/pri_info
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In addition to the usual information about the LEDs, this file also
provides useful information regarding ISDN Layer 1 and Layer 2 status.
For example, you can run the following command in order to monitor
the Layer 1 port statuses for all E1/T1 devices in the real time:

  watch -n1 -d 'grep "Layer 1:" /proc/xpp/XBUS-*/XPD-*/pri_info'

For the status of the D channel of the ports on all PRI spans, run:

  watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/pri_info'

Note: the layer 2 status is much more of a guesswork based on changes in
the contents of the channel that is supposed to be the D channel.

Writing to this file can be used to change the type of the device. The
device type can only be changed when the XPD is not registered as a
Zaptel span. The value is a whitespace-separated list of values that can 
be of:

E1::
  Provides 31 channels, of which channel 16 is normally the D-channel. 
  Common in places outside of North America and Japan. This is the 
  default setup.

T1::
  T1 provides 24 channels. The last one is normally the D-Channel.
  Common in North America.

TE::
  Use the bottom port (green LED) and don't invert any wiring. Hint to
  higher layers that this will be the TE side of the connection. This is
  the default setup.

NT::
  Use the top port (orange LED) and invert wiring (this is done to allow
  connecting an NT port and a TE port using a standard straight 8 wires 
  "ethernet" cable). Hint to higher layers that this will be the NT side 
  of the connection.

LOCALOOP::
  Set the device into local loop mode: loops the transmitted channels
  directly into the received channels.

NOLOCALLOOP::
  Ends local loop mode.

Normally those are set by the PRI initialization script . See the
definition of XPP_PRI_SETUP in 
xref:_zaptel_init_configuration_file[the sample Zaptel init 
configuration file] .


There are a bunch of other status files under /proc/xpp/.


/sys Interface
~~~~~~~~~~~~~~~
When an Astribank device loads it generates a device node in the bus 
'astribanks' in sysfs. You can see a directory for each device under 
/sys/bus/astribanks/devices/ and under it there are several attributes
for each Astribank (such as its connector string).

On each time an Astribank is initialized or destroyed a udev event is
generated. The rules from our sample udev rules file (xpp/utils/xpp.rules) 
make that event run the script /usr/share/zaptel/astribank_hook with the
parameter 'add' or 'remove', if such script exists. An example script
that just adjusts the Astribank sync settings is included in xpp/utils. 

cls::
  CLear Statistics: writing to this file clear the procfs statistics for
  this bus.

connector::
  Connector string for the device. The place to which the Astribank is
  connected. e.g: usb-0000:00:03.3-2

label::
  The label string of the Astribank unit. E.g: usb:00000135

status::
  'connected' (normal operation) or 'disconnected' (has been disconnected,
  some channels are still open).

timing::
  Provides some statistics in case the Astribank is not the sync source.
  The format of this file is subject to future changes.


Useful Module Parameters
~~~~~~~~~~~~~~~~~~~~~~~~
Compilation-time defaults for the all modules can be shown as part of the
description line for the parameter in the "modinfo" command output.

zap_autoreg (xpp)::
  Register spans automatically (1) or not (0). Default: 0. 
  Setting it simplifies operations with a single Astribank and no other 
  Zaptel hardware. However if you have such systems, automatic
  registration can cause the order of spans to be unpredictable.
  The standard startup scripts use 'zt_registration on' instead of this.

initdir (xpp)::
  This is the directory containing the initialization scripts.
  The default is /usr/share/zaptel .
  Setting this value could be useful if that location is inconvenient for you.

rx_tasklet (xpp)::
  Enable (1) or disable (0) doing most of the packets processing in
  separate tasklets. This should probably help on higher-end systems with
  multiple Astribanks.

debug (all modules)::
  It will make the driver to print tons of debugging messages. You can 
  set/unset the parameter at run-time. The parameter value is a bitmask 
  of several values. The different bits  meaning as it defined in 
  xpp/zap_debug.h: 

  * 0  - Disable debug messages
  * 1  - GENERAL - General debug comments.
  * 2  - PCM - PCM-related messages. Tends to flood logs.
  * 4  - LEDS - Anything related to the LEDs status control. The driver
         produces a lot of messages when the option is enabled.
  * 8  - SYNC - Synchronization related messages.
  * 16 - SIGNAL - Zaptel signalling related messages.
  * 32 - PROC - Messages related to the procfs interface.
  * 64 - REGS - Reading and writing to chip registers. Tends to flood
  	 logs.
  * 128 - DEVICES - Device instantiation, destruction and such.
  * 256 - COMMANDS - Protocol commands. Tends to flood logs.

  For example,

    echo 33 >/sys/modules/xpp/parameters/debug 

  forces module xpp to print general debugging messages (1) and procfs
  debugging messages (32).

vmwineon (xpd_fxs)::
  Enable (1) or disable (0) sending the voicemail message waiting indication
  signal to phones equipped with the Message Waiting neon lamp. It is 
  disabled by default because the feature requires extra work of the driver
  even when such a phone is not used and also may cause some unusual
  side effects with some phone models.

usb1 (xpp_usb)::
  Enable (1) or disable (0) support of USB1 devices. Disabled by default.

  USB1 devices are not well-tested. It seems that they don't work at all
  for Astribank BRI. Generally they should work with the current code, but
  we expect the voice quality issues. Hence we would like to make it
  very clear that you if you have a USB1 port (rather than a USB2 one, as 
  recommended) you will have to take an action to enable the device.

poll intervals (various)::
  There are various values which the driver occasionally polls the device
  for. For instance, the parameter poll_battery_interval for xpd_fxo
  to poll the battery, in order to know if the telco line is actually
  connected.

  The value of those parameters is typically a number in milliseconds. 
  0 is used to disable polling. Under normal operation there should be 
  no reason to play with those parameters.

dtmf_detection (xpd_fxs)::
  Enable (1) or disable (0) support of hardware DTMF detection by the 
  Astribank.


NOTE: XPP here does not stand for X Printing Panel, XML Pull Parser, 
X-Windows Phase Plane or XML Professional Publisher. It is simply the 
Xorcom Peripheral Protocol, which connects a computer to a XPD (Xorcom 
Peripheral Device). An XBUS (originally XPP Bus) is actually a single
Astribank device and the XPDs have become the single modules in it.