add more comments

collar.cpp

@@ -48,13 +48,19 @@ TinyLoRa lora = TinyLoRa(2, 10, 9);
 TinyGPSPlus gps;
 SoftwareSerial ss(6, 7);
 
-// Pinout for Adafruit Feather M0 LoRa
+/****************************************************
-//TinyLoRa lora = TinyLoRa(3, 8, 4);
+ * Track each pair of X and Y coordinates
-
+ * - arrays are used by the pnpoly function
+ ***************************************************/
 const uint8_t N_POLY_MAX=100;
 float polyx[N_POLY_MAX];
 float polyy[N_POLY_MAX];
 int n_poly=0;
+
+/****************************************************
+ * Add a coordinate to the arrays
+ * - stores a total of N_POLY_MAX pairs
+ ***************************************************/
 int push_vert(float x, float y) {
   if(n_poly>N_POLY_MAX)
     return 0;
@@ -63,9 +69,17 @@ int push_vert(float x, float y) {
   n_poly++;
   return 1;
 }
+/****************************************************
+ * 'Clear' pairs of coordinates
+ ***************************************************/
 void clear_verts() {
   n_poly=0;
 }
+/****************************************************
+ * Check a pair of coordinates against two lists
+ * of vertices
+ * - https://wrf.ecse.rpi.edu//Research/Short_Notes/pnpoly.html
+ ***************************************************/
 int pnpoly(int nvert, float *vertx, float *verty, float testx, float testy)
 { //from stack overflow, check that coordinate is within polygon boundary
   int i, j, c = 0;
@@ -76,9 +90,15 @@ int pnpoly(int nvert, float *vertx, float *verty, float testx, float testy)
   }
   return c;
 }
+/****************************************************
+ * Test a coordinate against all vertices
+ ***************************************************/
 int check_bounds(float x, float y) {
   return pnpoly(n_poly, polyx, polyy, x, y);
 }
+/****************************************************
+ * nanopb callback
+ ***************************************************/
 bool Fenceless_Coordinates_callback(pb_istream_t *stream, const pb_field_iter_t *field, void **arg) {
   Serial.println("Called");
   while(stream->bytes_left) {
@@ -90,6 +110,12 @@ bool Fenceless_Coordinates_callback(pb_istream_t *stream, const pb_field_iter_t
     return true;
   }
 }
+/****************************************************
+ * Load coordinates from protobuff stream
+ * - currently a maximum of 10 coordinates
+ * - loading arrays in nanopb does not appear
+ *   to work.
+ ***************************************************/
 void import_protobuf(uint8_t *protobuffer, uint32_t size) {
   Fenceless_Coordinates m;
 	pb_istream_t stream = pb_istream_from_buffer(protobuffer, size);
@@ -119,6 +145,9 @@ void import_protobuf(uint8_t *protobuffer, uint32_t size) {
       push_vert(m.coord0.x, m.coord0.y);
   }
 }
+/****************************************************
+ * nanopb callback
+ ***************************************************/
 bool Fenceless_Coordinates_encode(pb_ostream_t *stream, const pb_field_iter_t *field, void * const * arg) {
   Serial.println("Encode called");
   return false;
@@ -128,6 +157,9 @@ bool Fenceless_Coordinates_encode(pb_ostream_t *stream, const pb_field_iter_t *f
   }
   return pb_encode(stream, Fenceless_Coordinate_fields, field);
 }
+/****************************************************
+ * live test of protobuf
+ ***************************************************/
 void test() {
   Serial.println("Testing protobuf");
   uint8_t buffer[100] = {0};
@@ -139,21 +171,27 @@ void test() {
   }
   import_protobuf(buffer, sizeof(buffer));
 }
-int recieved = 0;
+/****************************************************
-void on_recieve(int n) {
+ * Initialize values
-  recieved = 1;
+ ***************************************************/
-}
 void setup()
 {
+  // give GPS time to start up
   delay(1000);
-  // start  uart
+ /****************************************************
+  * Configure USART
+  * - onboard serial to usb
+  * - software serial connected to GPS module
+  ***************************************************/
   Serial.begin(9600);
-  // start software uart for GPS
   ss.begin(4800);
   while (! Serial);
 
-  delay(1000);
+ /****************************************************
-  // Initialize pin LED_BUILTIN as an output
+  * Configure USART
+  * - onboard serial to usb
+  * - software serial connected to GPS module
+  ***************************************************/
   pinMode(LED_BUILTIN, OUTPUT);
 
   // Initialize GPS - GPS does not work indoors - This will block until GPS available 
@@ -169,11 +207,15 @@ void setup()
   //   }
   // }
 
-  // Initialize LoRa
+ /****************************************************
+  * Configure LoRa
+  * - set to multi-channel
+  * - set datarate
+  * - start communication
+  * - set transmission power
+  ***************************************************/
   Serial.print("Starting LoRa...");
-  // define multi-channel sending
   lora.setChannel(MULTI);
-  // set datarate
   lora.setDatarate(SF12BW125); // SF7BW125
   if(!lora.begin())
   {
@@ -181,15 +223,12 @@ void setup()
     Serial.println("Check your radio");
     while(true);
   }
-
-  // Optional set transmit power. If not set default is +17 dBm.
-  // Valid options are: -80, 1 to 17, 20 (dBm).
-  // For safe operation in 20dBm: your antenna must be 3:1 VWSR or better
-  // and respect the 1% duty cycle.
-
   lora.setPower(15); // 1
 
-  // start 1 second timer
+ /****************************************************
+  * Configure Timer Interrupt
+  * - set for one second intervals
+  ***************************************************/
   TCCR1A = 0;
   TCCR1B = 0;
 
@@ -200,7 +239,15 @@ void setup()
   Serial.println("OK");
 }
 
-// TIMER1_OVF_vect is called once per second
+/****************************************************
+ * Timer interrupt service routine
+ * - this logic could be moved to loop()
+ *   and be controlled by a state variable
+ * - generates a protobuf stream with current
+ *   GPS coordinate values
+ * - sends buffer over LoRaWAN on a given
+ *   send interval
+ ***************************************************/
 int sendCounter = 0;
 ISR(TIMER1_OVF_vect) {
   digitalWrite(LED_BUILTIN, sendCounter%2);
@@ -240,6 +287,11 @@ ISR(TIMER1_OVF_vect) {
   } 
   sendCounter--;
 }
+/****************************************************
+ * Main loop
+ * - feeds data to GPS module as it is made
+ *   available
+ ***************************************************/
 void loop()
 {
   // For later when recieving from gateway is implemented