Change in osmo-e1-hardware[master]: First version of icE1usb user manual

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

laforge gerrit-no-reply at lists.osmocom.org
Mon Dec 14 20:06:30 UTC 2020


laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-e1-hardware/+/21719 )


Change subject: First version of icE1usb user manual
......................................................................

First version of icE1usb user manual

Change-Id: Ia04890cf3b321f8cb01e3c513a730031e76376b9
---
A doc/manuals/Makefile
A doc/manuals/chapters/firmware.adoc
A doc/manuals/chapters/hardware.adoc
A doc/manuals/chapters/host-software.adoc
A doc/manuals/icE1usb-usermanual.adoc
5 files changed, 287 insertions(+), 0 deletions(-)



  git pull ssh://gerrit.osmocom.org:29418/osmo-e1-hardware refs/changes/19/21719/1

diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile
new file mode 100644
index 0000000..1bd4b6e
--- /dev/null
+++ b/doc/manuals/Makefile
@@ -0,0 +1,9 @@
+OSMO_GSM_MANUALS_DIR:=$(shell pkg-config osmo-gsm-manuals --variable=osmogsmmanualsdir)
+
+sdcdir = .
+
+ASCIIDOC = icE1usb-usermanual.adoc
+include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
+icE1usb-usermanual.pdf: chapters/*.adoc
+
+include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc
diff --git a/doc/manuals/chapters/firmware.adoc b/doc/manuals/chapters/firmware.adoc
new file mode 100644
index 0000000..665a657
--- /dev/null
+++ b/doc/manuals/chapters/firmware.adoc
@@ -0,0 +1,126 @@
+[[firmware]]
+== icE1usb Firmware
+
+The icE1usb _firmware_ is a small amount of bare-iron software running
+on the picoRISCV soft-core of the _gateware_.
+
+It mainly consists of drivers for the no2e1 E1 Framer IP core and the
+no2usb USB Device IP core which are part of the gateware described in
+<<gateware>>.
+
+=== Firmware Upgrade (DFU)
+
+icE1usb contains support for the USB DFU (Device Firmware Upgrade)
+standard.
+
+As such, you can use any USB DFU compliant utility to upgrade the
+firmware of the icE1usb device.
+
+DFU mode can be entered in two ways:
+
+* by performing a DFU detach from the normal application firmware
+  (obviously that requires a [still] working firmware present on the
+  device).  To do so, please use `dfu-util -e`
+
+* by pushing the push-button (see <<hw-pushbutton>>) during power-up.
+  Simply disconnect the USB cable, then push that button and keep it
+  pushed while re-attaching the USB cable.
+
+The icE1usb boot loader enumerates as VID:PID `1d50:6145`, while the
+normal application firmware enumerates as `1d50:6144`,
+
+You can for example use `lsusb` to check the VID:PID:
+
+----
+$ lsusb -d 1d50:
+Bus 001 Device 042: ID 1d50:6145<1> OpenMoko, Inc. icE1usb
+$ sudo dfu-util -d 1d50:6145 -e <2>
+...
+$ lsusb -d 1d50:
+Bus 001 Device 043: ID 1d50:6144<3> OpenMoko, Inc. icE1usb (DFU)
+----
+<1> initially the device is in normal runtime mode
+<2> we use `dfu-util -e` to switch to DFU mode
+<3> we can see, the device is now in DFU mode
+
+==== Obtaining firmware upgrades
+
+The latest firmware can currently be found at the personal developer
+directory of tnt at https://people.osmocom.org/tnt/e1/
+
+A more official download location will be provided shortly.
+
+==== Upgrading the FPGA gateware
+
+Gateware files are called `icE1usb-*.bin`.
+
+The gateware can be upgraded by accessing the DFU _altsetting 0_
+
+Assuming you already are in DFU mode, you would typically use a command
+like `dfu-util -d 1d50:6144 -a 0 -D icE1usb-202010-bd3999e96.bin -R` to perform the upgrade.
+
+NOTE: The `-R` will switch the device back to runtime mode after the
+upgrade.   If you want to upgrade the firmware in the same session, skip
+the `-R` in the above command.
+
+==== Upgrading the picoRISCV firmware
+
+Firmware files are called `fw_app*.bin`.
+
+The firmware can be upgraded by accessing the DFU _altsetting 1_
+
+Assuming you already are in DFU mode, you would typically use a command
+like `dfu-util -d 1d50:6144 -a 1 -D fw_app-202011-4d9a04e2.bin -R` to perform the upgrade.
+
+.Typical output during upgrade of the firmware
+----
+$ sudo dfu-util -d 1d50:6144 -a 1 -D ./fw_app.bin -R
+dfu-util 0.9
+
+Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
+Copyright 2010-2016 Tormod Volden and Stefan Schmidt
+This program is Free Software and has ABSOLUTELY NO WARRANTY
+Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
+
+dfu-util: Invalid DFU suffix signature
+dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
+Opening DFU capable USB device...
+ID 1d50:6144
+Run-time device DFU version 0101
+Claiming USB DFU Interface...
+Setting Alternate Setting #1 ...
+Determining device status: state = dfuIDLE, status = 0
+dfuIDLE, continuing
+DFU mode device DFU version 0101
+Device returned transfer size 4096
+Copying data from PC to DFU device
+Download        [=========================] 100%        11256 bytes
+Download done.
+state(2) = dfuIDLE, status(0) = No error condition is present
+Done!
+Resetting USB to switch back to runtime mode
+----
+
+As the `-R` option was used, the device will reset and re-enumerate in
+the newly programmed firmware.
+
+You can verify this as follows:
+
+----
+$ lsusb -d 1d50:
+Bus 001 Device 042: ID 1d50:6145<1> OpenMoko, Inc. icE1usb
+----
+
+or alternatively:
+
+----
+$ dfu-util -l -d 1d50:
+dfu-util 0.9
+
+Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
+Copyright 2010-2016 Tormod Volden and Stefan Schmidt
+This program is Free Software and has ABSOLUTELY NO WARRANTY
+Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
+
+Found Runtime: [1d50:6145] ver=0003, devnum=44, cfg=1, intf=1, path="1-2", alt=0, name="DFU runtime", serial="dc697407e7881531"
+----
diff --git a/doc/manuals/chapters/hardware.adoc b/doc/manuals/chapters/hardware.adoc
new file mode 100644
index 0000000..3f19513
--- /dev/null
+++ b/doc/manuals/chapters/hardware.adoc
@@ -0,0 +1,103 @@
+[[hardware]]
+== icE1usb Hardware
+
+The icE1usb Hardware consists of a single circuit board (in an optional
+enclosure).
+
+It's main building blocks are:
+
+* an iCE40 FPGA
+* Two E1 line interface (transformers, biasing networks and ESD protection) footnote:[Only one E1 line supported by firmware so far]
+* a GPS receiver module with 1PPS output to the FPGA footnote:[GPS-DO supported by firmware yet]
+
+=== Schematics
+
+As icE1usb is an OSHW (Open Source Hardware) project, the full schematics
+and design files are publicly available.
+
+The design files in KiCAD formwa are available at https://git.osmocom.org/osmo-e1-hardware/tree/hardware/icE1usb
+
+PDF rendered schematics are available at https://git.osmocom.org/osmo-e1-hardware/plain/hardware/icE1usb/r1.0/icE1usb.pdf
+
+=== Connectors
+
+==== X5A and X5B: E1 Interface Connectors
+
+On one side of the PCB there are two RJ45 connectors next to each other.
+
+Those are the two E1 line interfaces.  The interfaces are of symmetric
+120 Ohms type.
+
+Assuming the board is orented with the tab of the RJ45 connectors facing
+up:
+
+* Interface 0 is on the right side
+* Interface 1 is on the left side (next to the button)
+
+The pin-out of the connectors can be swapped between TE and NT mode using
+the J4 and J5 jumper blocks on the circuit board.
+
+A GSM BTS typically implements TE pin-out, while the icE1usb should then
+use NT mode pin-out if no cross-over cable is used.
+
+FIXME: pinout for both modes.
+
+NOTE: E1 cables use RJ45 like Ethernet, but Ethernet cables have a
+different pin-out.  Particularly, you cannot use an Ethernet cross-over
+cable as an E1 cross-over!
+
+==== X4: USB Connector
+
+The USB connector is a USB Type C connector.   However, it only carries
+USB 1.1 full-speed signals.  5V DC power is also sourced from this
+connector.
+
+==== X2: Serial Console Connector
+
+The serial console is used for development and debugging.  It uses an
+Osmocom-style 2.5mm stereo TRS jack.
+
+The serial console uses 3.3V CMOS logic levels
+
+The pin-out is as follows:
+
+* Tip: Tx output from PC (Rx input of icE1usb)
+* Ring: Rx input of PC (Tx output of icE1usb)
+* Shield: GND
+
+A compatible cable can be sourced from the sysmocom web-shop at
+http://shop.sysmocom.de/.
+
+==== X1: GPS Antenna Connector
+
+The GPS antenna connector is a female SMA connector.
+
+You can connect most standard active GPS antennas with built-in LNA.
+
+icE1us provide phantom voltage.
+
+The use of a GPS antenna is only required when you need a high precision
+clock reference for the 2.048 MHz E1 bit clock, e.g. to provide a clock
+reference to a cellular base station on the A-bis interface.
+
+==== X3: GPIO / Extension Connector
+
+This is a RJ45 connector adjacent to the USB connector.
+
+It is currently unused and reserved for future use.
+
+
+[[hw-pushbutton]]
+=== Pushbutton
+
+This is a push-button next to the E1 interface '1'.  It can be used to
+force booting into the DFU loader in order to recover from a broken
+firmware installation.
+
+
+=== Multi-Color LED
+
+Above the USB-C connector, there is a multi-color RGB LED.
+
+This LED is used by the firmware to indicate a variety of status
+information.  Pleas see the firmware documentation in <<firmware>>.
diff --git a/doc/manuals/chapters/host-software.adoc b/doc/manuals/chapters/host-software.adoc
new file mode 100644
index 0000000..8af1018
--- /dev/null
+++ b/doc/manuals/chapters/host-software.adoc
@@ -0,0 +1,34 @@
+== Host Software
+
+Host Software is software running on the USB host computer to which the
+icE1usb is attached.
+
+At the time of this writing, the only software implementing icE1usb
+support is `osmo-e1d`.
+
+=== `osmo-e1d`
+
+`osmo-e1d` utilizes `libusb` to talk to the icE1usb hardware and offers
+a unix domain socket based interface to application software.
+
+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
+
+=== 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 appliation
+* by implementing a device driver for whatever hardware interface (e.g.
+  for DAHDI) supported by your software
+* 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.
+
diff --git a/doc/manuals/icE1usb-usermanual.adoc b/doc/manuals/icE1usb-usermanual.adoc
new file mode 100644
index 0000000..260a18c
--- /dev/null
+++ b/doc/manuals/icE1usb-usermanual.adoc
@@ -0,0 +1,15 @@
+:gfdl-enabled:
+
+icE1usb User Manual
+===================
+Harald Welte <hwelte at sysmocom.de>
+
+include::./common/chapters/preface.adoc[]
+
+include::./chapters/hardware.adoc[]
+
+include::./chapters/firmware.adoc[]
+
+include::./chapters/host-software.adoc[]
+
+include::./common/chapters/gfdl.adoc[]

-- 
To view, visit https://gerrit.osmocom.org/c/osmo-e1-hardware/+/21719
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: osmo-e1-hardware
Gerrit-Branch: master
Gerrit-Change-Id: Ia04890cf3b321f8cb01e3c513a730031e76376b9
Gerrit-Change-Number: 21719
Gerrit-PatchSet: 1
Gerrit-Owner: laforge <laforge at osmocom.org>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20201214/75dfe781/attachment.htm>


More information about the gerrit-log mailing list