Xorcom Astribank Documentation

Building and installation is basically like the normal procedure of installing Dahdi with some additions.

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

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

The dahdi init.d script, genzaptelconf and the XPD init scripts uses the parameters located in file /etc/default/zaptel (on Debian) or /etc/sysconfig/zaptel (on RedHats). There is a number of useful parameters that may be defined there:

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

The firmware fails to load. Manually running xpp_fxloader gives:

Alternatively: an initialization script fails and gives the error

/etc/default/<service name> is the place used in Debian-based systems for initialization scripts. /etc/sysconfig/<service name> is used in Redhat and similar for the same purpose. For historical reasons many of our programs read configuration from there: either from /etc/default/zaptel or from /etc/sysconfig/zaptel .

The problem is what to do if both of those exist. Selecting an arbitrary one can lead to unexpected results. Likewise sourcing both of them. Therefore we prefer to fail in a noisy and expected way. In the future we will probably me to reading configuration from a file under /etc/dahdi .

Remove one of those two. There should be no reason to have both on the same system.

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

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

For each port there are two optional parameters that define its behavior:

Each port in the PRI module can be configured either as E1 or T1. The port type defaults to E1 and can be changed to T1 in the Dahdi Init Configuration File.

The Astribank xpp driver uses that information for correct hardware initialization that is performed before the Dahdi span registration process takes place. Because of that, xpp driver can't use the information from file /etc/dahdi/system.conf.

Another parameter that also can be defined in the Dahdi Init Configuration File is the function group TE (CPE) or NT (Network). This parameter is used for (a) building correct Dahdi & Asterisk configuration by genzaptelconf and (b) control RJ-45 sockets LEDs for better visual port control:

A port in the PRI module can be either E1 (default) or T1. It can also be either "TE" (default) or "NT".

To set them to a non-default value, you should use the variable XPP_PRI_SETUP in the Dahdi Init Configuration File (/etc/sysconfig/zaptel on Redhats, /etc/default/zaptel on Debians). This value is a whitespace-separated list of conditions. When a port is initialized it checks those conditions and uses the first one that matches.

Match expressions may be: - CONNECTOR/usb…./XPD-nn To identify by physical connector - NUM/XBUS-mm/XPD-nn To identify by bus number

Match expressions may contain "wildcards":

For each line you should define both if it is E1 or T1 and if it is NT or TE.

The list implicitly contains an NUM/*=TE,E1 catch all default, appended to its end.

A number of useful examples. Note that you should use just one of them.

This is currently implemented by writing a value to the pri_info file in procfs, but that may change in future versions.

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.

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

span: Dahdi breaks the channels it knows about to logical units called "spans". A port in a E1/T1/ISDN card is usually a span. An whole analog card is also a "span". You can see the list of spans as the list of files under /proc/dahdi directory or in output of the dahdi_tool utility.

XBUS: A funny way to call an Astribank device.

XPD: Basically this is a logical unit of the Astribank. It will be registered in Dahdi as a single span. This can be either an analog (FXS or FXO) module or a single port in case of a BRI module.

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 text hexadecimal 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 1130. 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 1131.

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 1131 (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:

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.

The Hotplug framework was popular for hot-plugging different devices and usually also for automatic device drivers loading. If Hotplug is used in your system, you'll see many files in folder /etc/hotplug. Hotplug will automatically load the most relevant USB and PCI kernel modules according to the USB and PCI IDs provided by devices. Please note, that if the Hotplug framework is in place and the correct configuration files are located in the right place, then the firmware should be loaded automatically.

In order to get the Hotplug framework to load the firmware into the Astribank automatically, the configuration file xpp_fxloader.usermap and the script xpp_fxloader should be copied into /etc/hotplug/usb/ . This is done by make -C xpp/utils install.

File xpp_fxloader.usermap includes a map of USB IDs and the command to run when such devices are encountered. It instructs the Hotplug to run the script xpp_fxloader from that directory. This is also done by make -C xpp/utils install .

When xpp_fxloader is run without any parameters it assumes that it was run by the hotplug scripts. Then it will check if the "add" event was accepted and if so, xpp_fxloader will install the required firmware file. The xpp_fxloader will be called twice, as after the load of the USB firmware the device will re-enumerate itself and thus "unplug" and "replug" in order to load the FPGA firmware.

The UDEV framework has replaced Hotplug in most recent systems. If you have a recent 2.6 system without Hotplug and with many files in folder /etc/udev, then there are good chances that are you using udev. As in case of Hotplug, if your udev framework is configured properly then the firmware should be loaded automatically.

In order to get udev to automatically load the firmware into the Astribank, the configuration file xpp.rules should be copied into folder /etc/udev/rules.d and the script xpp_fxloader should be copied into folder /etc/hotplug/usb/ . This is done by make -C xpp/utils install during Dahdi installation.

File xpp.rules instructs the udevd daemon to run xpp_fxloader script with the option "udev" and with the Astribank USB ID obtained from the device when it is plugged in. Please note, that exactly like in case of Hotplug, the xpp_fxloader will be called twice by the udevd. First time for the USB firmware loading and the second time for FPGA firmware loading.

Newer versions of the USB firmware can now be reset using fpga_load -r.

Also you can try the following:

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 , xpd_fxs and, possibly, xpd_fxo 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 install the xpd_fxo 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/1132 . 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.

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. Funny things happen if such a script exists but is not executable.

If because of some reasons this fails (the script is not in the place, or the file doesn't have the executable permissions), 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 in 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.

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

dahdi_registration checks if a span is registered or tries to register a span using the file /proc/xpp/XBUS-nn/XPD-mm/dahdi_registration . Reading from that file returns 0 if the span is unregisters or 1 if it is registered. You can register a span or ask to unregister it by writing 1 (register) or 0 (unregister) to that file. Registration should generally always succeed. Unregistration may fail if a span is in use.

You may choose to register the XPDs in 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 zap_autoreg in the modprobe configuration file (A file under /etc/modprobe.d or /etc/modprobe.conf):

From here you get a standard Dahdi span. It still needs to be configured by dahdi_cfg and used by a program such as Asterisk like any other Dahdi device. In order for you to get a dial-tone in a phone connected to the FXS port or a fully synchronized BRI port (layer 2 activated, as signalled by a more steady blink) you will actually need both the span configured by Dahdi and the channels configured in Asterisk.

You should generally refer to the general Dahdi documentation on how to configure those levels. e.g, the README file in the top-level directory, and

Dahdi now includes a utility called genzaptelconf (written as a big ugly shell script) to configure Dahdi automatically as good as possible. For analog channels it works quite well (because, IMHO, the "configuration" level on Dahdi should be optional there - there are already sane defaults). For digital spans - BRI and PRI , it may take some tuning.

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 utilities from the xpp/utils 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.

A read/write file. It contains information about current synchronization source. You can change the synchronization source by writing special command to the file. For example, command echo SYNC=01 > /proc/xpp/sync

Possible values are:

Though you'll normally use xpp_sync(8) for that.

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.

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:

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 zap_autoreg to register spans automatically. But this is only recommended on a system with a single Astribank and no other Dahdi device.

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:

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 (card_init_*).

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

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.

Writing to this file can be used to change the type of the device. The device type can only be changed when the XPD is not registered as a Dahdi span. The value is a whitespace-separated list of values that can be of:

Normally those are set by the PRI initialization script . See the definition of XPP_PRI_SETUP in the sample Dahdi init configuration file .

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

When an Astribank device loads it generates a device node in the bus astribanks in sysfs. You can see a directory for each device under /sys/bus/astribanks/devices/ and under it there are several attributes for each Astribank (such as its connector string).

On each time an Astribank is initialized or destroyed a udev event is generated. The rules from our sample udev rules file (xpp/utils/xpp.rules) make that event run the script /usr/share/dahdi/astribank_hook with the parameter add or remove, if such script exists. An example script that just adjusts the Astribank sync settings is included in xpp/utils.

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