retronetworking
/
osmo-e1-hardware
mirror of https://gerrit.osmocom.org/osmo-e1-hardware
13
0
Fork 0
Code Issues Projects Releases Wiki Activity

First version of icE1usb user manual 

Change-Id: Ia04890cf3b321f8cb01e3c513a730031e76376b9
This commit is contained in:
Harald Welte 2020-12-14 19:20:38 +01:00
parent 72865d866f
commit d645d44eb4
6 changed files with 329 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/manuals/Makefile Normal file
View File

@ -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

137
doc/manuals/chapters/firmware.adoc Normal file
View File

@ -0,0 +1,137 @@
[[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:
1. 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`
1. 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_ using `dfu-util` *`-a 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_ using `dfu-util` *`-a 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 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"
----
=== Use of the E1 Interface LEDs
Each E1 interface has two LEDs integrated into the RJ45 connector.
FIXME: describe how they are used.
=== Use of the Multi-Color RGB LED
FIXME: describe how it is used.

13
doc/manuals/chapters/gateware.adoc Normal file
View File

@ -0,0 +1,13 @@
[[gateware]]
== icE1usb Gateware
The icE1usb _gateware_ is where pretty much everything happens,
from the E1 Line Interface Unit to the E1 Framer/Deframer, the
picoRISCV soft-core running the [[firmware]] as well as the USB
device peripheral talking to the host PC.
As an OSHW project, all of it is available in source code format
at https://git.osmocom.org/osmo-e1-hardware/tree/gateware/icE1usb
Please use `git clone --recursive` when cloning the git repository
so you get all of the sub-modules for the various soft-cores.

119
doc/manuals/chapters/hardware.adoc Normal file
View File

@ -0,0 +1,119 @@
[[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 oriented 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.
.Pin-out of RJ45 E1 connectors
[options="header"]
|===
| Pin | Function (TE) | Function (NT Mode)
| 1 | Rx | Tx
| 2 | Rx | Tx
| 3 | not used | not used
| 4 | Tx | Rx
| 5 | Tx | Rx
| 7 | not used | not used
| 8 | not used | not used
|===
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 serial console uses a rate of 1000000 bps.
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 is recessed
to protect against accidental use. You will need to use a paper clip,
pen tip or other similar object to push it.
The button 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>>.

34
doc/manuals/chapters/host-software.adoc Normal file
View File

@ -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.

17
doc/manuals/icE1usb-usermanual.adoc Normal file
View File

@ -0,0 +1,17 @@
:gfdl-enabled:
icE1usb User Manual
===================
Harald Welte <hwelte@sysmocom.de>
include::./common/chapters/preface.adoc[]
include::./chapters/hardware.adoc[]
include::./chapters/gateware.adoc[]
include::./chapters/firmware.adoc[]
include::./chapters/host-software.adoc[]
include::./common/chapters/gfdl.adoc[]