README for the ISDN-subsystem
1. Preface
1.1 Introduction
This README describes how to set up and how to use the different parts
of the ISDN-subsystem.
For using the ISDN-subsystem, some additional userlevel programs are
necessary. Those programs and some contributed utilities are available
at
ftp.franken.de
/pub/isdn4linux/isdn4k-utils-<VersionNumber>.tar.gz
We also have set up a mailing-list:
The isdn4linux-project originates in Germany, and therefore by historical
reasons, the mailing-list's primary language is german. However mails
written in english have been welcome all the time.
to subscribe: write a email to majordomo@hub-wue.franken.de,
Subject irrelevant, in the message body:
subscribe isdn4linux <your_email_address>
To write to the mailing-list, write to isdn4linux@hub-wue.franken.de
1.1 Technical details
In the following Text, the terms MSN and EAZ are used.
MSN is the abbreviation for (M)ultiple(S)ubscriber(N)umber, and applies
to Euro(EDSS1)-type lines. Usually it is simply the phone-number.
EAZ is the abbreviation of (E)ndgeraete(A)uswahl(Z)iffer and
applies to German 1TR6-type lines. This is a one-digit string,
simply appended to the base phone-number
The internal handling is nearly identical, so replace the appropriate
term to that one, which applies to your local ISDN-environment.
When the link-level-module isdn.o is loaded, it supports up to 16
low-level-modules with up to 16 channels. (The number 16 is arbitrarily
chosen and can be configured at compile-time --ISDN_MAX in isdn.h).
A low-level-driver can register itself through an interface (which is
defined in isdnif.h) and gets assigned a slot.
The following char-devices are made available for each channel:
A raw-control-device with the following functions:
write: raw D-channel-messages (format: depends on driver).
read: raw D-channel-messages (format: depends on driver).
ioctl: depends on driver, for the ICN-driver, the base-address of
the ports and the shared memory on the card can be set and read
also the boot-code an the protocol software can be loaded into
the card.
O N L Y !!! for debugging (no locking against other devices):
One raw-data-device with the following functions:
write: data to B-channel.
read: data from B-channel.
In addition the following devices are made available:
32 tty-devices (16 cuix and 16 ttyIx) with integrated modem-emulator:
The functionality is almost the same as that of a serial device
(the line-discs are handled by the kernel, which lets you run
SLIP, CSLIP and asynchronous PPP through the devices. We have tested
Seyon, minicom, CSLIP (uri-dip) PPP and mgetty (compiled with NO_FAX),
XCept.
The modem-emulation supports the following:
1.3.1 Commands:
ATA Answer incoming call.
ATD<No.> Dial, the number may contain:
[0-9] and [,#.*WPT-S]
the latter are ignored until 'S'.
The 'S' must precede the number, if
the line is a SPV (German 1TR6).
ATE0 Echo off.
ATE1 Echo on (default).
ATH Hang-up.
ATH1 Off hook (ignored).
ATH0 Hang-up.
ATI Return "ISDN for Linux...".
ATI0 "
ATI1 "
ATO On line (data mode).
ATQ0 Enable result codes (default).
ATQ1 Disable result codes (default).
ATSx=y Set register x to y.
ATSx? Show contents of register x.
ATV0 Numeric responses.
ATV1 English responses (default).
ATZ Load registers and EAZ/MSN from Profile.
AT&Bx Set Send-Packet-size to x (max. 4000)
The real packet-size may be limited by the
low-level-driver used. i.e.: the Teles-Module-
limit is 2000. You will get NO Error-Message,
if you set it to higher Values, because at the
time of giving this command the corresponding
driver may not be selected (see "Automatic
Assignment") however the size of outgoing packets
will be limited correctly.
AT&D2 DTR-low-edge: Hang up and return to
command mode (default).
AT&D3 Same as AT&D2 but also resets all registers.
AT&Ex Set the EAZ/MSN for this channel to x.
AT&F Reset all registers and profile to "factory-defaults"
AT&Sx Set window-size for Teles-driver (x = 1..8) (not yet
implemented)
AT&V Show all settings.
AT&W0 Write registers and EAZ/MSN to profile. See also
iprofd (5.c in this README).
AT&X0 BTX-mode off (default)
AT&X1 BTX-mode on. (S13.1=1, S14=0, S16=7, S18=7, S19=0)
1.3.2 Escape sequence:
During a connection, the emulation reacts just like
a normal modem to the escape sequence <DELAY>+++<DELAY>.
(The escape character - default '+' - can be set in the
register 2).
The DELAY must at least be 1.5 seconds long and delay
between the escape characters must not exceed 0.5 seconds.
1.3.3 Registers:
Nr. Default Description
0 0 Answer on ring number.
(no auto-answer if S0=0).
1 0 Count of rings.
2 43 Escape character.
(a value >= 128 disables the escape sequence).
3 13 Carriage return character (ASCII).
4 10 Line feed character (ASCII).
5 8 Backspace character (ASCII).
6 3 Delay in seconds before dialing.
7 60 Wait for carrier (ignored).
8 2 Pause time for comma (ignored)
9 6 Carrier detect time (ignored)
10 7 Carrier loss to disconnect time (ignored).
11 70 Touch tone timing (ignored).
12 69 Bit coded register:
Bit 0: 0 = Suppress response messages.
1 = Show response messages.
Bit 1: 0 = English response messages.
1 = Numeric response messages.
Bit 2: 0 = Echo off.
1 = Echo on.
Bit 3 0 = DCD always on.
1 = DCD follows carrier.
Bit 4 0 = CTS follows RTS
1 = Ignore RTS, CTS always on.
Bit 5 0 = Low-edge on DTR: Hang up and
return to command mode.
1 = Same as 0 but also resets all
registers.
Bit 6 0 = DSR always on.
1 = DSR only on if channel is available.
Bit 7 0 = Cisco-PPP-flag-hack off (default).
1 = Cisco-PPP-flag-hack on.
13 0 Bit coded register:
Bit 0: 0 = Use delayed tty-send-algorithm
1 = Direct tty-send.
Bit 1: 0 = T.70 protocol (Only for BTX!) off
1 = T.70 protocol (Only for BTX!) on
14 0 Layer-2 protocol: (with the ICN-driver
currently always 0)
0 = X75/LAPB with I-frames
1 = X75/LAPB with UI-frames
2 = X75/LAPB with BUI-frames
3 = HDLC
15 0 Layer-3 protocol: (at the moment always 0)
0 = transparent
16 250 Send-Packet-size/16
17 8 Window-size for Teles-driver (not yet implemented)
18 7 Service-Octet-1
19 0 Service-Octet-2
Last but not least a (at the moment fairly primitive) device to request
the line-status (/dev/isdninfo) is made available.
Automatic assignment of devices to lines:
All inactive physical lines are listening to all EAZs for incoming
calls and are NOT assigned to a specific tty or network interface.
When an incoming call is detected, the driver looks first for a network
interfaces and then for an opened tty which:
1. is configured for the same EAZ.
2. has the same protocol settings for the B-channel.
3. (only for network interfaces if the security flag is set)
contains the caller number in its access list.
4. Either the channel is not bound exclusively to another Net-interface, or
it is bound AND the other checks apply to exact this Interface.
(For usage of the bind-features, refer to the isdnctrl-man-page)
Only when a matching interface or tty is found, the call is accepted
and the "connection" between the low-level-layer and the link-level-layer
is established and kept until the end of the connection.
In all other cases no connection is established. Isdn4linux can be
configured to either do NOTHING in this case (which is useful, if
other, external devices with the same EAZ/MSN are connected to the bus)
or to reject the call actively. (isdnctrl busreject ...)
For an outgoing call, the inactive physical lines are searched.
The call is placed on the first physical line, which supports the
requested protocols for the B-channel. If a net-interface, however
is pre-bound to a channel, this channel is used directly.
This makes it possible to configure several network interfaces and ttys
for one EAZ, if the network interfaces are set to secure operation.
If an incoming call matches one network interface, it gets connected to it.
If another incoming call for the same EAZ arrives, which does not match
a network interface, the first tty gets a "RING" and so on.
As soon as voice gets supported (with the availability of the Diehl-driver),
the service-identifier will be evaluated in addition.
2 System prerequisites:
ATTENTION! The program "insmod" from the Package "modules-1.2.8" (It's
on nearly all newer distributions) has a bug, which makes
it impossible to set both driver-Id's when loading the
icn-module for the Double-ICN-Card. A patch is supplied
in the utility-package called "insmod-1.2.8.patch". Change into
the source-directory of insmod, and type
"patch < insmod-1.2.8.patch". Then recompile it. This will fix
the bug.
This bug does NOT occur when using insmod with the Teles-driver
or a single ICN-card.
3. Lowlevel-driver configuration.
Configuration depends on how the drivers are built.
3.1 Drivers built into the kernel.
3.1.1 Teles driver.
The Teles driver can be configured using the commandline-feature
while loading the kernel with LILO or LOADLIN. It accepts the
following syntax:
teles=p0,i0,m0,d0[,p1,i1,m1,d1 ... ,pn,in,mn,dn][,idstring]
where
p0 = portbase of 1st card. (default: 0xd80)
i0 = irq of 1st card. (default: 15)
m0 = shared memory of 1st card. (default: 0xd0000)
d0 = D-channel protocol of 1st card. 1=1TR6, 2=EDSS1 (default: 2)
p1,i1,m1,d1 = Parameters of second card (defaults: none)
pn,in,mn,d1 = Parameters of n'th card (up to 16 cards are supported)
idstring = Driver-Id for accessing with utilities and identification
when using a Line-monitor. (default: none)
idstring must start with a character!
The type of the card is determined by the port, irq and shared memory:
port == 0, shared memory != 0 -> Teles S0-8
port != 0, shared memory != 0 -> Teles S0-16.0
port != 0, shared memory == 0 -> Teles S0-16.3
ATTENTION:
Due to limited hardware-capabilities, there is no way to check the
existence of a card. Therefore you need to be shure your card's setup
is correct. Also there are bugs in the printed manual of some newer
16.3 cards. The manual tells the port has to be 0x180. THIS IS WRONG!!
0xd80 is the correct value! Have a look to the kernel-syslog. With
most of the cards, you should see a line "HSCX version A:5 B:5" there.
3.1.2 ICN driver.
The ICN driver can be configured using the commandline-feature while
loading the kernel with LILO or LOADLIN. It accepts the following
syntax
icn=p,m[,idstring1[,idstring2]]
where
p = portbase (default: 0x320)
m = shared memory (default: 0xd0000)
When using the ICN double card, you MUST define TWO idstrings.
idstring must start with a character!
The ICN driver supports only one card at the moment. If you like to
use more than one card, build the modularized version, loading it
more than one time, each module driving a single card.
Using the "icnctrl"-utility, portbase and shared memory can also be
changed during runtime.
The D-channel protocol is configured by loading different firmware
into the card's memory using the "icnctrl"-utility.
3.2 Drivers built as modules.
3.2.1 Teles driver.
The module teles.o can be configured during "insmod'ing" it by
appending it's parameters to the insmod-commandline. The following
syntax is accepted:
io=m0,i0,p0,d0[,m1,i1,p1,d1 ... ,mn,in,pn,dn] teles_id=idstring
where
m0,i0,p0,d0 ... mn,in,pn,dn have the same meanings like the
parameters described for the kernel-
version above. Watchout: different
sequence!
3.2.2 ICN driver.
The module icn.o can be configured during "insmod'ing" it by
appending it's parameters to the insmod-commandline. The following
syntax is accepted:
portbase=p membase=m icn_id=idstring icn_id2=idstring2
where p, m, idstring1 and idstring2 have the same meanings like
parameters described for the kernel-
version above.
When using the ICN double card, you MUST define TWO idstrings.
idstring must start with a character!
The ICN driver supports only one card at the moment. If you like to
use more than one card, build the modularized version, loading it
more than one time, each module driving a single card.
Using the "icnctrl"-utility, portbase and shared memory can also be
changed during runtime.
The D-channel protocol is configured by loading different firmware
into the card's memory using the "icnctrl"-utility.
4. Device-inodes
The major and minor-numbers and it's names are described in
Documentation/devices.txt. The major-numbers are:
43 for the ISDN-tty's.
44 for the ISDN-callout-tty's.
45 for control/info/debug devices.
5. Application
a) (Only for ICN-cards) Load the firmware into the card:
cd icn
For 1TR6:
icnctrl [-d IDstring] load download/loadpg.bin download/pc_1t_ca.bin
For Euro-ISDN:
icnctrl [-d IDstring] load download/loadpg.bin download/pc_eu_ca.bin
When using the ICN-2B, the protocol-software for the second half of
the card must be appended to the command line.
-> The two LEDs at the back cover of the card (ICN-2B: 4 LEDs) must be
blinking intermittingly now. If a connection is up, the corresponding
led lits continuously.
b) If you only intend to use ttys, you are nearly ready now.
c) If you want to have really permanent "Modem"-settings on disk, you
can start the daemon iprofd. Give it a path to a file at the command-
line. It will store the profile-settings in this file every time
an AT&W0 is performed on any ISDN-tty. If the file already exists,
all profiles are initialized from this file. If you want to unload
any of the modules, kill iprofd first.
d) For networking, continue: Create an interface:
isdnctrl addif isdn0
e) Set the EAZ (or MSN for Euro-ISDN):
isdnctrl eaz isdn0 2
(For 1TR6 a single digit is allowed, for Euro-ISDN the number is your
real MSN e.g.: Phone-Number)
f) Set the number for outgoing calls on the interface:
isdnctrl addphone isdn0 out 1234567
... (this can be executed more than once, all assigned numbers are
tried in order)
and the number(s) for incoming calls:
isdnctrl addphone isdn0 in 1234567
g) Set the timeout for hang-up:
isdnctrl huptimeout isdn0 <timeout_in_seconds>
h) additionally you may activate charge-hang-up (= Hang up before
next charge-info, this only works, if your isdn-provider transmits
the charge-info during and after the connection, it does NOT work
with the Teles on an EDSS1-Line.):
isdnctrl chargehup isdn0 on
i) Setup the interface with ifconfig as usual, and set a route to it.
j) (optional) If you run X11 and have Tcl/Tk-wish Version4.0, you can use
the script tools/tcltk/isdnmon. You can add actions for line-status
changes. See the comments at the beginning of the script for how to
do that. There are other tty-based tools in the tools-subdirectory
contributed by Michael Knigge (imon), Volker Götz (imontty) and
Andreas Kool (isdnmon).
k) For initial testing, you can set the verbose-level to 2 (default: 0).
Then all incoming calls are logged, even if they are not addressed
to one of the configured net-interfaces:
isdnctrl verbose 2
Now you are ready! A ping to the set address should now result in a
dial-out (look at syslog kernel-messages).
The phone-numbers and EAZs can be assigned at any time with isdnctrl.
You can add as many interfaces as you like with addif following the
directions above. Of course, there may be some limitations. But we have
tested as many as 20 interfaces without any problem. However, if you
don't give an interface name to addif, the kernel will assign a name
which starts with "eth". The number of "eth"-interfaces is limited by
the kernel.
5. Additional options for isdnctrl:
"isdnctrl secure <InterfaceName> on"
Only incoming calls, for which the caller-id is listed in the access
list of the interface are accepted. You can add caller-id's With the
command "isdnctrl addphone <InterfaceName> in <caller-id>"
Euro-ISDN does not transmit the leading '0' of the caller-id for an
incoming call, therefore you should configure it accordingly.
If the real number for the dialout e.g. is "09311234567" the the number
to configure here is "9311234567". The pattern-match function
works similar to the shell mechanism.
? one arbitrary digit
* zero or arbitrary many digits
[123] one of the digits in the list
[1-5] one digit between '1' and '5'
a '^' as the first character in a list inverts the list
"isdnctrl secure <InterfaceName> off"
Switch of secure operation (default).
"isdnctrl ihup <InterfaceName> [on|off]"
Switch the hang-up-timer for incoming calls on or off.
"isdnctrl eaz <InterfaceName>"
Returns the EAZ of an interface.
"isdnctrl delphone <InterfaceName> in|out <number>"
Deletes a number from one of the the access-lists of the interface.
"isdnctrl delif <InterfaceName>"
Removes the interface (and possible slaves) from the kernel.
(You have to unregister it with "ifconfig <InterfaceName> down" before).
"isdnctrl callback <InterfaceName> [on|off]"
Switches an interface to callback-mode. In this mode, an incoming call
will be rejected and after this the remote-station will be called. If
you test this feature by using ping, some routers will re-dial very
quickly, so that the callback from isdn4linux may not be recognized.
In this case use ping with the option -i <sec> to increase the interval
between echo-packets.
"isdnctrl encap <InterfaceName> <EncapType>"
Selects the type of packet-encapsulation. The encapsulation can be changed
only while an interface is down.
At the moment th following Values are supported:
rawip (Default) Selects raw-IP-encapsulation. This means, MAC-headers
are stripped off.
ip IP with type-field. Same as IP but the type-field of the MAC-header
is preserved.
cisco-h A special-mode for communicating with a Cisco, which is configured
to do "hdlc"
ethernet No stripping. Packets are sent with full MAC-header.
The Ethernet-address of the interface is faked, from it's
IP-address: fc:fc:i1:i2:i3:i4, where i1-4 are the IP-addr.-values.
syncppp Synchronous PPP
Watching packets, using standard-tcpdump will fail for all encapsulations
except ethernet because tcpdump does not know how to handle packets
without MAC-header. A patch for tcpdump is included in the utility-package
mentioned above.
"isdnctrl l2_prot <InterfaceName> <L2-ProtocolName>"
Selects a layer-2-protocol.
(With the ICN-driver and the Teles-driver, "x75i" and "hdlc" is available.
With other drivers, "x75ui", "x75bui" may be possible too.)
isdnctrl l3_prot <InterfaceName> <L3-ProtocolName>
The same for layer-3. (At the moment only "trans" is allowed)
"isdnctrl list <InterfaceName>"
Shows all parameters of an interface and the charge-info.
Try "all" as the interface name.
"isdnctrl hangup <InterfaceName>"
Forces hangup of an interface.
"isdnctrl bind <InterfaceName> <DriverId>,<ChannelNumber> [exclusive]"
If you are using more than one ISDN-Card, it is sometimes necessary to
dial out using a specific Card or even preserve a specific Channel for
Dialout of a specific net-interface. This can be done with the above
command. Replace <DriverId> by whatever you assigned while loading the
module. The <ChannelNumber> is counting from zero. the upper Limit
depends on the card used. At the Moment no card supports more than
2 Channels, so the upper limit is one.
"isdnctrl unbind <InterfaceName>"
unbinds a previously bound interface.
"isdnctrl busreject <DriverId> on|off"
If switched on, isdn4linux replies a REJECT to incoming calls, it
cannot match to any configured interface.
If switched off, nothing happens in this case.
You normally should NOT enable this feature, if the ISDN-adaptor is not
the only device, connected to the S0-bus. Otherwise it could happen, that
isdn4linux rejects an incoming call, which belongs to another device on
the bus.
"isdnctrl addslave <InterfaceName> <SlaveName>
Creates a slave interface for channel-bundling. Slave interfaces are
not seen by the kernel, but their ISDN-part can be configured with
isdnctrl as usual. (Phone numbers, EAZ/MSN, timeouts etc.) If more
than two channels are to be bundled, feel free to create as many as you
want. InterfaceName must be a real interface, NOT a slave. Slave interfaces
start dialing, if the master interface resp. the previous slave interface
has a load of more than 7000 cps. They hangup if the load goes under 7000
cps, according to their "huptimeout"-parameter.
"isdnctrl sdelay <InterfaceName> secs."
This sets the minimum time an Interface has to be fully loaded, until
it sends an dial-request to it's slave.
"isdnctrl dial <InterfaceName>"
Forces an interface to start dialing even if no packets are to be
transferred.
"isdnctrl mapping <DriverId> MSN0,MSN1,MSN2,...MSN9"
This installs a mapping table for EAZ<->MSN-mapping for a single line.
Missing MSN's have to be given as "-" or can be omitted, if at the end
of the commandline.
With this command, it's now possible to have an interface listening to
mixed 1TR6- and Euro-Type lines. In this case, the interface has to be
configured to a 1TR6-type EAZ (one digit). The mapping is also valid
for tty-emulation. Seen from the interface/tty-level the mapping
CAN be used, however it's possible to use single tty's/interfaces with
real MSN's (more digits) also, in which case the mapping will be ignored.
Here is an example:
You have a 1TR6-type line with base-nr. 1234567 and a Euro-line with
MSN's 987654, 987655 and 987656. The DriverId for the Euro-line is "EURO".
isdnctrl mapping EURO -,987654,987655,987656,-,987655
...
isdnctrl eaz isdn0 1 # listen on 12345671(1tr6) and 987654(euro)
...
isdnctrl eaz isdn1 4 # listen on 12345674(1tr6) only.
...
isdnctrl eaz isdn2 987654 # listen on 987654(euro) only.
Same scheme is used with AT&E... at the tty's.
6. If you want to write a new low-level-driver, you are welcome.
The interface to the link-level-module is described in the file INTERFACE.
If the interface should be expanded for any reason, don't do it
on your own, send me a mail containing the proposed changes and
some reasoning about them.
If other drivers will not be affected, I will include the changes
in the next release.
For developers only, there is a second mailing-list. Write to me
(fritz@wuemaus.franken.de), if you want to join that list.
Have fun!
-Fritz
![[bottom]](../icons/bottom.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[first]](../icons/n_first.png){kind=icon}
![[last]](../icons/n_last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
![[top]](../icons/top.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}