Debian Codegraph @

xpp/README.Astribank

raw
1 Xorcom Astribank Documentation
2 ==============================
3 Xorcom Team <[email protected]>
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-1.0-0-dev on Debian (and
51 derivatives such as Ubuntu) or libusbx-devel on RedHat (and derivatives
52 such as CentOS).
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 it would be run automatically from the udev hooks
1261 run on device plug (handle_device), but you can also run it 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/hwid
1492 Prints <module type>.<module subtype>. Both are small numbers.
1493
1494 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/offhook
1495 Shows ports that are (1) or are not (0) off-hook. When a channel is
1496 not off-hook. For BRI and E1/T1 the value is 1 if the span is in use.
1497 This value can also be used to get the number of lines (channels) in
1498 this XPD: the count of items in this list.
1499
1500 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/span
1501 is a read/write file. Reading from it gives 0 if the span is
1502 unregistered, or the span number if it is registered.
1503
1504 Writing to it allows manual registration / unregistration from DAHDI:
1505 writing 1 registers a span (if it wasn't already registered) and writing
1506 0 attempts to unregister it (if it is registered. Span unregistration
1507 will fail if some channels from the span are used (e.g: by Asterisk).
1508
1509 A more convenient interface to this is the command dahdi_registration that
1510 registers or unregisters all the spans at once with a predefined order,
1511 and this is what you should normally use.
1512
1513 Alternatively you can use the parameter dahdi_autoreg to register spans
1514 automatically. But this is only recommended on a system with a single
1515 Astribank and no other DAHDI device.
1516
1517 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/driver
1518 This is a standard sysfs feature: from the directory of the device you
1519 have a link called "driver" to the directory of the driver that
1520 handles it. One specific interesting thing is that this allows you to
1521 easily see all the XPDs of the same type, as they are linked again
1522 from the driver's directory.
1523
1524
1525 ===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/pri_protocol
1526 Can have either of those two:
1527
1528 E1::
1529 Provides 31 channels, of which channel 16 is normally the D-channel.
1530 Common in places outside of North America and Japan. This is the
1531 default setup.
1532
1533 T1::
1534 T1 provides 24 channels. The last one is normally the D-Channel.
1535 Common in North America.
1536
1537 This can also be set by writing the strings explicitly to the file. But
1538 can only be done when an XPD is not a registered span.
1539
1540 This writing is normally done by the device initialization script, based
1541 on the 'pri_protocol' settings in
1542 xref:_xpp_conf_astribank_initialization[/etc/dahdi/xpp.conf] .
1543
1544
1545 Useful Module Parameters
1546 ~~~~~~~~~~~~~~~~~~~~~~~~
1547 Compilation-time defaults for the all modules can be shown as part of the
1548 description line for the parameter in the "modinfo" command output.
1549
1550 ==== dahdi_autoreg
1551 (xpp)
1552
1553 Register spans automatically (1) or not (0). Default: 0.
1554 Setting it simplifies operations with a single Astribank and no other
1555 DAHDI hardware. However if you have such systems, automatic
1556 registration can cause the order of spans to be unpredictable.
1557 The standard startup scripts use 'dahdi_registration on' instead of this.
1558
1559 ==== initdir
1560 (xpp)
1561
1562 This is the directory containing the initialization scripts.
1563 The default is /usr/share/dahdi .
1564 Setting this value could be useful if that location is inconvenient for you.
1565
1566 ==== rx_tasklet
1567 (xpp)
1568
1569 Enable (1) or disable (0) doing most of the packets processing in
1570 separate tasklets. This should probably help on higher-end systems with
1571 multiple Astribanks.
1572
1573 ==== debug
1574 (all modules)
1575
1576 It will make the driver to print tons of debugging messages. You can
1577 set/unset the parameter at run-time. The parameter value is a bitmask
1578 of several values. The different bits meaning as it defined in
1579 xpp/dahdi_debug.h:
1580
1581 * 0 - Disable debug messages
1582 * 1 - GENERAL - General debug comments.
1583 * 2 - PCM - PCM-related messages. Tends to flood logs.
1584 * 4 - LEDS - Anything related to the LEDs status control. The driver
1585 produces a lot of messages when the option is enabled.
1586 * 8 - SYNC - Synchronization related messages.
1587 * 16 - SIGNAL - DAHDI signalling related messages.
1588 * 32 - PROC - Messages related to the procfs interface.
1589 * 64 - REGS - Reading and writing to chip registers. Tends to flood
1590 logs.
1591 * 128 - DEVICES - Device instantiation, destruction and such.
1592 * 256 - COMMANDS - Protocol commands. Tends to flood logs.
1593
1594 For example,
1595
1596 echo 33 >/sys/modules/xpp/parameters/debug
1597
1598 forces module xpp to print general debugging messages (1) and procfs
1599 debugging messages (32).
1600
1601 ==== vmwi_ioctl
1602 (xpd_fxs)
1603
1604 Does userspace support VMWI notification via ioctl? Default: 1 (yes).
1605
1606 Disable this (0) to have the driver attempt to detect the voicemail
1607 message waiting indication status for this port from FSK messages
1608 userspace (Asterisk) sends. Set the ports to use AC neon-lamp style
1609 message waiting indication. The detection from the FSK messages takes
1610 extra CPU cycles but is required with e.g. Asterisk 1.4.x .
1611
1612 Also note that in order for this parameter to take effect, it must be
1613 set before the span is registered. This practically means that it
1614 should be set through modprobe.d files.
1615
1616 See also <<_voicemail_indication,Voicemail Indication>>.
1617
1618 ==== usb1
1619 (xpp_usb)
1620
1621 Enable (1) or disable (0) support of USB1 devices. Disabled by default.
1622
1623 USB1 devices are not well-tested. It seems that they don't work at all
1624 for Astribank BRI. Generally they should work with the current code, but
1625 we expect the voice quality issues. Hence we would like to make it
1626 very clear that you if you have a USB1 port (rather than a USB2 one, as
1627 recommended) you will have to take an action to enable the device.
1628
1629 ==== poll intervals
1630 (various)
1631
1632 There are various values which the driver occasionally polls the
1633 device for. For instance, the parameter poll_battery_interval for
1634 xpd_fxo to poll the battery, in order to know if the telco line is
1635 actually connected.
1636
1637 The value of those parameters is typically a number in milliseconds.
1638 0 is used to disable polling. Under normal operation there should be
1639 no reason to play with those parameters.
1640
1641 ==== dtmf_detection
1642 (xpd_fxs)
1643
1644 Enable (1) or disable (0) support of hardware DTMF detection by the
1645 Astribank.
1646
1647 ==== caller_id_style
1648 (xpd_fxo)
1649
1650 Various types of caller ID signalling styles require knowing the PCM
1651 even when the line is on-hook (which is usually a waste of CPU and
1652 bandwidth). This parameter allows fine-tuning the behaviour here:
1653
1654 * 0 (default) - Don't pass extra PCM when on-hook.
1655 * 1 ETSI-FSK: Wait for polarity reversal to come before a ring and
1656 then start passing PCM until the caller ID has been passed.
1657 * 2 Always: Always pass PCM.
1658
1659 This parameter is read-only. It cannot be changed at run-time.
1660
1661 ==== battery_threshold
1662 (xpd_fxo)
1663
1664 Minimum voltage that shows there is battery. Defaults to 3. Normally you
1665 should not need to change this, unless dealing with a funky PSTN
1666 provider.
1667
1668 ==== battery_debounce
1669 (xpd_fxo)
1670
1671 Minimum interval (msec) for detection of battery off (as opposed to e.g.
1672 a temporary power denial to signal a hangup). Defaults to 1000. As with
1673 battery_threshold above, there's normally no need to tweak it.
1674
1675
1676 NOTE: XPP here does not stand for X Printing Panel, XML Pull Parser,
1677 X-Windows Phase Plane or XML Professional Publisher. It is simply the
1678 Xorcom Peripheral Protocol, which connects a computer to a XPD (Xorcom
1679 Peripheral Device). An XBUS (originally XPP Bus) is actually a single
1680 Astribank device and the XPDs have become the single modules in it.