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