<p>laforge <strong>submitted</strong> this change.</p><p><a href="https://gerrit.osmocom.org/c/osmo-e1-hardware/+/21719">View Change</a></p><div style="white-space:pre-wrap">Approvals:
laforge: Looks good to me, approved; Verified
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">First version of icE1usb user manual<br><br>Change-Id: Ia04890cf3b321f8cb01e3c513a730031e76376b9<br>---<br>A doc/manuals/Makefile<br>A doc/manuals/chapters/firmware.adoc<br>A doc/manuals/chapters/gateware.adoc<br>A doc/manuals/chapters/hardware.adoc<br>A doc/manuals/chapters/host-software.adoc<br>A doc/manuals/icE1usb-usermanual.adoc<br>6 files changed, 329 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile</span><br><span>new file mode 100644</span><br><span>index 0000000..1bd4b6e</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/Makefile</span><br><span>@@ -0,0 +1,9 @@</span><br><span style="color: hsl(120, 100%, 40%);">+OSMO_GSM_MANUALS_DIR:=$(shell pkg-config osmo-gsm-manuals --variable=osmogsmmanualsdir)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+sdcdir = .</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ASCIIDOC = icE1usb-usermanual.adoc</span><br><span style="color: hsl(120, 100%, 40%);">+include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc</span><br><span style="color: hsl(120, 100%, 40%);">+icE1usb-usermanual.pdf: chapters/*.adoc</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc</span><br><span>diff --git a/doc/manuals/chapters/firmware.adoc b/doc/manuals/chapters/firmware.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..d0542bd</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/firmware.adoc</span><br><span>@@ -0,0 +1,137 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[firmware]]</span><br><span style="color: hsl(120, 100%, 40%);">+== icE1usb Firmware</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The icE1usb _firmware_ is a small amount of bare-iron software running</span><br><span style="color: hsl(120, 100%, 40%);">+on the picoRISCV soft-core of the _gateware_.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It mainly consists of drivers for the no2e1 E1 Framer IP core and the</span><br><span style="color: hsl(120, 100%, 40%);">+no2usb USB Device IP core which are part of the gateware described in</span><br><span style="color: hsl(120, 100%, 40%);">+<<gateware>>.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Firmware Upgrade (DFU)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+icE1usb contains support for the USB DFU (Device Firmware Upgrade)</span><br><span style="color: hsl(120, 100%, 40%);">+standard.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+As such, you can use any USB DFU compliant utility to upgrade the</span><br><span style="color: hsl(120, 100%, 40%);">+firmware of the icE1usb device.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+DFU mode can be entered in two ways:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+1. by performing a DFU detach from the normal application firmware</span><br><span style="color: hsl(120, 100%, 40%);">+ (obviously that requires a [still] working firmware present on the</span><br><span style="color: hsl(120, 100%, 40%);">+ device). To do so, please use `dfu-util -e`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+1. by pushing the push-button (see <<hw-pushbutton>>) during power-up.</span><br><span style="color: hsl(120, 100%, 40%);">+ Simply disconnect the USB cable, then push that button and keep it</span><br><span style="color: hsl(120, 100%, 40%);">+ pushed while re-attaching the USB cable.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The icE1usb boot loader enumerates as VID:PID `1d50:6145`, while the</span><br><span style="color: hsl(120, 100%, 40%);">+normal application firmware enumerates as `1d50:6144`,</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You can for example use `lsusb` to check the VID:PID:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+$ lsusb -d 1d50:</span><br><span style="color: hsl(120, 100%, 40%);">+Bus 001 Device 042: ID 1d50:6145<1> OpenMoko, Inc. icE1usb</span><br><span style="color: hsl(120, 100%, 40%);">+$ sudo dfu-util -d 1d50:6145 -e <2></span><br><span style="color: hsl(120, 100%, 40%);">+...</span><br><span style="color: hsl(120, 100%, 40%);">+$ lsusb -d 1d50:</span><br><span style="color: hsl(120, 100%, 40%);">+Bus 001 Device 043: ID 1d50:6144<3> OpenMoko, Inc. icE1usb (DFU)</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> initially the device is in normal runtime mode</span><br><span style="color: hsl(120, 100%, 40%);">+<2> we use `dfu-util -e` to switch to DFU mode</span><br><span style="color: hsl(120, 100%, 40%);">+<3> we can see, the device is now in DFU mode</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Obtaining firmware upgrades</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The latest firmware can currently be found at the personal developer</span><br><span style="color: hsl(120, 100%, 40%);">+directory of tnt at https://people.osmocom.org/tnt/e1/</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+A more official download location will be provided shortly.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Upgrading the FPGA gateware</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Gateware files are called `icE1usb-*.bin`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The gateware can be upgraded by accessing the DFU _altsetting 0_ using `dfu-util` *`-a 0`*</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Assuming you already are in DFU mode, you would typically use a command</span><br><span style="color: hsl(120, 100%, 40%);">+like `dfu-util -d 1d50:6144 -a 0 -D icE1usb-202010-bd3999e96.bin -R` to perform the upgrade.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NOTE: The `-R` will switch the device back to runtime mode after the</span><br><span style="color: hsl(120, 100%, 40%);">+upgrade. If you want to upgrade the firmware in the same session, skip</span><br><span style="color: hsl(120, 100%, 40%);">+the `-R` in the above command.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Upgrading the picoRISCV firmware</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Firmware files are called `fw_app*.bin`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The firmware can be upgraded by accessing the DFU _altsetting 1_ using `dfu-util` *`-a 1`*</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Assuming you already are in DFU mode, you would typically use a command</span><br><span style="color: hsl(120, 100%, 40%);">+like `dfu-util -d 1d50:6144 -a 1 -D fw_app-202011-4d9a04e2.bin -R` to perform the upgrade.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Typical output during upgrade of the firmware</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+$ sudo dfu-util -d 1d50:6144 -a 1 -D ./fw_app.bin -R</span><br><span style="color: hsl(120, 100%, 40%);">+dfu-util 0.9</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.</span><br><span style="color: hsl(120, 100%, 40%);">+Copyright 2010-2016 Tormod Volden and Stefan Schmidt</span><br><span style="color: hsl(120, 100%, 40%);">+This program is Free Software and has ABSOLUTELY NO WARRANTY</span><br><span style="color: hsl(120, 100%, 40%);">+Please report bugs to http://sourceforge.net/p/dfu-util/tickets/</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+dfu-util: Invalid DFU suffix signature</span><br><span style="color: hsl(120, 100%, 40%);">+dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!</span><br><span style="color: hsl(120, 100%, 40%);">+Opening DFU capable USB device...</span><br><span style="color: hsl(120, 100%, 40%);">+ID 1d50:6144</span><br><span style="color: hsl(120, 100%, 40%);">+Run-time device DFU version 0101</span><br><span style="color: hsl(120, 100%, 40%);">+Claiming USB DFU Interface...</span><br><span style="color: hsl(120, 100%, 40%);">+Setting Alternate Setting #1 ...</span><br><span style="color: hsl(120, 100%, 40%);">+Determining device status: state = dfuIDLE, status = 0</span><br><span style="color: hsl(120, 100%, 40%);">+dfuIDLE, continuing</span><br><span style="color: hsl(120, 100%, 40%);">+DFU mode device DFU version 0101</span><br><span style="color: hsl(120, 100%, 40%);">+Device returned transfer size 4096</span><br><span style="color: hsl(120, 100%, 40%);">+Copying data from PC to DFU device</span><br><span style="color: hsl(120, 100%, 40%);">+Download [=========================] 100% 11256 bytes</span><br><span style="color: hsl(120, 100%, 40%);">+Download done.</span><br><span style="color: hsl(120, 100%, 40%);">+state(2) = dfuIDLE, status(0) = No error condition is present</span><br><span style="color: hsl(120, 100%, 40%);">+Done!</span><br><span style="color: hsl(120, 100%, 40%);">+Resetting USB to switch back to runtime mode</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+As the `-R` option was used, the device will reset and re-enumerate in</span><br><span style="color: hsl(120, 100%, 40%);">+the newly programmed firmware.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You can verify this as follows:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+$ lsusb -d 1d50:</span><br><span style="color: hsl(120, 100%, 40%);">+Bus 001 Device 042: ID 1d50:6145 OpenMoko, Inc. icE1usb</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+or alternatively:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+$ dfu-util -l -d 1d50:</span><br><span style="color: hsl(120, 100%, 40%);">+dfu-util 0.9</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.</span><br><span style="color: hsl(120, 100%, 40%);">+Copyright 2010-2016 Tormod Volden and Stefan Schmidt</span><br><span style="color: hsl(120, 100%, 40%);">+This program is Free Software and has ABSOLUTELY NO WARRANTY</span><br><span style="color: hsl(120, 100%, 40%);">+Please report bugs to http://sourceforge.net/p/dfu-util/tickets/</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Found Runtime: [1d50:6145] ver=0003, devnum=44, cfg=1, intf=1, path="1-2", alt=0, name="DFU runtime", serial="dc697407e7881531"</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Use of the E1 Interface LEDs</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Each E1 interface has two LEDs integrated into the RJ45 connector.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+FIXME: describe how they are used.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Use of the Multi-Color RGB LED</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+FIXME: describe how it is used.</span><br><span>diff --git a/doc/manuals/chapters/gateware.adoc b/doc/manuals/chapters/gateware.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..03487e1</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/gateware.adoc</span><br><span>@@ -0,0 +1,13 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[gateware]]</span><br><span style="color: hsl(120, 100%, 40%);">+== icE1usb Gateware</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The icE1usb _gateware_ is where pretty much everything happens,</span><br><span style="color: hsl(120, 100%, 40%);">+from the E1 Line Interface Unit to the E1 Framer/Deframer, the</span><br><span style="color: hsl(120, 100%, 40%);">+picoRISCV soft-core running the [[firmware]] as well as the USB</span><br><span style="color: hsl(120, 100%, 40%);">+device peripheral talking to the host PC.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+As an OSHW project, all of it is available in source code format</span><br><span style="color: hsl(120, 100%, 40%);">+at https://git.osmocom.org/osmo-e1-hardware/tree/gateware/icE1usb</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Please use `git clone --recursive` when cloning the git repository</span><br><span style="color: hsl(120, 100%, 40%);">+so you get all of the sub-modules for the various soft-cores.</span><br><span>diff --git a/doc/manuals/chapters/hardware.adoc b/doc/manuals/chapters/hardware.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..4b2f694</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/hardware.adoc</span><br><span>@@ -0,0 +1,119 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[hardware]]</span><br><span style="color: hsl(120, 100%, 40%);">+== icE1usb Hardware</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The icE1usb Hardware consists of a single circuit board (in an optional</span><br><span style="color: hsl(120, 100%, 40%);">+enclosure).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It's main building blocks are:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* an iCE40 FPGA</span><br><span style="color: hsl(120, 100%, 40%);">+* Two E1 line interface (transformers, biasing networks and ESD protection) footnote:[Only one E1 line supported by firmware so far]</span><br><span style="color: hsl(120, 100%, 40%);">+* a GPS receiver module with 1PPS output to the FPGA footnote:[GPS-DO supported by firmware yet]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Schematics</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+As icE1usb is an OSHW (Open Source Hardware) project, the full schematics</span><br><span style="color: hsl(120, 100%, 40%);">+and design files are publicly available.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The design files in KiCAD formwa are available at https://git.osmocom.org/osmo-e1-hardware/tree/hardware/icE1usb</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+PDF rendered schematics are available at https://git.osmocom.org/osmo-e1-hardware/plain/hardware/icE1usb/r1.0/icE1usb.pdf</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Connectors</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== X5A and X5B: E1 Interface Connectors</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On one side of the PCB there are two RJ45 connectors next to each other.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Those are the two E1 line interfaces. The interfaces are of symmetric</span><br><span style="color: hsl(120, 100%, 40%);">+120 Ohms type.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Assuming the board is oriented with the tab of the RJ45 connectors facing</span><br><span style="color: hsl(120, 100%, 40%);">+up:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Interface 0 is on the right side</span><br><span style="color: hsl(120, 100%, 40%);">+* Interface 1 is on the left side (next to the button)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The pin-out of the connectors can be swapped between TE and NT mode using</span><br><span style="color: hsl(120, 100%, 40%);">+the J4 and J5 jumper blocks on the circuit board.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+A GSM BTS typically implements TE pin-out, while the icE1usb should then</span><br><span style="color: hsl(120, 100%, 40%);">+use NT mode pin-out if no cross-over cable is used.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Pin-out of RJ45 E1 connectors</span><br><span style="color: hsl(120, 100%, 40%);">+[options="header"]</span><br><span style="color: hsl(120, 100%, 40%);">+|===</span><br><span style="color: hsl(120, 100%, 40%);">+| Pin | Function (TE) | Function (NT Mode)</span><br><span style="color: hsl(120, 100%, 40%);">+| 1 | Rx | Tx</span><br><span style="color: hsl(120, 100%, 40%);">+| 2 | Rx | Tx</span><br><span style="color: hsl(120, 100%, 40%);">+| 3 | not used | not used</span><br><span style="color: hsl(120, 100%, 40%);">+| 4 | Tx | Rx</span><br><span style="color: hsl(120, 100%, 40%);">+| 5 | Tx | Rx</span><br><span style="color: hsl(120, 100%, 40%);">+| 7 | not used | not used</span><br><span style="color: hsl(120, 100%, 40%);">+| 8 | not used | not used</span><br><span style="color: hsl(120, 100%, 40%);">+|===</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NOTE: E1 cables use RJ45 like Ethernet, but Ethernet cables have a</span><br><span style="color: hsl(120, 100%, 40%);">+different pin-out. Particularly, you cannot use an Ethernet cross-over</span><br><span style="color: hsl(120, 100%, 40%);">+cable as an E1 cross-over!</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== X4: USB Connector</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The USB connector is a USB Type C connector. However, it only carries</span><br><span style="color: hsl(120, 100%, 40%);">+USB 1.1 full-speed signals. 5V DC power is also sourced from this</span><br><span style="color: hsl(120, 100%, 40%);">+connector.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== X2: Serial Console Connector</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The serial console is used for development and debugging. It uses an</span><br><span style="color: hsl(120, 100%, 40%);">+Osmocom-style 2.5mm stereo TRS jack.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The serial console uses 3.3V CMOS logic levels</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The serial console uses a rate of 1000000 bps.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The pin-out is as follows:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Tip: Tx output from PC (Rx input of icE1usb)</span><br><span style="color: hsl(120, 100%, 40%);">+* Ring: Rx input of PC (Tx output of icE1usb)</span><br><span style="color: hsl(120, 100%, 40%);">+* Shield: GND</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+A compatible cable can be sourced from the sysmocom web-shop at</span><br><span style="color: hsl(120, 100%, 40%);">+http://shop.sysmocom.de/.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== X1: GPS Antenna Connector</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The GPS antenna connector is a female SMA connector.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You can connect most standard active GPS antennas with built-in LNA.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+icE1us provide phantom voltage.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The use of a GPS antenna is only required when you need a high precision</span><br><span style="color: hsl(120, 100%, 40%);">+clock reference for the 2.048 MHz E1 bit clock, e.g. to provide a clock</span><br><span style="color: hsl(120, 100%, 40%);">+reference to a cellular base station on the A-bis interface.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== X3: GPIO / Extension Connector</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This is a RJ45 connector adjacent to the USB connector.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It is currently unused and reserved for future use.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[hw-pushbutton]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== Pushbutton</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This is a push-button next to the _E1 interface '1'_. It is recessed</span><br><span style="color: hsl(120, 100%, 40%);">+to protect against accidental use. You will need to use a paper clip,</span><br><span style="color: hsl(120, 100%, 40%);">+pen tip or other similar object to push it.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The button can be used to force booting into the DFU loader in order to</span><br><span style="color: hsl(120, 100%, 40%);">+recover from a broken firmware installation.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Multi-Color LED</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Above the USB-C connector, there is a multi-color RGB LED.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This LED is used by the firmware to indicate a variety of status</span><br><span style="color: hsl(120, 100%, 40%);">+information. Pleas see the firmware documentation in <<firmware>>.</span><br><span>diff --git a/doc/manuals/chapters/host-software.adoc b/doc/manuals/chapters/host-software.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..8af1018</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/host-software.adoc</span><br><span>@@ -0,0 +1,34 @@</span><br><span style="color: hsl(120, 100%, 40%);">+== Host Software</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Host Software is software running on the USB host computer to which the</span><br><span style="color: hsl(120, 100%, 40%);">+icE1usb is attached.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+At the time of this writing, the only software implementing icE1usb</span><br><span style="color: hsl(120, 100%, 40%);">+support is `osmo-e1d`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== `osmo-e1d`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+`osmo-e1d` utilizes `libusb` to talk to the icE1usb hardware and offers</span><br><span style="color: hsl(120, 100%, 40%);">+a unix domain socket based interface to application software.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Software such as `osmo-bsc` and `osmo-mgw` can interface `osmo-e1d` via</span><br><span style="color: hsl(120, 100%, 40%);">+the `libosmo-abis` support for `osmo-e1d`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+More information about `osmo-e1d` can be found at its homepage</span><br><span style="color: hsl(120, 100%, 40%);">+https://osmocom.org/projects/osmo-e1d/wiki</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Other software</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+you can interface 3rd party applications with osmo-e1d in the following</span><br><span style="color: hsl(120, 100%, 40%);">+ways:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* by adding support for `osmo-e1d`, e.g. via `libosmo-e1d` to the</span><br><span style="color: hsl(120, 100%, 40%);">+ respective appliation</span><br><span style="color: hsl(120, 100%, 40%);">+* by implementing a device driver for whatever hardware interface (e.g.</span><br><span style="color: hsl(120, 100%, 40%);">+ for DAHDI) supported by your software</span><br><span style="color: hsl(120, 100%, 40%);">+* by directly implementing the USB interface exposed by icE1usb in your</span><br><span style="color: hsl(120, 100%, 40%);">+ software</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Should you require any related development/porting services, please do</span><br><span style="color: hsl(120, 100%, 40%);">+not hesitate to reach out to sysmocom.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span>diff --git a/doc/manuals/icE1usb-usermanual.adoc b/doc/manuals/icE1usb-usermanual.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..5cfeef6</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/icE1usb-usermanual.adoc</span><br><span>@@ -0,0 +1,17 @@</span><br><span style="color: hsl(120, 100%, 40%);">+:gfdl-enabled:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+icE1usb User Manual</span><br><span style="color: hsl(120, 100%, 40%);">+===================</span><br><span style="color: hsl(120, 100%, 40%);">+Harald Welte <hwelte@sysmocom.de></span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./common/chapters/preface.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./chapters/hardware.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./chapters/gateware.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./chapters/firmware.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./chapters/host-software.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./common/chapters/gfdl.adoc[]</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-e1-hardware/+/21719">change 21719</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-e1-hardware/+/21719"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: osmo-e1-hardware </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: Ia04890cf3b321f8cb01e3c513a730031e76376b9 </div>
<div style="display:none"> Gerrit-Change-Number: 21719 </div>
<div style="display:none"> Gerrit-PatchSet: 3 </div>
<div style="display:none"> Gerrit-Owner: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-Reviewer: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>