Embedded Distributed Averaging System (EDAS)

This is a distributed embedded system, which returns the average of the temperatures measured by its components. The Average Consensus algorithm is executed on Thunderboard Sense 2 EFR32MG24 devices.

Description
Requirements
Configuration
Compilation and deployment
Documentation
Usage
Status
License
Authors

Description

EDAS is a distributed embedded system implemented on Thunderboard Sense 2 EFR32MG24 devices (from now on called nodes). Every node has a thermistor to measure the air temperature, as well as a TX/RX antenna to exchange messages wirelessly. Average Consensus algorithm relies on iterative exchange of messages between the nodes, until all nodes converge to a fixed point (which is the average of all measured temperatures).

Warning
The graph of the commuting nodes (i.e., the graph with an edge between every pair of nodes which can exchange messages, based on the system's topology) has to be connected, i.e., a path has to exist from any node to any other node in the graph.

The user communicates with the system via console commands given through a serial protocol. Thanks to its distributed nature, the user can connect, start the averaging process and get the result from any node of the network.

Requirements

Thunderboard Sense 2 EFR32MG24 devices which will be used as the nodes of the distributed network.
Efficient power supply for all the nodes of the network. The average temperature can be returned only if all nodes are operational.
Simplicity Studio 5 (tested) or newer (adaptations may be required).
Gecko SDK 4.1.3 (tested) or newer (adaptations may be required). It can be downloaded directly from the Simplicity Studio.
GNU ARM Toolchain 7.2.1 (tested) or newer (adaptations may be required). It can be downloaded directly from the Simplicity Studio.

Configuration

Configuration of the system has to take place before its deployment, because the user cannot make any changes at runtime. All configuration parameters are located in config/app_config.h and config/app_config.c files.

BOARD_ID: The (unique) identity of every node. It gets values from $0$ to NUM_OF_BOARDS$-1$ (also see the Compilation and deployment section below).
NUM_OF_BOARDS: The total number of nodes which comprise the system.
graph: The graph of the commuting nodes. For every pair of nodes $i$ and $j$, graph[i][j] has to be set true if node $i$ can exchange messages with node $j$, or if $i=j$. Otherwise, it has to be set false.
LENGTH_OF_BATON_PATH: Set this parameter equal to the length of the baton_path array (see below).
baton_path: It should contain a sequence of nodes which create a path and obey the following rules:
- RULE $1$: The array should include every node at least once.
- RULE $2$: Every node should have an edge (according to the graph) with its previous and next node (according to their ordering in the array).
- RULE $3$: The last node of the array should have an edge with the first one.
- RULE $4$: Every subarray of $2$ or more elements should be unique. For example, sequences like $...1,2,3...$ and $...1,2,4...$ should not exist in the same path.
MIN_TEMPERATURE: The minimum temperature that can be possibly measured (in Celsius degrees).
STOP_THRESHOLD: Determines when the execution of the Average Consensus algorithm will be terminated. More in detail, the execution will be terminated if $\left|\text{currentState}_i - \text{previousState}_i\right|\leq$STOP_THRESHOLD for every node $i=0,...,$NUM_OF_BOARDS$-1$. A smaller threshold results in a better estimation of the average but also more iterations of the algorithm before it terminates.
USE_EM_TRANSITION_LEDS: Set to $0$ to deactivate the LEDs of the nodes. Set to $1$ to activate the LEDs of the nodes (red indicates an awake and fully-functional node in EM0 mode, green indicates a node in EM1 sleep mode). This parameter plays no role on the energy states & transitions of the nodes, but only on the activation/deactivation of the indicative LEDs.
SIMULATE_TEMPERATURE_MEASUREMENTS: Set to $0$ to use the actual temperatures measured by the thermistors of the nodes. Set to $1$ to use some predetermined (by the simulated_temperatures parameter, see below) values for the temperatures (mainly for testing purposes).
simulated_temperatures: This array has a length equal to NUM_OF_BOARDS. The element at position $i$ is the (simulated) temperature used by the $i$-th node.

Note
If SIMULATE_TEMPERATURE_MEASUREMENTS$=0$, then the contents of simulated_temperatures are useless.

Compilation and deployment

To compile and deploy the project, follow the instructions below:

Download and install the Simplicity Studio software (see Requirements section).
From the Simplicity Studio, install a suitable version of the Gecko SDK and the GNU ARM Toolchain (see Requirements section).
Clone the project and import it to the Simplicity Studio (File - Import).
Configure the imported project appropriately (see Configuration section).
Set the parameter BOARD_ID to $0,...,$NUM_OF_BOARDS$-1$ successively. For each value:
- Build the project (Project - Build Project).
- Flash the arised binary file (edas.hex) to the respective Thunderboard device:
  - Connect the Thunderboard device to the computer via USB cable.
  - Right click on the .hex file (in Simplicity Studio's project explorer)
  - Flash to Device - select device - Program.

Usage

After programming the devices, place them at their positions and ensure that they are connected to a robust power supply. Moreover, ensure that their locations come in agreement with the graph variable.

Warning
While at least one node of the system is not working due to power outage, the system will not be able to estimate the average temperature. It is very important to ensure that there is sufficient power supply for all nodes.
Connect to any node of the system via an appropriate USB cable (USB-A to micro-USB) and establish a connection via the serial port (115200 bps, 8 bits, no parity, 1 stop bit).
Type help to see a list of available commands.
Type info to see the unique ID (given from the manufacturer) of the connected device.
Type average to start the execution of Average Consensus on the system. All boards will wake up and execute the iterations of the algorithm. Until its completion, a log with information will be printed on the screen. Finally, when it is terminated all boards will sleep and the estimated average temperature will be returned in the following form:

...

=====================================================
Estimated average temperature: 20.36 degrees Celsius.
=====================================================

Now going to sleep...

Documentation

To generate detailed documentation of the source code, the Doxygen tool can be utilized. Execute it from the project's directory and use Doxyfile.cfg for configuration.

Notice that the implementation of the distributed Average Consensus algorithm and the state machine of the system can be found in the /app/ folder, as well as in the config/app_config.h and config/app_config.c files. The remaining source files are mostly related to the SDK and its interaction with the implemented system.

Status

Under maintenance.

License

Distributed under the GPL-3.0 License. See LICENSE for more information.

Authors

Georgios Apostolakis

giorgapost / edas