From 362cd57d6f95a9fe77d00427407df54f3da41595 Mon Sep 17 00:00:00 2001 From: Teque5 Date: Sun, 14 Apr 2024 11:02:21 -0700 Subject: [PATCH] Changelog, Links, Versioning (#311) * Add CHANGELOG.md * Fix Repository & External Links * Update all example versions to v1.2.0 commensurate w/latest tag. --- CHANGELOG.md | 109 ++++++++++++++++++++++++ CODE_OF_CONDUCT.md | 4 +- README.md | 18 ++-- extensions/adsb.sigmf-ext.md | 4 +- extensions/antenna.sigmf-ext.md | 3 +- extensions/capture_details.sigmf-ext.md | 2 +- extensions/signal.sigmf-ext.md | 4 +- extensions/spatial.sigmf-ext.md | 2 +- extensions/traceability.sigmf-ext.md | 6 +- extensions/wifi.sigmf-ext.md | 4 +- logo/README.md | 4 +- logo/sigmf_logo.sigmf-meta | 2 +- sigmf-spec.md | 62 +++++++------- 13 files changed, 165 insertions(+), 59 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..9443700b --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,109 @@ +# Changelog + +All notable changes will be documented here for easy reference. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added + +- CHANGELOG + +## [1.2.0] - 2024-01-13 + +### Added + +- Core specification + - Optional `uuid` in `annotations` object +- SVG version of logo + +### Changed + +- Clarify optional Extensions +- Spatial extension + - Add range-rate to bearing object + - Add aperture_rotation field + +### Removed + +- Python module moved to separate repository [sigmf-python](https://github.com/sigmf/sigmf-python). + +## [1.1.0] - 2023-01-12 + +### Changed + +- Core specification + - Deprecate tuples in favor of JSON objects + - Clarify rules related to SigMF archives + - Fix table of contents errors + - Application compliance language clarification + +## [1.0.1] - 2022-12-03 + +### Added + +- Specifically point to the [NTIA extensions](https://github.com/NTIA/sigmf-ns-ntia) as good references. +- Spatial extension + +### Changed + +- Core specification + - Add examples + - Clarification of field types + - Conforming / compliant language + +### Removed + +- Undocumented & incomplete RFML extension + +## [1.0.0] - 2022-01-05 + +### Added + +- Core Specification + - Definition of Dataset + - GeoJSON to store locations in `geolocation` field + - New `header_bytes` and `trailing_bytes` field + - New `metadata_only` field + - Define SigMF compliance +- Add Collection Format +- Official logo & example `.sigmf` files +- Extensions + - ADS-B + - Antenna + - Capture Details + - RFML + - Signal + - WiFi +- Code of conduct + +### Changed + +- Core specification rewrite + - Descriptions for all fields + - Inclusion of block diagrams + - Clarification of data types + - Formalize extension definitions & versioning +- Formal license inclusion + +## [0.0.1] - 2018-01-05 + +### Added + +Initial release. + +- Core specification +- Citation information +- CC-BY-SA-4.0 License +- Modulation extension +- Volatile extension + + +[unreleased]: https://github.com/sigmf/SigMF/compare/v1.2.0...HEAD +[1.2.0]: https://github.com/sigmf/SigMF/compare/v1.1.0...v1.2.0 +[1.1.0]: https://github.com/sigmf/SigMF/compare/v1.0.1...v1.1.0 +[1.1.0]: https://github.com/sigmf/SigMF/compare/v1.0.1...v1.1.0 +[1.0.1]: https://github.com/sigmf/SigMF/compare/v0.0.1...v1.0.1 +[0.0.1]: https://github.com/sigmf/SigMF/tree/v0.0.1 \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 1ff88eba..edb2fe51 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,7 +1,6 @@ # Contributor Covenant Code of Conduct -This Code of Conduct is also available [here on the GNU Radio -wiki](https://wiki.gnuradio.org/index.php/Code_of_Conduct). +This Code of Conduct is a mirror of [the GNU Radio governance Code of Conduct](https://github.com/gnuradio/gr-governance/blob/main/CODE_OF_CONDUCT.md). ## Our Pledge @@ -77,4 +76,3 @@ available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.ht For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq - diff --git a/README.md b/README.md index 8a2443f8..eb273ea0 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

Rendered SigMF Logo

+

Rendered SigMF Logo

# Signal Metadata Format (SigMF) @@ -35,7 +35,7 @@ Together these files represent one recording, such as `example.sigmf-data` and "core:sample_rate": 1000000, "core:hw": "PlutoSDR with 915 MHz whip antenna", "core:author": "Art Vandelay", - "core:version": "1.0.0" + "core:version": "1.2.0" }, "captures": [ { @@ -51,19 +51,19 @@ Together these files represent one recording, such as `example.sigmf-data` and There are at least four ways you can use SigMF today, thanks to the community-supported projects: -1. Within **Python**, using the [official SigMF Python package **sigmf**](https://github.com/sigmf/sigmf-python) available from pip: `pip install sigmf` -2. Within **C++** using the [header-only C++ library **libsigmf**](https://github.com/deepsig/libsigmf) maintained by DeepSig -3. Within **GNU Radio** using the [out-of-tree module **gr-sigmf**](https://github.com/skysafe/gr-sigmf) maintained by SkySafe -4. Manually, using our examples and the [spec itself](sigmf-spec.md), even if it's simply editing a text file +1. Within **Python**, using the [official SigMF Python package **sigmf**](https://github.com/sigmf/sigmf-python) available from pip: `pip install sigmf`. +2. Within **C++** using the [header-only C++ library **libsigmf**](https://github.com/sigmf/libsigmf). +3. Within **GNU Radio** using the built-in SigMF [source](https://github.com/gnuradio/gnuradio/blob/main/gr-blocks/grc/blocks_sigmf_source_minimal.block.yml) & [sink](https://github.com/gnuradio/gnuradio/blob/main/gr-blocks/grc/blocks_sigmf_sink_minimal.block.yml) blocks. +4. Manually, using our examples and the [spec itself](sigmf-spec.md), even if it's simply editing a text file. ## Contributing The SigMF standards effort is organized entirely within this Github repository. Questions, suggestions, bug reports, etc., are discussed in [the issue -tracker](https://github.com/gnuradio/SigMF/issues), feel free to create +tracker](https://github.com/sigmf/SigMF/issues), feel free to create a new issue and provide your input, even if it's not a traditional issue. -Changes to the specification only occur through [Pull Requests](https://github.com/gnuradio/SigMF/pulls). +Changes to the specification only occur through [Pull Requests](https://github.com/sigmf/SigMF/pulls). This ensures that the history and background of all discussions and changes are maintained for posterity. There is also a SigMF chat room on [GNU Radio's Matrix chat server](https://wiki.gnuradio.org/index.php/Chat) @@ -76,7 +76,7 @@ discussions, the more useful the standard is likely to be! ## Extensions -The "Core" SigMF standard is intentionally kept limited in scope, additional metadata fields can be added through [SigMF Extensions](https://github.com/gnuradio/SigMF/blob/sigmf-v1.x/sigmf-spec.md#extension-namespaces). For example, the [signal extension](https://github.com/gnuradio/SigMF/blob/sigmf-v1.x/extensions/signal.sigmf-ext.md) provides a standard way to specify modulation schemes and other attributes of wireless comms signals. Several general purpose canonical extensions live within this repository directly in the [extensions directory](https://github.com/gnuradio/SigMF/tree/sigmf-v1.x/extensions), while others are maintained by third parties. Below are some popular sources for SigMF extensions. To have your extension reviewed for inclusion on this list, please open a PR adding the repository to the list below: +The "Core" SigMF standard is intentionally kept limited in scope, additional metadata fields can be added through [SigMF Extensions](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#extension-namespaces). For example, the [signal extension](https://github.com/sigmf/SigMF/blob/main/extensions/signal.sigmf-ext.md) provides a standard way to specify modulation schemes and other attributes of wireless comms signals. Several general purpose canonical extensions live within this repository directly in the [extensions directory](https://github.com/sigmf/SigMF/tree/main/extensions), while others are maintained by third parties. Below are some popular sources for SigMF extensions. To have your extension reviewed for inclusion on this list, please open a PR adding the repository to the list below: * [SigMF's Community Extension Repository](https://github.com/sigmf/community-extensions) * [NTIA's series of extensions](https://github.com/NTIA/sigmf-ns-ntia) diff --git a/extensions/adsb.sigmf-ext.md b/extensions/adsb.sigmf-ext.md index a85f7d2b..388a49a1 100644 --- a/extensions/adsb.sigmf-ext.md +++ b/extensions/adsb.sigmf-ext.md @@ -5,11 +5,11 @@ defines dynamic properties of ADS-B signals extending `annotations`. ## 1 Global -`adsb` does not extend [Global](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#global-object). +`adsb` does not extend [Global](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#global-object). ## 2 Captures -`signal` does not extend [Captures](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#captures-array). +`signal` does not extend [Captures](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#captures-array). ## 3 Annotations diff --git a/extensions/antenna.sigmf-ext.md b/extensions/antenna.sigmf-ext.md index 16fcc428..ce5c1efa 100644 --- a/extensions/antenna.sigmf-ext.md +++ b/extensions/antenna.sigmf-ext.md @@ -30,7 +30,7 @@ The following names are specified in the `antenna` namespace and should be used ## 2 Captures -`antenna` does not extend [Captures](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#captures-array). +`antenna` does not extend [Captures](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#captures-array). ## 3 Annotations @@ -55,4 +55,3 @@ The following fields are specificed in SigMF Collections. ## 5 Examples No `antenna` examples. - diff --git a/extensions/capture_details.sigmf-ext.md b/extensions/capture_details.sigmf-ext.md index 444b119b..f0bbf7ef 100644 --- a/extensions/capture_details.sigmf-ext.md +++ b/extensions/capture_details.sigmf-ext.md @@ -5,7 +5,7 @@ extending `captures` and dynamic IQ capture parameters extending `annotations`. ## 1 Global -`capture_details` does not extend [Global](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#global-object). +`capture_details` does not extend [Global](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#global-object). ## 2 Captures diff --git a/extensions/signal.sigmf-ext.md b/extensions/signal.sigmf-ext.md index b1b9765c..3e087263 100644 --- a/extensions/signal.sigmf-ext.md +++ b/extensions/signal.sigmf-ext.md @@ -6,11 +6,11 @@ the attributes of wireless communications signals and their emitters. ## 1 Global -`signal` does not extend [Global](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#global-object). +`signal` does not extend [Global](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#global-object). ## 2 Captures -`signal` does not extend [Captures](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#captures-array). +`signal` does not extend [Captures](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#captures-array). ## 3 Annotations diff --git a/extensions/spatial.sigmf-ext.md b/extensions/spatial.sigmf-ext.md index fb9179b5..e92b06cc 100644 --- a/extensions/spatial.sigmf-ext.md +++ b/extensions/spatial.sigmf-ext.md @@ -440,7 +440,7 @@ element recording: ```JSON { "collection": { - "core:version": "1.0.0", + "core:version": "1.2.0", "core:extensions" : [ { "name": "spatial", diff --git a/extensions/traceability.sigmf-ext.md b/extensions/traceability.sigmf-ext.md index d3292d25..eb38c25f 100644 --- a/extensions/traceability.sigmf-ext.md +++ b/extensions/traceability.sigmf-ext.md @@ -5,7 +5,7 @@ Format (SigMF) specification. This extension provides traceability information f ## 1 Global -`traceability` extends the [Global](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#global-object) object. +`traceability` extends the [Global](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#global-object) object. The following fields are added to the `global` object: @@ -33,11 +33,11 @@ The following fields are added to the `global` object: ## 2 Captures -`traceability` does not extend the [Captures](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#captures-array) object. +`traceability` does not extend the [Captures](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#captures-array) object. ## 3 Annotations -`traceability` extends the [Annotations](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#annotations-object) object. +`traceability` extends the [Annotations](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#annotations-object) object. The following fields are added to each annotation in the `annotations` array: diff --git a/extensions/wifi.sigmf-ext.md b/extensions/wifi.sigmf-ext.md index 73e67163..10b5c7be 100644 --- a/extensions/wifi.sigmf-ext.md +++ b/extensions/wifi.sigmf-ext.md @@ -5,11 +5,11 @@ The `wifi`namespace extension defines dynamic Wi-Fi burst parameters extending ## 1 Global -`wifi` does not extend [Global](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#global-object). +`wifi` does not extend [Global](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#global-object). ## 2 Captures -`wifi` does not extend [Captures](https://github.com/gnuradio/SigMF/blob/master/sigmf-spec.md#captures-array). +`wifi` does not extend [Captures](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#captures-array). ## 3 Annotations diff --git a/logo/README.md b/logo/README.md index cdeb1f52..3f753ab8 100644 --- a/logo/README.md +++ b/logo/README.md @@ -8,7 +8,7 @@ The intent of these files is to both serve as a nice visual and an exemplar meta ## Additional Versions -[The full logo archive](https://github.com/gnuradio/SigMF/wiki/logo/sigmf_logo_files.zip) contains a variety of versions of the logo for multiple use-cases. +[The full logo archive](https://github.com/sigmf/SigMFwiki/logo/sigmf_logo_files.zip) contains a variety of versions of the logo for multiple use-cases. * `sigmf_logo_fullband` is the unfiltered logo at 192 KHz sample rate. * `logo_*.wav` are audio files for playback without converstion from SigMF. @@ -25,4 +25,4 @@ The SigMF logo was created with the following steps: 0) Initial render in [Blender](https://www.blender.org/) with as simple geometry as possible. The `stl` is a very simplified and tweaked version of the [Eurostile](https://en.wikipedia.org/wiki/Eurostile) font. 1) A timeline was created with [OsciStudio](https://oscilloscopemusic.com/oscistudio.php) with various modulated artifacts over a 6 second period. 2) The lower 48KHz version was then lowpass filtered and adjusted for -14 LUFS in [Audacity](https://www.audacityteam.org/) per the [EBU R 128](https://en.wikipedia.org/wiki/EBU_R_128) loudness spec. -3) Original metadata was added with the [SigMF Python module](https://github.com/gnuradio/SigMF). +3) Original metadata was added with the [SigMF Python module](https://github.com/sigmf/SigMF). diff --git a/logo/sigmf_logo.sigmf-meta b/logo/sigmf_logo.sigmf-meta index e2e7c31a..81d35505 100644 --- a/logo/sigmf_logo.sigmf-meta +++ b/logo/sigmf_logo.sigmf-meta @@ -8,7 +8,7 @@ "core:recorder": "OsciStudio & Audacity", "core:sample_rate": 48000, "core:sha512": "69893900f22de266485031b584c28fc3a0d4f361acd1d623698ed258e616e082d3d398af40d2ce805a804864cb0be631dba060f7410a27c0c2e497becdca53bf", - "core:version": "1.0.0" + "core:version": "1.2.0" }, "captures": [ { diff --git a/sigmf-spec.md b/sigmf-spec.md index ece345c5..61290136 100644 --- a/sigmf-spec.md +++ b/sigmf-spec.md @@ -1,4 +1,4 @@ -# Signal Metadata Format Specification v1.0.0 +# Signal Metadata Format Specification v1.2.0 ## Abstract @@ -20,7 +20,7 @@ Copyright of contributions to SigMF are retained by their original authors. All **Table of Contents** -- [Signal Metadata Format Specification v1.0.0](#signal-metadata-format-specification-v100) +- [Signal Metadata Format Specification v1.2.0](#signal-metadata-format-specification-v100) - [Abstract](#abstract) - [Copyright Notice](#copyright-notice) - [Table of Contents](#table-of-contents) @@ -85,7 +85,7 @@ specified. Fields defined "human/machine-readable" SHOULD be short, simple text strings without whitespace that are easily understood by a human and readily parsed by software. -Specific keywords with semantic meaning in the context of this specification +Specific keywords with semantic meaning in the context of this specification are capitalized after being introduced (e.g., Recording). ## Specification @@ -106,14 +106,14 @@ includes information meant for the human users of the Dataset, such as a title and description, and information meant for computer applications (tools) that operate on the Dataset. -This specification defines a schema for metadata using a `core` namespace that +This specification defines a schema for metadata using a `core` namespace that is a reserved name and can only be defined by this specification. Other metadata -MAY be described by extension namespaces. This specification also defines a +MAY be described by extension namespaces. This specification also defines a model and format for how SigMF data should be stored at-rest (on-disk) using JSON. ### SigMF File Types -There are two fundamental filetypes defined by this specification: files with +There are two fundamental filetypes defined by this specification: files with metadata, and the files that contain the Datasets described by the metadata. There are two types of files containing metadata, a SigMF `Metadata` file, and a SigMF `Collection` file. There are also two types of Datasets, a SigMF `Dataset` @@ -122,10 +122,10 @@ mechanism to support using valid SigMF metadata to describe data that is not valid SigMF and formatted according to SigMF Dataset requirements. The primary unit of SigMF is a SigMF `Recording`, which comprises a Metadata file -and the Dataset file it describes. Collections are an optional feature that are -used to describe the relationships between multiple Recordings. +and the Dataset file it describes. Collections are an optional feature that are +used to describe the relationships between multiple Recordings. -Collections and multiple Recordings can be packaged for easy storage and +Collections and multiple Recordings can be packaged for easy storage and distribution in a SigMF `Archive`. ``` @@ -208,8 +208,8 @@ Rules for SigMF Archive files: ### SigMF Dataset Format -There are four orthogonal characteristics of sample data: complex or real, -floating-point or integer, bit-width, and endianness. The following ABNF +There are four orthogonal characteristics of sample data: complex or real, +floating-point or integer, bit-width, and endianness. The following ABNF rules specify the Dataset formats defined in the Core namespace. Additional Dataset formats MAY be added through extensions. @@ -282,7 +282,7 @@ When stored on-disk (at-rest), these rules apply: segment, then it MUST appear in that segment, even if the value is unchanged relative to the previous segment. -All SigMF metadata is defined using the structural concepts of JSON, and when +All SigMF metadata is defined using the structural concepts of JSON, and when stored on-disk, metadata MUST be proper JSON to be SigMF compliant. #### Datatypes @@ -307,7 +307,7 @@ Namespaces provide a way to further classify key/value pairs in metadata. This specification defines the `core` namespace. Only this specification can add fields to the Core namespace. -The goal of the Core namespace is to capture the foundational metadata +The goal of the Core namespace is to capture the foundational metadata necessary to work with SigMF data. Some keys within the Core namespace are OPTIONAL, and others are REQUIRED. The REQUIRED fields are those that are minimally necessary to parse and process the Dataset, or that have obvious @@ -532,14 +532,14 @@ stream, the entirety of which may not have been captured in a recorded Dataset. If omitted, this value SHOULD be treated as equal to `sample_start`. For example, some hardware devices are capable of 'counting' samples at -the point of data conversion. This sample count is commonly used to indicate +the point of data conversion. This sample count is commonly used to indicate a discontinuity in the datastream between the hardware device and processing. For example, in the below Captures array, there are two Segments describing -samples in a SigMF Dataset file. The first Segment begins at the start of the +samples in a SigMF Dataset file. The first Segment begins at the start of the Dataset file. The second segment begins at sample index 500 relative to the recorded samples (and since this is a conforming SigMF Dataset, is physically -located on-disk at location `sample_start * sizeof(sample)`), but the +located on-disk at location `sample_start * sizeof(sample)`), but the `global_index` reports this was actually sample number 1000 in the original datastream, indicating that 500 samples were lost before they could be recorded. @@ -604,19 +604,19 @@ data capture). If omitted, this value is considered to be zero. If this field is non-zero, the Dataset is by definition a Non-Conforming Dataset. For example, the below Metadata for a Non-Conforming Dataset contains -two segments describing chunks of 8-bit complex samples (2 bytes per sample) -recorded to disk with 4-byte headers that are not valid for +two segments describing chunks of 8-bit complex samples (2 bytes per sample) +recorded to disk with 4-byte headers that are not valid for processing. Thus, to map these two chunks of samples into memory, a reader -application would map the `500 samples` (equal to `1000 bytes`) in the first -Segment, starting at a file offset of `4 bytes`, and then the remainder of the -file through EOF starting at a file offset of `1008 bytes` (equal to the size +application would map the `500 samples` (equal to `1000 bytes`) in the first +Segment, starting at a file offset of `4 bytes`, and then the remainder of the +file through EOF starting at a file offset of `1008 bytes` (equal to the size of the previous Segment of samples plus two headers). ```json { "global": { "core:datatype": "cu8", - "core:version": "1.0.0", + "core:version": "1.2.0", "core:dataset": "non-conforming-dataset-01.dat" }, "captures": [ @@ -643,8 +643,8 @@ Objects. It MUST be sorted by the value of each Annotation Segment's ##### Annotation Segment Objects -Annotation segment Objects contain key/value pairs and MUST contain a -`core:sample_start` key/value pair, which indicates the first index +Annotation segment Objects contain key/value pairs and MUST contain a +`core:sample_start` key/value pair, which indicates the first index at which the rest of the Segment's key/value pairs apply. The following names are specified in the Core namespace for use in Annotation @@ -705,8 +705,8 @@ displaying up to 20 characters. ### SigMF Collection Format -The `sigmf-collection` file contains metadata in a single top-level Object -called a `collection`. The Collection Object contains key/value pairs that +The `sigmf-collection` file contains metadata in a single top-level Object +called a `collection`. The Collection Object contains key/value pairs that describe relationships between SigMF Recordings. The Collection Object associates SigMF Recordings together by specifying @@ -741,7 +741,7 @@ Example `top-level.sigmf-collection` file: ```JSON { "collection": { - "core:version": "1.0.0", + "core:version": "1.2.0", "core:extensions" : [ { "name": "antenna", @@ -791,10 +791,10 @@ permitted in tuples. ## Licensing -Open licenses are RECOMMENDED but you can specify any license. You can refer to -resources provided by the [Open Data Commons](https://opendatacommons.org/) when -deciding which open license fits your needs best. Cornell University has also -created [a guide](https://data.research.cornell.edu/content/intellectual-property#data-licensing) +Open licenses are RECOMMENDED but you can specify any license. You can refer to +resources provided by the [Open Data Commons](https://opendatacommons.org/) when +deciding which open license fits your needs best. Cornell University has also +created [a guide](https://data.research.cornell.edu/content/intellectual-property#data-licensing) to help you make these choices. ## SigMF Compliance