opportunistic-xbee/README.md

# | Opportunistic ZigBee |

<!-- toc -->

- [I. Overview](#i-overview)
- [II. File structure](#ii-file-structure)
- [III. Algorithm](#iii-algorithm)
    + [1) Data structure](#1-data-structure)
      - [Discover Request](#discover-request)
      - [Data Message](#data-message)
    + [2) Well](#2-well)
    + [3) Nodes](#3-nodes)

<!-- tocstop -->

## I. Overview



This project aims to design and optimize a solution for an optimistic network using [Arduino](https://www.arduino.cc/) 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 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` request 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;   // wave id (overflows at 255 ; uint8_t)
    uint8_t dist;   // current node's distance
};
```



##### Data Message

The `data` format is sent by nodes to submit messages to the well.

```c++
struct message {
    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 data[]; // 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]