docs: Update documentation

This commit updates the documentation of all relevant blocks. Further, the copyright information is updated as well. Finally, some unused, untested blocks are removed. Signed-off-by: Johannes Demel <[email protected]>
jdemel · May 3, 2022 · c2e66bf · c2e66bf
1 parent 9704818
commit c2e66bf
Show file tree

Hide file tree

Showing 35 changed files with 178 additions and 631 deletions.
diff --git a/.github/workflows/check-formatting.yml b/.github/workflows/check-formatting.yml
@@ -1,12 +1,6 @@
 name: Check Formatting
 
-on:
-  push:
-    paths-ignore:
-      - 'swig/'
-  pull_request:
-    paths-ignore:
-      - 'swig/'
+on: [push, pull_request]
 
 jobs:
   check-cpp-formatting:
@@ -27,4 +21,4 @@ jobs:
     - uses: actions/[email protected]
     - uses: quentinguidee/pep8-action@v1
       with:
-        arguments: '--max-line-length=120 --ignore E203,E265,E266,E402,E501,E704,E712,E713,E714,E711,E722,E741,W503,W504,W605 --exclude *.yml.py'
+        arguments: '--max-line-length=120 --ignore E203,E265,E266,E402,E501,E704,E712,E713,E714,E711,E722,E741,W503,W504,W605 --exclude *.yml.py'
diff --git a/MANIFEST.md b/MANIFEST.md
@@ -11,7 +11,7 @@ copyright_owner:
   - Leonard Göhrs
   - Johannes Demel
 license: GPLv3
-gr_supported_version: 3.8, 3.9
+gr_supported_version: 3.8, 3.9, 3.10
 repo: https://github.com/jdemel/XFDMSync
 #website: <module_website> # If you have a separate project website, put it here
 #icon: <icon_url> # Put a URL to a square image here that will be used as an icon on CGRAN

diff --git a/docs/doxygen/Doxyfile.in b/docs/doxygen/Doxyfile.in
@@ -28,19 +28,19 @@ DOXYFILE_ENCODING      = UTF-8
 # identify the project. Note that if you do not use Doxywizard you need
 # to put quotes around the project name if it contains spaces.
 
-PROJECT_NAME           = "GNU Radio's XFDM_SYNC Package"
+PROJECT_NAME           = "XFDMSync"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number.
 # This could be handy for archiving the generated documentation or
 # if some version control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = 1.0.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer
 # a quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = "Optimized preamble-based multicarrier synchronization blocks for GNU Radio."
 
 # With the PROJECT_LOGO tag one can specify an logo or icon that is
 # included in the documentation. The maximum height of the logo should not

diff --git a/docs/doxygen/other/main_page.dox b/docs/doxygen/other/main_page.dox
@@ -1,10 +1,46 @@
 /*! \mainpage
 
-Welcome to the GNU Radio XFDM_SYNC Block
+# Introduction
 
-This is the intro page for the Doxygen manual generated for the XFDM_SYNC
-block (docs/doxygen/other/main_page.dox). Edit it to add more detailed
-documentation about the new GNU Radio modules contained in this
-project.
+The XFDMSync [GNU Radio OOT module](https://wiki.gnuradio.org/index.php/OutOfTreeModules) provides optimized blocks for multicarrier synchronization.
+During development, the main targets for multicarrier systems are [OFDM](https://en.wikipedia.org/wiki/Orthogonal_frequency-division_multiplexing) and [GFDM](https://en.wikipedia.org/wiki/Non-orthogonal_frequency-division_multiplexing#Generalized_frequency_division_multiplexing_(GFDM)).
+Algorithmically, the module relies on an improved Schmidl&Cox algorithm according to Awoseyila.
+
+This module provides optimized blocks to compute preamble-based synchronization and stream synchronization for multiple antenna setups.
+
+## Usage
+
+After installation, the module can be imported like any other GNU Radio OOT module with
+\code
+    import xfdm_sync
+\endcode
+
+See the Doxygen documentation for details about the blocks available
+in this package.
+
+A quick listing of the details can be found in Python after importing
+by using:
+
+\code
+    help(xfdm_sync)
+\endcode
+
+## Blocks
+
+This OOT module provides the following blocks
+
+- Frame gate gr::xfdm_sync::frame_gate
+- Multi port synchronization: A hierachical Python block for multiple antenna stream synchronization.
+- Schmidl and Cox correlator gr::xfdm_sync::sc_delay_corr
+- Schmidl and Cox tagger gr::xfdm_sync::sc_tagger
+- Synchronization: A hierachical Python block for one antenna stream synchronization.
+- Tag align gr::xfdm_sync::sync_tag_align_cc
+- Cross-correlation tagger gr::xfdm_sync::xcorr_tagger
+
+## References
+
+* Awoseyila A, Kasparis C, Evans B: [Improved preamble-aided timing estimation for OFDM systems](https://ieeexplore.ieee.org/document/4717982). IEEE Commun. Lett 2008, 12(11):825-827, [DOI: 10.1109/LCOMM.2008.081054](https://doi.org/10.1109/LCOMM.2008.081054)
+
+* Gaspar, I.S., Mendes, L.L., Michailow, N. et al. [A synchronization technique for generalized frequency division multiplexing](https://doi.org/10.1186/1687-6180-2014-67). EURASIP J. Adv. Signal Process. (2014) 2014: 67. [DOI: 10.1186/1687-6180-2014-67](https://doi.org/10.1186/1687-6180-2014-67)
 
 */
diff --git a/examples/.gitignore b/examples/.gitignore
@@ -1 +1,2 @@
 *.py
+*.svg
diff --git a/grc/xfdm_sync_burstsilence_corr.block.yml b/grc/xfdm_sync_burstsilence_corr.block.yml
diff --git a/grc/xfdm_sync_fqsweep_corr.block.yml b/grc/xfdm_sync_fqsweep_corr.block.yml
diff --git a/include/xfdm_sync/sc_delay_corr.h b/include/xfdm_sync/sc_delay_corr.h
@@ -1,21 +1,9 @@
 /* -*- c++ -*- */
 /*
  * Copyright 2017 Leonard Göhrs.
+ * Copyright 2019, 2020, 2022 Johannes Demel.
  *
- * This is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 3, or (at your option)
- * any later version.
- *
- * This software is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this software; see the file COPYING.  If not, write to
- * the Free Software Foundation, Inc., 51 Franklin Street,
- * Boston, MA 02110-1301, USA.
+ * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
 
@@ -32,6 +20,14 @@ namespace xfdm_sync {
  * \brief Calculate fixed lag auto-correlation
  * \ingroup xfdm_sync
  *
+ * This block computes the fixed lag auto-correlation with a \p seq_len number of samples
+ * delay. In order to work, the preamble needs to half to identical parts and \p seq_len
+ * is the length of one part. Usually this block is followed by class:
+ * gr::xfdm_sync::sc_tagger which is followed by a class: gr::xfdm_sync::xcorr_tagger
+ * block.
+ *
+ * \param seq_len Number of samples for fixed lag. In most cases half the preamble length.
+ *
  */
 class XFDM_SYNC_API sc_delay_corr : virtual public gr::sync_block
 {

diff --git a/include/xfdm_sync/sc_tagger.h b/include/xfdm_sync/sc_tagger.h
@@ -1,21 +1,9 @@
 /* -*- c++ -*- */
 /*
  * Copyright 2017 Leonard Göhrs.
+ * Copyright 2018, 2019, 2020, 2022 Johannes Demel.
  *
- * This is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 3, or (at your option)
- * any later version.
- *
- * This software is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this software; see the file COPYING.  If not, write to
- * the Free Software Foundation, Inc., 51 Franklin Street,
- * Boston, MA 02110-1301, USA.
+ * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
 
@@ -32,6 +20,16 @@ namespace xfdm_sync {
  * \brief Find correlation peak based on fixed-lag auto-correlation result.
  * \ingroup xfdm_sync
  *
+ * This block performs fixed lag auto-correlation with a \p seq_len number of samples lag.
+ * A tag is added to the sample with the highest correlation magnitude in the are \p
+ * thres_high to \p thres_low.
+ *
+ * \param thres_low Lower threshold that marks the end of a correlation peak region.
+ * \param thres_high Higher threshold that marks the end of a correlation peak region.
+ * Must be higher than \p thres_low. \param seq_len Number of samples for fixed lag. In
+ * most cases half the preamble length. \param tag_key Key of tag that is placed at the
+ * detected correlation peak.
+ *
  */
 class XFDM_SYNC_API sc_tagger : virtual public gr::sync_block
 {

diff --git a/include/xfdm_sync/sync_tag_align_cc.h b/include/xfdm_sync/sync_tag_align_cc.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2020 Johannes Demel.
+ * Copyright 2020, 2022 Johannes Demel.
  *
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
@@ -18,8 +18,26 @@ namespace xfdm_sync {
  * \brief Make sure parallel streams share tags
  * \ingroup xfdm_sync
  *
- * In case of multiple RX streams, one needs a way to ensure that multiple streams detect
- * peaks at roughly the same positions.
+ * Each antenna is expected to be connected as follows:
+ * - RX input stream
+ * - class: gr::xfdm_sync::sc_delay_corr
+ * - class: gr::xfdm_sync::sc_tagger
+ * - class: gr::xfdm_sync::xcorr_tagger
+ * - input to this block with tags on identfied frame starts.
+ *
+ * In case of multiple RX streams, one needs a way to ensure that \p num_inputs streams
+ * detect peaks at roughly the same positions. It is crucial that the number of tags
+ * remain the same for all streams. If possible the streams are given a few samples of
+ * slack.
+ *
+ * The result is \p num_inputs streams that can be used in parallel to extract frames that
+ * correspond in time. This block does not help to synchronize between totally
+ * unsynchronized antenna streams. It only ensures that the number of tags are equal and
+ * on the same sample in each stream.
+ *
+ * \param num_inputs Number of parallel antenna streams. Translates into the number of
+ * input/output ports. \param tag_key Key of tag that is placed at the detected
+ * correlation peak.
  */
 class XFDM_SYNC_API sync_tag_align_cc : virtual public gr::sync_block
 {

diff --git a/include/xfdm_sync/xcorr_tagger.h b/include/xfdm_sync/xcorr_tagger.h
@@ -1,21 +1,9 @@
 /* -*- c++ -*- */
 /*
  * Copyright 2017 Leonard Göhrs.
+ * Copyright 2018, 2019, 2020, 2022 Johannes Demel.
  *
- * This is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 3, or (at your option)
- * any later version.
- *
- * This software is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this software; see the file COPYING.  If not, write to
- * the Free Software Foundation, Inc., 51 Franklin Street,
- * Boston, MA 02110-1301, USA.
+ * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
 
@@ -32,6 +20,12 @@ namespace xfdm_sync {
  * \brief Cross-correlate around detected fixed-lag auto-correlation peaks
  * \ingroup xfdm_sync
  *
+ * \param threshold A maximum above the threshold yields a tag at the cross-correlation
+ * peak. \param sync_sequence The expected preamble for cross-correlation. \param
+ * use_sc_rot Fix frequency offset before cross-correlation. \param tag_key Key of tag
+ * that the class: gr::xfdm_sync::sc_tagger yielded. \param antenna_port Add this integer
+ * to a newly placed tag.
+ *
  */
 class XFDM_SYNC_API xcorr_tagger : virtual public gr::sync_block
 {

diff --git a/lib/frame_gate_impl.cc b/lib/frame_gate_impl.cc
@@ -1,21 +1,9 @@
 /* -*- c++ -*- */
 /*
  * Copyright 2017 Leonard Göhrs.
+ * Copyright 2017, 2018, 2019, 2020 Johannes Demel.
  *
- * This is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 3, or (at your option)
- * any later version.
- *
- * This software is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this software; see the file COPYING.  If not, write to
- * the Free Software Foundation, Inc., 51 Franklin Street,
- * Boston, MA 02110-1301, USA.
+ * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
 #ifdef HAVE_CONFIG_H

diff --git a/lib/frame_gate_impl.h b/lib/frame_gate_impl.h
@@ -1,21 +1,9 @@
 /* -*- c++ -*- */
 /*
  * Copyright 2017 Leonard Göhrs.
+ * Copyright 2019, 2020, 2022 Johannes Demel.
  *
- * This is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 3, or (at your option)
- * any later version.
- *
- * This software is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this software; see the file COPYING.  If not, write to
- * the Free Software Foundation, Inc., 51 Franklin Street,
- * Boston, MA 02110-1301, USA.
+ * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
 #ifndef INCLUDED_XFDM_SYNC_FRAME_GATE_IMPL_H
@@ -25,6 +13,11 @@
 
 namespace gr {
 namespace xfdm_sync {
+
+/*!
+ * \brief Implementation for class: gr::xfdm_sync::frame_gate.
+ * \ingroup xfdm_sync
+ */
 class frame_gate_impl : public frame_gate
 {
 private: