laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-e1-hardware/+/29972 )
Change subject: doc/e1-tracer: Add an initial e1-tracer user manual ......................................................................
doc/e1-tracer: Add an initial e1-tracer user manual
Change-Id: I9413195d69325ba74b3993e6ec7a1fc7628b5dd1 --- M doc/manuals/Makefile A doc/manuals/chapters/e1-tracer/firmware.adoc A doc/manuals/chapters/e1-tracer/gateware.adoc A doc/manuals/chapters/e1-tracer/hardware.adoc A doc/manuals/chapters/e1-tracer/host-software.adoc A doc/manuals/e1-tracer-usermanual-docinfo.xml A doc/manuals/e1-tracer-usermanual.adoc A doc/manuals/images/e1-tracer-plate.png A doc/manuals/images/e1_tracer-bgt-front.jpg A doc/manuals/images/e1_tracer-koh1.jpg 10 files changed, 694 insertions(+), 1 deletion(-)
git pull ssh://gerrit.osmocom.org:29418/osmo-e1-hardware refs/changes/72/29972/1
diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile index 63bd422..53cb8ff 100644 --- a/doc/manuals/Makefile +++ b/doc/manuals/Makefile @@ -2,8 +2,9 @@
srcdir = .
-ASCIIDOC = icE1usb-usermanual.adoc +ASCIIDOC = icE1usb-usermanual.adoc e1-tracer-usermanual.adoc include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc icE1usb-usermanual.pdf: chapters/icE1usb/*.adoc +e1-tracer-usermanual.pdf: chapters/e1-tracer/*.adoc
include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc diff --git a/doc/manuals/chapters/e1-tracer/firmware.adoc b/doc/manuals/chapters/e1-tracer/firmware.adoc new file mode 100644 index 0000000..737f30a --- /dev/null +++ b/doc/manuals/chapters/e1-tracer/firmware.adoc @@ -0,0 +1,199 @@ +[[firmware]] +== e1-tracer Firmware + +The e1-tracer _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) + +e1-tracer 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 e1-tracer 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` + +2. 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 e1-tracer boot loader enumerates as VID:PID `1d50:6150`, while the +normal application firmware enumerates as `1d50:6151`, + +You can for example use `lsusb` to check the VID:PID: + +.Example output of `dfu-util` on a system with e1-tracer attached +---- +$ lsusb -d 1d50: +Bus 001 Device 042: ID 1d50:6151<1> OpenMoko, Inc. e1-tracer +$ sudo dfu-util -d 1d50:6151 -e <2> +... +$ lsusb -d 1d50: +Bus 001 Device 043: ID 1d50:6150<3> OpenMoko, Inc. e1-tracer (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/e1-tracer/firmware/latest/ +a backlog of earlier builds can be found at +https://ftp.osmocom.org/binaries/e1-tracer/firmware/all/ + +The latest gateware can currently only be found at the personal developer +directory of tnt at https://people.osmocom.org/tnt/e1-tracer/e1-tracer-gw-c7566442.bin +A more official download location for the gateware will be provided shortly. + +==== Upgrading the FPGA gateware + +Gateware files are called `e1-tracer-gw-*.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:6150 -a 0 -D e1-tracer-gw-c7566442.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 `e1_tracer-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:6150 -a 1 -D e1_tracer-fw-0.1-132-ga0df047.bin -R` to perform the upgrade. + +.Typical output during upgrade of the firmware +---- +$ sudo dfu-util -d 1d50:6150 -a 1 -D e1_tracer-fw-0.1-132-ga0df047.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:6150 +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:6151 OpenMoko, Inc. e1-tracer +---- + +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:6151] ver=0003, devnum=44, cfg=1, intf=1, path="1-2", alt=0, name="DFU runtime", serial="dc697407e7881531" +---- + + +=== Use of the LEDs + +==== LOS LEDs + +Each E1 channel has one red *LOS LED*. They are red if either + +* the E1 framer has not yet been initialized (done by starting host software) +* there is an actual LOS (Loss of Signal) condition in the respective direction + + +==== Multi-Color RGB STATUS LED + +The multi-color RGB *STATUS LED* is used to indicate overall hardware/firmware status. + +[options="header",cols="10,10,60"] +|=== +|Color | Pattern | Meaning +|Red | On | E1 interface not active (no host software?) +|Red | Blinking | E1 interface active, but error status (CRC, alignment) +|Green | On | E1 Receiver B aligned +|Green | Blinking | E1 Receiver A attempting to align +|Blue | On | E1 Receiver B aligned +|Blue | Blinking | E1 Receiver B attempting to align +|Cyan | On | E1 Receiver A+B aligned +|Cyan | Blinking | E1 Receiver A+B attempting to align +|=== + + + +=== Firmware - USB Host Interface + +The e1-tracer firmware provides a USB 1.1 full-speed (FS) device with two configurations + +* legacy configuration (for use with `e1-tracer-record`) +** 2 interfaces +*** combined interface for both E1 directions +*** DFU (device firmware upgrade) +* `osmo-e1d` compatible configuration +* 2 interfaces +** E1 direction A->B +** E1 direction A<-B + +The configurations and interfaces have self-explanatory string descriptors like + +---- + iInterface 8 E1 Direction A + iInterface 9 E1 Direction B +---- + +==== e1d compatible configuration: E1 ports + +There are two physical E1 ports in the e1-tracer. Each represents one direction +of the traced E1 circuit. Each is exposed via its own USB _interface_. + +Each port/direction (USB _interface_) contains two _altsettings_: + +* one altsetting with no data endpoints (E1 tracing disabled, this is the default) +* one altsetting with isochronous IN/OUT endpoints (E1 tracing enabled) + +In order to activate one E1 port, the driver must perform a USB standard +request to activate the _enabled_ altsetting. + +==== DFU (Device Firmware Upgrade) + +There's a DFU interface available in order to update the e1-tracer +gateware and firmware. For more information, see above. diff --git a/doc/manuals/chapters/e1-tracer/gateware.adoc b/doc/manuals/chapters/e1-tracer/gateware.adoc new file mode 100644 index 0000000..e0dc871 --- /dev/null +++ b/doc/manuals/chapters/e1-tracer/gateware.adoc @@ -0,0 +1,16 @@ +[[gateware]] +== e1-tracer Gateware + +The e1-tracer _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. + +The gateware is stored in binary form on the device-internal +non-volatile memory (SPI flash). It is field-upgradeable via USB. + +As an OSHW project, all of it is available in source code format +at https://git.osmocom.org/osmo-e1-hardware/tree/gateware/e1-tracer + +Please use `git clone --recursive` when cloning the git repository +so you get all of the sub-modules for the various soft-cores. diff --git a/doc/manuals/chapters/e1-tracer/hardware.adoc b/doc/manuals/chapters/e1-tracer/hardware.adoc new file mode 100644 index 0000000..1ba48df --- /dev/null +++ b/doc/manuals/chapters/e1-tracer/hardware.adoc @@ -0,0 +1,123 @@ +[[hardware]] +== e1-tracer Hardware + +The e1-tracer Hardware consists of a single circuit board, mechanically +either assembled into a desktop enclosure (KOH variant) or into a 3U component +carrier module (BGT variant). + +image::images/e1_tracer-bgt-front.jpg[width=400,title="e1-tracer BGT variant"] +image::images/e1_tracer-koh1.jpg[width=400,title="e1-tracer KOH variant"] + + +It's main building blocks are: + +* an iCE40 FPGA +* two E1 Line Interface Unit ICs +* two E1 line interface analog (transformers, biasing networks and ESD protection) + +=== Schematics / Board Layout + +As e1-tracer is an OSHW (Open Source Hardware) project, the full schematics +and design files are publicly available. + +The design files in EAGLE format are available at https://git.osmocom.org/osmo-e1-hardware/tree/hardware/e1-tracer + +PDF rendered schematics are available at https://gitea.osmocom.org/retronetworking/osmo-e1-hardware/raw/branch/master... + +=== Connectors / LEDs + +image::images/e1-tracer-plate.png[width=400,title="front side of e1-tracer"] + +From left to right, there are the following LED indcators, connectors and buttons: + +* LED block with 4 LED's +* Primary E1 Port (E1 A) +* Secondary E1 Port (E1 B) +* Serial Console Connector +* USB Connector +* Bootloader Button + +==== LEDs + +The left-most column of LEDs consists of two red *LOS LEDs*. +They indicate a LOS (Loss Of Signal) condition for the respective E1 direction. It is normal for the LEDs to be illuminated even in presence of a valid E1 signal until the host software has fully initialized the firmware for the first time after power-up. + +The right column of LEDs consists of two further LEDs: + +* a multi-color *STATUS LED* on the top +* a green *POWER LED* on the bottom + +The *STATUS LED* is used by the firmware to indicate a variety of status +information. Pleas see the firmware documentation in <<firmware>>. + +The green *POWER LED* is illuminated as soon as the device has DC power. + +==== J1A and J1B: E1 Interface Connectors + +There are two RJ45 connectors next to each other. + +Those are the connections for your symmetric 120 Ohms E1 interface +circuit. You insert the e1-tracer into your E1 link. The two ports are +internally wired straight-through, so you can insert the e1-tracer into +your E1 link. + +The actual tracing functionality is implemented via a high-impedance +tap, which will not disturb the normal E1 communications link. The link +remains unaffected even if the e1-tracer is unpowered. + +.Pin-out of RJ45 E1 connectors +[options="header"] +|=== +| Pin | Function (TE) | Function (NT Mode) +| 1 | Pair A | Pair A +| 2 | Pair A | Pair A +| 3 | not used | not used +| 4 | Pair B | Pair B +| 5 | Pair B | Pair B +| 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! + +==== X1: USB Connector + +The USB connector is a USB Mini B connector. The e1-tracer uses +USB 1.1 full-speed signals. As the e1-tracer is a bus-powered device, +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 e1-tracer) +* Ring: Rx input of PC (Tx output of e1-tracer) +* Shield: GND + +A compatible cable can be sourced from the sysmocom web-shop at +http://shop.sysmocom.de/. + +Note that CP2102 based cables require special programming to support +the baud rate of 1000000 (as opposed to the more standard 921600). + +[[hw-pushbutton]] +=== Bootloader Button + +There is a push-button next to the _USB B connector_. 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, when pressed while power-up, can be used to force booting +into the DFU loader in order to recover from a broken firmware +installation. + + diff --git a/doc/manuals/chapters/e1-tracer/host-software.adoc b/doc/manuals/chapters/e1-tracer/host-software.adoc new file mode 100644 index 0000000..585c4d2 --- /dev/null +++ b/doc/manuals/chapters/e1-tracer/host-software.adoc @@ -0,0 +1,291 @@ +== Host Software + +Host Software is software running on the USB host computer to which the +e1-tracer is attached. + +At the time of this writing, there are two options: + +* legcay tools from the `software/e1-tracer` sub-directory of the `osmo-e1-hardware.git` repository +* `osmo-e1d` + +=== Legacy Software + +The legacy software was the initial software developed for the +e1-tracer. Its purpose was raw trace recording for later offline +analysis. + +The source code of this software can be found in the +`software/e1-tracer` sub-directory of the `osmo-e1-hardware.git` +repository at https://gitea.osmocom.org/retronetworking/osmo-e1-hardware + +==== e1-tracer-record + +The `e1-tracer-record` program is used to create on-disk recordings of the +full E1 interface in both directions. + +You can use `e1-trace-record` to obtain a raw recording using the osmo-e1-tracer. + +Once the program is started, it will open the USB device (via libusb), enable it +and subsequently store all received E1 frames to a file on disk. The disk file format +is a custom format containing chunks of data, each prefixed by a header containing +metadata such as the receive timestamp and the direction of the data. + +The program supports the following command line arguments: + +.Command line arguments of `e1-tracer-record` program +---- + `-o FILE` the name of the output file to which the recording is to be stored. + `-a` append (instead of overwrite) the output file, if it already exists. + `-m` set the PHY into monitor (high-impedance) mode. You should always enable this. + `-r` use SCHED_RR *realtime* scheduling to reduce the likelihood of lost data on overloaded systems +---- + +A typical invocation of the program would look like this: + + `e1-trace-record -o /tmp/my_recording.e1cap -m -r` + +There are some additional low-level tuning parameters (`-n` and `-p`), but you should not need those +under normal operation. + +==== e1cap file format + +The recording file format consists of *chunks* of data. Each chunk contains a number of E1 frames in one +direction of the line. + +The chunk header is prefixed with a 32bit magic value 0xE115600D, followed by two 64bit values as timestamp +(seconds and microseconds), followed by a 16bit length value and an 8 bit USB endpoint number. The USB +endpoint number signifies the direction; it can be either 0x81 or 0x82. + +.Definition of chunk header +---- +struct e1_chunk_hdr { + uint32_t magic; + struct { + uint64_t sec; + uint64_t usec; + } time; + int16_t len; + uint8_t ep; +} __attribute__((packed)); +---- + +After the chunk header is a concatenation of multiple E1 frames, each 32bytes long (one byte for each timeslot +in the frame). + + +=== `osmo-e1d` + +`osmo-e1d` was originally implemented as a host software stack for the +icE1usb E1 USB interface, which is _terminating_ an E1 link and allows +receive and transmit use by external software. + +More recently, `osmo-e1d` and the e1-tracer firmware have been made +compatible. This means that `osmo-e1d` can now be used by applications +to get raw trace data from individual E1 timeslots in real-time using +the same API/interface that was originally designed for icE1usb. + +The e1-tracer appears to `osmo-e1d` as one _interface_ which two +_lines_. Each _line_ represents one direction of the E1 +traffic. + +In theory, `osmo-e1d` should work on any operating system with libusb +support for isochronous transfers. However, official support is limited +to GNU/Linux at this point. + +More information about `osmo-e1d` can be found at its homepage +https://osmocom.org/projects/osmo-e1d/wiki + +==== Example osmo-e1d configuration / start-up + +.Sample config file (pass as `-c /path/to/my/osmo-e1d.cfg` when starting osmo-e1d) +---- +log stderr + logging filter all 1 + logging color 1 + logging print category-hex 0 + logging print category 1 + logging print level 1 + logging timestamp 0 + logging print file 1 last + logging level e1d info + logging level linp info +e1d +---- + +.Sample output of osmo-e1d starting with above config file and one e1-tracer attached to USB +---- +DLGLOBAL NOTICE Available via telnet 127.0.0.1 4269 (telnet_interface.c:100) +DE1D NOTICE No configuration for e1-tracer serial 'dc696c80532f7d34' found, auto-generating it (usb.c:868) +DE1D NOTICE (I0) Created (intf_line.c:184) +DE1D NOTICE (I0:L0) Created (intf_line.c:285) +DE1D NOTICE (I0:L0) Activated (intf_line.c:319) +DE1D NOTICE (I0:L1) Created (intf_line.c:285) +DE1D NOTICE (I0:L1) Activated (intf_line.c:319) +---- + +This means that a single e1-tracer device was found, and that it has been designated *interface 0* with *line 0* and *line 1* within that interface. + +You can introspect the `osmo-e1d` state using its VTY interface: + +.Example VTY output when telnet-ing into the osmo-e1d VTY port 4269 +---- +$ telnet localhost 4269 +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. +Welcome to the osmo-e1d VTY interface + +(C) 2019-2022 by Sylvain Munaut, Harald Welte and contributors +osmo-e1d> show line <1> +Interface #0 (dc696c80532f7d34), Line #0, Mode CHANNELIZED: + TS00: Mode off, FD -1, Peer PID -1 + TS01: Mode off, FD -1, Peer PID -1 + TS02: Mode off, FD -1, Peer PID -1 + TS03: Mode off, FD -1, Peer PID -1 + TS04: Mode off, FD -1, Peer PID -1 + TS05: Mode off, FD -1, Peer PID -1 + TS06: Mode off, FD -1, Peer PID -1 + TS07: Mode off, FD -1, Peer PID -1 + TS08: Mode off, FD -1, Peer PID -1 + TS09: Mode off, FD -1, Peer PID -1 + TS10: Mode off, FD -1, Peer PID -1 + TS11: Mode off, FD -1, Peer PID -1 + TS12: Mode off, FD -1, Peer PID -1 + TS13: Mode off, FD -1, Peer PID -1 + TS14: Mode off, FD -1, Peer PID -1 + TS15: Mode off, FD -1, Peer PID -1 + TS16: Mode off, FD -1, Peer PID -1 + TS17: Mode off, FD -1, Peer PID -1 + TS18: Mode off, FD -1, Peer PID -1 + TS19: Mode off, FD -1, Peer PID -1 + TS20: Mode off, FD -1, Peer PID -1 + TS21: Mode off, FD -1, Peer PID -1 + TS22: Mode off, FD -1, Peer PID -1 + TS23: Mode off, FD -1, Peer PID -1 + TS24: Mode off, FD -1, Peer PID -1 + TS25: Mode off, FD -1, Peer PID -1 + TS26: Mode off, FD -1, Peer PID -1 + TS27: Mode off, FD -1, Peer PID -1 + TS28: Mode off, FD -1, Peer PID -1 + TS29: Mode off, FD -1, Peer PID -1 + TS30: Mode off, FD -1, Peer PID -1 + TS31: Mode off, FD -1, Peer PID -1 + Counters for each line in e1d: + Rx Signal Lost: 0 (0/s 0/m 0/h 0/d) + Rx Alignment Lost: 0 (0/s 0/m 0/h 0/d) + E1 Rx CRC Errors: 0 (0/s 0/m 0/h 0/d) + E1 Rx Overflow: 0 (0/s 0/m 0/h 0/d) + E1 Tx Underflow: 0 (0/s 0/m 0/h 0/d) + Rx Frames Reporting Remote CRC Error: 0 (0/s 0/m 0/h 0/d) + Rx Frames Reporting Remote Alarm: 0 (0/s 0/m 0/h 0/d) + E1 Tx Frames multiplexed: 0 (0/s 0/m 0/h 0/d) + E1 Rx Frames demultiplexed: 143680 (8000/s 142560/m 0/h 0/d) +Interface #0 (dc696c80532f7d34), Line #1, Mode CHANNELIZED: + TS00: Mode off, FD -1, Peer PID -1 + TS01: Mode off, FD -1, Peer PID -1 + TS02: Mode off, FD -1, Peer PID -1 + TS03: Mode off, FD -1, Peer PID -1 + TS04: Mode off, FD -1, Peer PID -1 + TS05: Mode off, FD -1, Peer PID -1 + TS06: Mode off, FD -1, Peer PID -1 + TS07: Mode off, FD -1, Peer PID -1 + TS08: Mode off, FD -1, Peer PID -1 + TS09: Mode off, FD -1, Peer PID -1 + TS10: Mode off, FD -1, Peer PID -1 + TS11: Mode off, FD -1, Peer PID -1 + TS12: Mode off, FD -1, Peer PID -1 + TS13: Mode off, FD -1, Peer PID -1 + TS14: Mode off, FD -1, Peer PID -1 + TS15: Mode off, FD -1, Peer PID -1 + TS16: Mode off, FD -1, Peer PID -1 + TS17: Mode off, FD -1, Peer PID -1 + TS18: Mode off, FD -1, Peer PID -1 + TS19: Mode off, FD -1, Peer PID -1 + TS20: Mode off, FD -1, Peer PID -1 + TS21: Mode off, FD -1, Peer PID -1 + TS22: Mode off, FD -1, Peer PID -1 + TS23: Mode off, FD -1, Peer PID -1 + TS24: Mode off, FD -1, Peer PID -1 + TS25: Mode off, FD -1, Peer PID -1 + TS26: Mode off, FD -1, Peer PID -1 + TS27: Mode off, FD -1, Peer PID -1 + TS28: Mode off, FD -1, Peer PID -1 + TS29: Mode off, FD -1, Peer PID -1 + TS30: Mode off, FD -1, Peer PID -1 + TS31: Mode off, FD -1, Peer PID -1 + Counters for each line in e1d: + Rx Signal Lost: 0 (0/s 0/m 0/h 0/d) + Rx Alignment Lost: 0 (0/s 0/m 0/h 0/d) + E1 Rx CRC Errors: 0 (0/s 0/m 0/h 0/d) + E1 Rx Overflow: 0 (0/s 0/m 0/h 0/d) + E1 Tx Underflow: 0 (0/s 0/m 0/h 0/d) + Rx Frames Reporting Remote CRC Error: 0 (0/s 0/m 0/h 0/d) + Rx Frames Reporting Remote Alarm: 0 (0/s 0/m 0/h 0/d) + E1 Tx Frames multiplexed: 0 (0/s 0/m 0/h 0/d) + E1 Rx Frames demultiplexed: 143648 (8000/s 142560/m 0/h 0/d) +---- +<1> typing `show line` will produce the below output, indicating that all timeslots are currently _off_ and 8000 E1 frames per second are received from both lines (i.e. directions) + +Other applications on the system can not connect to `osmo-e1d` and open individual timeslots either in _RAW_ or in _HDLC-FCS_ mode. + +An example program is included, it is called `osmo-e1d-pipe`. Using this program, you can get a raw output of an individual timeslot. + +.Command line reference of `osmo-e1d-pipe` utility +---- +$ ./osmo-e1d-pipe --help + -h --help This help message + -p --path PATH Path of the osmo-e1d control socket + -i --interface <0-255> E1 Interface Number + -l --line <0-255> E1 Line Number + -t --timeslot <0-31> E1 Timeslot Number + -m --mode (RAW|HDLC-FCS) E1 Timeslot Mode + -f --force Force open of the timeslot (may disconnect other client) + -r --read FILE Read from FILE instead of STDIN +---- + +.Sample output of one direction of a raw B-channel +---- +$./osmo-e1d-pipe -i 0 -l 0 -t 3 -m RAW -r /dev/zero | hexdump -v +0000000 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +0000010 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +0000020 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +0000030 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +0000040 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +0000050 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +0000060 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +0000070 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +0000080 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +0000090 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +00000a0 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 +... +---- + +.Sample output of one direction of a HDLC-FCS D-channel +---- +$ ./osmo-e1d-pipe -i 0 -l 1 -t 16 -m hdlc-fcs -r /dev/zero | hexdump -v +0000000 0102 027f 7f01 0102 027f 7f01 0102 027f +0000010 7f01 0102 027f 7f01 0102 027f 7f01 0102 +0000020 027f 7f01 0102 027f 7f01 0102 027f 7f01 +0000030 0102 027f 7f01 0102 027f 7f01 0102 027f +0000040 7f01 0102 027f 7f01 0102 027f 7f01 0102 +---- + + + +=== Other / 3rd party software + +you can interface 3rd party applications with osmo-e1d in the following +mutually exclusive ways: + +* by adding support for `osmo-e1d`, e.g. via `libosmo-e1d` to the + respective application. This way your application can receive traffic + one a per-timeslot basis. +* by directly implementing the USB protocol exposed by e1-tracer in your + software. This is definitely more effort, as you have to parse the + entire E1 frames, implement software HDLC decoders, etc. - all of + which are already present in `osmo-e1d` +* by post-processing the raw disk recordings generated by the + `e1-trace-recorder` program. + +Should you require any related development/porting services, please do +not hesitate to reach out to sysmocom. diff --git a/doc/manuals/e1-tracer-usermanual-docinfo.xml b/doc/manuals/e1-tracer-usermanual-docinfo.xml new file mode 100644 index 0000000..04cccc7 --- /dev/null +++ b/doc/manuals/e1-tracer-usermanual-docinfo.xml @@ -0,0 +1,46 @@ +<revhistory> + <revision> + <revnumber>1</revnumber> + <date>October 31, 2022</date> + <authorinitials>HW</authorinitials> + <revremark> + Initial user manual version + </revremark> + </revision> +</revhistory> + +<authorgroup> + <author> + <firstname>Harald</firstname> + <surname>Welte</surname> + <email>hwelte@sysmocom.de</email> + <authorinitials>HW</authorinitials> + <affiliation> + <shortaffil>sysmocom</shortaffil> + <orgname>sysmocom - s.f.m.c. GmbH</orgname> + <jobtitle>Managing Director</jobtitle> + </affiliation> + </author> +</authorgroup> + +<copyright> + <year>2020-2022</year> + <holder>sysmocom - s.f.m.c. GmbH</holder> +</copyright> + +<legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, + and no Back-Cover Texts. A copy of the license is included in + the section entitled "GNU Free Documentation License". + </para> + <para> + The Asciidoc source code of this manual can be found at + <ulink url="http://git.osmocom.org/osmo-gsm-manuals/"> + http://git.osmocom.org/osmo-gsm-manuals/ + </ulink> + </para> +</legalnotice> diff --git a/doc/manuals/e1-tracer-usermanual.adoc b/doc/manuals/e1-tracer-usermanual.adoc new file mode 100644 index 0000000..4cea7c1 --- /dev/null +++ b/doc/manuals/e1-tracer-usermanual.adoc @@ -0,0 +1,17 @@ +:gfdl-enabled: + +e1-tracer User Manual +=================== +Harald Welte hwelte@sysmocom.de + +include::./common/chapters/preface.adoc[] + +include::./chapters/e1-tracer/hardware.adoc[] + +include::./chapters/e1-tracer/gateware.adoc[] + +include::./chapters/e1-tracer/firmware.adoc[] + +include::./chapters/e1-tracer/host-software.adoc[] + +include::./common/chapters/gfdl.adoc[] diff --git a/doc/manuals/images/e1-tracer-plate.png b/doc/manuals/images/e1-tracer-plate.png new file mode 100644 index 0000000..dc604d7 --- /dev/null +++ b/doc/manuals/images/e1-tracer-plate.png Binary files differ diff --git a/doc/manuals/images/e1_tracer-bgt-front.jpg b/doc/manuals/images/e1_tracer-bgt-front.jpg new file mode 100644 index 0000000..d1e5179 --- /dev/null +++ b/doc/manuals/images/e1_tracer-bgt-front.jpg Binary files differ diff --git a/doc/manuals/images/e1_tracer-koh1.jpg b/doc/manuals/images/e1_tracer-koh1.jpg new file mode 100644 index 0000000..fe880e8 --- /dev/null +++ b/doc/manuals/images/e1_tracer-koh1.jpg Binary files differ