Time handling fallback behavior in sigmf-record is broken

[devnulling]

The SigMF Sink block in GRC supports setting the Time Handling Mode to either Relative or Absolute.

It would be nice to have this option extended into the sigmf-record utility.

[storborg]

This is kind of supported right now, but the behavior is implicit based on the available clock and time sources. We could use your help on figuring out the best way to handle and explain this behavior.

At the moment, the way it's supposed to work (this could be buggy, it's not thoroughly tested) is like this:

• sigmf-record will try to see if a GPSDO is available. If so, it will see if the GPS receiver has a fix, and try to synchronize the USRP time to GPS time, using the set_time_next_pps dance. Passing the --skip-gps flag will bypass this behavior and make sigmf-record act as if the USRP does not have a GPS receiver.
• If time sync is successful, the SigMF Sink will use Absolute time handling mode. Capture segments in the resulting dataset should then be GPS-synchronized to within a sample.
• If time sync is unsuccessful, the SigMF Sink will use Relative time handling mode, thus using the host PC time for capture segment timestamping. Obviously, the time alignment within the resulting dataset is now much, much worse than one sample.

Some of the shortcomings of the current behavior, as I see them:

• The produced dataset doesn't have a mechanism to note whether the GPS time was actually used, so you don't really know the timing accuracy of a given dataset.
• It's not possible to require certain behavior, which it hard to accomplish strict methodologies. E.g. you can't say "if GPS time alignment is not successful, fail."
• This is more a problem with the SigMF Sink block in general and not sigmf-record specifically: it's difficult to explain the exact semantics of Relative of Absolute modes.

[devnulling]

The desired behavior to fall back to a host time stamp seems to be buggy.

Tested with a B210 with no GPSDO, with some of the output truncated for readability:

$ sigmf-record -f 100e6 -g 0 --antenna RX2 -s 1e6 test1

Creating the usrp device with: ...
[INFO] [UHD] linux; GNU C++ version 7.3.0; Boost_106501; UHD_3.14.0.HEAD-0-g6875d061
...
[INFO] [B200] Detected Device: B210
...
[INFO] [B200] Detecting internal GPSDO.... 
[INFO] [GPS] No GPSDO found
...
[INFO] [B200] Asking for clock rate 16.000000 MHz... 
[INFO] [B200] Actually got clock rate 16.000000 MHz.
Setting RX Rate: 1.000000 MSps...
[INFO] [B200] Asking for clock rate 32.000000 MHz... 
[INFO] [B200] Actually got clock rate 32.000000 MHz.
Actual RX Rate: 1.000000 MSps...

Setting RX Freq: 100.000000 MHz...
Actual RX Freq: 100.000000 MHz...

Setting RX Gain: 0.000000 dB...
Actual RX Gain: 0.000000 dB...

Setting antenna to: RX2

Looking for GPS sensor...
No GPS sensor found, skipping GPS time sync.

Writing SigMF recording to:
  Samples: test1.sigmf-data
  Metadata: test1.sigmf-meta

Press Ctrl + C to stop streaming...
WARNING: USRP does not appear to have a GPS receiver, skipping GPS messages.
INFO: No core:datetime found, using host ts instead
^C

$ cat test1.sigmf-meta 
{
    "global": {
        "core:sample_rate": 1000000.0,
        "core:hw": "Ettus B210 / mboard_name:  / mboard_serial: F5EAB4 / rx_subdev_name: FE-RX2 / rx_subdev_spec: A:A A:B / rx_antenna: RX2 / rx_serial:  / rx_id: Unknown (0xffff)",
        "core:recorder": "sigmf_record",
        "core:license": "",
        "core:author": "",
        "core:description": "",
        "core:version": "0.0.2",
        "core:datatype": "ci16_le"
    },
    "captures": [
        {
            "core:sample_start": 0,
            "core:frequency": 100000000.0,
            "core:datetime": "1970-01-01T00:00:01.66469296874999995Z",
            "uhd:rx_gain": 0.0
        }
    ],
    "annotations": []
}

Using --skip-gps will also result in the unix epoch being used and not host time.

Some ideas:

• Having the time source filed explicitly set (via a new parameter) could be useful if using a setup that includes an octoclock. Some logic would need to be added to use the octoclock for a time reference though.
• expand the sigmf spec to include a time reference field? or perhaps this could be added in the annotations...

[storborg]

Yeah, that's definitely a bug, thanks. FWIW we've mostly tested with X310s, although it's possible it's just broken for all devices.

@pwicks86 and I have discussed the possibility of a time reference field, but haven't come to conclusions on what sort of structure it should have. It doesn't seem like it should be an annotation since it can't change within a given capture segment (and possibly couldn't change within a given file). Maybe it makes sense to just have a SigMF namespace specifically for gr-sigmf keys.

Another thought was just to include that in the core:hw field as "GPSDO: Jackson Labs LC_XO Synced" or similar.

Agreed that we should make it work with an octoclock. I think that should be similar in functionality to how it works with an X310 and a GPSDO, with the exception that the NMEA sentence needs to be read from the octoclock instead of the mboard on the usrp device. Here's a loose proposal for how that could work:

• Specify an octoclock addr like sigmf-record --octoclock-addr 192.168.123.45
• If an octoclock is specified, assume that all configured USRPs are being driven by the reference clock and PPS of that octoclock.
• Query the octoclock to get an NMEA sentence and parse it. If the octoclock has a GPSDO with a fix, synchronize all USRP clocks to that timestamp and set the SigMF Sink to absolute mode.
• Otherwise, set the SigMF Sink to relative mode.
• Include the Octoclock S/N in the core:hw string.