doc/manuals/chapters/host-software.adoc

== Host Software

Host Software is software running on the USB host computer to which the
icE1usb is attached.

At the time of this writing, there are two options for icE1usb driver interfaces:
`osmo-e1d` and `DAHDI`.

=== `osmo-e1d`

`osmo-e1d` is a pure user-space driver, not requiring any specific Linux kernel,
kernel patches or out-of-tree kernel modules.  It utilizes `libusb` to
talk to the icE1usb hardware and offers a unix domain socket based
interface to application software.

In theory, `osmo-e1d` should work on any operating system with libusb
support for isochronous transfers.  However, official support is limited
to GNU/Linux at this point.

Software such as `osmo-bsc` and `osmo-mgw` can interface `osmo-e1d` via
the `libosmo-abis` support for `osmo-e1d`.

More information about `osmo-e1d` can be found at its homepage
https://osmocom.org/projects/osmo-e1d/wiki

=== DAHDI driver

DAHDI (Digium Asterisk Hardware Driver Interface) is an extremely
popular driver for a variety of POTS/PSTN and also TDM interface boards
by originally Zaptel, later Digium and now most recently Sangoma.

DAHDI is available only for Linux, and is provided as source code for a
set of out-of-tree kernel modules.  You must compile those modules for
each specific Linux kernel version you are using.  Keep this in mind
when performing kernel upgrades and the like.

DAHDI is supported by a wide range of open source PBX / softswitch software,
including Asterisk, FreeSWITCH and yate.

There is a DAHDI driver for the icE1usb available from
the `laforge/icE1usb` branch of the https://github.com/osmocom/dahdi-linux
git repository.

When using that DAHDI Linux kernel driver, there is no need for
osmo-e1d.  The USB interface is directly managed inside the kernel.


==== Installing DAHDI driver
Example installation steps, tested on Debian 11, for installing DAHDI Linux & DAHDI Tools.
Note: Plugging in the device prior to installing may lead to issues.

----
$ sudo apt-get install -y linux-headers-`uname -r` git dfu-util make gcc autoconf libtool libnewt-dev
$ git clone https://git.osmocom.org/dahdi-linux/
$ git clone https://github.com/asterisk/dahdi-tools
$ cd dahdi-linux
$ sudo make install
$ cd ../dahdi-tools
$ sudo autoreconf -i
$ ./configure
$ sudo make install
$ sudo make install-config
$ sudo modprobe icE1usb
$ sudo /etc/init.d/dahdi start
----

At this point you can plug in the icE1usb, which

* should make the icE1usb enumerate on USB (dmesg, lsusb)
* should and scan for it with `sudo dahdi_scan` which should list the two E1 ports on the iCE1usb.
* see a `/proc/dahdi/N` file (with N being the span number, typically 1 unless you have other spans)
* see the device listed in `dahdi_scan` or `dahdi_tool`

.Example `dmesg` output when icE1usb is plugged in
----
usb 2-1: new full-speed USB device number 5 using xhci_hcd
usb 2-1: New USB device found, idVendor=1d50, idProduct=6145, bcdDevice= 0.03
usb 2-1: New USB device strings: Mfr=2, Product=3, SerialNumber=1
usb 2-1: Product: icE1usb
usb 2-1: Manufacturer: osmocom
usb 2-1: SerialNumber: dc697407e7682731
----

.Example `lsusb` output after icE1usb is plugged in
----
$ lsusb -d 1d50:
Bus 002 Device 005: ID 1d50:6145 OpenMoko, Inc. icE1usb
----

=== Other software

you can interface 3rd party applications with osmo-e1d in the following
ways:

* by adding support for `osmo-e1d`, e.g. via `libosmo-e1d` to the
  respective application
* by directly implementing the USB interface exposed by icE1usb in your
  software

Should you require any related development/porting services, please do
not hesitate to reach out to sysmocom.