Initial Commit

1 files changed, 79 insertions, 0 deletions

diff --git a/util_spectral_scan/readme.md b/util_spectral_scan/readme.md
new file mode 100644
index 0000000..6bcd33e
--- /dev/null
+++ b/util_spectral_scan/readme.md
@@ -0,0 +1,79 @@
+	  ______                              _
+	 / _____)             _              | |
+	( (____  _____ ____ _| |_ _____  ____| |__
+	 \____ \| ___ |    (_   _) ___ |/ ___)  _ \
+	 _____) ) ____| | | || |_| ____( (___| | | |
+	(______/|_____)_|_|_| \__)_____)\____)_| |_|
+	  (C)2014 Semtech-Cycleo
+
+Background Spectral Scan for LoRa gateway
+=========================================
+
+
+1. Introduction
+----------------
+
+This software is used to scan the spectral band where the LoRa gateway operates.
+It simply computes a RSSI histogram on several frequencies, that will help to
+detect occupied bands and get interferer profiles.
+It logs the histogram in a .csv file.
+
+This utility program is meant to run on the LoRa gateway reference design
+SX1301AP2 (with FPGA and additionnal SX127x).
+
+The background RSSI scan is a diagnostic tool and must be run on top of the
+gateway activity. Moreover the two SX1257 radios have to be configured in RX
+mode to optimize the matching impedance with SX127x. The 32MHz clock provided
+to the SX127x is available once SX1301 has enabled the two SX1257 radios, so
+the background RSSI scan must be launched after the packet forwarder.
+
+Note: if the FPGA running the spectral scan also supports Listen-Before-Talk
+feature (LBT), the LBT feature has to be enabled and running before launching
+util_spectral_scan. For example, if the lora_pkt_fwd runs in background, it has
+to use a global_conf.json file with "lbt_cfg.enable" set to true.
+
+2. Command line options
+------------------------
+
+`-h`
+will display a short help
+
+`-f start:step:stop`
+Frequency vector to scan in MHz: start:step:stop
+Valid range: start > 800, step > 0.005, stop < 1000
+
+`-b`
+Channel bandwidth to be used to configure the SX1272x radio for scanning in KHz
+Valid values: [25,50,100,125,200,250,500]
+
+`-n`
+Total number of RSSI points.
+Valid range: [1..65535]
+
+`-l`
+Log file name
+
+Note: For FPGA image that provides LBT support, the spectral scan gets less
+flexible. The following parameters have constraints:
+    - Frequency step: has to be multiple of 100KHz
+    - Channel bandwidth: hardcoded to 200KHz
+    - Number of RSSI points: 16641
+
+3. Usage
+---------
+
+The format of the log file is the following:
+Freq_1, RSSI_1, histo_1, ...., RSSI_128, histo_128
+Freq_2, RSSI_1, histo_1, ...., RSSI_128, histo_128
+...
+
+RSSI_n is the nth value of RSSI in dBm
+
+Default setup:
+- freq 863 : 0.2 : 870
+- 65535 RSSI points in total at 32kHz rate
+- 125KHz channel bandwidth
+
+Example with frequencies from 865 MHz to 870 MHz, by step of 100KHz, BW 200KHz
+10000 RSSI points processed at 10kHz rate, saved in "log.csv":
+./util_spectral_scan -f 865:0.1:870 -n 10000 -b 200 -l "log"