Xorcom Astribank Documentation

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.

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 astribank_tool) 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.

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 astribank_hexload and astribank_tool, which are 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:

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.

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/.

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).

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.

(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)

Does userspace support VMWI notification via ioctl? Default: 1 (yes).

Disable this (0) to have the driver attempt to detect the voicemail message waiting indication status for this port from FSK messages userspace (Asterisk) sends. Set the ports to use AC neon-lamp style message waiting indication. The detection from the FSK messages takes extra CPU cycles but is required with e.g. Asterisk 1.4.x .

Also note that in order for this parameter to take effect, it must be set before the span is registered. This practically means that it should be set through modprobe.d files.

See also Voicemail Indication.

(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.

(xpd_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.

(xpd_fxo)

Minimum voltage that shows there is battery. Defaults to 3. Normally you should not need to change this, unless dealing with a funky PSTN provider.

(xpd_fxo)

Minimum interval (msec) for detection of battery off (as opposed to e.g. a temporary power denial to signal a hangup). Defaults to 1000. As with battery_threshold above, there’s normally no need to tweak it.