This is the README file for the "isdn4linux" package from Fritz Elfert,
Jan den Ouden and Thinking Objects.

1 What is it, what does it give you? Why, why not and why anyway? ;-)
  1.1 General

   Isdn4linux consists of a linklevel-module, lowlevel-module for
   ICN ISDN-cards and a lowlevel-module for Teles-Cards by Jan den Ouden.

   Isdn4linux is currently distributed under the GNU-GPL.
   A copy of the GPL can be found in the file COPYING.
   Future developments (we are currently working on a driver for the
   Diehl ISDN-cards) will be available under a separate license which
   will be more restrictive (like the Ghostscript-license of Aladdin).

  1.2 Availability
 
   isdn4linux is available from the following ftp-servers:

   ftp.franken.de:pub/isdn4linux
   ftp.to.com:pub/isdn4linux

   We have created a mailing-list:
   to subscribe: write to isdn4linux-request@hub-wue.franken.de
   with a line containing "subscribe" in the message.
   
   The distributor for the ICN ISDN-card is:
    Thinking Objects Software GmbH
    Obere Heerbergstr. 17
    D-97078 Wrzburg
    Germany
    Tel: +49-931-2877950
    Fax: +49-931-2877951

    email uhl@to.com
    WWW   http:/www.to.com

  The card currently supports german national 1TR6 and european DSS1
  protocols.

  1.3 Technical details

  When the linklevel-module isdn.o is loaded, ist supports up to 16
  lowlevel-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 lowlevel-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-addresss of
            the ports and the shared memory on the card can be set and read
            also the bootcode 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 und mgetty (compiled with NO_FAX).
   The modem-emulation supports the following:
           1.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      Hangup.
	       ATH1     Off hook (ignored).
               ATH0     Hangup.
	       ATI      Return "ICN-ISDN...".
               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      Reset.
	       AT&Bx    Set Send-Packetsize to x (max. 4000)
                        The real packetsize may be limited by the
                        lowlevel-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: Hangup 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&V     Show all settings.

	   1.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.
     
           2.2 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: Hangup 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.
	     14   0         Layer-2 protocoll: (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 protocoll: (at the moment always 0)
                                      0 = transparent
	     16   250       Send-Packetsize/16

  Last but not least a (at the moment fairly primitive) device to request
  the line-ststus 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 protocoll settings for the B-channel.
  3. (only for network interfaces if the security flag is set)
     contains the caller number in its access list.
  Only when a matching interface or tty is found, the call is acceptes
  and the "connection" between the lowlevel-laye and the linklevel-layer
  is established and kept until the end of the connection.
  In all other cases NOTHING happens (the call is rejected).

  For an outgoing call, the inactive physical lines are searched.
  The call is placed on the first physical line, which supports the
  requested protocolls for the B-channel.
  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 availabilty of the Diehl-driver),
  the service-identifier will be evaluated in addition.

  Shortcomings:
  In a system with more than one ISDN-card, it often is necessary that
  an outgoing call is placed on a specific physical line, so that the
  remote site gets the correct caller-id.
  The next version will support the configuration of a line-id (with an 
  AT-command for a tty or a call to isdnctrl for a network interface).
  When the line-id is set, an outgoing call always gets placed on the
  designated line.

2 System prerequisites:

  isdn4linux needs kernel-version >= 1.2.0 and modutils >= 1.1.85

  No patches to the kernel are necessary, however one should not forget
  to configure IP-forwarding when building the kernel if the machine is
  to be used as a router for a local network.

3. Configuration, Compilation.
   
   Because the driver is not an official part of the linux-sourcetree,
   it has not yet been assigned an official major device-number.
   The defaults (31 for the raw- and control-device, 30 and 29 for
   the tty-emulator) should be unused on most standard systems.
   The configuration process checks for this in /proc/devices and
   possibly assigns new major numbers. The evaluated configuration
   is written to include/config.h.

   To build the driver, first do a:

   make config

   And then compile the whole thing:

   make

   This process needs several kernel include-files, which will only exist
   if the kernel was already successfully configured (which would be a 
   good start anyway).

   The installation now takes two steps:

3 Installation

   a) Create the device-inodes:

     make devices

   b) Install the module in /usr/src/linux/modules
      and the utilities in /sbin:

     make install

     To assure proper operation of the modutils, it is necessary to
     execute 
       make modules_install
     and
       depend -a  
     in /usr/src/linux afterwards. This copies the modules to their 
     final destination and updates the dependancies.
     

4. Application

   4.1 Loading the modules, hardware configuration.

   The directory ./etc contains an example startup-script which gets
   not installed automatically, because it MUST BE CONFIGURED IN ANY
   CASE! Please don't try to connect to the Internet witout setting
   your own IP-addresses.

   The following section describes the setup by hand:

   a) First load the linklevel-module:
       insmod isdn.o
     (Watchout for the syslog output)

   b) Load the lowlevel-driver(s):

       For the ICN-card:

         insmod icn.o [portbase=<value>] [membase=<value>]
   
         Defaults:
	   portbase: 0x320
	   membase:  0xd0000

       For the Teles:

         insmod teles.o [portbase=<value>] [membase=<value>] [irq=<value>]

	 Defaults:
           portbase: 0xd80
           membase:  0xd0000
           irq:      15

     (From now on, you can watch the communication between card and driver 
      wit "cat /dev/isdnctrl")

   c) Load the firmware into the card (only for ICN):
       cd icn
     For 1TR6:
       icnctrl load download/loadpg.bin download/pc_1t_ca.bin
     For Euro-ISDN:
       icnctrl load download/loadpg.bin download/pc_eu_ca.bin

     -> The two leds at the back cover of the card must be blinking 
        intermittingly now.

   d) If you only intend to use ttys, you are now ready.


   e) Create an interface:
       cd ../isdn
       isdnctrl addif isdn0

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

   g) Set the number for outgoing calls on the interface:
       isdnctrl addphone isdn0 out 1234567
       ... (this can be executed more then once, all assigned numbers are
            tried in order)
      and the number(s) for incoming calls:
       isdnctrl addphone isdn0 in 1234567

   h) Set the timeout for hanup:
       isdnctrl huptimeout isdn0 <timeout_in_seconds>

   i) additionally you may activate charge-hangup (= Hangup before 
      next charge-info, this only works, if your isdn-provider transmits
      the charge-info during and after the connection):
       isdnctrl chargehup isdn0 on

   j) Setup the interface with ifconfig as usual, and set a route to it.

   k) (optional) If you run X11 and have Tcl/Tk-wish, you can use
     the script tools/isdnmon. Just change the first line to point to 
     the location of wish. You also can add actions for line-status changes.
     See the comments at the beginning of the script for how to do that.

   l) For initial testing, you can set the verbose-level to 2 (default: 0).
      Then all incoming calls are logged, even if they are not adressed
      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
  dialout (look at syslog kernel-messages).
  The phonenumbers and EAZs can be assigned at any time with ifconfig.
  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-ids 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 hangup-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 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 redial 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> rawip" 
   Selects raw-IP-encapsulation (default).

   "isdnctrl encap <InterfaceName> ip" 
   Selects IP+typefield-encapsulation.

   "isdnctrl encap <InterfaceName> ethernet" 
   Selects Ethernet over ISDN.

   "isdnctrl l2_prot <InterfaceName> <L2-ProtocollName>" 
   Selects a layer-2-protocoll. 
   (With the ICN-driver only "x75i" is available.
   With other drivers, "x75ui", "x75bui" und "hdlc" are possible.)

   isdnctrl l3_prot <InterfaceName> <L3-Protocollname> 
   The same for layer-3. (At the moment only "trans" ist allowed)

   "isdnctrl list <InterfaceName>" 
   Shows all parameters of an interface and the charge-info.
   Try "all" as the interface name.

6. Coming soon:

   ... there will be 
    - a lowlevel-module for Teles-cards (only Euro)
    - a lowlevel-module for Diehl-cards
    - (possibly) a lowlevel-module for cards from
      ELSA, miro, InterCope.
    - Voice-Support.

7. If you want to write a new lowlevel-driver, you are welcome.
   The interface to the linklevel-module is described in the file INTERFACE.
   If the interface should be expanded for any reason, dont'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.

Have fun!

 -Fritz



