First version of icE1usb user manual
Change-Id: Ia04890cf3b321f8cb01e3c513a730031e76376b9
This commit is contained in:
parent
72865d866f
commit
d645d44eb4
|
@ -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
|
|
@ -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.
|
|
@ -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.
|
|
@ -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>>.
|
|
@ -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.
|
||||||
|
|
|
@ -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[]
|
Loading…
Reference in New Issue