Xorcom Astribank Documentation

The Xorcom Astribank is a USB-connected channel-bank. An Astribank may have up to 4 modules:

There is also a 6FXS-2FXO module that is essentially an FXS module with six lines instead of 8 (but still with the input and output ports) and an FXO module of two ports.

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

(As of DAHDI 2.2 this patch is no longer needed. Furthermore, it does not apply. The same directory has a newer patch that applies. This section is kept in the document for the time being for the benefit of those with older versions)

In order for the BRI module (xpd_bri.ko) to build, you still need an external patch:

http://updates.xorcom.com/astribank/bristuff/dahdi_bri_dchan.diff

You need to apply it to the dahdi-linux tarball before building:

Below are some commented sequences of commands that can be used at some common scenarios. Those scenarios begin only after you installed the software (dahdi-linux, dahdi-tools, asterisk, etc.).

Installing Astribank on a system where there's no existing Astribank. You install the driver when the Astribank was already connected:

Upgrading is roughly the same as a new installation. But in many cases you begin with resetting the firmware.

I also assume here that the configuration is valid, and hence I don't generate it.

We generally recommend to generate the configuration by using utility dahdi_genconf which are included with DAHDI. Nevertheless, the following can serve as reference configurations for a system where Astribank devices are used.

Also refer to the general README for documentation of the other DAHDI configuration files.

/etc/dahdi/xpp.conf is read by the initialization scripts of Astribank modules:

(This feature is available as of DAHDI 2.2)

On a system with multiple Astribank you would normally want to guarantee that Astribanks are registered in the same order regardless of the order in which they are connected or detected. Assuming that you register them all at the same time. In order to do that, you should list the Astribanks explicitly under /etc/dahdi/xpp_order .

Astribanks that are listed there are registered first (according to the order of lines in the files). Astribanks not listed there are added last, and sorted by the USB connector string.

You can identify an Astribank in two ways:

Identifying an Astribank by the label seems simpler and more predictable. Though it may have some slightly surprising effects if replace one Astribank with another.

The sample configuration file:

In order to generate one that includes all the Astribanks in the system with the current order in which they are connected, use:

For more technical details see the section [_registering_in_dahdi] below.

Sample dialplan (extensions.conf) for all the above:

The following commands provide useful information for debugging:

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

Check if the Astribank spans are registered with DAHDI:

You can get some information regarding DAHDI channels by running one of the following commands:

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

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

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

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

Reset the firmware:

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

You see USB-related errors similar to the following whenever you shut down the drivers of the Astribank or disconnect its drivers:

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

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

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

You may also see an error message such as:

from the exact time of the disconnecting.

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

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

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

You fail to find an Astribank device in the output of lsusb . But you see it in lsusb | grep e4e4

The perl module Dahdi::Hardware currently relies on /proc/bus/usb/devices (from usbfs) whereas lsusb can use either that or /dev/bus/usb .

Usbfs is generally deprecated and some distributions (OpenSUSE, Ubuntu) no longer mount it by default. Try:

and if that doesn't work:

However this is generally a cosmetic issue that only affects the listing in dahdi_hardware.

After upgrading to Zaptel 1.4.12 / 1.2.25 the initialization of the Astribank times out. In the logs you see:

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

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

Reset the firmware of the Astribank by either:

or disconnecting it from the power and reconnecting it.

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

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

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

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

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

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

As for the leds of the PRI ports, see the next section.

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

Each port in the PRI module can be configured either as E1 or T1. The default is E1, but it can be changed in xpp.conf (See the section above).

In addition to that, a port defaults to consider itself a CPE, or rather, to accept timing from the remote party. To override that you need to set the timing value to 0 (second parameter in the span= line in system.conf).

Thus the following in system.conf will also set an ornage LED:

Note that as this is only applied when ztcfg is run, the port will have the default green LED lit at the bottom until it is configured.

This section describes in great depth the initialization of the Xorcom Astribank. Normally it would not be really needed, as the standard installation of DAHDI should put everything in place. This is generally some documentation to read when things fail.

There are some technical terms that are used in this document and in the driver / dahdi.

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

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

The firmware files are named *.hex. They are presented in the Intel hex format. The files are copied from xpp/utils to /usr/share/dahdi folder during the DAHDI installation.

The Astribank needs a firmware loaded into it. Without the firmware, the device will appear in lsusb with Vendor ID e4e4 and Product ID 11x0 (1130, 1140, 1150, 1160 or 1163. 1163 behaves almost exactly as 1160). The firmware loading process consists of two stages. In the first stage the "USB" firmware is loaded by using program fxload. When the first stage is completed the Vendor ID is e4e4 and the Product ID is 11x1. (e.g. 1151 if it were 1150 previously).

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

where,

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

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

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

With older USB firmwares (before the one included in e.g. dahdi-linux 2.2) you needed to use instead of all the above:

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

On newer systems (e.g. Centos 4) /dev/bus/usb may not be available. In that case, use /proc/bus/usb . usbfs should be mounted there.

Udev is a framework for dynamic device nodes, which is supported in kernel 2.6. if your udev rules are properly configured then the firmware should be loaded automatically and you will see product ID 11x2 (e.g.: 1152).

Udev is mostly configured by files under /etc/udev/rules.d . The installer of dahdi-linux installs drivers/dahdi/xpp/xpp.rules into that directory.

This file instructs udev to run /usr/share/dahdi/xpp_fxloader for each time an Astribank connects and needs firmware. When the Astribank loads firmware or when it resets its firmware it "reenumerates" - disconnects and reconnects as a new device.

Below are kernel log messages of an Astribank loading firmware. It firs connects without any firmware (device no. 44). Udev tells it to load the USB firmware. It disconnects and reconnects (45). This Udev gets the FPGA firmware loaded into it. It disconnects again, and when it reconnects it is now ready to talk with the driver. The last message is from the driver.

Another useful tool for tracing UDEV-related issue is the udev monitor:

Or with some older versions of udev:

Hotplug is an obsolete framework for doing some of the things done by udev today. Specifically, handling kernel hotplug events. It is used in systems with kernel < 2.6.13 (e.g. RHEL4 / Centos4 and Debian 3.1). As such DAHDI still installs support for those. However if you package DAHDI for a more recent distribution, you should probably avoid including those obsolete config files.

The relevant files installed under /etc/hotplug/usb and are xpp/xpp_fxloader.usermap and xpp_fxloader (which is a symlink to /usr/share/dahdi/xpp_fxloader). the usermap file has the same format as modules.usbmap in the main kernel modules directory: it is intended to identify a (hotplugged) device.

Here is what should happen: In short: you should plug the Astribank device(s) or have them plugged in at the boot time. Then all the modules should be loaded automatically. You will see xpp_usb, xpp, and some xpd_* modules in the modules list (the output of lsmod).

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

Now to the ugly details:

The driver of the Astribank is composed of several modules:

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

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

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

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

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

When an Astribank connects, it tells the driver what ports it has. For instance, a system with 8BRI (=type 3) ports and 3 modules of 8FXS (=type 1) ports:

If dahdi, xpp or xpp_usb is missing or defective, you'll get relatively clear error messages. However if an xpd_* module fails to load (e.g.: because it is missing), the error is less intuitive:

In this case it was because I maliciously removed the module xpd_bri (type 3) from the system.

This can also happen if you accidentally blacklist the relevant xpd- module. blacklist some_module in modprobe.conf or modprobe.d/.conf means that a direct insmod or modprobe of their name will work, but any attempt to load a module through its aliases will fail. Recall that the cpd-* modules are loaded on-demand using the alias xpd-type-N .

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

Those scripts must be executable. If they are not, the initiallization will do nothing but will give no error, and the device will work in an unexpected way, if at all.

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

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

When the Astribank has finished initialization it also notifies userspace applications. This can be used to run a custom command when an Astribank is connected (after it has finished initialization) or when it has disconnected. The hook script is installed by default to /usr/share/dahdi/astribank_hook .

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

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

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

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

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

You can see the USB connector ID in the verbose output of the dahdi_hardware utility when xpp drivers are loaded. See CONNECTOR value in the example below:

If you have multiple Astribank devices, dahdi_registration will register them by the order of the "connector" field. This means that as long as the same Astribank is connected to the same port, the order of plugging is not important. Alternatively you can set an explicit registration order using /etc/dahdi/xpp_order . See above in section about xpp_order.

The registration is performed through the sysfs interface. See below the span attribute. Also note that dahdi_registration also allows you to unregister spans, which will work for all spans that are not in use (That is: none of their channels is in use).

By default, the Astribank drivers don't perform automatic span registration on DAHDI. It is in contrast to the all known drivers of PCI boards. Because of that, DAHDI channels related to the PCI board spans will get lower numbers than the channels related to Astribank devices.

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

If there is more than one Astribank on the system, all the Astribanks keep their clock in sync. Optionally the Astribanks can synchronize their clock to the master DAHDI device (in case it is a different DAHDI device). Normally you just use the default init.d script or run explicitly:

(For now see the man page of xpp_sync for more information)

From here you get a standard DAHDI span. The next step is to configure the span by running the dahdi_cfg utility. You would also need to configure the channels in the Asterisk chan_dahdi.conf file. Only after that you will be able to make calls through the telephony ports.

You can use dahdi_genconf, which is included with dahdi-tools, to generate a DAHDI and Asterisk configuration for your system. For analog channels it works quite well, and likewise for BRI. For E1/T1 it will probably take some tuning.

Please refer to the general DAHDI documentation for more deatils about DAHDI and Asterisk configuration. E.g, the README file in the top-level directory, and

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

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

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

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

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

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

Contains detailed information about port statuses of the device module (off-hook, on-hook etc.) For example, you can run the following command in order to monitor the port statuses in the real time:

Only for FXO modules. Apart from showing the status of the LEDs, it also shows for each FXO port if it is connected to a provider: look for the value of "battery" for that specific port, and a bunch of other characteristics of the port.

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

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

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

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

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

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

Astribanks on the system and the xpds themselves are also represented in SysFS. SysFS is a virtual file system mounted under /sys and provides information in a more structured way than ProcFS. In sysfs objects are represented as directories, simple attributes are shown as files in the directory of the object and more complex objects are subdirectories or symbolic links to other directories.

As with the procfs interface, we only document some interesting attribuets. Some attributes are writable and hence writing to them without knowing what you do is not exactly wise.

Like the procfs interface, this interface is subject to changes and should not be considered a stable interface. Please use the DAHDI-perl modules and utilities.

Each astribank is represented as a device under /sys/bus/astribanks/devices , with the name xbus-NN, where NN is its two-digit number (e.g.: 00, 01).

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

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

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

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

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

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

Reading from it prints the name and number of the state of the Astribank. This file is also writable: you can write either stop to disconnect the specific Astribank, or start to reconnect it.

(An attribute of the generic Astribanks driver)

The synchronization source. Normally the number of the astribank that is the synchronization master, or SYNC=DAHDI if Astribanks are synchronized from a different DAHDI device. Normally you should just use xpp_sync, though.

Current possible writable values:

Under the Astribank you'll find a subdirectory for each of its XPDs ("spans"). The name of the directory is composed of three numbers:

<astribank>:<module>:<subunit>

The two-digit number of the XPD in the procfs interface is in fact <module><subunit>.

Under this you see several attributes.

You can write here a number which will be considered to be a bitmask of the ports that should blink (0 - no blinking). Reading from here shows that bitmask. If you think that this is complicated, just use xpp_blink.

Provides direct read/write interface to the registers of each chip. Reading from the file shows the result of the last read request. To make either a read request or a write request you need to write to that file.

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

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

(Only on FXO) - shows ports that have (+) or don't have (-) battery current. That is: which ones are connected to an active FXS on the other side.

current. That is: which ones are connected to an active FXS on the other side.

Shows ports that are (1) or are not (0) off-hook. When a channel is not off-hook. For BRI and E1/T1 the value is 1 if the span is in use. This value can also be used to get the number of lines (channels) in this XPD: the count of items in this list.

is a read/write file. Reading from it gives 0 if the span is unregistered, or the span number if it is registered.

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

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

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

This is a standard sysfs feature: from the directory of the device you have a link called "driver" to the directory of the driver that handles it. One specific interesting thing is that this allows you to easily see all the XPDs of the same type, as they are linked again from the driver's directory.

Can have either of those two:

This can also be set by writing the strings explicitly to the file. But can only be done when an XPD is not a registered span.

This writing is normally done by the device initialization script, based on the pri_protocol settings in /etc/dahdi/xpp.conf .

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

(xpp)

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

(xpp)

This is the directory containing the initialization scripts. The default is /usr/share/dahdi . Setting this value could be useful if that location is inconvenient for you.

(xpp)

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

(all modules)

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

For example,

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

(xpd_fxs)

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

(xpp_usb)

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

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

(various)

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

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

(xpd_fxs)

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

(fxo)

Various types of caller ID signalling styles require knowing the PCM even when the line is on-hook (which is usually a waste of CPU and bandwidth). This parameter allows fine-tuning the behaviour here:

This parameter is read-only. It cannot be changed at run-time.