otdrs is a Rust implementation of a SOR file (Bellcore OTDR interchange format, specified in Telcordia SR-4731) parser.
It is intended as an absolute minimal parser implementation to produce a translation from the binary format to open, self-documenting formats, to permit easy development of analysis tools without having to deal with the complexities of managing a binary format that is broadly undocumented and difficult to parse.
Wherever possible, translation preserves the input format; otdrs does not try to fix peculiarities of particular test equipment or post-processing software or work around quirks in their input, except where they would break parsing of the format. No normalisation is attempted.
Where the parser cannot reliably extract information it is omitted; in this sense, otdrs is a best-effort parser.
Rust was chosen for its robustness, type-safety, and the excellent nom parser library. serde is used for serialisation for output.
otdrs takes one positional argument, the path to a SOR file. Its output is a single JSON or CBOR blob which contains the information within the SOR file; flags are used to set the output path (default is stdout) or the format to output. otdrs --help shows the available options.
If you have Rust/Cargo installed you can install otdrs with cargo install otdrs. otdrs is not otherwise packaged currently.
This is the author's first major Rust project, so use with caution.
This is absolutely not guaranteed to work in all cases with all files or produce correct output in all cases (or indeed any). Check the output with the files you're using and a known-good viewer if you care about what you're doing.
As otdrs handles arbitrary binary input and performs some arithmetic on it which can potentially lead to underruns and overruns as well as exciting undefined behaviour.
While Rust is a very good language to write such tools in, since runtime errors such as this are handled, otdrs makes an effort to avoid obvious situations where slice pointers violate bounds or where arithmetic on SOR contents may lead to unexpected situations. cargo-fuzz is used to fuzz with libFuzzer (on Linux only at present) to discover scenarios in which this can occur.
Checking of result validity is not performed on all fields, and users of the tool should take care to avoid trusting input parsed from SOR files. Sanitise your inputs.
There is no application of fixed scaling factors described in SR-4731. This is generally intentional, to permit correct post-processing as required in other applications.
While SOR files are standardised, not all of the content is; there are a set of standard and required blocks for the basic information, and otdrs only attempts to parse the standard blocks in a SOR file.
The content of proprietary blocks is dumped for analysis by upstream tools that may either have knowledge of proprietary formats or wish to simply know of the existence of such blocks. The map block will in all cases list all blocks within the file.
The parser has been tested on SOR files generated from:
Further test files are desired and should be submitted to the author or as a pull request with tests against known values.
To actually interpet any of this data correctly you are going to need to read SR-4731, which can be found here for around $750.
This parser makes no attempt to correctly interpret the resulting data from the SOR file format, merely to make it accessible for applications to perform correct interpretation. Actually locating events and measuring cable data based on OTDR data requires careful consideration of data offsets (e.g. front panel to user offset, scaling factors, etc).
As with pretty much every standard out there, every vendor has interpreted it differently. For one example, some Noyes OTDRs store a 30 second averaging period as 3000 whereas EXFO and Anritsu record it as 30. The specification, of course, says this should be stored as 300. Professional software struggles with this - for instance, EXFO's FastReporter3 software misinterprets the Noyes result.
Documentation of storage quirks compared to "standard" behaviour such as the above, against known behaviour would be helpful for those developing post-processing software; if you have access to test equipment, you can helpfully run a controlled test, write down the actual values displayed by the tester etc and store the SOR file directly.
While "fixing" vendor quirks to generate a standards-compliant output is not currently in the scope of otdrs, this is something that could be added as an optional post-processing step.
GPLv3 has been selected specifically to drive improved open source engagement with equipment manufacturers and developers of OTDR processing software in an industry that has struggled with open data exchange, proprietary (and vendor-locked) software, and poor maintenance of existing software.
otdrs - a SOR file parsing tool Copyright (C) 2020 James Harrison
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.