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