push lib

IOT/receiver LoRa/lib/Farm-Data-Relay-System/extras/Gateway.md

@@ -0,0 +1,196 @@
+# FDRS Gateway
+
+The FDRS Gateway listens for packets over ESP-NOW, UART, LoRa, and/or MQTT, then retransmits the packets over these interfaces using rules defined in the "Routing" section of the configuration file.
+
+A basic FDRS gateway's sketch file (.ino) will look like this:
+
+``` cpp
+#include "fdrs_gateway_config.h"
+#include <fdrs_gateway.h>
+
+void setup() {
+  beginFDRS();
+}
+
+void loop() {
+  loopFDRS();
+}
+```
+
+## Addresses
+#### ```#define UNIT_MAC 0xNN```
+The ESP-NOW and LoRa address of the gateway. This is the address that nodes and other gateways will use to pass data to this device.
+#### ```#define ESPNOW_NEIGHBOR_1 0xNN```, ```ESPNOW_NEIGHBOR_2 0xNN```
+The addresses of any ESP-NOW repeaters neighboring this gateway.
+#### ```#define LORA_NEIGHBOR_1 0xNN```, ```LORA_NEIGHBOR_2 0xNN```
+The addresses of any LoRa repeaters neighboring this gateway.
+## Interfaces
+#### ```#define USE_ESPNOW```
+Enables ESP-NOW.
+
+#### ```#define USE_LORA```
+Enables LoRa. Ensure your pins are configured correctly.
+#### ```#define USE_WIFI```
+Enables WiFi for use by MQTT. Do not enable WiFi and ESP-NOW simultaneously.
+#### ```#define USE_ETHERNET```
+Enables ethernet to be used by MQTT. 
+
+## Routing
+**Events** occur when data arrives at the gateway via its various interfaces. When an event occurs it triggers one or more **actions**, which are functions that re-send the incoming data over the same or different interfaces.
+
+**Example:** In the following configuration, a packet that arrives at the serial port will be sent to the gateway's neighbor #2, and then to all ESP-NOW nodes that are connected:
+```
+#define SERIAL_ACT sendESPNowNbr(2); sendESPNowPeers();
+```
+#
+### Events
+
+#### ```#define ESPNOWG_ACT ```
+Actions that occur when data arrives from an ESP-NOW device that is *not* listed as a neighbor.
+#### ```#define LORAG_ACT ```
+Actions that occur when data arrives from a LoRa device that is *not* listed as a neighbor.
+#### ```#define SERIAL_ACT ```
+Actions that occur when JSON data arrives over UART.
+#### ```#define MQTT_ACT ```
+Actions that occur when JSON data is posted to the MQTT topic defined by ```TOPIC_COMMAND``` in 'src/fdrs_globals.h'.
+#### ```#define INTERNAL_ACT ```
+Actions that occur when data is entered by a user-defined function. Used for sending the gateway's own voltage or temperature.
+#### ```#define ESPNOW1_ACT ``` and ```ESPNOW2_ACT ```
+Actions that occur when data arrives from the devices defined by ```ESPNOW_NEIGHBOR_1``` and ```ESPNOW_NEIGHBOR_2```.
+#### ```#define LORA1_ACT ``` and ```LORA2_ACT ```
+Actions that occur when data arrives from the devices defined by ```LORA_NEIGHBOR_1``` and ```LORA_NEIGHBOR_2```.
+#
+### Actions
+#### ```sendSerial();```
+Transmits the data in JSON format via both the debugging terminal as well as a second UART interface. (If available. See below.)
+#### ```sendMQTT();```
+Posts the data in JSON format to the MQTT topic defined by ```TOPIC_DATA```
+#### ```sendESPNowNbr(1 or 2);```
+Sends the data to the address defined by ```ESPNOW_NEIGHBOR_1``` or ```ESPNOW_NEIGHBOR_2```
+#### ```sendESPNowPeers();```
+Sends the data to any ESP-NOW controller node that has registered with this gateway as a peer.
+#### ```sendLoRaNbr(1 or 2);```
+Sends the data to the address defined by ```LORA_NEIGHBOR_1``` or ```LORA_NEIGHBOR_2```
+#### ```broadcastLoRa();```
+Broadcasts the data to any LoRa controller node that is listening to this gateway. No registration is needed to pair with a LoRa controller.
+#### ```sendESPNow(0xNN);```
+Sends the data directly to the ESP-NOW gateway address provided. There is no LoRa equivalent of this function.
+
+#
+## LoRa Configuration
+#### ```#define RADIOLIB_MODULE cccc```
+The name of the RadioLib module being used. Tested modules: SX1276, SX1278, SX1262.
+#### ```#define LORA_SS n```
+LoRa chip select pin.
+#### ```#define LORA_RST n```
+LoRa reset pin.
+#### ```#define LORA_DIO n```
+LoRa DIO pin. This refers to DIO0 on SX127x chips and DIO1 on SX126x chips.
+#### ```#define LORA_BUSY n```
+For SX126x chips: LoRa BUSY pin. For SX127x: DIO1 pin, or "RADIOLIB_NC" to leave it blank. 
+#### ```#define LORA_TXPWR n```
+LoRa TX power in dBm.
+#### ```#define USE_SX126X```
+Enable this if using the SX126x series of LoRa chips.
+
+#### ```#define CUSTOM_SPI```
+Enable this to define non-default SPI pins.
+#### ```#define LORA_SPI_SCK n```, ```LORA_SPI_MISO n```, ```LORA_SPI_MOSI n```
+Custom SPI pin definitions.
+
+#
+**LoRa radio parameters are generally configured in the 'src/fdrs_globals.h' file.** The following values may be set in the gateway configuration file if the user wishes to override the global value:
+
+The actual allowed values may vary by chip. Check the datasheet and/or RadioLib documentation.
+#
+#### ```#define LORA_FREQUENCY n```
+LoRa frequency in MHz. Allowed values range from 137.0 MHz to 1020.0 MHz.
+#### ```#define LORA_SF n```
+LoRa spreading factor. Allowed values range from 6 to 12. 
+#### ```#define LORA_BANDWIDTH n```
+LoRa bandwidth in kHz. Allowed values are 10.4, 15.6, 20.8, 31.25, 41.7, 62.5, 125, 250 and 500 kHz.
+#### ```#define LORA_CR n```
+LoRa coding rate denominator. Allowed values range from 5 to 8.
+#### ```#define LORA_SYNCWORD n```
+LoRa sync word. Can be used to distinguish different networks. Note that 0x34 is reserved for LoRaWAN.
+#### ```#define LORA_INTERVAL n```
+Interval between LoRa buffer releases. Must be longer than transmission time-on-air.
+
+## WiFi and MQTT Configuration
+WiFi and MQTT parameters are generally configured in the 'src/fdrs_globals.h' file. The following values may be set in the gateway configuration file if the user wishes to override the global value:
+#### ```#define WIFI_SSID "cccc"``` and ``` WIFI_PASS "cccc"  ```
+WiFi credentials
+#### ```#define MQTT_ADDR "n.n.n.n"``` or ```MQTT_ADDR "cccc"```
+The address of the MQTT server, either the IP address or domain name.
+#### ```#define MQTT_PORT n ```
+The port of the MQTT server.
+#### ```#define MQTT_AUTH ```
+Enable this if using MQTT authentication 
+#### ```#define MQTT_USER "cccc"``` and ```MQTT_PASS "cccc"```
+
+#
+### SSD1306 OLED Display
+Built on the [ThingPulse OLED SSD1306 Library](https://github.com/ThingPulse/esp8266-oled-ssd1306)
+#### ```#define OLED_HEADER "cccc"```
+The message to be displayed at the top of the screen.
+#### ```#define OLED_SDA n``` and ```OLED_SCL n```
+OLED I²C pins.
+#### ```#define OLED_RST n```
+OLED reset pin. Use '-1' if not present or known.
+#
+### Miscellaneous
+#### ```#define FDRS_DEBUG```
+Enables debugging messages to be sent over the serial port and OLED display.
+#### ```#define RXD2 (pin)``` and ```TXD2 (pin)```
+Configures a second, data-only UART interface on ESP32. The ESP8266 serial interface is not configurable, and thus these options don't apply.
+
+#### ```#define USE_LR```
+Enables ESP-NOW Long-Range mode. Requires ESP32.
+## Neighbors
+*To-do: Describe neighbors and how to use them to make repeaters.*
+
+## User-Defined Functions
+This feature allows the user to send data from the gateway itself. For example: the battery level or ambient temperature at the gateway.
+
+Calling ```scheduleFDRS(function, interval);``` after initializing FDRS will schedule ```function()``` to be called every ```interval``` milliseconds.
+
+Within this function, the user may utilize the same ```loadFDRS()``` and ```sendFDRS()``` commands used by sensors. After the data is sent, it triggers ```INTERNAL_ACT``` where it can be routed to the front-end.
+
+#### ```loadFDRS(float data, uint8_t type, uint16_t id);```
+Loads some data into the current packet. 'data' is a float, 'type' is the data type, and 'id' is the DataReading id.
+#### ```sendFDRS();```
+Sends the current packet using actions defined by ```INTERNAL_ACT```. Does not return any value.
+
+**Example:**
+``` cpp
+#define GTWY_READING_ID 42
+#define INTERVAL_SECONDS 60
+
+#include "fdrs_gateway_config.h"
+#include <fdrs_gateway.h>
+#include <your_bms.h>
+
+void sendReading() {
+  float v = bms.readVoltage();
+  loadFDRS(v, VOLTAGE_T, GTWY_READING_ID);
+  sendFDRS();
+}
+
+void setup() {
+  beginFDRS();
+  scheduleFDRS(sendReading, INTERVAL_SECONDS * 1000);
+}
+
+void loop() {
+  loopFDRS();
+}
+```
+
+#
+![Basic](Basic_Setup.png)
+
+![Advanced](Advanced_Setup.png)
+
+![Basic LoRa](Basic_LoRa_Setup.png)
+
+![Advanced LoRa](Advanced_Setup_LoRa.png)

IOT/receiver LoRa/lib/Farm-Data-Relay-System/extras/Node.md

@@ -0,0 +1,166 @@
+# FDRS Node
+A node is a device that sends and receives data from a nearby gateway. A node can be a **sensor**, **controller**, ***or both***.
+## Addresses
+#### ```#define READING_ID  n```
+The unique ID that the node will use when sending sensor values. Can be any integer 0 - 65535. Nodes are not necessarily tied to this parameter. They can be subscribed to up to 256 different IDs or send using several different IDs.
+#### ```#define GTWY_MAC  0xnn```
+The ```UNIT_MAC``` of the gateway that this device will be paired with.
+
+## Usage
+#### ```beginFDRS();```
+Initializes FDRS, powers up the sensor array, and begins ESP-NOW and/or LoRa.
+#### ```uint32_t pingFDRS(timeout);```
+Sends a ping request to the device's paired gateway with a timeout in ms. Returns the ping time in ms as well as displaying it on the debugging console.
+
+## Sensor API
+#### ```loadFDRS(float data, uint8_t type, uint16_t id);```
+Loads some data into the current packet. 'data' is a float, 'type' is the data type (see below), and 'id' is the DataReading id.
+#### ```loadFDRS((float data, uint8_t type);```
+Same as above, but the 'id' is preset to the node's ```READING_ID```. 
+#### ```bool sendFDRS();```
+Sends the current packet using ESP-NOW and/or LoRa. Returns true if packet is confirmed to have been recieved successfully by the gateway.
+#### ```sleepFDRS(seconds)```
+Time to sleep in seconds. If ```DEEP_SLEEP``` is enabled, the device will enter sleep. Otherwise it will use a simple ```delay()```.
+
+## Controller API
+#### ```addFDRS(void callback);```
+Initializes controller functionality by selecting the function to be called when incoming commands are recieved. If using LoRa, the controller will automatically recieve any packets sent with broadcastLoRa(), provided they were sent by the paired gateway. ESP-NOW requires the device to register with its gateway before it will recieve incoming commands. This is done automatically, and the ESP-NOW node will continue recieving data until the paired gateway is reset. A maximum of 16 ESP-NOW controllers can recieve data from a single gateway. There is no limit to how many LoRa controllers can listen to the same gateway.
+#### ```subscribeFDRS(uint16_t sub_id);``` 
+Sets the device to listen for a specific DataReading id. When a DataReading with id ```sub_id``` is received, the callback function will be called and given the full DataReading as a parameter.
+#### ```unsubscribeFDRS(uint16_t sub_id);``` 
+Removes ```sub_id``` from subscription list.
+#### ```loopFDRS();``` 
+Always add this to ```loop()``` to handle the controller's listening capabilities.
+
+## Basic Examples:
+### Sensor
+Sensors load a packet with data, then send the packet to the gateway that they are addressed to.
+``` cpp
+#include "fdrs_node_config.h"
+#include <fdrs_node.h>
+
+void setup() {
+  beginFDRS();  // Start the system
+  pingFDRS(2000); // Send ping and wait 2000ms for response
+}
+void loop() {
+  loadFDRS(21.0, TEMP_T); // Load a temperature of 21.0 into the queued packet
+  sendFDRS();        // Send the queued packet
+  sleepFDRS(60); // Sleep for 60 seconds
+}
+```
+
+### Controller
+Controllers register with the gateway they are addressed to, then receive data from it. 
+
+``` cpp
+#include "fdrs_node_config.h"
+#include <fdrs_node.h>
+
+void fdrs_recv_cb(DataReading theData) {
+  DBG("ID: " + String(theData.id));
+  DBG("Type: " + String(theData.t));
+  DBG("Data: " + String(theData.d));
+}
+
+void setup() {
+  beginFDRS();       // Start the system
+  addFDRS(fdrs_recv_cb);  // Call fdrs_recv_cb() when data arrives.
+  subscribeFDRS(READING_ID);  // Subscribe to DataReadings with ID matching READING_ID
+}
+void loop() {
+  loopFDRS();  // Listen for data
+}
+```
+
+## Configuration
+
+#### ```#define USE_ESPNOW```
+Enables/disables ESP-NOW.
+#### ```#define USE_LORA```
+Enables/disables LoRa.
+#### ```#define LORA_ACK```
+Enables LoRa packet acknowledgement. The device will use CRC to ensure that the data arrived at its destination correctly. If disabled, ```sendFDRS()``` will always return true when sending LoRa packets.
+
+Thanks to [aviateur17](https://github.com/aviateur17) for this feature!
+#### ```#define FDRS_DEBUG```
+This definition enables debug messages to be sent over the serial port. If disabled, no serial debug interface will be initialized. 
+#### ```#define DEEP_SLEEP```
+If enabled, device will enter deep-sleep when the sleepFDRS() command is used. If using ESP8266, be sure that you connect the WAKE pin (GPIO 16) to RST or your device will not wake up. 
+#### ```#define POWER_CTRL n```
+If defined, power control will bring a GPIO pin high when FDRS is initialized. This is useful for powering sensors while running on battery.
+#
+## LoRa Configuration
+#### ```#define RADIOLIB_MODULE cccc```
+The name of the RadioLib module being used. Tested modules: SX1276, SX1278, SX1262.
+#### ```#define LORA_SS n```
+LoRa chip select pin.
+#### ```#define LORA_RST n```
+LoRa reset pin.
+#### ```#define LORA_DIO n```
+LoRa DIO pin. This refers to DIO1 on SX127x chips and DIO1 on SX126x chips.
+#### ```#define LORA_BUSY n```
+For SX126x chips: LoRa BUSY pin. For SX127x: DIO1 pin, or "RADIOLIB_NC" to leave it blank. 
+#### ```#define LORA_TXPWR n```
+LoRa TX power in dBm.
+#### ```#define USE_SX126X```
+Enable this if using the SX126x series of LoRa chips.
+#
+### SSD1306 OLED Display
+Built on the [ThingPulse OLED SSD1306 Library](https://github.com/ThingPulse/esp8266-oled-ssd1306)
+##### ```#define OLED_HEADER "cccc"```
+The message to be displayed at the top of the screen.
+#### ```#define OLED_SDA n``` and ```OLED_SCL n```
+OLED I²C pins.
+#### ```#define OLED_RST n```
+OLED reset pin. Use '-1' if not present or known.
+#
+## Callback Function
+The callback function is executed when data arrives with an ID that the controller is subscribed to. Inside of this function, the user has access to the incoming DataReading. If multiple readings are recieved, the function will be called for each of them. While you should always be brief in interrupt callbacks (ISRs), it's okay to do more in this one.
+## Type Definitions 
+For the moment, my thought is to reserve the first two bits of the type. I might use them in the future to indicate the data size or type (bool, char,  int, float, etc?). This leaves us with 64 possible type definitions. If you have more types to add, please get in touch!
+```
+#define STATUS_T        0  // Status 
+#define TEMP_T          1  // Temperature 
+#define TEMP2_T         2  // Temperature #2
+#define HUMIDITY_T      3  // Relative Humidity 
+#define PRESSURE_T      4  // Atmospheric Pressure 
+#define LIGHT_T         5  // Light (lux) 
+#define SOIL_T          6  // Soil Moisture 
+#define SOIL2_T         7  // Soil Moisture #2 
+#define SOILR_T         8 // Soil Resistance 
+#define SOILR2_T        9 // Soil Resistance #2 
+#define OXYGEN_T        10 // Oxygen 
+#define CO2_T           11 // Carbon Dioxide
+#define WINDSPD_T       12 // Wind Speed
+#define WINDHDG_T       13 // Wind Direction
+#define RAINFALL_T      14 // Rainfall
+#define MOTION_T        15 // Motion
+#define VOLTAGE_T       16 // Voltage
+#define VOLTAGE2_T      17 // Voltage #2
+#define CURRENT_T       18 // Current
+#define CURRENT2_T      19 // Current #2
+#define IT_T            20 // Iterations
+#define LATITUDE_T      21 // GPS Latitude
+#define LONGITUDE_T     22 // GPS Longitude
+#define ALTITUDE_T      23 // GPS Altitude
+#define HDOP_T          24 // GPS HDOP
+#define LEVEL_T         25 // Fluid Level
+#define UV_T            26 // UV
+#define PM1_T           27 // 1 Particles
+#define PM2_5_T         28 // 2.5 Particles
+#define PM10_T          29 // 10 Particles
+#define POWER_T         30 // Power
+#define POWER2_T        31 // Power #2
+#define ENERGY_T        32 // Energy
+#define ENERGY2_T       33 // Energy #2
+```
+## Under the Hood
+```
+typedef struct __attribute__((packed)) DataReading {
+  float d;
+  uint16_t id;
+  uint8_t t;
+} DataReading;
+```
+Each node in the system sends its data inside of a structure called a DataReading. Its global sensor address is represented by an integer 'id', and each type of reading is represented by a single byte 't'.  If a sensor or gateway needs to send multiple DataReadings, then they are sent in an array. A single DataReading.id may have readings of multiple types ('t') associated with it.