ntia / sigmf-ns-ntia Goto Github PK

Change reference description in ntia-algorithm segments FrequencyDomainDetection and TimeDomainDetection to

Data reference point, e.g., "signal analyzer input", "preselector input", "antenna terminal".

Knowing what your reference point and direction is useful, especially if both sensor and emitter are moving.

Logging location data in Meta seems potentially problematic... seems like there is a blurred line in what is actual data and what is required information to be included.

Suggest adding the ability to more granularly control the level of security/sensitivity of information in metadata, and the ability to differentiate the security level of (for example) an IQ .sigmf-data file vs. its corresponding .sigmf-meta.

Potential ideas:

• Separate namespace to make machine reading simpler
• classification becomes meta_classification (highest in the file) and only exceptions to it (lower classifications) must be marked, although anything can be marked
• Hierarchical classification, e.g., meta_classification applies to everything and is overruled by classification at the object level
• New data_classification (required) to specify classification of .sigmf-data file
• Add a paragraph at the bottom of the main SigMF-NS-NTIA page that mentions this, once implemented
• Add a simple example in ntia-core section 4

This is a small issue in the grand scheme, but having a preselector/receiver id would be helpful for inventory.

Existing DigitalFilter object in ntia-algorithm could be improved in a few ways. The motivating issues are:

• Global key name anti_aliasing_filter is misleading and does not provide flexibility when annotating the use of a digital filter used for other purposes. Specifically an anti-aliasing filter refers to a filter before the sampling stage in order to satisfy sampling theorem bandwidth limits. We may instead wish to annotate filters used after sampling for other purposes.
• Support only exists for annotating a single digital filter.

I recommend addressing this by the following changes:

• Replace the global key for a digital filter annotation with a renamed key, and changing the type to support a list of DigitalFilter objects:

• Update the DigitalFilter object by adding optional keys, which are useful especially when annotating multiple digital filters: id, description, and supplemental_information. Also add a frequency_passband to provide another option for flexibility when annotating filters.

Accidentally wrote this to the gnuradio. I am so bad at git:(

"It would be nice if we could have a value that linked to further supplemental information in each object. For instance, in the antenna object, if I could provide a directory link or url to the spec sheet or any files that don't necessarily condense down into the SigMF format."

If name is required then we can remove the ambiguity of how to refer to preselector paths and how to interface with the preselector in software. This would simplify the interface to just set_source on the preselector instead of also supporting set_rf_path.

Issue

Signal analyzers have a variety of configurable parameters, depending on their specific hardware and their manufacturer’s design decisions. While many of these parameters are universal, such as a configured center frequency, others only apply to specific analyzers. For instance, some devices allow a configurable attenuation, while others use gain, and others use reference level. Currently, device-specific configuration parameters are left out of SigMF metadata since there is no general metadata field for these values.

Solution

Capture all signal analyzer configuration parameters in metadata by further extending the ntia-sensor SigMF namespace extension.

Classes

To do this, ‘classes’ of signal analyzers are defined, as names for groups of signal analyzers which share the same configuration parameters. For example:

Extension of ntia-sensor's SensorAnnotation

By adding these parameters to the SensorAnnotation, we are able to associate specific samples with specific configured sigan settings. Therefore, if a parameter is adjusted between two parts of the same data set, this is properly and easily tracked using the existing Annotation functionality. A new property is added to ntia-sensor’s SensorAnnotation:

The new property is an instance of a new object, SiganSettings, which has only one required property:

A number of non-required properties are then defined and associated with each class as needed. For example, the tekrsa_usb class would define the following additional properties of SiganSettings:

An example of this in use in a SigMF metadata file, for a measurement recorded with a Tektronix RSA 500A/600A series device:

...
"annotations": [{
  "ntia-core:annotation_type": "SensorAnnotation",
  "core:sample_start": 0,
  "ntia-sensor:sigan_settings": {
    "class": "tekrsa_usb",
    "reference_level": -33.0,
    "iq_bandwidth": 10000000.0,
    "attenuation": 0.0,
    "preamp_enable": true,
    "auto_attenuation_enable": false
  }
}]

This would raise a red flag if we measure signals where classified system operate.

We might also need to raise a flag when IQ data is captured and offered for distro.

In ntia-sensor/Sensor object, change name of element from receiver to signal_analyzer. Also, change name of associated object from Receiver to SignalAnalyzer.

Check each namespaces for missing code examples.

Measurement object should have an rf_path attribute to identify which path was used to make the measurement. The value should be the name of the rf_path that was used.

In the Antenna Object, the vertical and horizontal beamwidth properties are defined as ..._beam_width, implying beamwidth is two words. Beamwidth is one word, and thus is should be ..._beamwidth. This effects the Java object as well.

The ntia-location specification document was last updated in March 2020, when SigMF had only basic support for annotating latitude and longitude.

Upstream SigMF has Improved

SigMF now (v1.0.0) includes better geolocation handling, using GeoJSON which is standardized and commonly supported by software libraries.

The SigMF v1.0.0 specification includes a core:geolocation field which uses a GeoJSON point object to record latitude, longitude, and altitude. GeoJSON forces adherence to: the WGS84 coordinate system, decimal degrees for latitude and longitude, and meters above the WGS84 ellipsoid for altitude. WGS84 is the standard coordinate system for GPS.

GeoJSON objects are, similarly to SigMF itself, extensible per RFC 7946 Section 6.1 by adding "foreign member" fields to the object. The SigMF specification now recommends that location-related extensions make use of this:

Because the SigMF requirement for the geolocation field is to be a valid GeoJSON point Object, users MAY include Foreign Member fields here for user-defined purposes (position valid indication, GNSS SV counts, dillution of precision, accuracy, etc). It is strongly RECOMMENDED that all fields be documented in a SigMF Extension document.

How Does ntia-location Compare to SigMF v1.0.0

• ntia-location provides the following benefits compared to base SigMF:
  • It adds support for mobile recorders/emitters, using the speed and bearing fields of the Location object, and recording units in the CoordinateSystem object.
  • It provides flexibility to use a multitude of coordinate systems (though I am unaware of use cases which motivate use of non-WGS84 coordinate systems).
• ntia-location is a worse solution than base SigMF in the following ways:
  • Allowing multiple coordinate systems creates a need for much more metadata in order to annotate the coordinate system. The majority of the ntia-location specification deals with annotating the use of non-standard coordinate systems or projections. This information requires manual parsing (by a human) prior to post-processing. The diversity of possibilities makes it more difficult to properly integrate ntia-location into automated measurement software.
  • It creates a huge level of complication when most applications would simply record standard GPS coordinates.

What Should Change?

A new definition for ntia-location could supplement use of the base SigMF core:geolocation field for recording location as a GeoJSON point object. In this case, the ntia-location extension would become substantially smaller, easier to use, and better standardized (being more in line with SigMF and GPS standards). From a user standpoint, use of any non-WGS84 coordinate systems would need to be handled outside of the metadata. This approach makes SigMF files using ntia-location much more machine-readable, by removing the necessity for human intervention to interpret the coordinate system.

If there is interest any changes along these lines, I can draft a new ntia-location specification document.

with options for downsampling

Reference point, e.g., "receiver input", "antenna output", "output of isotropic antenna".

This would be a useful diagnostic to track, to get a better sense for the trustworthiness of timestamps and as an indicator of NTP synchronization problems.