DeTeWe ISDN device driver 0.1.2 =============================== About ===== Since many years now, beta versions of DeTeWe-made ISDN PBX devices are mainly distributed by the german telco "Deutsche Telekom". These devices are bundled with ISDN BRIs and so, especially the Eumex x04 models, are widely distributed through Germany. The only problem was, that they never released a linux device driver for them. After meny requests, DeTeWe released a binary only driver for Linux kernel 2.2.14 and 2.2.16. But then "Deutsche Telekom" put some pressure on DeTeWe, it seems that they don't want Linux support for "their" products, and so the binary driver was discontinued. This project was started in 2001 by Fabian Melzow. First, the goal was only to public document the used protocols, since everybody was saying the can't be supported, because the used protocols are to complicated. After the USB and serial transport protocol of the Eumex 504 device was reverse engineered, the project was subscribed to Sourceforge. First, only a configuration program for the Eumex/OpenCom devices should be developed. In 2004, after some of the packet handling code has been written, Michael Krupka joined the project. He further developed the configuration program, analysed the Eumex 604 USB transport protocol and then transformed the configurator into the first USB kernel device driver. In the meantime, we found many more DeTeWe hardware which are useing these protocols, sometimes in slightly modified form. Shortly the first DECT phone was found, which use a broken version of the Eumex 504 serial transport protocol. So the project has been renamed from "Eumex/OpenCom device driver" to "DeTeWe ISDN device driver. This device driver, the additional tools etc. are distributed unter the GNU General Public Licence v2 or above. Licence details can be faound in the file COPYING, which comes with this release. The latest version of this device driver can be obtained over our project homepage http://eumex.sf.net. The developers can be reached over the developers mailinglist or directly using the following email addresses: Fabian Melzow Michael Krupka Structure of the driver ======================= The driver, for now, consists of two kernel modules, named "eumex" and "eumex_i4l". For hardware level communication the device /dev/eumex is created, which is also used by emxconf, emxrouter and emxflash. The function of the two modules is as follows: * eumex: This module is the real device driver and must always be loaded. It supports the network-over-USB facility and the /dev/eumex userspace Interface, which is used for device configuration, router control and firmware upgrade. * eumex_i4l: This module connects your device to the ISDN4Linux subsystem in the Linux kernel. You will need this module if you want to make incoming or outgoing connections with your ISDN device, such as using it for internet dial in. Furthermore, this driver comes with the userspace utilities emxrouter, emxconf and emxflash. With emxrouter you can control the buildin router of your device. Emxconf can be used for PBX device configuration, but is german only for now and with emxflash you can upgrade the firmware or reupload it, when you find your device suddenly to be in the raw mode. The raw mode can be recognized by some flashing LEDs while the device is not working anymore. If your device shows 6 flashing LEDs, but without the ISDN LED or only a fast flashing ISDN LED, the it's sure to be in raw mode. For raw mode can also be checked, if your connect the device to the USB bus, since the driver will recognize it. If you already have tried to upload the firmware with the windows FlashLoad before, but the upload failed and "emxflash -F" reports a two image firmware file, then you should try a "emxflash -1 firmware.efw" to work around this software limitation of the windows FlashLoad tool. It is always using the second firmware image in this condition. Requirements ============ Software: --------- * at least a working kernel build system and kernel header files from Linux 2.6.5 or above. With Debian, the kernel header package should do. * kernel support for your USB hostcontroller and additional for ISDN4Linux with SyncPPP protocol support, if you want to use the eumex_i4l module * optional: the libusb for the old userspace dispatchers * gcc 3.x or above to compile the driver and the module-init-tools to load the modules after that Hardware: --------- * Devices, which announce at least a vendor ID of 0x086c to the USB bus. You can check for this by having a look at /proc/bus/usb/devices or with "lsusb" from the usbutils. The output of "lsusb" should contain a line looking like this one: Bus 0XX Device 0XX: ID 086c:YYYY DeTeWe - Deutsche Telephonwerke AG & Co. Where X is a arbitrary digit and YYYY should be one of the following hexadecimal product IDs which are currently known and recognized by this driver: PID device names, which are known to us ------------------------------------------------------------------------ 1001 Eumex 504PC USB oder Euracom 140 USB 1002 " " in raw mode (6 flashing LEDs, but not the ISDN LED) 1003 TA33 USB 1004 " " in raw mode 1005 Eumex 604PC HomeNet 1006 " " in raw mode 1007 Eumex 704PC DSL 1008 " " in raw mode 1009 Eumex 724PC DSL oder Swisscom TOP C503 100a " " in raw mode 100b OpenCom 30 100c " " im raw mode 100d BeeTel Home 100 100e " " in raw mode 1013 Eumex 704PC LAN 1014 " " in raw mode (fast flashing ISDN LED) 1019 Eumex 504 SE 101a " " in raw mode (6 flashing LEDs, but not the ISDN LED) 1021 OpenCom 40dsl 1022 " " in raw mode 1023 OpenCom 45dsl 1024 " " in raw mode 102c Eumex 604PC HomeNet in raw mode 1030 Eumex 704PC DSL in raw mode 1032 OpenCom 40dsl in raw mode 1033 OpenCom 30plus 1034 " " in raw mode 1037 Eumex 620 LAN 1038 " " in raw mode 1039 TA33 USB 103a " " in raw mode 103b TA44dsl 103c " " in raw mode 103f OpenCom 36lan 1040 " " in raw mode 1041 Eumex 220PC 1042 " " in raw mode 1047 highly experimental test support for the Eumex 520 device 1055 Eumex 220PC 1056 " " in raw mode 105b TA33 USB 105c " " in raw mode 1067 Eumex 200 1068 " " in raw mode What should be working ====================== Eumex 504PC USB, OpenCom 30, TA33 USB, BeeTel Home 100, Eumex 604 and Eumex 704 DSL should be completely supported. The ISDN4Linux support (internet dial in) should be also working for every nonexperimental device, nevertheless we could not test it with all devices, so please report back, if it really works for other devices as which are listed above. The driver supports HDLC and transparent as Layer 2 protocols. For internet dial in HDLC on Layer 2 and syncPPP encapsulation, and for audio, a transparent L2 is commonly used. Router control should be possible with all devices, which have a router build in and are not listed as experimental above. All the other devices can only be partiallly configured with eumexconf, with should not really make a difference, since emxconf has only a german language interface for now. But it will be translated in the future. Upgrading the firmware with emxflash should be working for the following devices Eumex 504 USB, Eumex 604, Eumex 704 LAN/DSL, Eumex 220, Eumex 200, TA33 USB, BeeTel Home 100, OpenCom 30, OpenCom 40 and Eumex 220. For the Eumex 504 SE respectively the OpenCom 30plus, it's only working with firmware files up to a size of 232 kb. Installation ============ Check that the required kernel modules are loaded ------------------------------------------------- First you need to check, if your kernel will be able to support the USB bus. The modules usbcore and at least one out of uhci_hcd or ohci_hcd must be loaded. Of course, you can also compile USB support and the proper host controller driver into your kernel. When you want to use your device for dial in e.g. to the internet, you will need ISDN4Linux in addition. For this to work, the isdn module must be loaded and the capi, capifs and kernelcapi modules must be unloaded, if you don't want to compile I4L support into your kernel. Compile and install the driver ------------------------------ After unpacking the source with tar -xvzf eumex-0.1.1.tar.gz or with tar -xvjf eumex-0.1.1.tar.bz2 you need to change into the untared directory with cd eumex-0.1.1 Threre you can do the well known standard installation with the following commands: ./configure make su make install This should normally sufficient to compile and install the driver. When the kernel sources can't be found, you can specify the path to it with the configure option --with-kernel-dir=/some/dir. After successful installation you should be able to load the driver with "modprobe eumex" and "modprobe eumex_i4l". Automatic module loading during system startup ---------------------------------------------- These solutions should be intentionally distribution independent, as the right setup for your specific distribution should be described in the manual which comes with it. There are two common possibilities to load the modules. The first one, is to let them always load on startup, also if there is no supported device connected. The second and better one, is to load the modules automatically via the hotplug mechanism, if they are needed. If you only want to use the eumex module, it should work out of the box, when you have a correct working hotplug mechanism. If you also want to use the eumex_i4l module, you should put something like this entry install eumex /sbin/modprobe --ignore-install eumex;/sbin/modprobe eumex_i4l in /etc/modprobe.conf or in a new file under /etc/modprobe.d for Debian. Setting up USB networking ------------------------- When your device has network(Ethernet)-over-USB support, the network device ethemx should be automatically created after the device is plugged into your USB hub. This net device can be configured as usual with ifconfig/route or ip, if you not want to use the DCHP server of your device, which is on by default. Example for using static IP addresses: ifconfig ethemx 192.168.69.1/24 up route add default gw 192.168.69.254 Example for using of DHCP: dhclient ethemx or otherwise, depending of which is installed on your system: pump -i ethemx The build in router of your device can be controlled by using "emxrouter". Notice, that you should use the command "emxrouter -tl" to immediately terminate the connection and lock the router. With "emxrouter -l" an ongoing connection will first be terminated on timeout. Setting up ISDN dial in ----------------------- This example will show you how to set up internet dial in with the commonly used protocols HDLC on layer 2 and syncPPP on Layer 3. You will need isdnctrl from the isdnutils and an installed ipppd. Depending on the authentification scheme (PAP or CHAP), which is used by your ISP, you have to put the following entry in /etc/ppp/pap-secrets (for PAP) or /etc/ppp/pap-secrets (for CHAP), or in both files if it's unknown. "USERNAME" "*" "PASSWORD" Where USERNAME have to be replaced with your username for dial in and PASSWORD with your dial in password. Thereafter put something like this into /etc/ppp/ioptions: debug name USERNAME -bsdcomp -pc -ac -vj -vjccomp noipdefault defaultroute ms-get-dns ipcp-accept-local ipcp-accept-remote More information about these options can be found in the manpage of ipppd(8). Now your have to make sure, that your ISP's nameservers are automatically placed into /etc/resolv.conf. This can be done by using a script like this one in /etc/ppp/ip-up: #!/bin/bash echo search `/bin/hostname -d` > /etc/resolv.conf echo nameserver $MS_DNS1 >> /etc/resolv.conf echo nameserver $MS_DNS2 >> /etc/resolv.conf To restore your old nameservers, you can use this script in your /etc/ppp/ip-down file: #!/bin/bash /bin/mv /etc/resolv.conf.old /etc/resolv.conf Don't forgot to do a "chmod a+x /etc/ppp/ip-up" and "chmod a+x /etc/ppp/ip-up" after you have created these files, if they not exist already. The real line setup will be done by the following commands: # clear all ISDN network interfaces isdnctrl reset # add a new inferface "ippp0" isdnctrl addif ippp0 # set the layer 2 protocol to HDLC isdnctrl l2_prot ippp0 hdlc # set the layer 3 protocol to transparent isdnctrl l3_prot ippp0 trans # use syncPPP data packet encapsulation isdnctrl encap ippp0 syncppp # set your local MSN to 1111 isdnctrl eaz ippp0 1111 # hangup after one minute isdnctrl huptimeout ippp0 60 # use manual dial in isdnctrl dialmode ippp0 manual # set the number to where you want to connect to 2222 isdnctrl addphone ippp0 out 2222 # now let's start ipppd ipppd ippp0 To set up the connection then execute: isdnctrl dial ippp0 and to hang up: isdnctrl hangup ippp0 Also see the ISDN4Linux FAQ (http://www.mhessler.de/i4lfaq/) for a more detailed and better description. Troubleshooting =============== Problem: When you try to configure the driver with "isdnctrl" you will get the error "Inappropriate ioctl for device". You have probably loaded the CAPI kernel driver beside the ISDN4Linux driver. The eumex_i4l module only need the I4L subsystem and so you should unload the capi, capifs und kernelcapi modules. Problem: When you try to load the eumex_i4l module it fails and you have found the message "eumex_i4l: Unknown symbol register_isdn" in the syslog. Your kernel lacks I4L support. Try to load the isdn module or compile ISDN4Linux support into your kernel. Bug reporting ------------- Since there is no spec available by the vendor and we are humans too, it is always possible that an error will occur. Especially, as the DeTeWe firmware are full of random bugs in some versions. Already known problems are listet in the TODO file. When it is not listed there, please report it to us via this website: http://sourceforge.net/tracker/?group_id=66803&atid=515801 then we can try to fix it in later versions. Please don't post any obvious bugs and problems to our forum! To better track down your problem, you should provide as much information as possible related to your problem. Here are a list of information you should try to include into your bug report: - the full name and the used firmware version of your device. The sylog output during device detection or the output of "emxflash -D" would help us even more. - all messages from the syslog, related to your problem. The syslog output ist normally found unter /var/log/*, mostly in the messages or syslog file there. - gcc version ("gcc --version"), especially when compiling fails - the version of your running kernel ("uname -r") and the included kernel patches, if known - your Linux distribution, if their kernel or gcc is used - for USB related problems: a copy of the file /proc/bus/usb/devices - your architecture ("uname -m"), only if it's not Intel x86 Development =========== Old userspace dispatchers ------------------------- We are doing a simple file check for the libusb and it's header during the build of the code. If the libusb is found on your system, then the code under the userspace/* is also build. This directory contains the deprecated code of the serial and USB userspace dispatcher. When build, these programs are installed as disp_usb and disp_serial. These are a rudimentary userspace implementations of the USB and serial transport protocols, which the configuration program emxconf has been used in the beginning. Yes, the libusb is not needed for the serial version of the dispatcher, but we don't want to let this deprecated code build on every beginners system. For developers or advanced users the serial dispatcher can be useful, since the serial device driver is still under development. It will replace the serial dispatcher in the future, as this USB driver already did for the USB version of the dispatcher. The USB dispatcher is included to help you to easier understand the Euemx 504 USB transport protocol, but should not be used as a reference. To use the serial dispatcher, first load it with the serial interface as parameter e.g. "disp_serial /dev/ttyS0 &", thereafter call emxconf like this "emxconf -us", but be warned that emxconf only has a german language user interface for now. The PBX configuration is compatible with the Eumex 404, Eumex 504, Eumex 604 und Opencom 20, 30(plus), QuickNet ISDN and probably other devices. Missing configuration options ----------------------------- For some devices there are still missing configuration options or there may be some small handshake or protocol bugs. The reason in most cases is, that nobody has provided the data to us and that we have not figured it out by ourself yet. So, If you found such a problem, feel free to send patches or helpful protocol traces to us. All USB devices which have 0x86c as vendor id, must be suspected to be compatible with this driver. To make USB traces, SnoopyPro which you can be optained from http://sourceforge.net/projects/usbsnoop/, is a proven solution for Windows 2k and XP systems to get USB traces. Developers mailinglist ---------------------- Patches or technical requests sould be directed to our developers mailinglist. You can subsribe to it under: http://lists.sourceforge.net/lists/listinfo/eumex-devel Debug options of the driver --------------------------- The debug options of the eumex mudule should be or-ed, when you want to use more then one of them. Debug output can activated by loading eumex with Debug as option e.g. "modprobe eumex Debug=0x28" or by echoing the wanted value to /sys/module/eumex/parameters/Debug. The following options are availiable for now: 0x0001 B1 channel on hardware level 0x0002 B2 channel on hardware level 0x0004 Command channel on hardware level (all without the B channels!) 0x0008 Commands from/to userspace 0x0010 Networking data (ethernet frames) 0x0020 Data from/to eumex_i4l CVS --- See http://sourceforge.net/cvs/?group_id=66803 for instructions on how to get the latest developer version of this device driver. If you want to directly look in the CVS with VievCVS, go to http://cvs.sf.net/viewcvs.py/eumex/. Our project page on SourceForge is http://sf.net/projects/eumex/. Thanks ====== Thanks goes to the following projects, which wrote really helpful tools: * USBSnoop (http://sf.net/projects/usbsnoop/) for usbsnoop and SnoopyPro * SynCE (http://synce.sourceforge.net/synce/) for unshield * cabextract (http://www.kyz.uklinux.net/cabextract.php) * Wine (http://winehq.org) * many others, which I don't want to list here for now... ...and to this people: * Andreas Ruhmich (fund the broken fuse hardware bug) * Martin Weissbach (subsription of the PCs to the Eumex 620 LAN) * Michael Rauscher (reading router config commands for the Eumex 704 LAN) * Andreas Bierfert (initial autotools support) * Michael Heide (found a mem leak and a devfs support bug) * all these people, which name I don't have handy yet, but which helped especillay at the beginning with USB protocol traces.