Feature/tagged stream input (#56)

* Added conda package installation guide

* fix data format between fft_demod and deinterleaver

* added support of tagged stream input

* add frequency issue related to repo update

* change uint to uint32_t for windows build

* removed utilities.h from python bindings
Prevents issue with out of date bindings when editing utilities.h

* add comments and documentation

.conda/recipe/meta.yaml

@@ -113,4 +113,7 @@ about:
     publication "An Open-Source LoRa Physical Layer Prototype on GNU Radio" 
     (<a href="https://ieeexplore.ieee.org/document/9154273">IEEE Xplore</a>,  
     <a href="https://arxiv.org/abs/2002.08208">arXiv</a>)
+    <h3>Installation issue</h3>
+    Add conda-forge to the list of channel for installation with:<br>
+    `conda install -c tapparelj -c conda-forge gnuradio-lora_sdr`
     

Changelog.md

@@ -1,3 +1,6 @@
+# v0.5.6
+- Added tagged stream input support (for frame definition of frame length)
+- Fixed LLR stream format between _fft\_demod_ and _deinterleaver_ 
 # v0.5.5
 - added tags to crc verification output stream indication frame start, length and CRC result.
 # v0.5.4

README.md

@@ -1,11 +1,12 @@
 [![GitHub last commit](https://img.shields.io/github/last-commit/tapparelj/gr-lora_sdr)](https://img.shields.io/github/last-commit/tapparelj/gr-lora_sdr)
-![gnuradio](https://img.shields.io/badge/GNU%20Radio-3.10.3-important)
-![version](https://img.shields.io/badge/Version-0.5.5-brightgreen)
+![gnuradio](https://img.shields.io/badge/GNU%20Radio-3.10.5-important)
+![version](https://img.shields.io/badge/Version-0.5.6-brightgreen)
 [![arXiv](https://img.shields.io/badge/arXiv-2002.08208-<COLOR>.svg)](https://arxiv.org/abs/2002.08208)
 [![Hits](https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2Ftapparelj%2Fgr-lora_sdr&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false)](https://hits.seeyoufarm.com)
 [![Build conda package](https://github.com/tapparelj/gr-lora_sdr/actions/workflows/conda-build.yml/badge.svg)](https://github.com/tapparelj/gr-lora_sdr/actions/workflows/conda-build.yml)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) 
 
+
 ## Summary
 This is the fully-functional GNU Radio software-defined radio (SDR) implementation of a LoRa transceiver with all the necessary receiver components to operate correctly even at very low SNRs. The transceiver is available as a module for GNU Radio 3.10. This work has been conducted at the Telecommunication Circuits Laboratory, EPFL. 
 
@@ -65,6 +66,8 @@ If you find this implementation useful for your project, please consider citing
 
 The conda environment used to develop this module is described by the environment.yml file. 
 ## Installation
+The out of three module gr-lora_sdr can be installed from source or directly as a conda package.
+### From source
 - Clone this repository
 	```sh
 	git clone https://github.com/tapparelj/gr-lora_sdr.git
@@ -73,7 +76,7 @@ The conda environment used to develop this module is described by the environmen
 	```sh
 	cd gr-lora_sdr/
 	```
-- A functionning environment with all dependencies can be installed with conda.
+- A functionning environment with all dependencies can be installed with conda or you can install them individually and skip to the next step.
 	You can follow this [tutorial](https://www.how2shout.com/how-to/install-anaconda-wsl-windows-10-ubuntu-linux-app.html) or simply following:
 	- First download the latest release of conda, for example:
 		```sh
@@ -112,6 +115,10 @@ The conda environment used to develop this module is described by the environmen
 	```sh
 	sudo ldconfig 
 	```
+- You can test that the installation is successful by running
+  ```sh
+  make test
+  ```
 - Now you should be able to run some codes. For example, open the GNU Radio Companion user interface and check if the blocks of gr-lora_sdr are available on the blocks list (e.g. under LoRa_TX).
 	```sh
 	gnuradio-companion &
@@ -121,13 +128,51 @@ The conda environment used to develop this module is described by the environmen
 	python3 examples/tx_rx_functionnality_check.py 
 	```
 
-## Usage
+#### Usage
 - An example of a LoRa transmitter and receiver can be found in gr-lora_sdr/examples/ (both python and grc).
 - The .grc files can be opened with gnuradio-companion to set the different transmission parameters.
 - The python file generated by grc can be executed with ``` python3 ./{file_name}.py```
 
-
+### From conda
+Thanks to Ryan Volz this OOT module can also directly be installed as a Conda package. Note that gnuradio will also be installed in the conda environment.
+
+- Create or activate the conda environment you want to install this module in. Refer to the conda [getting start guide](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html) if you are not familiar with it already.
+- Install the module from the anaconda channel [tapparelj](https://anaconda.org/tapparelj/gnuradio-lora_sdr) with:
+	```sh
+	conda install -c tapparelj -c conda-forge gnuradio-lora_sdr
+	```
+- Depending on your needs you might want to install complementary packages for gnuradio with:
+	```sh
+	conda install -c conda-forge gnuradio
+	```
+- The gnuradio metapackage installs all of the following subpackages: 
+	- `gnuradio-grc`
+	- `gnuradio-iio`
+	- `gnuradio-qtgui`
+	- `gnuradio-soapy`
+	- `gnuradio-uhd`
+	- `gnuradio-video-sdl`
+	- `gnuradio-zeromq`
+- If you don't want all of those and their dependencies, you can install the ones you'd like individually with: 
+	```sh
+	conda install -c conda-forge gnuradio-uhd
+	```
+#### Usage
+- Example gnuradio-companinon flowgraphs are installed with the package and can be found in:
+	- (Linux/macOS) `$CONDA_PREFIX/share/gr-lora_sdr/examples`
+	- (Windows) `%CONDA_PREFIX%\Library\share\gr-lora_sdr\examples`
+
+
 ## Frequent issues:  
+- Fail to `make` after pulling a new version from git
+	- If the parameters of a block have changed in the new version, you need to first clean the old installation before building the module again.
+	- from within the build folder, run 
+		```
+		(sudo) make uninstall
+		make clean
+		make -j4
+		(sudo) make install
+		```
 - "ImportError: No module named lora_sdr":
 	- This issue comes probably from missing PYTHONPATH and LD_LIBRARY_PATH                             
 	- Refer to https://wiki.gnuradio.org/index.php/ModuleNotFoundError to modify those variables. If you set a prefix during the "cmake" call, skip directly to point C.(Verifying that the paths exist in your folders might help.)
@@ -137,43 +182,19 @@ The conda environment used to develop this module is described by the environmen
 		[grc]
 		local_blocks_path=path_to_the_downloaded_folder/gr-lora_sdr/grc
 ## Changelog
+- Added tagged stream input support (for frame definition of frame length)
+- Fixed LLR stream format between _fft\_demod_ and _deinterleaver_ 
 - added tags to crc verification output stream indication frame start, length and CRC result.
 - added separator option for file input
 - added preamble length option
 - added parameter for frame zero-padding
 - add low datarate optimisation support
-
 - add support of spreading factors smaller than 7
 
-- add sampling frequency offset estimation and compensation
-    - Estimation leverages the relation between CFO and SFO, both caused by the same reference clock
-    - The compensation method consists in a two step refinement of the estimates in the preamble and a puncturing/insertion of samples during the payload
-
-- Add frame error rate simulation script in apps/simulation
-
  	<font size="10"> [...](./Changelog.md)</font>
 
 ## Credit
 This work was inspired from [https://github.com/rpp0/gr-lora](https://github.com/rpp0/gr-lora) by Pieter Robyns, Peter Quax, Wim Lamotte and William Thenaers. Which architecture and functionalities have been improved to better emulate the physical layer of LoRa. 
 
 ## Licence
 Distributed under the GPL-3.0 License License. See LICENSE for more information.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

data/GRC_default/example_tx_source.txt

@@ -1 +1 @@
-HztlXcpsegzpnbkq,rkvpzpbdmnxxhoch,lkcaxkyajmntudou,hfzumtbgtavjfwsp,mzebvqousvhrsanl,ingkzvddatxfgjzh,rbhibtwkfyuvecbb,vvzdjzflvgaevyzd,rfvhcmuqskiqlpag,zfpgxcjzhehcydjf
+HztlXcpsegzpnbkq,rkvpzpbd,mnxxhoch,lkcaxkyajmntudouhfzumtbgtavjfwsp,mzebvqousvhrsanl,ingkzvddatxfgjzh,rbhibtwkfyuvecbb,vvzdjzflvgaevyzd,rfvhcmuqskiqlpag,zfpgxcjzhehcydjf

data/GRC_default/example_tx_source_for_tagged_stream.txt

@@ -0,0 +1 @@
+0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz

examples/lora_RX.py

@@ -7,7 +7,7 @@
 # GNU Radio Python Flow Graph
 # Title: Lora Rx
 # Author: Tapparel Joachim@EPFL,TCL
-# GNU Radio version: 3.10.3.0
+# GNU Radio version: 3.10.5.1
 
 from gnuradio import gr
 from gnuradio.filter import firdes
@@ -46,6 +46,7 @@ def __init__(self):
         ##################################################
         # Blocks
         ##################################################
+
         self.uhd_usrp_source_0 = uhd.usrp_source(
             ",".join(("addr=192.168.10.6", '')),
             uhd.stream_args(

examples/lora_TX.grc

@@ -288,10 +288,12 @@ blocks:
     alias: ''
     comment: ''
     is_hex: 'False'
+    length_tag_name: '''packet_len'''
     maxoutbuf: '0'
     minoutbuf: '0'
     separator: ''','''
     source_type: message_strobe
+    use_length_tag: 'False'
   states:
     bus_sink: false
     bus_source: false
@@ -591,4 +593,4 @@ connections:
 
 metadata:
   file_format: 1
-  grc_version: 3.10.3.0
+  grc_version: 3.10.5.1

examples/lora_TX.py

@@ -7,7 +7,7 @@
 # GNU Radio Python Flow Graph
 # Title: Lora Tx
 # Author: Tapparel Joachim@EPFL,TCL
-# GNU Radio version: 3.10.3.0
+# GNU Radio version: 3.10.5.1
 
 from gnuradio import blocks
 import pmt
@@ -47,6 +47,7 @@ def __init__(self):
         ##################################################
         # Blocks
         ##################################################
+
         self.uhd_usrp_sink_0 = uhd.usrp_sink(
             ",".join(("addr=192.168.10.5", '')),
             uhd.stream_args(
@@ -63,7 +64,7 @@ def __init__(self):
         self.uhd_usrp_sink_0.set_antenna('TX/RX', 0)
         self.uhd_usrp_sink_0.set_bandwidth(bw, 0)
         self.uhd_usrp_sink_0.set_gain(TX_gain, 0)
-        self.lora_sdr_whitening_0 = lora_sdr.whitening(False,',')
+        self.lora_sdr_whitening_0 = lora_sdr.whitening(False,False,',','packet_len')
         self.lora_sdr_payload_id_inc_0 = lora_sdr.payload_id_inc(':')
         self.lora_sdr_modulate_0 = lora_sdr.modulate(sf, samp_rate, bw, [8,16], (int(20*2**sf*samp_rate/bw)),8)
         self.lora_sdr_modulate_0.set_min_output_buffer(10000000)