otdrs

otdrs 是一个 SOR 文件解析器和生成器的 Rust 实现。SOR 文件用作光学时间域反射仪（OTDR）测试的存储格式，OTDR 测试通常用于表征和验证光纤网络的正确构造。SOR 正式称为 Bellcore OTDR 交换格式，由 Telcordia SR-4731 专用标准指定。OTDR 测试涉及在测试光纤中发射短光脉冲，并测量随时间返回的光的强度。

otdrs 的目的是作为一个最小但有效且健壮的解析器实现，以便将封闭的二进制格式转换为开放、自文档格式，以允许轻松开发分析工具，而无需处理管理广泛未记录且难以解析的二进制格式的复杂性。它还提供了 OTDR 文件的 Rust 原语和一个写入器，允许加载、修改和写回文件。

尽可能保持输入格式；otdrs 不试图修复特定测试设备或后处理软件的异常性，或解决它们输入中的怪癖，除非它们会破坏格式的解析。不尝试进行标准化。

当解析器无法可靠地提取信息时，将省略这些信息；在这个意义上，otdrs 是一个尽力而为的解析器。

文件写入尽可能谨慎，并计算可选的校验和块。生成的文件在多个专业应用程序中打开时没有问题，并且专有数据无损失地保留。

选择 Rust 是因为它具有健壮性、类型安全和出色的 nom 解析器库。使用 serde 进行输出序列化。

用法

otdrs 接受一个位置参数，即 SOR 文件的路径。它的输出是一个包含 SOR 文件内信息的单一 JSON 或 CBOR 块；使用标志来设置输出路径（默认为 stdout）或输出格式。使用 otdrs --help 可以显示可用选项。

后处理示例可以在本仓库中的 demo.py 脚本中找到，它将绘制 OTDR 文件中的数据。

安装

如果您已安装 Rust/Cargo，可以使用 cargo install otdrs 安装 otdrs。目前 otdrs 没有其他打包。

库使用

您可以将 otdrs 作为 Rust 库来读取、修改和写入 SOR 文件。例如，以下最小化程序将修改文件的纤芯 ID 和电缆 ID，并将文件的标称波长打印到终端。

use otdrs::parser::parse_file;
use std::fs::File;
use std::io::prelude::*;
fn main() -> std::io::Result<()>  {
    // Read the file into memory
    let mut in_file = File::open("input.sor")?;
    let mut in_data = Vec::new();
    in_file.read_to_end(&mut in_data)?;
    // Parse the file
    let mut sor = parse_file(&in_data).unwrap().1;
    // Most blocks are Options because the parser can't guarantee them
    // This is true even of "required" blocks in the spec, because otdrs is permissive.
    match sor.general_parameters.as_mut() {
        Some(mut gp) => {
            // If we've got a block we can read and modify it!
            println!("Nominal wavelength of this SOR record: {:?}", gp.nominal_wavelength);
            gp.fiber_id = "Hello world";
            gp.cable_id = "Foo bar";
            // Note that we don't check the values you write a valid, outside of type enforcement
            // Even then you need to be careful to adhere to the spec. e.g. no UTF-8 glyphs
            // No emojis in your comments field 😭😭😭
        }
        None => {
            println!("Your SOR file has no General Parameters block!")
        }
    }
    // Encode the SORFile structure to a binary SOR file again...
    // Note you'd normally want to handle errors properly here, but we're an example, so...
    let bytes_to_write = sor.to_bytes().unwrap();
    // Write the file out to disk!
    let mut out_file = File::create("output.sor").unwrap();
    out_file.write_all(&bytes_to_write)?;
    return Ok(());
}

代码质量、合规性/一致性

这是作者的第一个主要 Rust 项目，因此请谨慎使用。

这绝对不能保证在所有情况下都能与所有文件一起工作，或产生正确的输出（或确实任何）。如果您关心所做的事情，请使用您正在使用的文件和一个已知良好的查看器检查输出。

安全注意事项

由于 otdrs 处理任意二进制输入并在其上进行一些可能引起未定义行为的算术运算，因此它可能存在未定义行为。

虽然 Rust 是编写此类工具的非常好的语言，因为运行时错误（如此类错误）被处理，但 otdrs 尽力避免明显的违规情况，例如切片指针越界，或者对 SOR 内容的算术运算可能导致意外情况。使用 cargo-fuzz（目前仅限于 Linux）和 libFuzzer 进行模糊测试以发现可能发生此类情况的场景，包括通过写入和来回传递 OTDR 文件。

未对所有字段进行检查结果的有效性，因此工具的使用者应小心，不要信任从 SOR 文件解析的输入。净化您的输入。

已知问题

• 由于作者没有包含它的测试文件，因此当前未解码“链路参数”块。这在常见的 OTDR 集中未使用。
• 测试不如应该的全面和广泛，尤其是在写入文件时。

没有应用 SR-4731 中描述的固定缩放因子。这通常是故意的，以允许在其他应用程序中根据需要正确后处理。

专有块

尽管 SOR 文件是标准化的，但并非所有内容都是；有一组标准且必需的块用于基本信息，而 otdrs 仅尝试解析 SOR 文件中的标准块。

专有块的内容将被转储以供上游工具分析，这些工具可能了解专有格式或希望简单地了解此类块的存在。在所有情况下，映射块都将列出文件中的所有块。

写入 SOR

otdrs 对从 Rust 数据结构生成 SOR 具有实验性支持。严格来说，当写入时，映射块会被大量重新计算；所有块都期望有带有修订号和头的 BlockInfo 块，但大小和计数是动态生成的。这是因为在实际序列化数据之前计算大小几乎是不可能的（或者至少是非常困难的），因此最好在写入时完成。

编辑者负责确保文件中任何其他数据修改都是有意义的，例如，如果 DataPointsAtScaleFactor 结构中的点数已更改，则编辑者必须修改 n_points 字段；otdrs 不会为您做这件事。

目前，地标和 LinkParameters 没有被写入，因为这些在实际中很少使用，目前没有可用于测试的示例数据。

测试

解析器已在以下生成的 SOR 文件上进行过测试：

• Noyes OFL280 OTDRs，包括从 EXFO FastReporter3 重新导出的文件
• Anritsu Access Master OTDRs
• EXFO MaxTester 730C 和 FTB-4/FTBx730 OTDRs
• 从 EXFO FastReporter3 导出到 SOR 的 EXFO iOLM 文件
• 在集中式 PON 测试部署中的 EXFO 735C-SM7R 模块（通过分路器向高反射性设备发射）

往返测试也确认，上述所有文件都可以由 otdrs 读取和写入，数据无损失或更改。

希望有更多测试文件，应提交给作者或作为包含对已知值测试的 pull request。

解释

要正确解释任何这些数据，你可能需要阅读 SR-4731，可以在以下网址找到：[SR-4731](https://telecom-info.telcordia.com/site-cgi/ido/docs.cgi?ID=SEARCH&DOCUMENT=SR-4731&)，约需 750 美元。

此解析器不试图正确解释 SOR 文件格式生成的数据，而只是使其可供应用程序进行正确解释。根据 OTDR 数据定位事件和测量电缆数据需要仔细考虑数据偏移（例如，前面板到用户偏移，缩放因子等）。

供应商怪癖

与几乎所有标准一样，每个供应商都有不同的解释。例如，一些 Noyes OTDRs 将 30 秒的平均周期存储为 3000，而 EXFO 和 Anritsu 记录为 30。当然，规范规定应存储为 300。