init readme | init well codebase

.gitignore

@@ -0,0 +1 @@
+.vscode

README.md

@@ -0,0 +1,103 @@
+# | Opportunistic ZigBee |
+
+
+
+## I. Overview
+
+
+
+This project aims to design and optimize a solution for an optimistic network using Arduino and [XBee](https://www.digi.com/xbee).
+
+The base scenario takes place in a mesh network of similar <u>nodes</u> ; each being subject to real-time motion. Every node has to transmit logging data (*i.e. periodically*) to a special node : the **well ** ; the well is unique in the network and is the only one that actually receives data, every other node has the same source code and behavior.
+
+
+
+**Main goals :**
+
+1. Optimize network usage : limit duplicates and retransmissions
+2. Maximize relative space-awareness throughout time : avoid losses and retransmissions
+3. [TODO]
+
+
+
+**Vocabulary**
+
+- **distance** - the relative distance to the well. The well has a distance of 0, its direct neighbors a distance of 1 and so on.  
+
+- **wave** - a distance propagation of distances throughout the network that share a common source.
+
+
+
+ 
+
+----
+
+## II. File structure
+
+
+
+The code is split over 2 sub-projects :
+
+- the **well**, located inside `well/main/`.
+- **nodes**, located in the `node/main` folder.
+
+> The project bundles its required libraries - for compatibility purposes - inside the `libraries/` folder. Symbolic links make them available for each sub-project.
+
+
+
+
+
+----
+
+## III. Algorithm
+
+
+
+#### 1) Data structure
+
+Every communication follows a consistent data format which can be split into 2 types ; the first *byte* (*i.e. called opcode*) allows receivers to identity the data type.
+
+
+
+##### Discover Request
+
+The `discover` data format is used to propagate the relative distances throughout the network. The **well** is the only node that can initiate a discover request, other nodes only make sure of the propagation.
+
+```c++
+struct discover {
+    uint8_t opcode; // opcode = 0
+    uint8_t wave;   // id de la wave
+    uint8_t dist;   // current node's distance
+};
+```
+
+
+
+##### Data Message
+
+The `data` format is sent by nodes to submit messagesca to the well.
+
+```c++
+struct data {
+    uint8_t opcode;    // opcode = 1
+    uint8_t dist;      // distance of the last sender
+    uint8_t ttl;       // time to live default = 10
+    uint8_t size;      // size of message in bytes
+    uint8_t message[]; // actual message
+};
+```
+
+
+
+#### 2) Well
+
+The well features 2 routines :
+
+1. Send <u>[discover](#discover-request)</u> requests periodically
+2. Listen for incoming [data](#data-message).
+
+
+
+#### 3) Nodes
+
+[TODO]

well/main/libraries

@@ -0,0 +1 @@
+../../libraries

well/main/main.ino

@@ -0,0 +1,59 @@
+#include <Wire.h>
+#include <XBee.h>
+#include "protocol.h"
+#include <LiquidCrystal_I2C.h>
+
+// CONSTANTS
+#define WAVE_TIMEOUT 5000 // send wave every (in ms)
+
+// Peripherals
+LiquidCrystal_I2C screen(0x27, 16, 2);
+XBee xbee = XBee();
+
+// ACTUAL DATA
+uint8_t wave_id = 250;
+struct discover req = {0,0,0};
+
+void setup() {
+  Serial.begin(38400);
+  Serial.println("+ ready");
+
+  screen.begin();
+  screen.backlight();
+
+  xbee.setSerial(Serial1);
+  Serial1.begin(38400);
+
+  // xbee.begin(38400);
+}
+
+void loop() {
+
+  delay(WAVE_TIMEOUT);
+
+  // increment wave id (will overflow from 255 to 0)
+  req.wave = ++wave_id; // set wave id
+
+  screen.clear();
+  screen.print("+ wave");
+  screen.print(req.wave);
+
+  uint8_t payload[3] = {req.opcode, req.wave, req.dist};
+
+  XBeeAddress64 addr64 = XBeeAddress64(0x00000000, 0x0000FFFF);
+  Tx64Request tx = Tx64Request(addr64, payload, sizeof(payload));
+  xbee.send(tx);
+
+  /* Check the status of our sent payload (not mandatory)
+
+    TxStatusResponse txStatus = TxStatusResponse();
+    xbee.readPacket();
+    if( xbee.getResponse().isAvailable() ){
+      if( xbee.getResponse().getApiId() == TX_STATUS_RESPONSE ){
+            xbee.getResponse().getTxStatusResponse(txStatus);
+            txStatus.isSuccess() && Serial.println(" ... sent") || Serial.println(" ... failed");
+      }
+    }
+
+  */
+}

well/main/protocol.h

@@ -0,0 +1,52 @@
+#ifndef _PROTOCOL_H_
+	#define _PROTOCOL_H_
+
+	#define DISCOVER_TTL 10000
+	#define DISCOVER_SIZE sizeof(int)*2
+
+	// discover request (c.f. class node)
+	struct discover {
+		uint8_t opcode; // opcode = 0
+		uint8_t wave;   // id de la wave
+		uint8_t dist;   // current node's distance
+	};
+
+
+	struct data {
+		uint8_t opcode;    // opcode = 1
+		uint8_t dist;      // distance of the last sender
+		uint8_t ttl;       // time to live default = 10
+		uint8_t size;      // size of message in bytes
+		uint8_t message[]; // actual message
+	};
+
+	// A <node> object is held by each node which values are determined thanks
+	// to the DISCOVER requests it receives; each node broadcasts a DISCOVER
+	// request every DISCOVER_TTL milliseconds
+    class node{
+		private:
+			// unique id of the node : MAC ADDR
+			int id;
+
+			// last received wave id
+			uint8_t last_wave;
+
+			// relative node-distance to the well
+			// WELL                  : dist = 0
+			// NODE1 can reach WELL  : dist = 1
+			// NODE2 can reach NODE1 : dist = 2
+			// and so on...
+			uint8_t dist;
+
+		public:
+
+			// send a discover request
+			bool discover();
+
+			// update the current node according to a (received)
+			// discover request
+			bool update(struct discover req);
+    };
+
+
+#endif