| [[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:6144`, while the |
| normal application firmware enumerates as `1d50:6145`, |
| |
| 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 be found at |
| https://ftp.osmocom.org/binaries/icE1usb/firmware/latest/ |
| |
| The latest gateware can currently only be found at the personal developer |
| directory of tnt at https://people.osmocom.org/tnt/ice1usb/icE1usb-202010-bd399e96.bin |
| A more official download location for the gateware will be provided shortly. |
| |
| ==== Upgrading the FPGA gateware |
| |
| Gateware files are called `icE1usb-*.bin`. (without 'fw' in the name) |
| |
| 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 `icE1usb-fw*.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. They |
| are (starting to get) used by the firmware to indicate status |
| information to the user. |
| |
| [options="header"] |
| |=== |
| |Color | Pattern | Meaning |
| |Green | Blinking (slow) | E1 Receiver attempting to align |
| |Green | On | E1 Receiver fully aligned |
| |=== |
| |
| |
| === Use of the Multi-Color RGB LED |
| |
| FIXME: describe how it is used. |
| |
| |
| === Firmware <-> USB Host Interface |
| |
| The icE1usb firmware provides a USB 1.1 full-speed (FS) device with |
| |
| * one configuration |
| * 5 interfaces |
| ** E1 port 0 |
| ** E1 port 1 |
| ** CDC-ACM (control + data) |
| ** DFU (device firmware upgrade) |
| |
| The interfaces have self-explanatory string descriptors like |
| |
| ---- |
| iInterface 6 E1 port 0 |
| iInterface 8 E1 port 1 |
| iInterface 9 GPS (CDC control) |
| iInterface 10 GPS (CDC data) |
| iInterface 11 DFU runtime |
| ---- |
| |
| ==== E1 ports |
| |
| There are two physical E1 ports in the icE1usb. Each is exposed via its own USB _interface_. |
| |
| Each port (USB _interface_) contains two _altsettings_: |
| |
| * one altsetting with no data endpoints (E1 disabled, this is the default) |
| * one altsetting with isochronous IN/OUT endpoints (E1 enabled) |
| |
| In order to activate one E1 port, the driver must perform a USB standard |
| request to activate the _enabled_ altsetting. |
| |
| NOTE:: Please note that on many XHCI host controllers there seem to be |
| implementation flaws in the XHCI host controller firmware preventing the |
| activation of both icE1usb ports simultaneously. The XHCI controller |
| firmware erroneously claims that there is insufficient bus bandwidth. |
| However, the same icE1usb hardware/firmware works perfectly fine with |
| OHCI, UHCI and EHCI host controllers. See |
| https://osmocom.org/projects/e1-t1-adapter/wiki/Isochronous_USB_Issues for a user-maintained list of USB hosts / controllers and whether or not they work with two E1 ports. |
| |
| As most modern [PC] hardware has XHCI host controllers, you need to |
| choose your hardware carefully if concurrent operation of both icE1usb |
| ports is required in your application. |
| |
| ==== CDC-ACM with GPS NMEA |
| |
| There's a CDC-ACM (virtual com port) interface available in the icE1usb. |
| This will be supported by the standard `cdc_acm` driver of your |
| operating system, and will expose a `/dev/ttyACMx` device on Linux. |
| |
| The port provides read-only access to the GPS receiver on-board the |
| icE1usb. You can use this to |
| |
| * determine the GPS fix (and hence 1PPS frequency reference) |
| availability |
| * obtain the GPS position of the device |
| |
| NOTE:: Write access to the GPS receiver is not permitted as the icE1usb |
| firmware needs to control the GPS receiver for frequency reference |
| purposes. |
| |
| ==== DFU (Device Firmware Upgrade) |
| |
| There's a DFU interface available in order to update the icE1usb |
| gateware and firmware. For more information, see [[firmware]] above. |