From 7dad63879fd9577d9b3d429583ba1a21c1fdce64 Mon Sep 17 00:00:00 2001 From: Praneeth Challagonda <58634765+Praneethsvch@users.noreply.github.com> Date: Tue, 27 Oct 2020 17:16:25 -0400 Subject: [PATCH] readme update --- README.md | 62 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 498889bb..2f63e3aa 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,16 @@ This repository contains the source code for the Floodsense sensor which uses ul * [Flood Sense Sensor Library](#flood-sense-sensor-library) * [About this Project](#about-this-project) - * [Using this Library](#using-this-library) - * [Sensor Config File](#sensor-config-file) + * [Using this Library](#using-this-library) + * [Sensor Config File](#sensor-config-file) * [LoRa](#lora) - * [LoRa Configuration](#lora-configuration) - * [Duty Cycle](#duty-cycle) - * + * [Uplink Packet Format](#uplink-packet-format) + * [Downlink Packet Format](#downlink-packet-format) + * [Changing parameters via Downlink](#changing-parameters-via-downlink) + * [Changing dutycycle](#changing-dutycycle) + * [Changing sensor mode](#changing-sensor-mode) + * [Changing sensor sampling rate](#changing-sensor-sampling-rate) + * [Changing number of sensor readings per measurement](#changing-number-of-sensor-readings-per-measurement) * [TTN Payload Decoder](#ttn-payload-decoder) * [TTN Credentials](#ttn-credentials) * [Ultrasonic Sensor Modes](#ultrasonic-sensor-modes) @@ -29,10 +33,10 @@ Here below is a list of parameters that can be changed during the run-time of th - Duty Cycle - Ultrasonic Sensing Modes -### LoRa +## LoRa This library uses the [Arduino-lmic](https://github.com/mcci-catena/arduino-lmic) library to handle the LoRa communication. The Things Network has a LoRaWAN [compliance](https://www.thethingsnetwork.org/docs/lorawan/duty-cycle.html). This means every radio device must be compliant with the regulated duty cycle limits. To program the node to stay within the limits, an [air-time calculator](https://avbentem.github.io/airtime-calculator/ttn/us915) can be used. -#### Uplink Packet Format +### Uplink Packet Format | Error flags | Battery Level | Ultrasonic reading | |--------------|---------------|---------------------| | 1 byte | 2 bytes | 2 bytes | @@ -54,16 +58,16 @@ This library uses the [Arduino-lmic](https://github.com/mcci-catena/arduino-lmic | | | | | | | | SD error flag| -#### Downlink Packet Format +### Downlink Packet Format |Duty Cycle in seconds | Sensor Mode | Sampling Rate| Number of readings per measurement | |----------------------|--------------|---------------| --------------------------------- | | 2 bytes | 1 byte | 2 bytes | 1 byte | -#### Changing parameters via Downlink +### Changing parameters via Downlink To change the duty cycle and sensor parameters via downlink the above downlink packet format must be used. For this use case the maximum packet size is 6 bytes and can be varied. The parameters to be changed should be a non-zero entries and the rest can be left as zeroes if no changes are needed. The following sections describe changing duty cycle and sensor configurations with some examples. -##### Changing dutycycle +#### Changing dutycycle Uplink frequency at the end node is determined by the TX_INTERVAL. This TX_INTERVAL is used as a variable in this library to add the functionality of varying duty cycle. Few examples of changing duty cycle by updating `TX_INTERVAL` are mentioned below: | Downlink Packet format| Explanation| @@ -74,7 +78,7 @@ Uplink frequency at the end node is determined by the TX_INTERVAL. This TX_INTER |`00 3C 00 00 00 00` | Only duty cycle is changed and rest are unchanged. 6 bytes used for the downlink | -##### Changing sensor mode +#### Changing sensor mode The sensor mode can be changed by adding non-zero values to the sensor mode byte in the downlink packet. Any invalid modes entered are discarded. Examples: | Downlink Packet format| Explanation| @@ -84,7 +88,7 @@ The sensor mode can be changed by adding non-zero values to the sensor mode byte | `00 00 06 00 00 00` |Discarded and no change since 6 is an invalid mode. Consumes 6 bytes | | `01`| Valid packet format but doesn't change sensor mode, instead duty cycle is changed to 1 sec| -##### Changing sampling rate +#### Changing sampling rate The sensor sampling rate can be changed by adding non-zero values to the corresponding bytes in the downlink packet. Examples: | Downlink Packet format| Explanation| @@ -93,12 +97,25 @@ The sensor sampling rate can be changed by adding non-zero values to the corresp | `00 00 00 04 E2 00` |changing sensor sampling rate to 1250ms and the rest are unchanged. Consumes 6 bytes | | `04 E2`| Valid packet format but doesn't change sensor sampling rate, instead duty cycle is changed to 1250 sec| -##### Changing dutycycle +#### Changing number of sensor readings per measurement +Similarly, the number of sensor readings per measurement can be changed by adding non-zero values to the corresponding bytes in the downlink packet. A maximum of 20 is allowed. Examples: +| Downlink Packet format| Explanation| +|---|---| +| `00 00 00 00 00 05` | 5 readings per measurement. Consumes 5 bytes: minimal sampling rate change| +| `00 00 00 00 00 22` | invalid, maximum of 20 readings are allowed and the configuration is unchanged.| + +#### Changing multiple parameters via single downlink: +Multiple sensor parameters can be changed via downlink and below are such examples: +| Downlink Packet format| Explanation| +|---|---| +| `00 78 02 00 00 05` | Change duty cycle to 120 seconds, sensor mode to 2 (Median) and 5 readings per measurement| +| `00 78 03 00 FA 12` | Change duty cycle to 120 seconds, sensor mode to 1(Mode), 250ms sampling rate and 12 readings per measurement| +**Note:** the above downlink payload formats must be implemented with caution, else there is a danger of sleeping the MCU for unwanted periods of time or indefinitely or even a possible crash! -#### TTN Payload Decoder +### TTN Payload Decoder ``` // decoder variable contains battery and distance @@ -127,14 +144,15 @@ function Decoder(b, port) { return decoded; } ``` - -### Ultrasonic Sensor +### TTN Credentials +The TTN Credentials should be entered into the `ttncredentials.h` file from the TTN console. +## Ultrasonic Sensor Ultrasonic sensors measure the distance to an object by measuring the time difference between sending a signal and receiving an echo from the object. The Ultrasonic sensor used for this project is [Maxbotix's MB-7389](https://www.maxbotix.com/Ultrasonic_Sensors/MB7389.htm). -##### Ultrasonic sensor Configuration: +### Ultrasonic sensor Configuration: The Ultrasonic sensor has an internal averaging methods to avoid small obstacles, irregularities and reporting the distance to the largest acoustic return while ignoring smaller targets. However, some anomalies are observed due to corner reflections and metal surfaces. These anomalies can be avoided using statistical methods such as averaging or calculating median of multiple measurements. -##### Sensor modes: +#### Sensor modes: These statistical methods are implemented as `sensorModes`. For example, `sensorMode = 2` uses a median of all the readings. The following are the available sensor modes: |Sensor mode| Statistical method| @@ -143,11 +161,11 @@ These statistical methods are implemented as `sensorModes`. For example, `sensor | 2 | Median | | 3 | Mode | -##### Number of Readings: +#### Number of Readings: The number of readings for these averaging methods can be changed via variable `sensor_numberOfReadings`. -##### Sensor Sampling Frequency: -Single read from the sensor is as fast as 150 to 250 milliseconds and five of such measurements would be sensed over a period of 0.75 - 1.5 seconds. These measurements can be spread out to average over a larger interval using the variable `sensor_sampling_rate`. Each measurement corresponding to a sensor mode is followed by an interval of `sensor_sampling_rate`. +#### Sensor Sampling Frequency: +Single read from the sensor is as fast as 150 to 250 milliseconds and five of such measurements would be sensed over a period of 0.75 - 1.5 seconds. These measurements can be spread out over a larger interval by changing the variable `sensor_sampling_rate`, which enables to use averaging methods with varying rates. Each measurement corresponding to a sensor mode is followed by an interval of `sensor_sampling_rate` milliseconds. -### SD Card logging and RTC +## SD Card logging and RTC Every lora event, sensor states and measurements are locally logged onto the SD Card using the [SDFat](https://github.com/greiman/SdFat) library. The sensor sets the SD Card error flag high if the local logging is failed. A Real-time Clock is used to create timestamps for these local logs.