Retronetworking » OCTOI - Osmocom Community TDM over IP

{{>toc}}

h1. Getting Started

This page is a work-in-progress documenting what you need to do to get connected to the [[Community_TDMSS7_Network]] using an icE1usb.

h1. Required Hardware

* [[e1-t1-adapter:ICE40_E1_USB_interface|icE1usb]] hardware (contact @sales@sysmocom.de@ for an OCTOI community special price of EUR 75)

* GPS antenna with SMA male plug (not included)

* Some equipment with an E1 interface which you want to connect to the community network.  Typically this is a PBX with E1/PRI/S2M upstream connection.

* Some computer running Linux with a USB host controller to connect the icE1usb to.  Note: Many USB XHCI host controllers suffer from bugs, restricting operation to only one of the two E1 ports, see [[e1-t1-adapter:Isochronous_USB_Issues]] for details. If you have a system with UHCI/OHCI/EHCI, use that.

h2. Major steps required for setup

# Installing latest gateware and firmware into the icE1usb

# installing [[osmo-e1d:]]

# requesting a connection with the OCTOI hub

# creating a config file for @osmo-e1d@

h2. Installing latest gateware and firmware into the icE1usb

Please follow the instructions of the "icE1usb user manaul":https://downloads.osmocom.org/docs/latest/icE1usb-usermanual.pdf

Firmware is available from https://downloads.osmocom.org/binaries/icE1usb/firmware/all/

You will need "dfu-util":http://dfu-util.sourceforge.net/ for performing the USB device firmware upgrade.  Most distributions should have a package for this.

h2. installing [[osmo-e1d:]]

h3. via packages

h3. from source

As the protocol is still under fluctuation, the lastest patches may not yet be part of the @master@ branch and hence not available as a binary package yet.  If you want to try those, you will need to build [[osmo-e1d:]] from source.

h4. dependencies

You will need

* build-essential (gcc, binutils, make, ...)

* autotools (autoconf, automake)

* libtool

* pkg-config

* talloc

* libosmocore

* libusb-1.0

If using distribution packages, make sure you install the _development_ packages (e.g. @libtalloc-dev@).

h4. building

<pre>

autoreconf -fi

./configure

make

</pre>

h4. installation (optional)

you can run osmo-e1d from the build directory, there's no strict need to install it.

If you do install it using the below instructions, the binary will be in @/usr/local/bin@ or whatever is configured at configure time.

<pre>

make install

</pre>

h2. requesting connection

Please contact @laforge with your IP address and port number.  *Right now the protocol does not yet support dynamic IP addresses.*

h2. creating a config file

A minimal configuration file @osmo-e1d.cfg@ looks like shown below.  @osmo-e1d@ looks for the config file in the current working directory from where you start the program, or you can specify it with @-c@ e.g. @osmo-e1d -c /path/to/my/osmo-e1d.cfg@.

<pre>

log stderr

 logging filter all 1

 logging color 1

 logging print category-hex 0

 logging print category 1

 logging print thread-id 0

 logging timestamp 1

 logging print file 1

 logging level e1d info

 logging level linp info

e1d

 interface 0 icE1usb

  usb-serial SERIAL_NR

  line 0

   mode e1oip

octoi-client HUB_IP HUB_PORT

 local-bind LOCAL_IP LOCAL_PORT

 account USER_NAME

  mode ice1usb

  ice1usb serial-number SERIAL_NR

</pre>

Where you need to substitute the upper-case terms as follows:

|_.Variable|_.Description|

|SERIAL_NR|The serial number string (iSerial) of your device as visible for example using @lsusb -v -d 1d50:6145@. Should be a hex digit sequence like @dc697407e74f292@|

|LOCAL_IP|The local IP address to be used by osmo-e1d for this line (can be 0.0.0.0 for automatic)|

|LOCAL_PORT|The local UDP port to be used by osmo-e1d for this line|

|HUB_IP|The remot IP address to be used by osmo-e1d for this line. Provided by @laforge|

|HUB_PORT|The remote UDP port to be used by osmo-e1d for this line. Provided by @laforge|

|USER_NAME|The username provided by @laforge|

h2. Checking status

@osmo-e1d@ like most Osmocom software offers a _cisco style_ command line interface called VTY. The VTY of @osmo-e1d@ listens to localhost:4269, so you can use @telnet localhost 4269@ to reach it.  Check commands like @show line@, @show interface@, @show octoi-client@ and @show stats@ for start.

h3. GPS lock status

To avoid cycle slips, the GPS-DO needs a proper GPS fix

<pre>

osmo-e1d> show interface 

Interface #0 (dc697407e74f2922), Driver: usb

 GPS-DO: mode=AUTO, fix=TRUE, state=TUNE_FINE antenna=OK, tune=2055/2078, freq_est=30720000

</pre>

If things are good, the state should be TUNE_FINE and antenna=OK.  If you see other output, please check your antenna setup.

h2. Monitoring

There are a number of metrics exported by osmo-e1d that help you to analyze the performance and status of your setup.

See [[Monitoring_via_collectd]] or [[Monitoring_via_Grafana]] 

h2. Configuring your E1 device

You should configure your device (PBX, etc.) with settings along the following lines:

h3. Physcal E1

* channelized E1 with CRC4

* clock master *must* be the icE1usb. Your device (PBX) must recover the clock it receives from icE1usb and use that clock to transmit towards the icE1usb.  This is the classic mode of operation for user equipment attached to public networks.

h3. Signaling

* Your PBX is in "User" role, the hub is "Network" role (just like connecting to public ISDN)

* Layer 2: Q.921 (LAPD) on TS16

* Layer 3: Q.931, ideally DSS1 (Euro-ISDN)

* Country Code 49

* Area code 030

* Phone number: +49-30-xxxx-yyyy where @xxxx@ has to be registered with @laforge and entered into [[Phonebook]]

* All other TS (1-15,17-31) can be used for both inbound or outbound channels