From 7e068801fbf82413ac0a5e63e586c268bd457434 Mon Sep 17 00:00:00 2001 From: tzafrir Date: Mon, 4 Feb 2008 23:00:48 +0000 Subject: Move kernel stuff to under kernel/ (merged branch /zaptel/team/tzafrir/move ) Closes issue #7117. git-svn-id: http://svn.digium.com/svn/zaptel/branches/1.4@3793 5390a7c7-147a-4af0-8ec9-7488f05a26cb --- kernel/xpp/README.Astribank | 1131 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1131 insertions(+) create mode 100644 kernel/xpp/README.Astribank (limited to 'kernel/xpp/README.Astribank') diff --git a/kernel/xpp/README.Astribank b/kernel/xpp/README.Astribank new file mode 100644 index 0000000..342c6a9 --- /dev/null +++ b/kernel/xpp/README.Astribank @@ -0,0 +1,1131 @@ +Xorcom Astribank Documentation +============================== +Xorcom Team +$Revision$, $Date$ + +This file documents the Zaptel drivers for the Xorcom Channel Bank. +The drivers reside in a separate subdirectory, 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 +~~~~~~~~~~~~~~~~ +On zaptel 1.2 you will need to run the following extra step to build the +Astribank drivers, apart from the standard 'make': + + make -C xpp/utils install + +In order to build the user space utilities, you will need the libusb-dev +package on Debian (and derivatives like Ubuntu) or libusb-devel on RedHat +(and derivatives like CentOS/Trixbox). + +Apart from the standard 'make install' in the zaptel directory, +run: + + make -C xpp/utils install + +Though this should be done automatically on zaptel >= 1.4.1 . + +PRI Port Setup +~~~~~~~~~~~~~~ +A port in the PRI module can be either E1 (default) or T1. It can also be +either "TE" or "NT". + +TE:: + Use the bottom port (green LED) and don't invert any wiring. Hint to + higher layers that this will be the TE (CPE) 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 (Net) + side of the connection. + +The value XPP_PRI_SETUP in the init configuration file (see example +below) can be used to change those defaults. This value is a +whitelist-separated list of conditions. When a port is initialized it +checks those conditions and uses the firs 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. + + +Sample Configurations +--------------------- +We generally recommend to generate the configuration by using utility +genzaptelconf. The following reference configuration will work for a +system where Astribank devices are used. + + +[[sect-default]] +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 hotplug 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 = bri_net_ptmp + ;signalling = bri_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 = bri_net_ptmp + ;signalling = bri_net + context = from-internal + group = 2,12 + channel => 25-47 + + group = 2,14 + channel => 73-95 + + +Please check, that the mailbox and callerid parameters generated by +genzaptelconf are good for you and change them if necessary. + + +If you have Astribank device with 8 FXS and 8FXO ports connected and set +up, then the Zaptel channels will be allocated as the following: + + root@rapid:~# cat /proc/zaptel/* + Span 1: XBUS-00/XPD-00 "Xorcom XPD #00/00: FXS" + + 1 XPP_FXS/00/00/0 FXOLS (In use) + 2 XPP_FXS/00/00/1 FXOLS (In use) + 3 XPP_FXS/00/00/2 FXOLS (In use) + 4 XPP_FXS/00/00/3 FXOLS (In use) + 5 XPP_FXS/00/00/4 FXOLS (In use) + 6 XPP_FXS/00/00/5 FXOLS (In use) + 7 XPP_FXS/00/00/6 FXOLS (In use) + 8 XPP_FXS/00/00/7 FXOLS (In use) + 9 XPP_OUT/00/00/8 FXOLS (In use) (no pcm) + 10 XPP_OUT/00/00/9 FXOLS (In use) (no pcm) + 11 XPP_IN/00/00/10 FXOLS (In use) (no pcm) + 12 XPP_IN/00/00/11 FXOLS (In use) (no pcm) + 13 XPP_IN/00/00/12 FXOLS (In use) (no pcm) + 14 XPP_IN/00/00/13 FXOLS (In use) (no pcm) + Span 2: XBUS-00/XPD-01 "Xorcom XPD #00/01: FXO" (MASTER) + + 15 XPP_FXO/00/01/0 FXSKS (In use) + 16 XPP_FXO/00/01/1 FXSKS (In use) (no pcm) + 17 XPP_FXO/00/01/2 FXSKS (In use) (no pcm) + 18 XPP_FXO/00/01/3 FXSKS (In use) (no pcm) + 19 XPP_FXO/00/01/4 FXSKS (In use) (no pcm) + 20 XPP_FXO/00/01/5 FXSKS (In use) (no pcm) + 21 XPP_FXO/00/01/6 FXSKS (In use) (no pcm) + 22 XPP_FXO/00/01/7 FXSKS (In use) (no pcm) + + + +/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. +----------------------------------------------------------- + + + + +Troubleshhoting +--------------- +The following commands provide useful information for debugging: + +* 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. + - 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. + +* 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. + +* Check the Zaptel 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) + +* Check the Asterisk 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: + (a) chan_zap.so is not even built. Check if the file exists: + + ls -l /usr/lib/asterisk/modules/chan_zap.so + + (b) 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` + + +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). + + +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 hotplugging 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 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 +hardwriting 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 + +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 initializaton +of an FXS XPD may take a few seconds. + + +Astribank in Sysfs +^^^^^^^^^^^^^^^^^^ +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. + + +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 unregisteres 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. Registeration should +generally always succeed. Unregistration may fail if a span is in use. + +You may choose to register the XPDs in Zaptel automatically, in order to +allow finer control of the process. 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 dialtone 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 toplevel 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. +(Note that the details of this interface are still potentially subject to +changes) + + +/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: + +:: + Make the Astribank XBUS- the sync source for other Astribanks. + +ZAPTEL:: + Make the astribanks synchronize with the Zaptel timing master span. + You probably ned 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 therms of Zaptel) there is folder /proc/XBUS-nn/XPD-mm. + + +/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 convient 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_*). + + +/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. + + +/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 recieved channels. + +NOLOCALLOOP:: + Ends local loop mode. + +Normally those are set by the PRI initialization script . See the +definition of XPP_PRI_SETUP in xref:sect-default[the sample Zaptel init +configuration file] . + +There are a bunch of other status files under /proc/xpp/. + + +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 systes with + multiple Astribanks. + +print_dbg (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. Tend 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 - procfs interface related messages. + * 64 - REGS - Reading and writing to chip registers. The driver produces + a lot of messages when the option is enabled. + + For example, + + echo 33 >/sys/modules/xpp/parameters/print_dbg + + 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 Wainting 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 or 0 + to disable. 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. -- cgit v1.2.3