diff options
Diffstat (limited to 'xpp/README.Astribank')
| -rw-r--r-- | xpp/README.Astribank | 256 |
1 files changed, 164 insertions, 92 deletions
diff --git a/xpp/README.Astribank b/xpp/README.Astribank index a240f36..ba39793 100644 --- a/xpp/README.Astribank +++ b/xpp/README.Astribank @@ -1,34 +1,37 @@ -This file documents the Zaptel drivers for the Xorcom Astribank8 Channel Bank. +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, xpp/ . +It is generally a more technical document than the +http://www.xorcom.com/documentation/manuals/[Astribank User Manual] + -Building and Installation: -""""""""""""""""""""""""" +Building and Installation +------------------------- Building and installation is basically like the normal procedure of installing Zaptel with some additions. -Building drivers: -"""""""""""""""" -Unlike earlier versions, the Astribank driver (xpp) will now build -automatically. To build the drivers follow the usual Zaptel -documentation. E.g: run: - - make - -in the top-level directory. +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': -Next you will need to build the user-space tools needed for loading the -firmware and initialization files for the Astribank: + make -C xpp/utils install - make -C xpp/utils - 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 Centox/Trixbox). - -INSTALLATION: -"""""""""""" +And the following extra step to install: + + make -C xpp/utils install + +INSTALLATION +------------ apart from the standard 'make install' in the zaptel directory, run: @@ -55,8 +58,9 @@ Run: to load firmware. -LEDs Indication: -""""""""""""""" + +LEDs Indication +--------------- The Astribank has 4 global indication leds and one or two per-port leds. In the Astribank 16 and in the Astribank BRI (USB product IDs 113x and 114x, respectively) the indication leds will normally be in the side. @@ -85,16 +89,18 @@ synchronization. The per-port green led on analog (both FXS and FXO) indicate that the port is off-hook. -On the BRI, the green led blinks when the port is TE and has layer-1 -connectivity to the other party, and the orange led blinks when the unit -is in NT mode and has layer-1 connectivity to the other party. +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: -"""""""""""""" +DEVICE STARTUP +-------------- -Terminology: -""""""""""" +Terminology +~~~~~~~~~~~ Some technical terms that are used throughout the document and in the driver / zaptel . Only used in the technical parts. @@ -109,11 +115,12 @@ A funny way to call an Astribank device. XPD: This is basically a logical unit of the Astribank. It will be registered to -Zaptel as a single span. This will basically be 8 analog channels. +Zaptel as a single span. This can be either an analog (FXS or FXO) +module or a single port in a BRI module. -Loading Firmware: -"""""""""""""""" +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 ID of the Astribank changes to e4e4 @@ -156,8 +163,8 @@ number. So you need to re-check the value of NNN with lsusb. Typically this will be the old value + 1. -Firmware Loading with Hotplug: -""""""""""""""""""""""""""""" +Firmware Loading with Hotplug +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Hotplug framework was popular for hotplugging and usually also autoloading drivers. If it is used on your system, you'll see /etc/hotplug with many files under it. Hotplug will automatically load @@ -183,8 +190,8 @@ firmware the device will reenumerate itself and thus "unplug" and "replug" to load the FPGA firmware. -Firmware Loading with UDEV: -"""""""""""""""""""""""""" +Firmware Loading with UDEV +~~~~~~~~~~~~~~~~~~~~~~~~~~ The UDEV framework has replaced Hotplug in most recent systems. If you have a recent 2.6 system with no Hotplug and files under /etc/udev, chances are you ude udev. udev does quite a few nice things. @@ -205,8 +212,8 @@ device will reenumerate itself and thus "unplug" and "replug" to load the FPGA firmware. -Firmware Resetting (Experimental): -""""""""""""""""""""""""""""""""" +Firmware Resetting +~~~~~~~~~~~~~~~~~~ Newer versions of the USB firmware can now be reset using 'fpga_load -r'. This will only work when the device is not used by the driver, so you may need to 'rmmod xpp_usb' in order to reset the firmware. @@ -221,8 +228,8 @@ Also try: # and start/restrart asterisk. -Loading The Modules: -""""""""""""""""""" +Loading The Modules +~~~~~~~~~~~~~~~~~~~ Here is what should happen: In short: you should plug it or have it plugged at boot time, and all the modules should load. You will see xpp_usb , xpd_fxs and possibly @@ -268,8 +275,8 @@ required some special modprobe.conf setup, but this is no longer the case. -Device Initializations Scripts: -"""""""""""""""""""""""""""""" +Device Initializations Scripts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The chips in the device need to be initialized. This involves sending a bunch of values to certain registers in those chips. We decided that hardwiring those values in the driver itself would not be a good idea. @@ -283,8 +290,9 @@ invocation has failed. The XPD will then be removed (you won't see that a directory for that XPD under the relevant /proc/xpp/XBUS-* directory) and not be registered with Zaptel. -Registering With Zaptel: -""""""""""""""""""""""" + +Registering With Zaptel +~~~~~~~~~~~~~~~~~~~~~~~ Now we finally got to the "lights party" part: the lights in a unit (XPD) get lit before it registers with Zaptel and are turned off after that. @@ -302,21 +310,26 @@ register the spans manually. For your convenience the command zt_registration -SAMPLE CONFIGURATIONS: -"""""""""""""""""""""" +SAMPLE CONFIGURATIONS +--------------------- +We generally recommend generating the configuration with the utility +genzaptelconf. The following reference configuration will work for a +system whose sole Zaptel hardware device is the said Astribank. -/etc/zaptel.conf: - - Astribank 8: +/etc/zaptel.conf +~~~~~~~~~~~~~~~ +Astribank 8 +^^^^^^^^^^^ fxoks=1-14 - Astribank 16: 8FXS/8FXO - +Astribank 16: 8FXS/8FXO +^^^^^^^^^^^^^^^^^^^^^^^ fxoks=1-14 fxsks=15-22 - Astribank 4 BRI +Astribank 4 BRI +^^^^^^^^^^^^^^^ # Assumed ports settings: # Ports 1,3: TE # Ports 2,4: NT @@ -335,9 +348,9 @@ SAMPLE CONFIGURATIONS: /etc/asterisk/zapata.conf - - Astribank 8: - +~~~~~~~~~~~~~~~~~~~~~~~~~ +Astribank 8 +^^^^^^^^^^^ [channels] signalling=fxo_ks ; The real analog ports: @@ -348,16 +361,16 @@ SAMPLE CONFIGURATIONS: channel => 1-8 ; output ports: - context=astbank-outputs + context=astbank-output channel => 9-10 ; input ports: immediate=yes - context=astbank-inputs + context=astbank-input channel => 11-14 immediate=no - Astribank 16: 8FXS/8FXO - +Astribank 16: 8FXS/8FXO +^^^^^^^^^^^^^^^^^^^^^^^ [channels] signalling=fxo_ks ; The real analog ports: @@ -368,11 +381,11 @@ SAMPLE CONFIGURATIONS: channel => 1-8 ; output ports: - context=astbank-outputs + context=astbank-output channel => 9-10 ; input ports: immediate=yes - context=astbank-inputs + context=astbank-input channel => 11-14 immediate=no @@ -382,8 +395,8 @@ SAMPLE CONFIGURATIONS: callerid=asreceived channel => 15-22 - Astribank 4 BRI: - +Astribank 4 BRI +^^^^^^^^^^^^^^^ ; Assumed ports settings: ; Ports 1,3: TE ; Ports 2,4: NT @@ -410,7 +423,6 @@ SAMPLE CONFIGURATIONS: group = 2,14 channel => 7,8 - See also the output of genzaptelconf for examples of mailbox and @@ -440,51 +452,78 @@ When loaded, you should get one span, of 8 extensions, 2 output ports and Sample dialplan (extensions.conf) for all the above: -[phones-zap] -; 401 will dial to channel 1, 420, to zaptel channel 20, etc. -exten => _4XX,1,Dial(ZAP/${EXTEN:1}) - +----------------------------------------------------------- +[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 81 will dial it through -; span 1, etc. The two leading digits are stripped. -; (Each digital span is also added to group 10+span number ). +; 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. +; 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) - -[astbank-inputs] -exten => s,1,Set(ZAP_CHAN=Cut(${CHANNEL},-,1)) -exten => s,n,Set(ZAP_CHAN=Cut(${ZAP_CHAN},/,2)) + +; Alternatively, the following will redirect you to the demo IVR +; from the sample extenbtions.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=Math(${ZAP_CHAN}-11)) +;exten => s,n,Set(INPUT_NUM=$[${ZAP_CHAN}-11)]) ; The sample below just logs the signal. -exten => s,n,NoOp(Got signal from input port number ${INPUT_NUM}) +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. +; of their own. Sending them to a context of their on makes +; 'zap show channels' in the CLI provide useful display, though. +----------------------------------------------------------- /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) @@ -500,6 +539,9 @@ synchronization source. printing to it can change the synchronization source. Host-synchronization is currently the default but for better sound quality you should synchronize from the Astribank. +Reading it may provide you some information regarding the timing +behaviour of Asterisk. + /proc/xpp/XBUS-nn gives information about device number nn (starting from 00). under it, /proc/XBUS-nn/XPD-mm gives information regarding span number m in that device. @@ -517,16 +559,32 @@ This shows which ports are off-hook, which are ringing, etc. It also shows the current audio sample in both direction, which is useful to see if there is something going at all. -(There are a bunch of other status files under /proc/xpp/ ) + +For FXO modules, /proc/xpp/XBUS-nn/XPD-mm/fxo_info also provides a +"battery" line to show if the + + +For the BRI module, /proc/xpp/XBUS-nn/XPD-mm/bri_info provides very +useful information regarding layer 1 and layer 2 status. For the +lower-layer status: + + watch -n1 -d 'grep "Layer 1:" /proc/xpp/XBUS-*/XPD-*/bri_info' + +For the status of the D channel of the span, see: + + watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/bri_info' + + +There are a bunch of other status files under /proc/xpp/ . Zaptel Init Configuration File -"""""""""""""""""""""""""""""" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The zaptel init.d script, genzaptelconf and the XPD init scripts source the file /etc/init.d/zaptel (on Debian) or /etc/sysconfig/zaptel (on RedHats). A number of useful values for there: -############################### +----------------------------------------------------------- # Lines beginning with '#' are considered comments and ignored. # A two-letter country code. genzaptelconf uses it to better guess @@ -542,14 +600,13 @@ lc_country=us # /usr/share/zaptel/init_fxo_mode . #opermode=FCC #opermode=FRANCE +----------------------------------------------------------- -# If you feel like flooding your logs with debug output of the calibration -# process: -#DEBUG_CALIBRATION=1 -############################### +Useful Module Parameters +~~~~~~~~~~~~~~~~~~~~~~~~ +Compile-time defaults of all modules can be shown as part of the +description line for the parameter in the output of modinfo. -Useful Module Parameters: -"""""""""""""""""""""""" zap_autoreg: (xpp) Register spans automatically (1) or not (0). Default: 1. Unsetting this could be useful if you have several Astribanks and you @@ -566,9 +623,24 @@ It will make the driver print tons of debugging messages. Can be sometime even handy, but overly-verbose in the case of xpp_usb. Can be safely set/unset at run-time using /sys/modules . +vmwineon: (xpd_fxs) +Enable (1) or disable (0) sending voicemail message waiting indication +to phones with a neon lamp. Disabled by default as it requires extra +work of the driver even without such a phone and may potentially have +some strange sideeffects with some phones. + +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 (if the telco 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 such parameters. -BTW: XPP here does not stand for X Printing Panel, XML Pull Parser, +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). +Peripheral Device). An XBus (originally XPP Bus) is actually a single +Astribank device and the XPDs have become the single modules in it. |