fxstest: Use DAHDI_SPECIFY when opening by integer channel number.
[dahdi/tools.git] / README
1 DAHDI Telephony Interface Driver
2 =================================
3 Asterisk Development Team <asteriskteam@digium.com>
4 $Revision$, $Date$
5
6 DAHDI stands for Digium Asterisk Hardware Device Interface. This
7 package contains the user-space tools to configure the kernel modules
8 included in the package dahdi-linux.
9
10 Build Requirements
11 ------------------
12 This package needs the headers from dahdi-linux. Thus you should install
13 dahdi-linux before building dahdi-tools.
14
15 Build System
16 ~~~~~~~~~~~~
17 GCC and friends. Generally you will need to install the package gcc.
18 There may be cases where you will need a specific version of gcc to build
19 kernel modules.
20
21
22 Extra Libraries
23 ~~~~~~~~~~~~~~~
24 Some libraries are needed for extra utilities that are provided with
25 DAHDI.
26
27 - libusb is needed for building fpga_load, needed for firmware loading of
28   the Xorcom Astribank.
29 - libnewt is needed to build the optional but useful utility dahdi_tool.
30
31
32 Installation
33 ~~~~~~~~~~~~
34 Note: If using `sudo` to build/install, you may need to add /sbin to your PATH.
35 ----------------------------------
36 ./configure
37 make
38 make install
39 # To install init scripts and config files:
40 #make config
41 ----------------------------------
42
43
44 Build Tweaks
45 ~~~~~~~~~~~~
46 Partial Build/Install
47 ^^^^^^^^^^^^^^^^^^^^^
48 There are some make targets that are provided to build or install just
49 parts of DAHDI:
50
51 . Build targets:
52   - make: Build DAHDI user-space programs. partial
53     targets of it:
54     * make 'utilname': builds 'utilname' alone (e.g: `make dahdi_diag`)
55     * make utils: Build libtonezone.
56     * make libs: Build libtonezone.
57 . Install targets:
58   - make install: Installs user space tools into /usr/sbin/ (TODO - list
59     partial targets)
60   - make config: should be run once to configure 
61
62
63 Installation to a Subtree
64 ^^^^^^^^^^^^^^^^^^^^^^^^^
65 The following may be useful when testing the package or when preparing a
66 package for a binary distribution (such as an rpm package) installing
67 onto a subtree rather than on the real system.
68
69   make install DESTDIR=targetdir
70
71 This can be useful for any partial install target from the list above.
72
73
74 Options For ./configure
75 ^^^^^^^^^^^^^^^^^^^^^^^
76 The configure script executes various tests and based on them generates
77 makeopts. You can pass it --with options and variable settings, for
78 instance:
79
80   ./configure --without-ncurses CC="gcc-4.10"
81
82 If you just want to recreate the same files without a full detection
83 run, use:
84
85   ./config.status
86
87 To re-run ./configure with the same parameters it was run with last
88 time, use:
89
90   ./config.status --recheck
91
92
93 Configuration
94 -------------
95 Configuration for DAHDI resides under /etc/dahdi . 
96
97 /etc/dahdi/system.conf
98 ~~~~~~~~~~~~~~~~~~~~~~
99 The main method to configure DAHDI devices is using the utility
100 *dahdi_cfg*. dahdi_cfg reads data from the configuration file 
101 /etc/dahdi/system.conf , figures out what configuration to send to 
102 channels, and send it to the kernel.
103
104 A sample annotated system.conf is included in this directory and
105 installed by default. Edit it to suit your configuration. Alternatively 
106 use the script dahdi_genconf to generate one that should work with your 
107 system. Note that while dahdi_genconf will generate a working configuration,
108 it will not automatically detect hardware echo cancellation modules.  These
109 will have to be enabled manually in system.conf.
110
111 /etc/dahdi/init.conf
112 ~~~~~~~~~~~~~~~~~~~~
113 The configuration file of the dahdi init.d script is
114 /etc/dahdi/init.conf . That file is used to override defaults that are 
115 set at the beginning of the init.d script.
116
117 Reference Configuration
118 ~~~~~~~~~~~~~~~~~~~~~~~
119 Sample system.conf
120 ~~~~~~~~~~~~~~~~~~
121 include::system.conf.asciidoc[]
122
123
124 Sample init.conf
125 ~~~~~~~~~~~~~~~~
126 include::init.conf.asciidoc[]
127
128
129 Sample genconf_parameters
130 ~~~~~~~~~~~~~~~~~~~~~~~~~
131 FIXME: still not properly formatted.
132
133 include::genconf_parameters.asciidoc[]
134
135
136 Tonezones
137 ~~~~~~~~~
138 The file zonedata.c contains the information about the tone zones used
139 in libtonezone (and hence also in dahdi_cfg). Here is a list of those zones:
140
141 include::tonezones.txt[]
142
143
144 DAHDI PERL modules
145 ~~~~~~~~~~~~~~~~~~
146 The directory xpp has, in addition to helper utilities for the
147 Xorcom Astribank, a collection of PERL modules to provide information
148 related to DAHDI. The PERL modules themselves are under xpp/perl_modules/ .
149 In xpp/ there are several utilities that use those modules:
150 - xpp-specific: dahdi_registration, xpp_sync, xpp_blink .
151 - General: lsdahdi, dahdi_genconf, dahdi_hardware, dahdi_drivers
152
153 The DAHDI PERL modules will currently only be automatically installed if you
154 happen to install the xpp directory. Those utilities require the PERL modules
155 to be installed, however they will also look for them in the directory 
156 perl_modules, and thus can be run directly from the DAHDI source tree. For 
157 example:
158
159   ./xpp/dahdi_hardware -v
160
161 To get usage information on a program, you can also use perldoc
162 (sometimes provided in a package separate from perl itself). For
163 instance:
164
165   perldoc ./xpp/lsdahdi
166
167 Some of them are specific for the Xorcom Astribank and described in its
168 documentation. the others are:
169
170 lsdahdi:: 
171   A somewhat glorified `cat /proc/dahdi/*`.
172 dahdi_genconf::
173   Generates configuration based on the existing DAHDI channels and on
174   /etc/dahdi/genconf_parameters (replaces genzaptelconf as well).
175 dahdi_drivers::
176   A two-liner script (not installed by default) that simply returns the
177   modules that should be modprobe-d on this system.
178 dahdi_hardware:: 
179   Uses the information from SysFS and its own knowledge to show
180   what PCI/USB DAHDI hardware is connected and if it is currently used
181   by a driver. Shows also some more information for Astribanks from
182   /proc/xpp .
183
184
185 PPP Support
186 ~~~~~~~~~~~
187 DAHDI digital cards can provide data channels through PPP as
188 point-to-point connections. This requires a plug-in to the PPP daemon
189 that is included in the ppp/ subdirectory. To install it:
190
191 1. Make sure you have the PPP source / headers installed. On Debian:
192
193    apt-get install ppp-dev
194
195 2. Run 'make' on the ppp subdirectory:
196
197    make -C ppp 
198    make -C ppp install
199
200 3. Make sure your kernel has support for both PPP (which is common is
201    distribution kernels and for HDLC (much less common) - CONFIG_PPP and
202    CONFIG_HDLC .
203
204
205 include::UPGRADE.txt[]
206
207
208 License
209 -------
210 This package is distributed under the terms of the GNU General Public License
211 Version 2, except for some components which are distributed under the terms of
212 the GNU Lesser General Public License Version 2.1. Both licenses are included
213 in this directory, and each file is clearly marked as to which license applies.
214
215 If you wish to use the DAHDI drivers in an application for which the license
216 terms are not appropriate (e.g. a proprietary embedded system), licenses under
217 more flexible terms can be readily obtained through Digium, Inc. at reasonable
218 cost.
219
220
221 Reporting Bugs
222 --------------
223 Please report bug and patches to the Asterisk bug tracker at
224 http://bugs.digium.com/[] in the "DAHDI" category.
225
226
227 Links
228 -----
229 - http://asterisk.org/[] - The Asterisk PBX
230 - http://voip-info.org/[]
231 - http://voip-info.org/wiki/view/DAHDI[]
232 - http://docs.tzafrir.org.il/dahdi-tools/README.html[Up-to-date HTML version
233   of this file]