This file documents the Zaptel drivers for the Xorcom Astribank8 Channel Bank. The drivers reside in a separate subdirectory, xpp/ . Building and Installation: """"""""""""""""""""""""" Building and installation is basically like the normal procedure of installing Zaptel with some additions. Building drivers: """""""""""""""" Unlike earlier versions, the Astribank driver (xpp) will now build automatically. To build the drivers follow the usual Zaptel documentation. E.g: run: make in the top-level directory. Next you will need to build the user-space tools needed for loading the firmware and initialization files for the Astribank: make -C xpp/utils INSTALLATION: """""""""""" apart from the standard 'make install' in the zaptel directory, run: make -C xpp/utils install Alternatively, do the following manually: All firmware files should be copied to a new directory: /usr/share/zaptel/ The xpp_fxloader and xpp_fxloader.usermap should be copied to: /etc/hotplug/usb/ In addition, the file xpp/xpp_modprobe contains optional modprobe settings. It may be copied verbatim into /etc/modprobe.conf or (better) copied to /etc/modprobe.d/ . Note that loading through udev is not yet provided. Run /etc/hotplug/usb/xpp_fxloader load to load firmware. The FXS calibration script requires the perl module Time::HiRes. This modules is already packaged for most distributions including Debian, Fedora, RedHat and CentOS. To test for the existance of this module run: perl -MTime::HiRes -e '' This should run cleanly (without output) if the module exists and issue a long error message otherwise. At least in RedHat, CentOS and Fedora-2 until Fedora-5 it is in a package named perl-Time-HiRes. In Debian and Fedora-6 it is bundled with perl. DEVICE STARTUP: """""""""""""" Terminology: """"""""""" Some technical terms that are used throughout the document and in the driver / zaptel . Only used in the technical parts. span: Zaptel breaks the channels it knows bout to logical units called "spans". A port in a E1/T1/ISDN card is usually a span. So is a complete analog card. You can see the list of spans as the list of files under /proc/zaptel or the list in zttool. XBUS: A funny way to call an Astribank device. XPD: This is basically a logical unit of the Astribank. It will be registered to Zaptel as a single span. This will basically be 8 analog channels. Loading Firmware: """""""""""""""" Normally this is done using the script xpp_fxloader.If it works fine, you don't need to bother reading this section. Once the firmware is loaded the USB ID of the Astribank changes to e4e4 1132, and the driver can pick it up. You'll also see the top led lit. First and foremost: the simplest and most useful tool to debug problems here is lsusb. The output of lsusb should show exactly if the device is connected and if its firmware is loaded. The firmware files are named *.hex. The are in the Intel hex format (read: plain text, but not readable) that is copied at install time from xpp/utils to /usr/share/zaptel . 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 is loaded in two stages. In the first stage we load the "USB" firmware using the program fxload. After the first stage the USB ID is e4e4 1131. In the second stage we load the "FPGA" firmware. The first is done using the the program fxload. To load it manually, use the command: fxload -t fx2 -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/USB_1130.hex fxload is standard program that is typically part of the package 'fxload' or 'hotplug-utils' . /proc/bus/usb is the mount point of the USB file-system (usbfs). MMM is the first number (bus number) and NNN is the second number (device number) you see for the device in lsusb, with full 3 digits. If the load is successful, the device disconnects and reconnects with USB product ID 1131 (and a new device number). The second-stage loader is done using the program fpga_load, which is built in the directory xpp/utils and installed to /usr/sbin/fpga_load . Its syntax is based on fxload. To load with it manually, use: fpga_load -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/FPGA_FXS.hex Note that as the device has reconnected, it now has a new device number. So you need to re-check the value of NNN with lsusb. Typically this will be the old value + 1. Firmware Loading with UDEV: """""""""""""""""""""""""" Firmware loading with udev should work but is not installed automatically, yet. See the comments in the beginning of the script /etc/hotplug/usb/xpp_fxloader . Loading The Modules: """"""""""""""""""" Here is what should happen: In short: you should plug it or have it plugged at boot time, and all the modules should load. 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 discovered there you will see a directory /prc/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: xpp is the basic one, that contains the functionality to connect to Zaptel and other common functions. xpd_fxs is the module for controlling FXS spans. xpd_fxo is the module for controlling FXO spans. xpd_usb is the module that holds the functionality needed to connect to the USB bus. All modules depend on xpp, and modprobing them will install xpp as well. However the xpd_* modules are only installed on-demand: no need to install xpd_fxo if you only have FXS Astribank. You either plug in the Astribank , or start the hotplug/udev system while an Astribank is connected, after the firmware is loaded. The Vendor-ID/Product-ID of the device is e4e4/1132 . The handler for that combination is listed as the kernel module xpp_usb . Thus the system runs 'modprobe xpp_usb' if that module is not already loaded. The module xpp_usb depends on the modules zaptel and xpp . Both of which are loaded before xpp_usb is loaded. As usual, parameters and rules form /etc/modprobe.conf and/or /etc/modprobe.d/* will apply to the module, as modprobe is used. The modules to handle the specific span types (xpd_fxs, xpd_fxo) may or may not have been loaded yet at this stage (when the command 'modprobe xpp_usb' returns). At this point the xpp driver asks the box what logical units it has. According to the answers it gets, it will figure what xpd_* modules it will need, and modprobe for them. At some earlier version of the driver this has required some special modprobe.conf setup, but this is no longer the case. Device Initializations Scripts: """""""""""""""""""""""""""""" The chips in the device need to be initialized. This involves sending a bunch of values to certain registers in those chips. We decided that hardwiring those values in the driver itself would not be a good idea. before registering a XPD as a span in Zaptel, we run an initialization script: /usr/share/zaptel/initialize_registers . If this fails (e.g: because the script is not there, or is not executable), you will get an error message in the logs [FIXME: quote error message] that the invocation has failed. The XPD will then be removed (you won't see that a directory for that XPD under the relevant /proc/xpp/XBUS-* directory) and not be registered with Zaptel. Registering With Zaptel: """"""""""""""""""""""" Now we finally got to the "lights party" part: the lights in a unit (XPD) get lit before it registers with Zaptel and are turned off after that. You may choose not to register the XPDs to Zaptel automatically, to allow finer control of the process. This is done using the module parameter zap_autoreg. Set in the modprobe configuration file (e.g: /etc/modprobe.conf ) the line: options xpp zap_autoreg=0 to disable automatic registration at startup. You will then need to register the spans manually. SAMPLE CONFIGURATIONS: """""""""""""""""""""" /etc/zaptel.conf: Astribank 8: fxoks=1-14 Astribank 16: 8FXS/8FXO fxoks=1-14 fksks=15-22 /etc/asterisk/zapata.conf Astribank 8: [channels] signalling=fxo_ks ; The real analog ports: context=from-internal ; echocancel=yes ; echocancelwhenbriged=yes ; echotraining=9 channel => 1-8 ; output ports: context=astribank-outputs channel => 9-10 ; input ports: immediate=yes context=astribank-inputs channel => 11-14 immediate=no Astribank 16: 8FXS/8FXO [channels] signalling=fxo_ks ; The real analog ports: context=from-internal ; echocancel=yes ; echocancelwhenbriged=yes ; echotraining=9 channel => 1-8 ; output ports: context=astribank-outputs channel => 9-10 ; input ports: immediate=yes context=astribank-inputs channel => 11-14 immediate=no ; FXO ports signalling=fxs_ks context=from-pstn callerid=asreceived channel => 15-22 See also the output of genzaptelconf for examples of mailbox and callerid, and for channel numbers that will match your specific settings. For that reason I only give the above two sample configurations. When loaded, you should get one span, of 8 extensions, 2 output ports and 4 input ports: root@rapid:~# cat /proc/zaptel/2 Span 1: XBUS-0/XPD-0 "Xorcom XPD #0/0: FXS" 1 XPP_FXS/0-0 FXOKS (In use) 2 XPP_FXS/0-1 FXOKS (In use) 3 XPP_FXS/0-2 FXOKS (In use) 4 XPP_FXS/0-3 FXOKS (In use) 5 XPP_FXS/0-4 FXOKS (In use) 6 XPP_FXS/0-5 FXOKS (In use) 7 XPP_FXS/0-6 FXOKS (In use) 8 XPP_FXS/0-7 FXOKS (In use) 9 XPP_OUT/0-8 FXOKS (In use) 10 XPP_OUT/0-9 FXOKS (In use) 11 XPP_IN/0-10 FXOKS (In use) 12 XPP_IN/0-11 FXOKS (In use) 13 XPP_IN/0-12 FXOKS (In use) 14 XPP_IN/0-13 FXOKS (In use) /proc Interface """"""""""""""" The Astribank drivers provide their own /proc interface under /proc/xpp . (Note that the details of this interface are still potentially subject to changes) /proc/xpp/xbuses lists the connected devices (an xbus is such a device), one per line. A device is normally "connected". "missing" means that it was disconnected, but Asterisk still holds channels from it open. You can also see in the xbuses file to which physical connection the Astribank is connected. /proc/xpp/sync is a read/write file . It prints the current synchronization source. printing to it can change the synchronization source. Host-synchronization is currently the default but for better sound quality you should synchronize from the Astribank. /proc/xpp/XBUS-n gives information about device number n (starting from 0). under it, /proc/XBUS-n/XPD-m gives information regarding span number m in that device. /proc/xpp/XBUS-n/XPD-m/zt_registration is a read-write file for manually registering/unregistering the span with Zaptel. A span will register automatically when generated, though. Span unregistration may fail if some channels from the span are used (e.g: by Asterisk). Registration is by writing 1 and unregistration is by writing 0 to the file. (There are a bunch of other status files under /proc/xpp/ ) Useful Module Parameters: """""""""""""""""""""""" zap_autoreg: (xpp) Register spans automatically (1) or not (0). Default: 1. Unsetting this could be useful if you have several Astribanks and you want to set their registration order manually using zt_registration in the /proc interface. initdir: (xpp) This is the directory containing the initialization scripts. The default is /usr/share/zaptel . Setting this value could be useful if that location is inconvenient for you. print_dbg: (all modules) It will make the driver print tons of debugging messages. Can be sometime even handy, but overly-verbose in the case of xpp_usb. Can be safely set/unset at run-time using /sys/modules . BTW: XPP here does not stand for X Printing Panel, XML Pull Parser, X-Windows Phase Plane or XML Professional Publisher. It is simply the Xorcom Peripheral Protocol, which connects a computer to a XPD (Xorcom Peripheral Device).