Skip to content

OpenSOD - RFC0002 #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hydratim wants to merge 2 commits into
base: main
Choose a base branch
from
Open

OpenSOD - RFC0002 #1

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9d0bd2c
First draft of RFC0002
hydratim Dec 4, 2024
e2b59ea
Fixes some typos
hydratim Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 208 additions & 0 deletions RFC0002.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,208 @@
# RFC 0002

This document adds support for multi-wavelength and bidirectional traces to be stored in a singular OpenSOD file.

To do this we propose a new version of the General Parameters and Fixed Parameters blocks, provides Implementation Guidelines.


## Table of Contents
1. [Implementation Guidelines](#implementation-guidelines)
2. [Definitions](#definitions)
3. [Data Format](#data-format)
1. [General Parameters](#general-parameters)
2. [Fixed Parameters](#fixed-parameters)
5. [Copyright](#copyright-statement)

# Implementation Guidelines

Files containing multiple wavelengths must detail the nominal frequencies used in the general parameters and must detail the wavelength, pulsewidtch, sample spacing, and number of datapoints for each trace.

# Definitions

Byte order = Little-Endian

`uint16` = A 16-bit long unsigned integer (a.k.a. an `unsigned short`).

`uint32` = A 32-bit long unsigned integer (a.k.a an `unsigned int`).

`int16` = A 16-bit long signed integer (a.k.a a `short`).

`int32` = A 32-bit long signed integer (a.k.a an `int`).

`char[n]` = A fixed-length string of length `n`.

`string` = A NULL (`/0`) terminated string.

`list<T>` = A list of objects of type `T`.

# Data Format

## General Parameters

`Name = GenParams`

`Ver = 1002`

### Changes
1. We redefined the `uint16` `WaL (Wavelength)` value as `NWa (Number of Wavelengths)`
2. We added a new field `WaveLngts (Wavelengths)` which is a `list<uint16>` of length `NWa` defining the nominal wavelengths present in the file

### Data Structure

The General Parameters block contains all the information about the fibre under test.

```
|--/---/--|-+-|--/---/--|--/---/--|-+-|-+-|--/---/--|--/---/--|--/---/--|
|Name |Lng|CableId |FibreId |Typ|NWa|WaveLngts|LocationA|LocationB|
|--/---/--|-+-|-+-+-+-|-+-+-+-|--/---/--|--/---/--|-+-+-+-+-+-+-+-+-+-+-|
|CableCode|BuC|Offset |OffDist|Operator |Comments |
|-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
```

The `Name` field is a `string` that matches the block name `GenParams`.

The `Lng` field is a `char[2]` that contains an ISO 639 Set 1 Country Code.

The `CableId` field is a `string` set by the user. It is normally used to indicate the patch panel ID at the test location.

The `FibreId` field is a `string` set by the user. It is normally used to indicate the patch panel port number at the test location.

The `Typ` field is a `uint16` containing the ITU-T G.xxx classification of the fibre under test (e.g. 657 for ITU-T G.657).

The `NWa` field is a `uint16` specifying how many nominal wavelengths are present in the file.

The `WaveLngts` field is a `list<uint16>` containing the array of nominal wavelengths present in the file (e.g. 1310nm, 1550nm, 1625nm).

The `LocationA` field is a `string` set by the user. Most technicians leave this as the default (or blank), but some use it for the coordinates or the address of the A-side.

The `LocationB` field is a `string` set by the user. Most technicians leave this as the default (or blank), but some use it for the coordinates or the address of the B-side.

The `CableCode` field is a `string` whose use varies per vendor; some have it as a user-settable string, whereas others have it as the plaintext ITU-T G.xxx code of the fibre (e.g. ITU-T G.657).

The `BC` field is a `char[2]` that contains the Built Condition. We believe the common codes used here are:

`BC`: as-built / Build Condition,
`CC`: as-current / Current Condition / Pre-Work,
`RC`: as-repaired / Repaired Condition / Post-Work,
`NC`: as-new / New Condition / Post-Work,
`OT`: other.

The `Offset` field is a `uint32`, defining the length of the launch lead fibre measured in the units defined in the fixed parameters block as a fixed-point decimal with an exponent of 10^1.

The `OffDist` field is a `uint32`, the same as above, but as an integer dropping any decimal values.

The `Operator` field is a `string` set by the user. It is intended to be used for the Technician’s Name and/or Employee ID - This is normally configured once during device allocation.

The `Comments` field is a `string` set by the user. It is normally blank but is intended for the technician to write their notes in.

## Fixed Parameters

`Name = FxdParams`

`Ver = 1002`

### Changes
1. We removed the `WaL` field
2. We removed the `IoR` field
3. We removed the `PulseWidth` array
4. We removed the `SampleSpacing` array
5. We removed the `NumbperOfDataPointsInTrace` array
6. We removed the `AcOffsD` field as it was redundant (can be calculated from the `AcOffs` field)
7. We removed the `AcRangD` field as it was redundant (can be calculated from the `AcRange` field)
8. We reordered the `fxdparams` data structure into logical groupings:
* Global Settings (`TrT`, `AcOffs`, `AcRange`),
* Calculation Settings (`AvT`, `BsC`, `NFL`, `NFS`, `POf`, `LoT`, `ReT`, `EoT`, `FntPnlO`),
* Trace Headers (`Ntr`, `TraceHeaders`),
* Default Viewing Window (`X1`, `Y1`, `X2`, `Y2`)
9. We redefined the `TimeStp` field to be a `uint64` to prevent the overflow in 2038
9. We defined the `TraceHeader` object that defines the Wavelength, IoR, Pulse Width, Sample Spacing, and Number of Data Points of a trace contained in the Data Points block
10. We added the `TraceHeadersArr` field, which is a `list<TraceHeader>` that matches the order of traces in the Data Points block
11. We added the `BI` type to the `TrT` enum

### Data Structures

The Fixed Parameters block contains the configuration used for the specific test.

```
Fixed Params
|1 1 1 1 1 1 1 1|1 1|2 2 2 2|2 2 2 2|2 2 3 3
0 1 2 3 4 5 6 7 8 9|0 1 2 3 4 5 6 7|8 9|0 1 2 3|4 5 6 7|8 9 0 1
|--/-------------/--|-+-+-+-+-+-+-+-|-+-|-+-+-+-|-+-+-+-|-+-+-+-|
|Name |TimeStp |TrT|AcOffs |AcRange|NumAvgs|
|-+-|-+-|-+-|-+-|-+-|-+-|-+-|-+-|-+-+-+-|-+-|--/-------------/--|
|AvT|BsC|NFL|NFS|POf|LoT|ReT|EoT|FntPnlO|NTr| TraceHeadersArr |
|-+-+-+-|-+-+-+-|-+-|-+-|-+-|-+-|-+-|-+-|-+-+-+-|-+-+-+-|-+-+-+-|
|X1 |Y1 | X2 |Y2 |
|-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
```

The `Name` field is a `string` that matches the block name `FxdParams`.

The `TimeStp` field is a `uint64` that contains the time the test was done represented as the number of seconds since the Unix Epoch.

The `TrT` field is a `char[2]` that defines the type of trace. The codes used are:

`ST`: Standard/Forward Trace
`RT`: Reverse Trace
`DT`: Difference Trace
`RF`: Reference Trace
`BI`: Bidirectional Trace

The `AcOffs` field is an `int32` that defines the Acquisition Offset in nanoseconds as a fixed-point decimal with an exponent of 10^4 . I.E., how much of the data was ignored due to launch blindness (the period of time during which the detector is blind after the pulse is sent/launched).

The `AcRange` field is a `uint32` that stores the acquisition range in **μs** as a fixed-point decimal with an exponent of 10^4. I.E., how long the data was captured for.

The `NumAvgs` field is a `uint32` that varies in use per vendor. In most cases, it represents the number of samples used in averages.

The `AvT` field is a `uint16` that stores the sample time used to calculate averages.

The `BsC` field is a `uint16`, which is either detected or user-configured. It records the Backscattering Coefficient of the fibre under test.

The `NFL` field is a `uint16` that stores the detected (or calibrated) noise floor, the lowest power level below which the 98th percentile of the signal noise is found.

The `NFS` field is a `uint16` that stores the detected (or calibrated) noise floor scaling factor.

The `POf` field is a `uint16` that stores the Power Offset / Attenuation used by some devices.

The `LoT` field is a `uint16` that stores the Loss Threshold (in dB as a fixed-point decimal with an exponent of 10^3) used to identify splice/non-reflective loss events to be stored in the Key Events block.

The `ReT` field is a `uint16` that stores the Reflection Threshold (in dB as a fixed-point decimal with an exponent of 10^3) used to identify coupling/fracture/reflective events to be stored in the Key Events block.

The `EoT` field is a `uint16` that stores the End of Transmission Threshold (in dB as a fixed-point decimal with an exponent of 10^3), which is used to identify the Launch and End of the Fibre events that will be stored in the Key Events block.

The `FntPnlO` field is an `int32` that stores the Front Panel Offset used by some implementations.

The `NTr` field is a `uint16` that defines the number of traces present in the file.

The `TraceHeadersArr` field is an ordered `list<TraceHeader>` (defined below) that records the specific settings used for the Traces present in the Data Points block.

Following this are four `int32` fields, `X1`, `Y1`, `X2`, and `Y2`, that define a default viewing window used by some implementations.

#### TraceHeader
The `TraceHeader` structure, used in the `TraceHeadersArr` array, provides a simple way to document the settings used for each of the traces in the Data Points block.


```
TraceHeader
1 1 1 1 1 1 1 1
0 1|2 3 4 5|6 7|8 9 0 1|2 3 4 5|6 7|
|-+-|-+-+-+-|-+-|-+-+-+-|-+-+-+-|-+-|
|WaL|IoR |PlW|SmplSpc|NumDPts|Dir|
|-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
```

The `WaL` field is a `uint16`, defines the calibrated wavelength (in **nm**) used by the module for the test. The wavelength is represented as a fixed-point decimal with an exponent of 10^1. This should aproximately aline with one of the wavelengths listed in the **General Parameters**.

The `IoR` field is a `uint32`, which is either detected or user-configured. It records the Index of Refraction of the fibre under test (either detected or user-configured) as a fixed-point decimal with an exponent of 10^5. To convert this back to its decimal format, use the following formula `float ior_f = ior_i / 100000.0`. If it’s unset, then a safe default IoR is around 1.46800 (the nominal IoR of G.652 @ 1550nm).

The `PlW` field is a `uint16` containing the pulse width (in nanoseconds) used the trace.

The `SmplSpc`field is a `uint32` containing the sample spacing (time taken to acquire 10,000 points) used for the trace, as a fixed-point decimal with an exponent of 10^3.

The `NumDPts` field is a `uint32` containing the number of data points in the trace.

The `Dir` field is a `uint16` that is treated as a boolean indicating the direction of the trace where `0` is to be interpreted as A->B (AKA a forward trace) and `1` is to be interpreted as B->A (AKA a reverse trace). If the `TrT` field of the Fixed Parammeters block is any value other than `BI` (i.e `FxdParams.TrT != "BI"`) this field MUST equal `0` (even if the `FxdParams.TrT == "RT"`).


# Copyright Statement
Copyright 2024 BaldrAI Ltd.