Damian Gabino / picoGW_hal

Host driver/HAL to build a LoRa Picocell Gateway which communicates through USB with a concentrator board based on Semtech SX1308 multi-channel modem and SX1257/SX1255 RF transceivers.

util_pkt_logger/readme.md@0:102b50f941d0, 2018-04-11 (annotated)

Committer:
dgabino
Date:
Wed Apr 11 14:38:42 2018 +0000
Revision:
0:102b50f941d0
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dgabino 0:102b50f941d0 1 / _____) _ | |
dgabino 0:102b50f941d0 2 ( (____ _____ ____ _| |_ _____ ____| |__
dgabino 0:102b50f941d0 3 \____ \| ___ | (_ _) ___ |/ ___) _ \
dgabino 0:102b50f941d0 4 _____) ) ____| | | || |_| ____( (___| | | |
dgabino 0:102b50f941d0 5 (______/|_____)_|_|_| \__)_____)\____)_| |_|
dgabino 0:102b50f941d0 6 (C)2013 Semtech-Cycleo
dgabino 0:102b50f941d0 7
dgabino 0:102b50f941d0 8 LoRa packet logger
dgabino 0:102b50f941d0 9 ===================
dgabino 0:102b50f941d0 10
dgabino 0:102b50f941d0 11 1. Introduction
dgabino 0:102b50f941d0 12 ----------------
dgabino 0:102b50f941d0 13
dgabino 0:102b50f941d0 14 This software is used to set up a LoRa concentrator using a JSON configuration
dgabino 0:102b50f941d0 15 file and then record all the packets received in a log file, indefinitely, until
dgabino 0:102b50f941d0 16 the user stops the application.
dgabino 0:102b50f941d0 17 No filtering is done and all packets that are LoRa packets with the correct RF
dgabino 0:102b50f941d0 18 parameters (frequency, datarate, bandwidth) should appear in the log.
dgabino 0:102b50f941d0 19
dgabino 0:102b50f941d0 20 2. Dependencies
dgabino 0:102b50f941d0 21 ----------------
dgabino 0:102b50f941d0 22
dgabino 0:102b50f941d0 23 This program uses the Parson library (http://kgabis.github.com/parson/) by
dgabino 0:102b50f941d0 24 Krzysztof Gabis for JSON parsing.
dgabino 0:102b50f941d0 25 Many thanks to him for that very practical and well written library.
dgabino 0:102b50f941d0 26
dgabino 0:102b50f941d0 27 This program is a typical example of LoRa concentrator HAL usage for receiving
dgabino 0:102b50f941d0 28 packets.
dgabino 0:102b50f941d0 29
dgabino 0:102b50f941d0 30 Only high-level functions are used (the ones contained in loragw_hal) so there
dgabino 0:102b50f941d0 31 is no hardware dependencies assuming the HAL is matched with the proper version
dgabino 0:102b50f941d0 32 of the hardware.
dgabino 0:102b50f941d0 33 Data structures of the received packets are accessed by name (ie. not at a
dgabino 0:102b50f941d0 34 binary level) so new functionalities can be added to the API without affecting
dgabino 0:102b50f941d0 35 that program at all.
dgabino 0:102b50f941d0 36
dgabino 0:102b50f941d0 37 It was tested with v1.3.0 of the libloragw library, and should be compatible
dgabino 0:102b50f941d0 38 with any later version of the library assuming the API is downward-compatible.
dgabino 0:102b50f941d0 39
dgabino 0:102b50f941d0 40 3. Usage
dgabino 0:102b50f941d0 41 ---------
dgabino 0:102b50f941d0 42
dgabino 0:102b50f941d0 43 To stop the application, press Ctrl+C.
dgabino 0:102b50f941d0 44
dgabino 0:102b50f941d0 45 The only optional parameter when launching the application is the log rotation
dgabino 0:102b50f941d0 46 time (in seconds).
dgabino 0:102b50f941d0 47
dgabino 0:102b50f941d0 48 The way the program takes configuration files into account is the following:
dgabino 0:102b50f941d0 49 * if there is a debug_conf.json parse it, others are ignored
dgabino 0:102b50f941d0 50 * if there is a global_conf.json parse it and look for the next file
dgabino 0:102b50f941d0 51 * if there is a local_conf.json parse it
dgabino 0:102b50f941d0 52 If some parameters are defined in both global and local configuration files, the
dgabino 0:102b50f941d0 53 local definition overwrites the global definition.
dgabino 0:102b50f941d0 54
dgabino 0:102b50f941d0 55 The global configuration file should be exactly the same throughout your
dgabino 0:102b50f941d0 56 network, contain all global parameters (parameters for "sensor" radio channels)
dgabino 0:102b50f941d0 57 and preferably default "safe" values for parameters that are specific for each
dgabino 0:102b50f941d0 58 gateway (eg. specify a default MAC address).
dgabino 0:102b50f941d0 59
dgabino 0:102b50f941d0 60 If you have build the libloragw library for a specific radio band (eg. ETSI
dgabino 0:102b50f941d0 61 868 MHz band) a ready-to-use global_conf.json file is generated by the Makefile
dgabino 0:102b50f941d0 62 with a set of channels typical for a 'LoRa MAC' network application.
dgabino 0:102b50f941d0 63 If you don't specify a radio band, an empty global_conf.json is generated and
dgabino 0:102b50f941d0 64 must be filled with the settings you need.
dgabino 0:102b50f941d0 65
dgabino 0:102b50f941d0 66 The local configuration file should contain parameters that are specific to each
dgabino 0:102b50f941d0 67 gateway (eg. MAC address, frequency for backhaul radio channels).
dgabino 0:102b50f941d0 68
dgabino 0:102b50f941d0 69 In each configuration file, the program looks for a JSON object named
dgabino 0:102b50f941d0 70 "SX1301_conf" that should contain the parameters for the LoRa concentrator board
dgabino 0:102b50f941d0 71 (RF channels definition, modem parameters, etc) and another JSON object called
dgabino 0:102b50f941d0 72 "gateway_conf" that should contain the gateway parameters (gateway MAC address,
dgabino 0:102b50f941d0 73 IP address of the LoRa MAC controller, network authentication parameters, etc).
dgabino 0:102b50f941d0 74
dgabino 0:102b50f941d0 75 To learn more about the JSON configuration format, read the provided JSON files
dgabino 0:102b50f941d0 76 and the API documentation. A dedicated document will be available later on.
dgabino 0:102b50f941d0 77
dgabino 0:102b50f941d0 78 The received packets are put in a CSV file whose name include the MAC address of
dgabino 0:102b50f941d0 79 the gateway in hexadecimal format and a UTC timestamp of log starting time in
dgabino 0:102b50f941d0 80 ISO 8601 recommended compact format:
dgabino 0:102b50f941d0 81 yyyymmddThhmmssZ (eg. 20131009T172345Z for October 9th, 2013 at 5:23:45PM UTC)
dgabino 0:102b50f941d0 82
dgabino 0:102b50f941d0 83 To able continuous monitoring, the current log file is closed is closed and a
dgabino 0:102b50f941d0 84 new one is opened every hour (by default, rotation interval is settable by the
dgabino 0:102b50f941d0 85 user using -r command line option).
dgabino 0:102b50f941d0 86 No packet is lost during that rotation of log file.
dgabino 0:102b50f941d0 87 Every log file but the current one can then be modified, uploaded and/or deleted
dgabino 0:102b50f941d0 88 without any consequence for the program execution.
dgabino 0:102b50f941d0 89
dgabino 0:102b50f941d0 90 4. License
dgabino 0:102b50f941d0 91 -----------
dgabino 0:102b50f941d0 92
dgabino 0:102b50f941d0 93 Copyright (c) 2013, SEMTECH S.A.
dgabino 0:102b50f941d0 94 All rights reserved.
dgabino 0:102b50f941d0 95
dgabino 0:102b50f941d0 96 Redistribution and use in source and binary forms, with or without
dgabino 0:102b50f941d0 97 modification, are permitted provided that the following conditions are met:
dgabino 0:102b50f941d0 98
dgabino 0:102b50f941d0 99 * Redistributions of source code must retain the above copyright
dgabino 0:102b50f941d0 100 notice, this list of conditions and the following disclaimer.
dgabino 0:102b50f941d0 101 * Redistributions in binary form must reproduce the above copyright
dgabino 0:102b50f941d0 102 notice, this list of conditions and the following disclaimer in the
dgabino 0:102b50f941d0 103 documentation and/or other materials provided with the distribution.
dgabino 0:102b50f941d0 104 * Neither the name of the Semtech corporation nor the
dgabino 0:102b50f941d0 105 names of its contributors may be used to endorse or promote products
dgabino 0:102b50f941d0 106 derived from this software without specific prior written permission.
dgabino 0:102b50f941d0 107
dgabino 0:102b50f941d0 108 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
dgabino 0:102b50f941d0 109 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
dgabino 0:102b50f941d0 110 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
dgabino 0:102b50f941d0 111 DISCLAIMED. IN NO EVENT SHALL SEMTECH S.A. BE LIABLE FOR ANY
dgabino 0:102b50f941d0 112 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
dgabino 0:102b50f941d0 113 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
dgabino 0:102b50f941d0 114 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
dgabino 0:102b50f941d0 115 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
dgabino 0:102b50f941d0 116 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
dgabino 0:102b50f941d0 117 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
dgabino 0:102b50f941d0 118
dgabino 0:102b50f941d0 119 5. License for Parson library
dgabino 0:102b50f941d0 120 ------------------------------
dgabino 0:102b50f941d0 121
dgabino 0:102b50f941d0 122 Parson ( http://kgabis.github.com/parson/ )
dgabino 0:102b50f941d0 123 Copyright (c) 2012 Krzysztof Gabis
dgabino 0:102b50f941d0 124
dgabino 0:102b50f941d0 125 Permission is hereby granted, free of charge, to any person obtaining a copy
dgabino 0:102b50f941d0 126 of this software and associated documentation files (the "Software"), to deal
dgabino 0:102b50f941d0 127 in the Software without restriction, including without limitation the rights
dgabino 0:102b50f941d0 128 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
dgabino 0:102b50f941d0 129 copies of the Software, and to permit persons to whom the Software is
dgabino 0:102b50f941d0 130 furnished to do so, subject to the following conditions:
dgabino 0:102b50f941d0 131
dgabino 0:102b50f941d0 132 The above copyright notice and this permission notice shall be included in
dgabino 0:102b50f941d0 133 all copies or substantial portions of the Software.
dgabino 0:102b50f941d0 134
dgabino 0:102b50f941d0 135 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
dgabino 0:102b50f941d0 136 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
dgabino 0:102b50f941d0 137 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
dgabino 0:102b50f941d0 138 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
dgabino 0:102b50f941d0 139 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
dgabino 0:102b50f941d0 140 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
dgabino 0:102b50f941d0 141 THE SOFTWARE.
dgabino 0:102b50f941d0 142
dgabino 0:102b50f941d0 143 *EOF*