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