Typos. Mostly by Lintian
[dahdi/tools.git] / xpp / README.Astribank
1 Xorcom Astribank Documentation
2 ==============================
3 Xorcom Team <support@xorcom.com>
4 $Revision$, $Date$
5
6 This file documents the DAHDI drivers for the Xorcom Channel Bank.
7
8 It is generally a more technical document than the 
9 http://www.xorcom.com/product-manuals/product-manuals.html[Astribank 
10 User Manual]
11
12 An HTML version of the latest version of this document could be found at 
13 http://docs.tzafrir.org.il/dahdi-tools/README.Astribank.html[]
14
15 Introduction
16 ------------
17 The Xorcom Astribank is a USB-connected channel-bank. An Astribank may
18 have up to 4 modules:
19
20 PRI:: 
21   1, 2 or 4 ports of E1 or T1. Can only be the first (left-most) module
22   of the Astribank. Note that each port has physically a pair of ports,
23   where the top one has crossed wiring.
24
25 BRI::
26   2, 4 or 8 ports of BRI. Can only be used as the first (left-most)
27   module of the Astribank. 
28
29 FXO::
30   8 ports of FXO (connector to an analog PSTN line).
31
32 FXS::
33   8 ports of FXS (connector to an analog phone). If used as the first
34   (left-most) module, it will also have 2 output lines and 4 input lines
35   that will appear on DAHDI like standard DAHDI ports. The input and
36   output ports are connected from the two RJ-45 connectors on the right
37   side of the module.
38
39 There is also a 6FXS-2FXO module that is essentially an FXS module with
40 six lines instead of 8 (but still with the input and output ports) and
41 an FXO module of two ports.
42
43
44 Building and Installation
45 -------------------------
46 Apart from the standard DAHDI build requirements, you also need:
47
48 * *libusb development headers* to build the Astribank firmware tools
49   (astribank_tool, astribank_hexload, astribank_allow).
50   This is typically the package libusb-dev on Debian (and derivatives
51   like Ubuntu) or libusb-devel on RedHat (and derivatives like
52   CentOS/Trixbox).
53 * *Echo Canceller Module firmware*: If you have an Astribank with an
54   echo canceller module, see the following section.
55
56 Follow the build instructions of DAHDI-linux and DAHDI-tools. But
57 Basically, in dahdi-linux run:
58
59   make
60   make install # as root
61
62 And later in dahdi-tools:
63
64   ./configure
65   make
66   make install # as root
67
68
69 Echo Canceller Firmware
70 ~~~~~~~~~~~~~~~~~~~~~~~
71 If you install from source, you should copy OCT6104E-256D.ima to the
72 source tree (before running make install:
73
74   wget http://updates.xorcom.com/astribank/hwec/OCT6104E-256D.ima
75   mv OCT6104E-256D.ima drivers/dahdi/xpp/firmwares/
76
77 Alternatively, if you have already installed DAHDI-linux (e.g. from a
78 binary package that does not include the firmware) you can just copy
79 it directly to the target directory, /usr/share/dahdi using:
80
81   cd /usr/share/dahdi
82   wget http://updates.xorcom.com/astribank/hwec/OCT6104E-256D.ima
83
84
85 Installation Scenarios
86 ~~~~~~~~~~~~~~~~~~~~~~
87 Below are some commented sequences of commands that can be used at some
88 common scenarios. Those scenarios begin only after you installed the
89 software (dahdi-linux, dahdi-tools, asterisk, etc.).
90
91 New Installation Scenario
92 ^^^^^^^^^^^^^^^^^^^^^^^^^
93 Installing Astribank on a system where there's no existing Astribank.
94 You install the driver when the Astribank was already connected:
95
96 --------------------------------------------
97 # If you had the hardware already connected: Load just the USB firmware
98 /usr/share/dahdi/xpp_fxloader usb
99 # (you could use 'load' instead of 'usb' but this is also a good test
100 # that automatic load through firmware is also in place)
101 dahdi_hardware -v
102 # wait until the Astribank has a product ID of 11x2
103 sleep 5 # Just wait a little bit 
104 dahdi_hardware -v # now that you see that all's well:
105 /etc/init.d/dahdi start
106 # generate configuration:
107 dahdi_genconf
108 # Apply it:
109 dahdi_cfg
110
111 # edit /etc/asterisk/chan_dahdi.conf to #include dahdi-channels.conf or
112 # copy its content to the end of chan_dahdi.conf
113 #
114 # This stops existing DAHDI calls, if any, but does no other harm:
115 asterisk -rx 'dahdi restart' 
116 --------------------------------------------
117
118
119 Upgrade Scenario
120 ^^^^^^^^^^^^^^^^
121 Upgrading is roughly the same as a new installation. But in many cases 
122 you begin with  resetting the firmware.
123
124 I also assume here that the configuration is valid, and hence I don't
125 generate it.
126
127 --------------------------------------------
128 # If you need to reset the firmware:
129 /usr/share/dahdi/xpp_fxloader reset
130 # (you could use 'load' instead of 'usb' but this is also a good test
131 # that automatic load through firmware is also in place)
132 dahdi_hardware -v
133 # wait until the Astribank has a product ID of 11x2
134 sleep 5 # Just wait a little bit
135 dahdi_hardware -v # now that you see that all's well:
136 /etc/init.d/dahdi start
137 #
138 # This stops existing DAHDI calls, if any, but does no other harm:
139 asterisk -rx 'dahdi restart' 
140 --------------------------------------------
141
142
143 Sample Configurations
144 ---------------------
145 We generally recommend to generate the configuration by using utility
146 dahdi_genconf which are included with DAHDI. Nevertheless, the following 
147 can serve as reference configurations for a system where Astribank devices 
148 are used.
149
150 Also refer to the general README for documentation of the other DAHDI
151 configuration files.
152
153 xpp.conf: Astribank Initialization
154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155 /etc/dahdi/xpp.conf is read by the initialization scripts of Astribank
156 modules:
157 -----------------------------------------------------------
158 # /etc/dahdi/xpp.conf
159 #
160 # This file is used to configure the operation
161 # of init_card_* initialization scripts.
162 #
163
164 # Adds many more tracing messages that are sent to syslog:
165 #debug          1
166
167 # xpd_pri: E1 or T1. The default is E1 for all the ports.
168 #   Setting T1 instead:
169 #pri_protocol   T1
170 #
171 #  Or if you actually want to mix E1 and T1:
172 #pri_protocol/xbus-00/xpd-02    T1
173 #pri_protocol/connector:usb-0000:00:1d.7-7/xpd-03       T1
174 #pri_protocol/label:usb:0000183/xpd-03  T1
175 # If several definitions can refer to a port, the last wins. 
176 # If none applies, the default of E1 holds.
177
178 #  FXO: country to adjust settings to:
179 #opermode       FRANCE
180
181 #  Don't run power calibration on the FXS units. This can save time
182 #  but can also get you unit randomly disconnect, if badly used:
183 #fxs_skip_calib 1
184 -----------------------------------------------------------
185
186
187 xpp_order: Explicitly order Astribanks
188 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189 (This feature is available as of DAHDI 2.2)
190
191 On a system with multiple Astribank you would normally want to guarantee
192 that Astribanks are registered in the same order regardless of the order
193 in which they are connected or detected. Assuming that you register them
194 all at the same time. In order to do that, you should list the
195 Astribanks explicitly under /etc/dahdi/xpp_order .
196
197 Astribanks that are listed there are registered first (according to the
198 order of lines in the files). Astribanks not listed there are added
199 last, and sorted by the 'USB connector' string.
200
201 You can identify an Astribank in two ways: 
202
203 Label::
204   each Astribank (except some really old ones) has a label . This 
205   identifies the actual Astribank box.
206
207 Connector::
208   Identify the path the Astribank is connected through. E.g.: to what
209   USB port you connected it.
210
211 Identifying an Astribank by the label seems simpler and more
212 predictable. Though it may have some slightly surprising effects if
213 replace one Astribank with another.
214
215 The sample configuration file:
216 -----------------------------------------------------------
217 #
218 # This is an optional configuration file for ordering
219 # Dahdi registration.
220 #
221 # It is read from /etc/dahdi/xpp_order. This location
222 # may be overriden via the environment variable XPPORDER_CONF
223 #
224 # Lines may contain:
225 #   - The Astribank label (verbatim)
226 #   - The Astribank connector string (prefixed with @)
227 # Ordering number of each listed Astribank is determined
228 # by its position in this file.
229 # Astribanks not listed in this file, get an ordering
230 # number of 99 (last).
231 #
232 # Astribanks with same ordering number are sorted by their
233 # connectors (to preserve legacy behaviour).
234 #
235 # Examples:
236 #usb:1234
237 #@usb-0000:06:02.2-2
238 -----------------------------------------------------------
239
240 In order to generate one that includes all the Astribanks in the system
241 with the current order in which they are connected, use:
242
243   dahdi_genconf xpporder
244
245 For more technical details see the section <<_registering_in_dahdi>>
246 below.
247
248
249 /etc/dahdi/system.conf
250 ~~~~~~~~~~~~~~~~~~~~~~
251
252 Astribank 8
253 ^^^^^^^^^^^
254     fxoks=1-14
255
256 Astribank 6FXS/2FXO
257 ^^^^^^^^^^^^^^^^^^^
258     fxoks=1-12
259     fxsks=13-14
260
261 Astribank 16: 8FXS/8FXO
262 ^^^^^^^^^^^^^^^^^^^^^^^
263     fxoks=1-14
264     fxsks=15-22
265
266 Astribank 4 BRI
267 ^^^^^^^^^^^^^^^
268     # Assumed ports settings:
269     # Ports 1,3: TE
270     # Ports 2,4: NT
271     span=1,1,1,ccs,ami
272     span=2,0,1,ccs,ami
273     span=3,2,1,ccs,ami
274     span=4,0,1,ccs,ami
275     bchan=1-2,4-5,7-8,10-11
276     ; if you applied the bri_dchan patch:
277     ;dchan=3,6,9,12
278     hardhdlc=3,6,9,12
279
280 Astribank 4 PRI E1
281 ^^^^^^^^^^^^^^^^^^
282     # Assumed ports settings:
283     # Ports 1,3: TE (CPE)
284     # Ports 2,4: NT (Net)
285     span=1,1,1,ccs,hdb3,crc4
286     span=2,0,1,ccs,hdb3,crc4
287     span=3,2,1,ccs,hdb3,crc4
288     span=4,0,1,ccs,hdb3,crc4
289     bchan=1-15,17-30,31-45,47-60,61-75,77-90,91-105,107-120
290     dchan=16,46,76,106
291
292 Astribank 4 PRI T1
293 ^^^^^^^^^^^^^^^^^^
294     # Assumed ports settings:
295     # Ports 1,3: TE (CPE)
296     # Ports 2,4: NT (Net)
297     span=1,1,1,esf,b8zs
298     span=2,0,1,esf,b8zs
299     span=3,2,1,esf,b8zs
300     span=4,0,1,esf,b8zs
301     bchan=1-23,25-47,49-71,73-95
302     dchan=24,48,72,96
303   
304
305 /etc/asterisk/chan_dahdi.conf
306 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
307 Astribank 8
308 ^^^^^^^^^^^   
309     [channels]
310     signalling=fxo_ks
311     ; The real analog ports:
312     context=from-internal
313     echocancel=yes
314     ; echocancelwhenbriged=yes
315     ; echotraining=no
316     channel => 1-8
317
318     ; output ports:
319     context=astbank-output
320     channel => 9-10
321     ; input ports:
322     immediate=yes
323     context=astbank-input
324     channel => 11-14
325     immediate=no
326
327 Astribank 6FXS/2FXO
328 ^^^^^^^^^^^^^^^^^^^   
329     [channels]
330     signalling=fxo_ks
331     ; The real analog ports:
332     context=from-internal
333     echocancel=yes
334     ; echocancelwhenbriged=yes
335     ; echotraining=no
336     channel => 1-6
337
338     ; output ports:
339     context=astbank-output
340     channel => 7-8
341     ; input ports:
342     immediate=yes
343     context=astbank-input
344     channel => 9-12
345     immediate=no
346
347     ; FXO ports
348     signalling=fxs_ks
349     context=from-pstn
350     callerid=asreceived
351     channel => 13-14
352
353 Astribank 16: 8FXS/8FXO
354 ^^^^^^^^^^^^^^^^^^^^^^^   
355     [channels]
356     signalling=fxo_ks
357     ; The real analog ports:
358     context=from-internal
359     echocancel=yes
360     ; echocancelwhenbriged=yes
361     ; echotraining=no
362     channel => 1-8
363
364     ; output ports:
365     context=astbank-output
366     channel => 9-10
367     ; input ports:
368     immediate=yes
369     context=astbank-input
370     channel => 11-14
371     immediate=no
372
373     ; FXO ports
374     signalling=fxs_ks
375     context=from-pstn
376     callerid=asreceived
377     channel => 15-22
378
379 Astribank 4 BRI
380 ^^^^^^^^^^^^^^^    
381     ; Assumed ports settings:
382     ; Ports 1,3: TE
383     ; Ports 2,4: NT
384     [channels]
385     switchtype = euroisdn
386     callerid = asreceived
387     
388     ; TE ports:
389     signalling = bri_cpe_ptmp
390     ;signalling = bri_cpe
391     context = from-pstn
392     group = 1,11
393     channel => 1,2
394     
395     group = 1,13
396     channel => 7,8
397     
398     ; NT ports:
399     signalling = bri_net_ptmp
400     ;signalling = bri_net
401     context = from-internal
402     group = 2,12
403     channel => 4,5
404     
405     group = 2,14
406     channel => 10,11
407
408 Astribank 4 PRI E1
409 ^^^^^^^^^^^^^^^^^^ 
410     ; Assumed ports settings:
411     ; Ports 1,3: TE
412     ; Ports 2,4: NT
413     [channels]
414     switchtype = euroisdn
415     callerid = asreceived
416     
417     ; TE ports:
418     signalling = pri_cpe
419     context = from-pstn
420     group = 1,11
421     channel => 1-15,17-30
422     
423     group = 1,13
424     channel => 61-75,77-90
425     
426     ; NT ports:
427     signalling = pri_net
428     ;signalling = pri_net
429     context = from-internal
430     group = 2,12
431     channel => 31-45,47-60
432     
433     group = 2,14
434     channel => 91-105,107-120
435
436 Astribank 4 PRI T1
437 ^^^^^^^^^^^^^^^^^^ 
438     ; Assumed ports settings:
439     ; Ports 1,3: TE
440     ; Ports 2,4: NT
441     [channels]
442     switchtype = national
443     callerid = asreceived
444     
445     ; TE ports:
446     signalling = pri_cpe
447     context = from-pstn
448     group = 1,11
449     channel => 1-23
450     
451     group = 1,13
452     channel => 49-71
453     
454     ; NT ports:
455     signalling = pri_cpe
456     ;signalling = pri_net
457     context = from-internal
458     group = 2,12
459     channel => 25-47
460     
461     group = 2,14
462     channel => 73-95
463
464
465 /etc/asterisk/extensions.conf
466 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
467 Sample dialplan (extensions.conf) for all the above:
468
469 -----------------------------------------------------------
470 [phones-dahdi]
471 ; With Asterisk 1.4 you will may need to use here 'Zap' instead of
472 ; DAHDI. See Zaptel-to-DAHDI.txt .
473 ;
474 ; 6001 will dial to channel 1, 6020, to DAHDI channel 20, etc.
475 exten => _6XXX,1,Dial(DAHDI/${EXTEN:1})
476 ; Useful for debugging trunks. Will potentially allow users to
477 ; bypass context limitations.
478 ;exten => _6XXX.,1,Dial(DAHDI/${EXTEN:1:3}/${EXTEN:4})
479
480 [trunk]
481 ; A number that begins with 9: dial it through a trunk
482 ; (we put FXO channels and TE channels in group 0).
483 ; The leading 9 is stripped.
484 exten => _9.,1,Dial(DAHDI/g0/${EXTEN:1})
485 ; dialing a number that begins with 83 will dial it through
486 ; span 3, and so forth. The two leading digits are stripped.
487 ; (Each digital span is also added to group 10+span number).
488 exten => _8X.,1,Dial(DAHDI/g1${EXTEN:1:1}/${EXTEN:2})
489
490 [from-internal] 
491 ; The context of FXS ports: analog phones.
492 ; They are allowed to dial to all other phones 
493 include => phones-dahdi 
494 ; They are also allowed to call through the trunk: 
495 include => trunk
496 ; some simple tests:
497 include => astbank-test
498
499 [from-pstn] 
500 ; Calls from the PSTN enter here. Redirect calls to an IVR 
501 ; or a default extension in the s context here. In this case we  
502 ; redirect calls to DAHDI channel 1: 
503 exten => s,1,Dial(DAHDI/1) 
504
505 ; Alternatively, the following will redirect you to the demo IVR 
506 ; from the sample extensions.conf of Asterisk:
507 include => demo
508
509 ; An extra context with some simple tests
510 [astbank-test]
511 ; 200: echo test
512 exten => 200,1,Answer
513 exten => 200,n,Wait(1)
514 exten => 200,n,Echo()
515 exten => 200,n,Hangup
516
517 ; 203: say extension number. Will only work if caller ID 
518 ; is properly set in chan_dahdi.conf / dahdi-channels.conf
519 exten => 203,1,Answer
520 exten => 203,n,Wait(1)
521 exten => 203,n,SayNumber(${CALLERID(num)})
522 exten => 203,n,Hangup
523
524 [astbank-input] 
525 exten => s,1,Set(DAHDI_CHAN=${CUT(CHANNEL,-,1)}) 
526 exten => s,n,Set(DAHDI_CHAN=${CUT(DAHDI_CHAN,/,2)}) 
527 ; 11 is the number of the first input port. At least in the sample 
528 ; configuration below. 
529 ;exten => s,n,Set(INPUT_NUM=$[${DAHDI_CHAN}-11)]) 
530 ; The sample below just logs the signal.  
531 exten => s,n,NoOp(Got signal from DAHDI Channel ${DAHDI_CHAN}) 
532 ; Alternatively: 
533 ;exten => s,n,System(run something) 
534
535 ; No. We did not forget the context astbank-outputs. Output 
536 ; ports only get calls from the PBX. Thus they don't need a context 
537 ; of their own. Sending them to a context of their on makes 
538 ; 'dahdi show channels' in the CLI provide useful display, though.
539 -----------------------------------------------------------
540
541
542 Troubleshooting
543 ---------------
544 The following commands provide useful information for debugging:
545
546 lsusb Test
547 ~~~~~~~~~~
548 Check USB level status. You can use one of the following utilities for it:
549
550   dahdi_hardware -v
551        or
552   lsusb | grep e4e4
553
554 - Look for the USB Product ID (the second number after e4e4).
555 - If you see *11x2* (e.g: 1152)- the FPGA firmware has been loaded.
556   Move on.
557   dahdi_hardware will also show you some more details if the driver
558   is loaded while the lsusb will just list the device.
559 - If it shows something as product ID *11x0* - the USB firmware is not
560   loaded. Maybe you need to run fxload. Or maybe just unplug and plug again
561   the device. Also make sure that you have fxload installed.
562 - If lsusb shows the Product ID as *11x1* - only the USB firmware is loaded 
563   and not the FPGA firmware is loaded. If this is still the case after 
564   a while - either the firmware loading has failed or you don't have
565   astribank_hexload/astribank_tool. Make sure you have libusb-dev(el)
566   installed when building DAHDI. After you have installed it, you may need
567   to re-run ./configure .
568 - It should list all of your Astribank devices. If it doesn't (for
569   more than period of time needed for the initial firmware
570   loading) - Check that the Astribank is connected indeed.
571
572
573 DAHDI Registration
574 ~~~~~~~~~~~~~~~~~~
575 Check if the Astribank spans are registered with DAHDI:
576
577   dahdi_registration
578
579 - This should give useful results after the drivers have identified
580   and your devices are initialized.
581 - It should list all Astribank XPDs. For each of them it should write
582   "on" or "off". If the registration status is "off", then it means that
583   the span has not been registered in DAHDI and therefore can not be used
584   yet.
585 - Registration is normally done as part of `/etc/init.d/dahdi start`.
586   If you want to register the spans manually, then run command:
587   `dahdi_registration on` .
588
589
590 DAHDI Level Information
591 ~~~~~~~~~~~~~~~~~~~~~~~
592 You can get some information regarding DAHDI channels by running one of the
593 following commands:
594
595     lsdahdi
596        or
597     cat /proc/dahdi/*
598
599 - Those two are almost the same. The lsdahdi produced more correctly sorted
600   output if you have more than 10 spans, and also make the output listing
601   looks a little bit nicer.
602 - You can see if your DAHDI spans and channels were loaded, if
603   they were configured by dahdi_cfg and if they are in use (typically by
604   Asterisk).
605   For example:
606   Not configured Astribank FXS channel will be displayed as:
607
608      42 FXS
609
610 - When *dahdi_cfg* has applied the configuration of the channel (from 
611   /etc/dahdi/system.conf), you will see an extra column for the signalling
612   type of the channel. The same channel after it has been configured:
613
614     42 FXS        FXOKS
615
616 - If a program (which is typically Asterisk) uses it, you'll see:
617
618     42 FXS        FXOKS      (In use)
619
620
621
622 Asterisk Level Information
623 ~~~~~~~~~~~~~~~~~~~~~~~~~~
624   asterisk -rx 'dahdi show channels'
625
626 - If you get error "Unable to connect to remote asterisk" then it
627   means that the Asterisk is not running. It is possible that Asterisk
628   has failed to start due to misconfigured chan_dahdi.conf or whatever reason.
629   Check /var/log/asterisk/messages or /var/log/asterisk/full .
630 - If you get the error that "there is no such command" then it means that
631   chan_dahdi.so is not loaded. There are two reasons for such problem:
632   * chan_dahdi.so is not even built. Check if the file exists:
633
634        ls -l /usr/lib/asterisk/modules/chan_dahdi.so
635
636   * the chan_dahdi.so file exists but it is not loaded. Try to load it manually:
637
638        asterisk -rx 'module load chan_dahdi.so'
639
640   * In some cases chan_dahdi failed to load properly and needs to be unloaded
641     before re-loading:
642
643        asterisk -rx 'module unload chan_dahdi.so'
644        asterisk -rx 'module   load chan_dahdi.so'
645
646 - You see "pseudo" channel only. It means that you have not configured any
647   channels. If you have configured channels in chan_dahdi.conf, you may
648   need either to restart the Asterisk or unload/load chan_dahdi.so manually.
649   You can use the following Asterisk CLI commands for it: `unload chan_dahdi.so` 
650   and `load chan_dahdi.so`
651
652
653 Known Issues
654 ~~~~~~~~~~~~
655 Empty /proc dir
656 ^^^^^^^^^^^^^^^
657 .Symptoms:
658 - Error message:
659
660   "ERR-xpd_fxo: XBUS-00/XPD-00: Failed initializing registers (-22)"
661   
662 - Likewise for all XPDs. 
663 - The directory /proc/xpp exists but is empty (not even the files 
664   'xbuses' and 'sync').
665
666 .Cause:
667 The driver failed to recreate the procfs directory /proc/xpp and hence
668 everything under it. This is because it has already existed. And it
669 existed because a process still uses it. This is typically because you
670 have a shell whose working directory is /proc/xpp or somewhere under
671 it:
672
673   # lsof /proc/xpp
674   COMMAND  PID USER   FD   TYPE DEVICE SIZE       NODE NAME
675   bash    2741 root  cwd    DIR    0,3    0 4026532684 /proc/xpp
676
677 .Fix:
678 Move that process from that directory, or close the file it uses from
679 under /proc/xpp and reload the dahdi / xpp drivers.
680
681
682 Bad Firmware Version
683 ^^^^^^^^^^^^^^^^^^^^
684 .Symptoms:
685 - An Astribank finishes initialization quickly, the /proc/XBUS-nn
686   directory has no XPD-mm subdirectories.
687 - Error in the kernel logs about:
688
689   NOTICE-xpp: XBUS-00: XPD at 00: type=6.0 has bad firmware revision 2.6 
690
691 .Cause:
692 This is normally caused by an Astribank with an older firmware connected
693 to a 
694
695 The protocol version supported by the firmware will typically be the same 
696 one as in the device initialization scripts installed to 
697 /usr/share/dahdi . Hence if this version installed 
698 `/usr/share/dahdi/init_card_3_29` it will probably include firmware of 
699 protocol version 29.
700
701 .Fix:
702 Reset the firmware:
703
704   /usr/share/dahdi/xpp_fxloader reset
705
706 Or disconnect the Astribank from the power and reocnnect. On some older 
707 versions of the USB firmware resetting the firmware (or any operation of 
708 astribank_tool) would fail if the driver is loaded. Hence you would need to
709 run `rmmod xpp_usb` . In the end, reload the drivers.
710
711
712 USB Errors at Shutdown
713 ^^^^^^^^^^^^^^^^^^^^^^
714 .Symptoms:
715 You see USB-related errors similar to the following whenever you shut
716 down the drivers of the Astribank or disconnect its drivers:
717
718   ERR-xpp_usb: XBUS-00: Failed to submit a receive urb
719
720 .Cause:
721 This is a normal part of the shutdown of the USB connection. 
722
723 .Fix:
724 Ignore them. Unless the USB should not have disconnected at that time.
725
726
727 BRI Layer 1 Down
728 ^^^^^^^^^^^^^^^^
729 .Symptoms:
730 With the BRI module only, and not in the middle of an active call, you
731 notice that suddenly the line goes down. The LED of the port stops
732 blinking, layer1 not listed as "active" in the bri_info file in
733 /proc/xpp, and the span is in RED alarm in DAHDI.
734
735 You may also see an error message such as:
736
737   NOTICE-xpd_bri: XBUS-00/XPD-02: D-Chan RX Bad checksum: [2A:01=FC] (252)
738
739 from the exact time of the disconnecting.
740
741 .Cause:
742 This is expected with most european BRI PtMP providers. If they support
743 PtMP, they are normally also expected to support ISDN phones, that get
744 the power from the provider. And thus they shut down the line whenever
745 there's no active call. 
746
747 Sometimes the line is shut down in the middle of a layer 2 message. In
748 the BRI driver the HDLC decoding/encoding is done in the card. In that
749 case we may get the above error.
750
751 .Fix:
752 Normaly this is not a problem. The driver will re-establish a connection
753 once a new call needs to be made.
754
755
756 Astribank in lsusb but not in dahdi_hardware
757 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
758 .Symptoms:
759 You fail to find an Astribank device in the output of lsusb . But you
760 see it in `lsusb | grep e4e4`
761
762 .Cause:
763 The perl module Dahdi::Hardware currently relies on
764 /proc/bus/usb/devices (from usbfs) whereas lsusb can use either that or
765 /dev/bus/usb . 
766
767 .Fix:
768 Usbfs is generally deprecated and some distributions (OpenSUSE, Ubuntu) no 
769 longer mount it by default. Try:
770
771   mount /proc/bus/usb
772
773 and if that doesn't work:
774
775   mount -t usbfs usbfs /proc/bus/usbfs
776
777 However this is generally a cosmetic issue that only affects the listing
778 in dahdi_hardware.
779
780
781 Astribank not initialized: Premature packet end
782 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
783 .Symptoms:
784 After upgrading to Zaptel 1.4.12 / 1.2.25 the initialization of the
785 Astribank times out. In the logs you see:
786
787   kernel: NOTICE-xpp: XBUS-00(00): FIRMWARE: ERROR_CODE CODE = 0x3 (Premature packet end) 
788
789 .Cause:
790 When an Astribank is detected, the driver asks it what is its version
791 and what components it has. Normally if the version of the firmware and
792 of the driver does not match the driver gives an ugly message and fails
793 the initialization.
794
795 However in the change of the protocol between versions 2.9 (29) and 3.0
796 (30), the response that the new driver receives from a device with the
797 old version is now considered to be an illegal packet and gets
798 discarded. As a result, the Astribank waits till time-out for the
799 initialization to end.
800
801 .Fix:
802 Reset the firmware of the Astribank by either:
803
804   /usr/share/dahdi/xpp_fxloader reset
805
806 or disconnecting it from the power and reconnecting it.
807
808
809 Reference
810 ---------
811 LEDs Indication
812 ~~~~~~~~~~~~~~~
813 The Astribank has 4 global indication leds and one or two per-port leds.
814 On some of the models the LEDs are located on the left side on the front
815 panel. If there are no separate LEDs there, then the red LEDs of the
816 upper left-most ports of the device are used as the indication LEDs. Don't 
817 confuse them with green port status LEDs.
818
819 The first led is the "Power" led. It is on if the unit gets power.
820 The second led is the "Active" led, which is on when there is at 
821 least one "active" port (in a call / off-hook, though the meaning of this is 
822 different in BRI).
823 The last led is called "Hardware OK", but is actually only is on in case of  
824 the hardware failure.
825
826 The third led is the "Sync" led. If it blinks, the device is synchronized 
827 with the driver on the computer. If the device is selected to be the  
828 synchronization source for all of the Astribank devices then it will blink
829 a quick single blink.
830 If the device gets synchronization from the driver, it will blink in a 
831 more steady frequency.
832
833 "Double blink" indicates that the unit has an FXO module, and still is
834 getting synchronization from the computer, and is not the synchronization
835 source.
836
837 The per-port green led on analog (both FXS and FXO) indicates that the
838 port is off-hook.
839
840 On the BRI, the green led indicates a TE port whereas an orange led
841 indicates an NT port. If the led is solid, the port is down (not even
842 layer-1 connection is up). If it is blinking a double blink, layer 1
843 is up. A slower single blinking indicates that layer 2 is up as well
844 (which means that Asterisk is driving the port).
845
846 As for the leds of the PRI ports, see the next section.
847
848
849 PRI Ports Configuration
850 ~~~~~~~~~~~~~~~~~~~~~~~
851 Astribank PRI module has two RJ-45 sockets for each PRI port. The lower
852 socket provides typical PRI CPE side wiring: Rx- pins 1,2; Tx - pins 
853 4,5. The upper socket provides typical PRI Network side  wiring: Rx- pins
854 4,5; Tx - pins 1,2. The both sockets are permanently active and you can 
855 use any of them regardless of any configuration parameters (Both
856 connectors are live. And connecting both of them with a flat 8-wire
857 ethernet cable is a simple way to do a loop test for the port).
858
859 Each port in the PRI module can be configured either as E1 or T1. 
860 The default is E1, but it can be changed in xpp.conf (See the section
861 above).
862
863 In addition to that, a port defaults to consider itself a CPE, or
864 rather, to accept timing from the remote party. To override that you
865 need to set the timing value to 0 (second parameter in the 'span=' line
866 in system.conf).
867
868 Thus the following in system.conf will also set an orange LED:
869
870   span=2,0,3,ccs,hdb3,crc4
871
872 Note that as this is only applied when dahdi_cfg is run, the port will have
873 the default green LED lit at the bottom until it is configured.
874
875
876 Voicemail Indication
877 ~~~~~~~~~~~~~~~~~~~~
878 Asterisk supports several forms of voicemail message waiting indication
879 (VMWI) on a phone connected to a FXS port. One of them is a stutter tone
880 sent when the phone is picked up. Another one is an FSK tone that
881 encodes the number of messages waiting (or 0, for none). Alternatively it
882 may send an ioctl call on the channel (DAHDI_VMWI) to indicate the VMWI
883 status on the channel.
884
885 The DAHDI FXS device may implement any of extra three VMWI notification
886 methods. The Astribank currently only supports one of them (AC neon LED).
887 With Asterisk, as of 1.6.2 you can enable that using the following line
888 in the channel's config in chan_dahdi.conf:
889
890  mwisendtype = neon 
891
892 Versions of Asterisk before 1.6.0 did not support this ioctl. You will
893 need to reset the module parameter <<_vmwi_ioctl,vmwi_ioctl>>.
894
895
896 Device Startup
897 ~~~~~~~~~~~~~~
898 This section describes in great depth the initialization of the Xorcom
899 Astribank. Normally it would not be really needed, as the standard
900 installation of DAHDI should put everything in place. This is generally
901 some documentation to read when things fail.
902
903 Terminology
904 ^^^^^^^^^^^
905 There are some technical terms that are used in this document and in the
906 driver / dahdi.
907
908 span::
909   DAHDI breaks the channels it knows about to logical units called
910   "spans". A port in a E1/T1/ISDN card is usually a span. An whole
911   analog card is also a "span". You can see the list of spans as the list
912   of files under /proc/dahdi directory or in output of the dahdi_tool
913   utility.
914
915 XBUS::
916   A funny way to call an Astribank device.
917
918 XPD::
919   Basically this is a logical unit of the Astribank. It will be 
920   registered in DAHDI as a single span. This can be either an analog 
921   (FXS or FXO) module or a single port in case of a BRI module.
922
923
924 Loading Firmware
925 ^^^^^^^^^^^^^^^^
926 Normally this is done using the script /usr/share/dahdi/xpp_fxloader.
927 If it works fine, you don't need to bother reading this section.
928 Once the firmware is loaded the USB Vendor ID and Product ID of the Astribank
929 became to be e4e4 11x2, and now the driver can pick it up.
930
931 First and foremost: the simplest and most useful tool to debug problems
932 is lsusb. The output of lsusb should show you if the device is connected
933 if its firmware is loaded. 
934
935 The firmware files are named *.hex. They are presented in the Intel hex
936 format. The files are copied from xpp/utils to /usr/share/dahdi folder 
937 during the DAHDI installation.
938
939 The Astribank needs a firmware loaded into it. Without the firmware, 
940 the device will appear in lsusb with Vendor ID e4e4 and Product ID 11x0
941 (1130, 1140, 1150, 1160 or 1163. 1163 behaves almost exactly as 1160).
942 The firmware loading process consists of two
943 stages. In the first stage the "USB" firmware is loaded by using program
944 fxload. When the first stage is completed the Vendor ID is e4e4 and the
945 Product ID is 11x1. (e.g. 1151 if it were 1150 previously).
946
947 You can use the following command in order to load the "USB" firmware
948 manually:
949
950   fxload -t fx2 -D /dev/bus/usb/MMM/NNN -I /usr/share/dahdi/USB_FW.hex
951
952 where,
953
954 fxload::
955   A standard program that is typically part either of package 'fxload' 
956   or 'hotplug-utils' . 
957 /dev/bus/usb::
958   On some old systems it is missing . /proc/bus/usb (usbfs) could be
959   used instead.
960 MMM::
961   the first number (bus number)
962 NNN::
963   the second number (device number) you see for the device in lsusb
964
965 If the loading process has been completed successfully, the device 
966 disconnects and then connects again itself with USB Product ID 11x1 
967 (and a new device number).
968
969 In the second stage, the "FPGA" firmware is loaded.
970 The second-stage firmware loading is performed by using program
971 astribank_hexload and astribank_tool, which are built in the directory
972 xpp/utils and then copied to folder /usr/sbin during DAHDI installation.
973
974 The command syntax is similar to the syntax of fxload. You can use the 
975 following command in order to load the FPGA firmware manually:
976
977   # pick the right name according to the device ID. FPGA_1161.hex is for
978   # 116x Astribanks:
979   astribank_hexload -D /dev/bus/usb/MMM/NNN -F /usr/share/dahdi/FPGA_1161.hex
980   # If the device has an echo canceller unit (If the unit is BRI/E1, you
981   # need to add an extra -A to the command-line after the -O)
982   #astribank_hexload -D /dev/bus/usb/MMM/NNN -O /usr/share/dahdi/OCT6104E-256D.ima
983   # Note the shell expantion in this line:
984   astribank_hexload -D /dev/bus/usb/MMM/NNN -p /usr/share/dahdi/PIC_TYPE_[1-4].hex
985   # reenumerate (disconnect and reconnect)
986   astribank_tool  -D /dev/bus/usb/MMM/NNN -n
987
988 Please note, that  NNN value differs from that that was used for the 
989 fxload command due to the fact that device has "reconnected" itself 
990 with another Product ID number. So you need to run lsusb again and get 
991 the new NNN value. Usually, the new value is equal to the old value 
992 incremented by 1.
993
994 On newer systems (e.g. Centos 4) /dev/bus/usb may not be available. In
995 that case, use /proc/bus/usb . usbfs should be mounted there.
996
997
998 Automatic Firmware Loading
999 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1000 Udev is a framework for dynamic device nodes, which is supported in
1001 kernel 2.6. if your udev rules are properly  configured then the 
1002 firmware should be loaded automatically and you will see product ID 11x2
1003 (e.g.: 1152). 
1004
1005 Udev is mostly configured by files under /etc/udev/rules.d . The
1006 installer of dahdi-linux installs drivers/dahdi/xpp/xpp.rules into that
1007 directory.
1008
1009 This file instructs udev to run /usr/share/dahdi/xpp_fxloader for each
1010 time an Astribank connects and needs firmware. When the Astribank loads
1011 firmware or when it resets its firmware it "reenumerates" - disconnects
1012 and reconnects as a new device. 
1013
1014 Below are kernel log messages of an Astribank loading firmware. It firs
1015 connects without any firmware (device no. 44). Udev tells it to load the
1016 USB firmware. It disconnects and reconnects (45). This Udev gets the
1017 FPGA firmware loaded into it. It disconnects again, and when it
1018 reconnects it is now ready to talk with the driver. The last message is
1019 from the driver.
1020 -------------------------------------
1021 usb 7-1: configuration #1 chosen from 1 choice
1022 usb 7-1: New USB device found, idVendor=e4e4, idProduct=1150
1023 usb 7-1: New USB device strings: Mfr=0, Product=0, SerialNumber =0
1024 usb 7-1: USB disconnect, address 44
1025 usb 7-1: new high speed USB device using ehci_hcd and address 45
1026 usb 7-1: configuration #1 chosen from 1 choice
1027 usb 7-1: New USB device found, idVendor=e4e4, idProduct=1151
1028 usb 7-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
1029 usb 7-1: Product: Astribank
1030 usb 7-1: Manufacturer: Xorcom LTD
1031 usb 7-1: SerialNumber: 00000123
1032 usb 7-1: USB disconnect, address 45
1033 usb 7-1: new high speed USB device using ehci_hcd and address 46
1034 usb 7-1: configuration #1 chosen from 1 choice
1035 usb 7-1: reset high speed USB device using ehci_hcd and address 46
1036 INFO-xpp_usb: XUSB: Xorcom LTD -- Astribank -- FPGA
1037 -------------------------------------
1038
1039 Another useful tool for tracing UDEV-related issue is the udev monitor:
1040
1041   udevadm monitor
1042
1043 Or with some older versions of udev:
1044
1045   udevmonitor
1046
1047
1048 Firmware Loading with Hotplug
1049 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1050 Hotplug is an obsolete framework for doing some of the things done by
1051 udev today. Specifically, handling kernel hotplug events. It is used in
1052 systems with kernel < 2.6.13 (e.g. RHEL4 / Centos4 and Debian 3.1). As
1053 such DAHDI still installs support for those. However if you package
1054 DAHDI for a more recent distribution, you should probably avoid
1055 including those obsolete config files.
1056
1057 The relevant files installed under /etc/hotplug/usb and are
1058 xpp/xpp_fxloader.usermap and xpp_fxloader (which is a symlink to
1059 /usr/share/dahdi/xpp_fxloader). the usermap file has the same format as
1060 modules.usbmap in the main kernel modules directory: it is intended to
1061 identify a (hotplugged) device.
1062
1063
1064 Loading The Modules
1065 ^^^^^^^^^^^^^^^^^^^
1066 Here is what should happen:
1067 In short: you should plug the Astribank device(s) or have them plugged in at
1068 the boot time. Then all the modules should be loaded automatically.
1069 You will see xpp_usb, xpp, and some xpd_* modules in the modules list 
1070 (the output of lsmod).
1071
1072 After the module xpp is loaded, you'll also be able to see the directory
1073 /proc/xpp. For any Astribank device discovered, you will see there a 
1074 directory /proc/xpp/XBUS-n (where n is a number: typically 0). Once a unit have
1075 been discovered you'll see subdirectories: /proc/xpp/XBUS-n/XPD-m (where
1076 m may be another number: 0, 1 ,etc).
1077
1078 Now to the ugly details:
1079
1080 The driver of the Astribank is composed of several modules: 
1081
1082 xpp::
1083   The basic module, that communicates with DAHDI and provides some 
1084   common services to other modules.
1085 xpd_fxs::
1086   FXS modules (analog phones). Module type 1.
1087 xpd_fxo::
1088   FXO modules (Analog PSTN lines). Module type 2.
1089 xpd_bri::
1090   BRI ("ISDN") modules. Module type 3.
1091 xpd_pri::
1092   The module for controlling E1/T1 modules. Module type 4.
1093 xpd_echo::
1094   The module for controlling hardware echo canceller modules. Module type 5.
1095   Does not generate a span.
1096 xpp_usb::
1097   The functionality needed to connect to the USB bus.
1098
1099 All modules depend on xpp, and modprobing them will install xpp as well.
1100 However the xpd_* modules are installed on-demand: no need to load 
1101 xpd_fxs if you have only Astribank FXS.
1102
1103 Once an Astribank device connected and the firmware is loaded, the
1104 Vendor-ID/Product-ID of the device will be  e4e4/11x2 . The handler for that
1105 combination is listed as the kernel module xpp_usb. Therefore, the system
1106 runs 'modprobe xpp_usb' if that module is not already loaded.
1107
1108 The module xpp_usb depends on the dahdi and xpp modules. Both of them 
1109 are loaded before xpp_usb. As usual, parameters and rules form
1110 /etc/modprobe.conf and/or from /etc/modprobe.d/* will be applied to 
1111 the module.
1112
1113 When command 'modprobe xpp_usb' returns, the span type specific modules
1114 (e.g., xpd_fxs, xpd_fxo) may or may not have been loaded yet.
1115
1116 At this point the xpp driver "asks" the box about its software
1117 (firmware) version) and the type of telephony modules it has. According 
1118 to the answers it receives, the xpp driver will "modprobe" the required 
1119 xpd_* modules. 
1120
1121 When an Astribank connects, it tells the driver what ports it has. For
1122 instance, a system with 8BRI (=type 3) ports and 3 modules of 8FXS
1123 (=type 1) ports:
1124 ----------------------------------------------
1125 INFO-xpp: XBUS-00: DESCRIPTOR: 4 cards, protocol revision 30
1126 INFO-xpp: XBUS-00:     CARD 0 type=3.0 ports=8 (2x4), port-dir=0xCC
1127 INFO-xpp: XBUS-00:     CARD 1 type=1.0 ports=8 (8x1), port-dir=0xFF
1128 INFO-xpp: XBUS-00:     CARD 2 type=1.0 ports=8 (8x1), port-dir=0xFF
1129 INFO-xpp: XBUS-00:     CARD 3 type=1.0 ports=8 (8x1), port-dir=0xFF
1130 ----------------------------------------------
1131
1132 If dahdi, xpp or xpp_usb is missing or defective, you'll get relatively
1133 clear error messages. However if an xpd_* module fails to load (e.g.:
1134 because it is missing), the error is less intuitive:
1135 --------------------------------------------------
1136 NOTICE-xpp: xproto_get: Failed to load module for type=3. exit status=256.
1137 NOTICE-xpp: XBUS-00: CARD 0: missing protocol table for type 3. Ignored.
1138 --------------------------------------------------
1139 In this case it was because I maliciously removed the module xpd_bri
1140 (type 3) from the system.
1141
1142 This can also happen if you accidentally blacklist the relevant xpd-*
1143 module. 'blacklist some_module' in modprobe.conf or modprobe.d/*.conf
1144 means that a direct insmod or modprobe of their name will work, but any
1145 attempt to load a module through its aliases will fail. Recall that the
1146 cpd-* modules are loaded on-demand using the alias 'xpd-type-N' .
1147
1148
1149 Device Initializations Scripts
1150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1151 The chips in the device need to be initialized. This requires sending a
1152 bunch of values to certain registers in those chips. We decided that
1153 hardwiring those values in the driver code is not a good idea.
1154 Before registering a XPD as a span in DAHDI, we run an initialization
1155 script: /usr/share/dahdi/init_card_N_MM where,
1156
1157 * N  is telephony module type: 1 for an FXS span and 2 for an FXO span, 
1158   3 for BRI and 4 for PRI.
1159 * MM - is a version number. Currently it equals 30.
1160
1161 Those scripts must be executable. If they are not, the initiallization
1162 will do nothing but will give no error, and the device will work in an
1163 unexpected way, if at all.
1164
1165 If because of some reasons this fails (the script is not in the place, 
1166 or the running it produced an error), then you will get an error message 
1167 in the logs and the XPD will then be removed (you won't see directory
1168 for that XPD under the corresponding /proc/xpp/XBUS-* directory) and 
1169 will not be registered with DAHDI.
1170
1171 As the XPD is initialized, you'll see the green LEDs of the ports steadily 
1172 turn on and later off ("a train of lights"). This is a bit slower than the 
1173 faster "blinking" when the XPDs register as DAHDI spans. The initialization 
1174 of an FXS XPD may take a few seconds.
1175
1176
1177 Connect / Disconnect Hook
1178 ^^^^^^^^^^^^^^^^^^^^^^^^^
1179 When the Astribank has finished initialization it also notifies
1180 userspace applications. This can be used to run a custom command when an
1181 Astribank is connected (after it has finished initialization) or when it
1182 has disconnected. The hook script is installed by default to
1183 /usr/share/dahdi/astribank_hook .
1184
1185
1186 Registering in DAHDI
1187 ^^^^^^^^^^^^^^^^^^^^
1188 The XPDs will not automatically register as DAHDI spans. This is
1189 intended to allow you to set the registration order (and hence the order
1190 of DAHDI spans and channels) among multiple Astribank devices,
1191 or between an Astribank and a different DAHDI device.
1192
1193 When the XPD registers with DAHDI, all the green LEDs will be lit for a
1194 short while. 
1195
1196 Spans are normally registered with the utility dahdi_registration. Simply
1197 running 'dahdi_registration' shows the available XPDs and whether or not
1198 they are registered. To register: 
1199
1200   dahdi_registration on
1201
1202 For a system with several spans you'll see a "fast train of lights".
1203
1204 If you have multiple Astribank devices, dahdi_registration will
1205 register them by the ascending order of the USB connector ID. This
1206 means that as long as the same Astribank is connected to the same
1207 port, the order of plugging is not important.
1208
1209 You can see the USB connector ID in the verbose output of the 
1210 dahdi_hardware utility when xpp drivers are loaded. See CONNECTOR value 
1211 in the example below:
1212
1213 ------------------------------------------------------
1214 # dahdi_hardware -v
1215 usb:004/006     xpp_usb+     e4e4:1152 Astribank-multi FPGA-firmware
1216  LABEL=[usb:0000148]        CONNECTOR=usb-0000:00:03.3-2
1217         XBUS-00/XPD-00: E1_TE    Span 1  DAHDI-SYNC
1218         XBUS-00/XPD-10: FXS      Span 2
1219         XBUS-00/XPD-20: FXS      Span 3
1220 usb:004/007     xpp_usb+     e4e4:1152 Astribank-multi FPGA-firmware
1221  LABEL=[usb:0000150]        CONNECTOR=usb-0000:00:03.3-6
1222         XBUS-01/XPD-00: FXS      Span 4
1223         XBUS-01/XPD-10: FXO      Span 5
1224 ------------------------------------------------------
1225
1226 If you have multiple Astribank devices, dahdi_registration will register
1227 them by the order of the "connector" field. This means that as long as
1228 the same Astribank is connected to the same port, the order of plugging
1229 is not important. Alternatively you can set an explicit registration
1230 order using /etc/dahdi/xpp_order . See above in section about
1231 <<_xpp_order_explicitly_order_astribanks,xpp_order>>.
1232
1233 The registration is performed through the sysfs interface. See below
1234 <<_sys_devices_xpp_xbus_nn_nn_m_p_span,the span attribute>>. Also note 
1235 that dahdi_registration also allows you to unregister spans, which will 
1236 work for all spans that are not in use (That is: none of their channels 
1237 is in use).
1238
1239 By default, the Astribank drivers don't perform automatic span
1240 registration on DAHDI. It is in contrast to the all known drivers of
1241 PCI boards. Because of that, DAHDI channels  related to the PCI board
1242 spans will get lower numbers than the channels related to Astribank
1243 devices.
1244
1245 You may choose to register the XPDs with DAHDI automatically. This may
1246 make the startup sequence a bit simpler, but is generally not
1247 recommended on a system with more than one Astribank or an Astribank and
1248 a different DAHDI device. This behavior may be defined by setting
1249 parameter <<_dahdi_autoreg>> in the modprobe configuration file (A file under
1250 /etc/modprobe.d or /etc/modprobe.conf):
1251
1252   options xpp dahdi_autoreg=1
1253
1254
1255 Astribanks Synchronization Source
1256 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1257 If there is more than one Astribank on the system, all the Astribanks
1258 keep their clock in sync. Optionally the Astribanks can synchronize
1259 their clock to the master DAHDI device (in case it is a different DAHDI
1260 device). Normally you just use the default init.d script or run
1261 explicitly:
1262
1263   xpp_sync auto
1264
1265 (For now see the man page of xpp_sync for more information)
1266
1267
1268 DAHDI And Above
1269 ^^^^^^^^^^^^^^^
1270 From here you get a standard DAHDI span. The next step is to configure
1271 the span by running the dahdi_cfg utility. You would also need to 
1272 configure the channels in the Asterisk chan_dahdi.conf file. Only after 
1273 that you will be able to make calls through the telephony ports.
1274
1275 You can use dahdi_genconf, which is included with dahdi-tools, to
1276 generate a DAHDI and Asterisk configuration for your system.
1277 For analog channels it works quite well, and likewise for BRI. For E1/T1 
1278 it will probably take some tuning.
1279
1280 Please refer to the general DAHDI documentation for more deatils about
1281 DAHDI and Asterisk configuration. E.g, the README file in the
1282 top-level directory, and 
1283
1284   http://voip-info.org/wiki/view/Asterisk+config+chan_dahdi.conf[]
1285
1286 Alternatively, write you own configuration, based on the sample from the
1287 "Sample Configurations" section.
1288
1289
1290 /proc Interface
1291 ~~~~~~~~~~~~~~~
1292 The Astribank drivers provide their own /proc interface under /proc/xpp.
1293 Here we review the more useful details of the procfs interface. There
1294 are many other debugging details that are exposed through the procfs
1295 interface. 
1296
1297 Also note that those details are subject to changes. Generally the
1298 recommended stable interface are the DAHDI-perl modules and utilities 
1299 from the xpp/ directory.
1300
1301
1302 /proc/xpp/xbuses
1303 ^^^^^^^^^^^^^^^^
1304 File /proc/xpp/xbuses lists the connected Astribank devices (one line 
1305 per device).
1306
1307 A device is normally has status "connected". The status "missing" means that
1308 the device has been disconnected, but Asterisk still holds channels from it
1309 open.
1310
1311
1312 For each Astribank device there is folder /proc/xpp/XBUS-nn and for each device
1313 module (span in the terms of DAHDI) there is folder /proc/XBUS-nn/XPD-mm.
1314
1315 /proc/xpp/XBUS-nn/XPD-mm/summary 
1316 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1317 Contains detailed information about port statuses of the device module 
1318 (off-hook, on-hook etc.) For example, you can run the following command
1319 in order to monitor the port statuses in the real time:
1320
1321   watch -n1 cat /proc/xpp/XBUS-00/XPD-00/summary
1322
1323
1324 /proc/xpp/XBUS-nn/XPD-mm/fxo_info
1325 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1326 Only for FXO modules. Apart from showing the status of the LEDs, it also
1327 shows for each FXO port if it is connected to a provider: look for the
1328 value of "battery" for that specific port, and a bunch of other
1329 characteristics of the port.
1330
1331
1332 /proc/xpp/XBUS-nn/XPD-mm/bri_info
1333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1334 In addition to the usual information about the LEDs, this file also
1335 provides useful information regarding ISDN Layer 1 and Layer 2 status.
1336 For example, you can run the following command in order to monitor
1337 the Layer 1 port statuses for all BRI devices in the real time:
1338
1339   watch -n1 -d 'grep "Layer 1:" /proc/xpp/XBUS-*/XPD-*/bri_info'
1340
1341 For the status of the D channel of the ports on all BRI spans, run:
1342
1343   watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/bri_info'
1344
1345
1346 /proc/xpp/XBUS-nn/XPD-mm/pri_info
1347 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1348 In addition to the usual information about the LEDs, this file also
1349 provides useful information regarding ISDN Layer 1 and Layer 2 status.
1350 For example, you can run the following command in order to monitor
1351 the Layer 1 port statuses for all E1/T1 devices in the real time:
1352
1353   watch -n1 -d 'grep "Layer 1:" /proc/xpp/XBUS-*/XPD-*/pri_info'
1354
1355 For the status of the D channel of the ports on all PRI spans, run:
1356
1357   watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/pri_info'
1358
1359 Note: the layer 2 status is much more of a guesswork based on changes in
1360 the contents of the channel that is supposed to be the D channel.
1361
1362
1363 There are a bunch of other status files under /proc/xpp/.
1364
1365
1366 /sys Interface
1367 ~~~~~~~~~~~~~~
1368 Astribanks on the system and the xpds themselves are also represented
1369 in SysFS. SysFS is a virtual file system mounted under /sys and provides 
1370 information in a more structured way than ProcFS. In sysfs objects are 
1371 represented as directories, simple attributes are shown as files in 
1372 the directory of the object and more complex objects are subdirectories 
1373 or symbolic links to other directories.
1374
1375 As with the procfs interface, we only document some interesting
1376 attribuets. Some attributes are writable and hence writing to them
1377 without knowing what you do is not exactly wise.
1378
1379 Like the procfs interface, this interface is subject to changes and
1380 should not be considered a stable interface. Please use the DAHDI-perl
1381 modules and utilities.
1382
1383
1384 Astribanks in SysFS
1385 ^^^^^^^^^^^^^^^^^^^
1386 Each astribank is represented as a device under
1387 /sys/bus/astribanks/devices , with the name xbus-NN, where NN is its 
1388 two-digit number (e.g.: 00, 01).
1389
1390 ===== /sys/bus/astribanks/devices/xbus-NN/cls
1391 CLear Statistics: writing to this file clear the procfs statistics for
1392 this Astribank.
1393
1394 ===== /sys/bus/astribanks/devices/xbus-NN/connector
1395 Connector string for the device. The place to which the Astribank is
1396 connected. e.g: usb-0000:00:03.3-2
1397
1398 ===== /sys/bus/astribanks/devices/xbus-NN/label
1399 The label string of the Astribank unit. E.g: usb:00000135
1400
1401 ===== /sys/bus/astribanks/devices/xbus-NN/status
1402 'connected' (normal operation) or 'disconnected' (has been disconnected,
1403 some channels are still open).
1404
1405 ===== /sys/bus/astribanks/devices/xbus-NN/timing
1406 Provides some statistics in case the Astribank is not the sync source.
1407 The format of this file is subject to future changes.
1408
1409 ===== /sys/bus/astribanks/devices/xbus-NN/waitfor_xpds
1410 Reading from this file only returns when the Astribank has finished
1411 initialization of the XPDs or in case of a timeout. It prints the number
1412 of XPDs to initialize, and the number initialize. Unless something went
1413 wrong, those two numbers are the same. Once the span was initialized,
1414 reading from this file returns immediately:
1415
1416   XPDS_READY: XBUS-00: 3/3
1417
1418 ===== /sys/bus/astribanks/devices/xbus-NN/xbus_state
1419 Reading from it prints the name and number of the state of the
1420 Astribank. This file is also writable: you can write either 'stop' to
1421 disconnect the specific Astribank, or 'start' to reconnect it.
1422
1423 ===== /sys/bus/astribanks/drivers/xppdrv/sync
1424 (An attribute of the generic Astribanks driver)
1425
1426 The synchronization source. Normally the number of the astribank that is
1427 the synchronization master, or 'SYNC=DAHDI' if Astribanks are
1428 synchronized from a different DAHDI device. Normally you should just use
1429 xpp_sync, though.
1430
1431 Current possible writable values:
1432
1433 <number>::
1434   Make the Astribank XBUS-<number> the sync source for other Astribanks.
1435
1436 DAHDI::
1437   Make the Astribanks synchronize with the DAHDI timing master span.
1438   You probably need this to get faxes from a non-Astribank adapter to an
1439   Astribank.
1440
1441
1442 XPDs in SysFS
1443 ^^^^^^^^^^^^^
1444 Under the Astribank you'll find a subdirectory for each of its XPDs
1445 ("spans"). The name of the directory is composed of three numbers:
1446
1447 <astribank>:<module>:<subunit>
1448
1449 astribank::
1450   Two-digit name of the Astribank in which this XPD is in. If it is
1451   xbus-03, you will see there '03'.
1452
1453 module::
1454   The number of the Astribank module: from 0 (left-most) to 3
1455   (right-most).
1456
1457 subunit::
1458   In a module that has several spans: the number of the span. In
1459   practice this is only for BRI and PRI and hence the module number will
1460   always be 0 in this case. 
1461
1462 The two-digit number of the XPD in the procfs interface is in fact
1463 <module><subunit>.
1464
1465 Under this you see several attributes.
1466
1467 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/blink
1468 You can write here a number which will be considered to be a bitmask
1469 of the ports that should blink (0 - no blinking). Reading from here
1470 shows that bitmask. If you think that this is complicated, just use
1471 xpp_blink.
1472
1473 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/chipregs
1474 Provides direct read/write interface to the registers of each chip. 
1475 Reading from the file shows the result of the last read request. To make
1476 either a read request or a write request you need to write to that file.
1477
1478 It is mainly used by the initialization scripts (init_card_*).
1479
1480 Incorrect usage of this file is one possible way of damaging the
1481 Astribank.
1482
1483 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/fxo_battery
1484 (Only on FXO) - shows ports that have (+) or don't have (-) battery
1485 current. That is: which ones are connected to an active FXS on the
1486 other side.
1487
1488 current. That is: which ones are connected to an active FXS on the
1489 other side.
1490
1491 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/offhook
1492 Shows ports that are (1) or are not (0) off-hook. When a channel is
1493 not off-hook. For BRI and E1/T1 the value is 1 if the span is in use.
1494 This value can also be used to get the number of lines (channels) in
1495 this XPD: the count of items in this list.
1496
1497 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/span
1498 is a read/write file. Reading from it gives 0 if the span is
1499 unregistered, or the span number if it is registered.
1500
1501 Writing to it allows manual registration / unregistration from DAHDI:
1502 writing 1 registers a span (if it wasn't already registered) and writing
1503 0 attempts to unregister it (if it is registered.  Span unregistration 
1504 will fail if some channels from the span are used  (e.g: by Asterisk).
1505
1506 A more convenient interface to this is the command dahdi_registration that
1507 registers or unregisters all the spans at once with a predefined order,
1508 and this is what you should normally use.
1509
1510 Alternatively you can use the parameter dahdi_autoreg to register spans
1511 automatically. But this is only recommended on a system with a single
1512 Astribank and no other DAHDI device.
1513
1514 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/driver
1515 This is a standard sysfs feature: from the directory of the device you
1516 have a link called "driver" to the directory of the driver that
1517 handles it. One specific interesting thing is that this allows you to
1518 easily see all the XPDs of the same type, as they are linked again
1519 from the driver's directory.
1520
1521
1522 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/pri_protocol
1523 Can have either of those two:
1524
1525 E1::
1526   Provides 31 channels, of which channel 16 is normally the D-channel. 
1527   Common in places outside of North America and Japan. This is the 
1528   default setup.
1529
1530 T1::
1531   T1 provides 24 channels. The last one is normally the D-Channel.
1532   Common in North America.
1533
1534 This can also be set by writing the strings explicitly to the file. But
1535 can only be done when an XPD is not a registered span.
1536
1537 This writing is normally done by the device initialization script, based
1538 on the 'pri_protocol' settings in 
1539 xref:_xpp_conf_astribank_initialization[/etc/dahdi/xpp.conf] .
1540
1541
1542 Useful Module Parameters
1543 ~~~~~~~~~~~~~~~~~~~~~~~~
1544 Compilation-time defaults for the all modules can be shown as part of the
1545 description line for the parameter in the "modinfo" command output.
1546
1547 ==== dahdi_autoreg
1548 (xpp)
1549
1550 Register spans automatically (1) or not (0). Default: 0. 
1551 Setting it simplifies operations with a single Astribank and no other 
1552 DAHDI hardware. However if you have such systems, automatic
1553 registration can cause the order of spans to be unpredictable.
1554 The standard startup scripts use 'dahdi_registration on' instead of this.
1555
1556 ==== initdir
1557 (xpp)
1558
1559 This is the directory containing the initialization scripts.
1560 The default is /usr/share/dahdi .
1561 Setting this value could be useful if that location is inconvenient for you.
1562
1563 ==== rx_tasklet
1564 (xpp)
1565
1566 Enable (1) or disable (0) doing most of the packets processing in
1567 separate tasklets. This should probably help on higher-end systems with
1568 multiple Astribanks.
1569
1570 ==== debug
1571 (all modules)
1572
1573 It will make the driver to print tons of debugging messages. You can 
1574 set/unset the parameter at run-time. The parameter value is a bitmask 
1575 of several values. The different bits  meaning as it defined in 
1576 xpp/dahdi_debug.h: 
1577
1578 * 0  - Disable debug messages
1579 * 1  - GENERAL - General debug comments.
1580 * 2  - PCM - PCM-related messages. Tends to flood logs.
1581 * 4  - LEDS - Anything related to the LEDs status control. The driver
1582        produces a lot of messages when the option is enabled.
1583 * 8  - SYNC - Synchronization related messages.
1584 * 16 - SIGNAL - DAHDI signalling related messages.
1585 * 32 - PROC - Messages related to the procfs interface.
1586 * 64 - REGS - Reading and writing to chip registers. Tends to flood
1587          logs.
1588 * 128 - DEVICES - Device instantiation, destruction and such.
1589 * 256 - COMMANDS - Protocol commands. Tends to flood logs.
1590
1591 For example,
1592
1593   echo 33 >/sys/modules/xpp/parameters/debug 
1594
1595 forces module xpp to print general debugging messages (1) and procfs
1596 debugging messages (32).
1597
1598 ==== vmwi_ioctl
1599 (xpd_fxs)
1600
1601 Does userspace support VMWI notification via ioctl? Default: 1 (yes).
1602
1603 Disable this (0) to have the driver attempt to detect the voicemail
1604 message waiting indication status for this port from FSK messages
1605 userspace (Asterisk) sends. Set the ports to use AC neon-lamp style
1606 message waiting indication. The detection from the FSK messages takes
1607 extra CPU cycles but is required with e.g. Asterisk 1.4.x .
1608
1609 Also note that in order for this parameter to take effect, it must be
1610 set before the span is registered. This practically means that it
1611 should be set through modprobe.d files.
1612
1613 See also <<_voicemail_indication,Voicemail Indication>>.
1614
1615 ==== usb1
1616 (xpp_usb)
1617
1618 Enable (1) or disable (0) support of USB1 devices. Disabled by default.
1619
1620 USB1 devices are not well-tested. It seems that they don't work at all
1621 for Astribank BRI. Generally they should work with the current code, but
1622 we expect the voice quality issues. Hence we would like to make it
1623 very clear that you if you have a USB1 port (rather than a USB2 one, as 
1624 recommended) you will have to take an action to enable the device.
1625
1626 ==== poll intervals 
1627 (various)
1628
1629 There are various values which the driver occasionally polls the
1630 device for. For instance, the parameter poll_battery_interval for
1631 xpd_fxo to poll the battery, in order to know if the telco line is
1632 actually connected.
1633
1634 The value of those parameters is typically a number in milliseconds. 
1635 0 is used to disable polling. Under normal operation there should be 
1636 no reason to play with those parameters.
1637
1638 ==== dtmf_detection
1639 (xpd_fxs)
1640
1641 Enable (1) or disable (0) support of hardware DTMF detection by the 
1642 Astribank.
1643
1644 ==== caller_id_style
1645 (xpd_fxo)
1646
1647 Various types of caller ID signalling styles require knowing the PCM
1648 even when the line is on-hook (which is usually a waste of CPU and
1649 bandwidth). This parameter allows fine-tuning the behaviour here:
1650
1651 * 0 (default) - Don't pass extra PCM when on-hook.
1652 * 1 ETSI-FSK: Wait for polarity reversal to come before a ring and 
1653   then start passing PCM until the caller ID has been passed.
1654 * 2 Always: Always pass PCM.
1655
1656 This parameter is read-only. It cannot be changed at run-time.
1657
1658 ==== battery_threshold
1659 (xpd_fxo)
1660
1661 Minimum voltage that shows there is battery. Defaults to 3. Normally you
1662 should not need to change this, unless dealing with a funky PSTN
1663 provider.
1664
1665 ==== battery_debounce
1666 (xpd_fxo)
1667
1668 Minimum interval (msec) for detection of battery off (as opposed to e.g.
1669 a temporary power denial to signal a hangup). Defaults to 1000. As with
1670 battery_threshold above, there's normally no need to tweak it.
1671
1672
1673 NOTE: XPP here does not stand for X Printing Panel, XML Pull Parser, 
1674 X-Windows Phase Plane or XML Professional Publisher. It is simply the 
1675 Xorcom Peripheral Protocol, which connects a computer to a XPD (Xorcom 
1676 Peripheral Device). An XBUS (originally XPP Bus) is actually a single
1677 Astribank device and the XPDs have become the single modules in it.