add use-case-diagram to project and move some docs into docs directory

This commit is contained in:
Mika Bomm 2024-10-11 13:29:19 +02:00
parent dde916bd38
commit ce5d574bdf
6 changed files with 319 additions and 88 deletions

View file

@ -1,89 +1,4 @@
# Documentation: Wireless Decentralized Network Prototype
# ApfelNetzwerk
## Table of Contents
1. [Introduction](#introduction)
2. [Requirements](#requirements)
3. [Approaches](#approaches)
- [LoRa/WAN Approach](#lora-wan-approach)
- [BLE Approach](#ble-approach)
- [WLAN Approach](#wlan-approach)
4. [Devices Used and Tested](#devices-used-and-tested)
5. [Development Environments](#development-environments)
6. [Challenges and Issues](#challenges-and-issues)
- [BLE Issues](#ble-issues)
- [LoRa/WAN Issues](#lora-wan-issues)
- [WLAN Issues](#wlan-issues)
- [ESP-MESH](#esp-mesh)
7. [Conclusion](#conclusion)
---
## Introduction
The wireless decentralized network prototype aims to explore the feasibility of creating a low-power communication network for agricultural purposes. This network is designed to facilitate communication between devices over long distances without the need for traditional centralized infrastructure. Several communication protocols and hardware devices were tested, and their performance and feasibility were analyzed to determine the most suitable approach.
## Requirements
- Low-power communication between devices.
- Decentralized structure (no need for a central hub or server).
- Support for long-range communication across large fields (e.g., agricultural applications).
- Flexible communication protocol to support a variety of devices.
## Approaches
The following communication protocols were explored in our prototype development:
### LoRa/WAN Approach
LoRa (Long Range) is a wireless technology that allows for long-distance communication with low power consumption. LoRaWAN adds a network layer to LoRa, enabling devices to connect over large distances with minimal power usage. This protocol is often favored for IoT projects requiring long-range communication.
### BLE Approach
Bluetooth Low Energy (BLE) is a short-range wireless communication protocol designed for low-power devices. It is suitable for small data packets over shorter distances but faces limitations in range compared to other technologies like LoRa.
### WLAN Approach
WLAN (Wireless Local Area Network) communication via ESP-NOW is a low-power communication technology that allows devices to communicate directly without a router. It provides low-latency data transmission but is limited in range.
## Devices Used and Tested
| Device | Communication Type | Notes |
|----------------------|---------------------|----------------------------------------|
| Raspberry Pi Pico | BLE | Stack issues during compilation |
| Rak Wireless | LoRa/WAN | Limited due to single module availability |
| ESP8266 (ESP-NOW) | WLAN | Successful testing with low power usage |
## Development Environments
- **Arduino IDE**: Used to develop and test with **Rak Wireless** and **ESP8266** for both LoRa/WAN and WLAN.
- **VSCode**: Used for developing on **Raspberry Pi Pico** with BLE, though the BLE stack compilation issues halted progress.
## Challenges and Issues
### BLE Issues
- The Bluetooth stack for the **Raspberry Pi Pico** did not compile, resulting in the inability to transmit or receive data.
- No usable data could be exchanged via the BLE approach, which halted further development and testing with BLE for this project.
### LoRa/WAN Issues
- We only had **one LoRa/WAN module**, meaning we could only transmit or receive data, but not establish a complete network.
- Due to the absence of multiple modules, we couldnt properly test the decentralized network capabilities.
### WLAN Issues
- The **ESP-NOW** protocol using **ESP8266** was successful in terms of data transmission and reception with low power consumption.
- However, the **range limitations** are a concern. ESP-NOW can reach about **480 meters in good conditions**, which is significantly less than the **16 km** range achievable with LoRa under ideal conditions.
- For small-scale or prototype testing, WLAN (ESP-NOW) is sufficient, but in large agricultural fields, the shorter range may become a critical issue.
### ESP-MESH
- The continuation of the **ESP-NOW** protocol is done in the **ESP-MESH** protocol however that is only usable the ESP32 variations which we dont have enough of to build a decentralized network, we also had problems talking to the ESP32 which in turn ment that we could not work with it.
## Conclusion
In this project, we explored three different approaches—LoRa/WAN, BLE, and WLAN (ESP-NOW)—for building a decentralized, wireless communication network. Each technology has its own advantages and limitations:
- **LoRa/WAN** offers the best long-range communication but was hindered by the availability of only one module, preventing a full test.
- **BLE** is not viable due to the compilation issues and range limitations.
- **WLAN (ESP-NOW)**, though limited in range compared to LoRa, showed promise for short-distance, low-power communication in prototype testing.
---
- **Hardware** we hat a lot of problems finding the right hardware to do the job because either we experienced unusual errors that we could not solve or the device was incapable of the protocol we are trying to develop with
For future developments, expanding the availability of **LoRa/WAN modules** would be ideal, as it would allow for thorough testing and deployment of a long-range communication network suitable for large-scale agricultural fields. For small areas, **ESP-NOW** may suffice, but further testing is required to determine if it meets all the field requirements.
[Considerations](docs/considerations.md) \
[Setup](docs/SETUP.md)

89
docs/considerations.md Normal file
View file

@ -0,0 +1,89 @@
# Documentation: Wireless Decentralized Network Prototype
## Table of Contents
1. [Introduction](#introduction)
2. [Requirements](#requirements)
3. [Approaches](#approaches)
- [LoRa/WAN Approach](#lora-wan-approach)
- [BLE Approach](#ble-approach)
- [WLAN Approach](#wlan-approach)
4. [Devices Used and Tested](#devices-used-and-tested)
5. [Development Environments](#development-environments)
6. [Challenges and Issues](#challenges-and-issues)
- [BLE Issues](#ble-issues)
- [LoRa/WAN Issues](#lora-wan-issues)
- [WLAN Issues](#wlan-issues)
- [ESP-MESH](#esp-mesh)
7. [Conclusion](#conclusion)
---
## Introduction
The wireless decentralized network prototype aims to explore the feasibility of creating a low-power communication network for agricultural purposes. This network is designed to facilitate communication between devices over long distances without the need for traditional centralized infrastructure. Several communication protocols and hardware devices were tested, and their performance and feasibility were analyzed to determine the most suitable approach.
## Requirements
- Low-power communication between devices.
- Decentralized structure (no need for a central hub or server).
- Support for long-range communication across large fields (e.g., agricultural applications).
- Flexible communication protocol to support a variety of devices.
## Approaches
The following communication protocols were explored in our prototype development:
### LoRa/WAN Approach
LoRa (Long Range) is a wireless technology that allows for long-distance communication with low power consumption. LoRaWAN adds a network layer to LoRa, enabling devices to connect over large distances with minimal power usage. This protocol is often favored for IoT projects requiring long-range communication.
### BLE Approach
Bluetooth Low Energy (BLE) is a short-range wireless communication protocol designed for low-power devices. It is suitable for small data packets over shorter distances but faces limitations in range compared to other technologies like LoRa.
### WLAN Approach
WLAN (Wireless Local Area Network) communication via ESP-NOW is a low-power communication technology that allows devices to communicate directly without a router. It provides low-latency data transmission but is limited in range.
## Devices Used and Tested
| Device | Communication Type | Notes |
|----------------------|---------------------|----------------------------------------|
| Raspberry Pi Pico | BLE | Stack issues during compilation |
| Rak Wireless | LoRa/WAN | Limited due to single module availability |
| ESP8266 (ESP-NOW) | WLAN | Successful testing with low power usage |
## Development Environments
- **Arduino IDE**: Used to develop and test with **Rak Wireless** and **ESP8266** for both LoRa/WAN and WLAN.
- **VSCode**: Used for developing on **Raspberry Pi Pico** with BLE, though the BLE stack compilation issues halted progress.
## Challenges and Issues
### BLE Issues
- The Bluetooth stack for the **Raspberry Pi Pico** did not compile, resulting in the inability to transmit or receive data.
- No usable data could be exchanged via the BLE approach, which halted further development and testing with BLE for this project.
### LoRa/WAN Issues
- We only had **one LoRa/WAN module**, meaning we could only transmit or receive data, but not establish a complete network.
- Due to the absence of multiple modules, we couldnt properly test the decentralized network capabilities.
### WLAN Issues
- The **ESP-NOW** protocol using **ESP8266** was successful in terms of data transmission and reception with low power consumption.
- However, the **range limitations** are a concern. ESP-NOW can reach about **480 meters in good conditions**, which is significantly less than the **16 km** range achievable with LoRa under ideal conditions.
- For small-scale or prototype testing, WLAN (ESP-NOW) is sufficient, but in large agricultural fields, the shorter range may become a critical issue.
### ESP-MESH
- The continuation of the **ESP-NOW** protocol is done in the **ESP-MESH** protocol however that is only usable the ESP32 variations which we dont have enough of to build a decentralized network, we also had problems talking to the ESP32 which in turn ment that we could not work with it.
## Conclusion
In this project, we explored three different approaches—LoRa/WAN, BLE, and WLAN (ESP-NOW)—for building a decentralized, wireless communication network. Each technology has its own advantages and limitations:
- **LoRa/WAN** offers the best long-range communication but was hindered by the availability of only one module, preventing a full test.
- **BLE** is not viable due to the compilation issues and range limitations.
- **WLAN (ESP-NOW)**, though limited in range compared to LoRa, showed promise for short-distance, low-power communication in prototype testing.
---
- **Hardware** we hat a lot of problems finding the right hardware to do the job because either we experienced unusual errors that we could not solve or the device was incapable of the protocol we are trying to develop with
For future developments, expanding the availability of **LoRa/WAN modules** would be ideal, as it would allow for thorough testing and deployment of a long-range communication network suitable for large-scale agricultural fields. For small areas, **ESP-NOW** may suffice, but further testing is required to determine if it meets all the field requirements.

34
docs/use_case_diagram Normal file
View file

@ -0,0 +1,34 @@
digraph {
node [color=lightgrey fontname=Arial shape=ellipse style=filled]
edge [fontname=Arial]
subgraph cluster_sensor_nodes {
color=blue label="Ad-hoc Network" style=dashed
"Sensor Nodes 1" [label="ESP8266 Nodes
(Temperature Sensors)"]
"Sensor Nodes 2" [label="ESP8266 Nodes
(Temperature Sensors)"]
"Sensor Nodes 3" [label="ESP8266 Nodes
(Temperature Sensors)"]
"Sensor Nodes 4" [label="ESP8266 Nodes
(Temperature Sensors)"]
}
"Exit Node" [label="ESP8266
(Exit Node)"]
"Backend Server" [label="Rust Backend
(on PC)"]
"Postgres DB" [label="PostgreSQL
Database"]
Frontend [label="Frontend
(Web Browser/App)"]
API [label=API]
User [label=User]
"Sensor Nodes 1" -> "Exit Node" [label="Sends Data"]
"Sensor Nodes 2" -> "Exit Node" [label="Sends Data"]
"Sensor Nodes 3" -> "Exit Node" [label="Sends Data"]
"Sensor Nodes 4" -> "Sensor Nodes 3" [label="Sends Data"]
"Exit Node" -> "Backend Server" [label="Sends Data over WLAN"]
"Backend Server" -> "Postgres DB" [label="Persists Data in DB"]
"Backend Server" -> API [label="Provides API Endpoints"]
Frontend -> API [label="API Calls to Backend"]
User -> Frontend [label="Interacts with Frontend"]
}

45
docs/use_case_diagram.py Normal file
View file

@ -0,0 +1,45 @@
import graphviz
# Create a new Digraph for the use case diagram
use_case = graphviz.Digraph(format='svg')
# Define the style for nodes and edges
use_case.attr('node', shape='ellipse', style='filled', color='lightgrey', fontname='Arial')
use_case.attr('edge', fontname='Arial')
# Define the nodes (Actors and Systems)
with use_case.subgraph(name='cluster_sensor_nodes') as c:
c.attr(style='dashed', color='blue', label='Ad-hoc Network')
c.node('Sensor Nodes 1', 'ESP8266 Nodes\n(Temperature Sensors)')
c.node('Sensor Nodes 2', 'ESP8266 Nodes\n(Temperature Sensors)')
c.node('Sensor Nodes 3', 'ESP8266 Nodes\n(Temperature Sensors)')
c.node('Sensor Nodes 4', 'ESP8266 Nodes\n(Temperature Sensors)')
use_case.node('Exit Node', 'ESP8266\n(Exit Node)')
use_case.node('Backend Server', 'Rust Backend\n(on PC)')
use_case.node('Postgres DB', 'PostgreSQL\nDatabase')
use_case.node('Frontend', 'Frontend\n(Web Browser/App)')
use_case.node('API', 'API')
use_case.node('User', 'User')
# Add edges between nodes to show interactions
use_case.edge('Sensor Nodes 1', 'Exit Node', label='Sends Data')
use_case.edge('Sensor Nodes 2', 'Exit Node', label='Sends Data')
use_case.edge('Sensor Nodes 3', 'Exit Node', label='Sends Data')
use_case.edge('Sensor Nodes 4', 'Sensor Nodes 3', label='Sends Data')
use_case.edge('Exit Node', 'Backend Server', label='Sends Data over WLAN')
use_case.edge('Backend Server', 'Postgres DB', label='Persists Data in DB')
use_case.edge('Backend Server', 'API', label='Provides API Endpoints')
use_case.edge('Frontend', 'API', label='API Calls to Backend')
use_case.edge('User', 'Frontend', label='Interacts with Frontend')
# Render the use case diagram as an SVG
use_case.render('docs/use_case_diagram')
#use_case.render('/mnt/data/use_case_diagram')
# Output the file path for user to download
"docs/use_case_diagram.svg"
#"/mnt/data/use_case_diagram.svg"

148
docs/use_case_diagram.svg Normal file
View file

@ -0,0 +1,148 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 12.1.1 (0)
-->
<!-- Pages: 1 -->
<svg width="750pt" height="536pt"
viewBox="0.00 0.00 750.25 535.56" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 531.56)">
<polygon fill="white" stroke="none" points="-4,4 -4,-531.56 746.25,-531.56 746.25,4 -4,4"/>
<g id="clust1" class="cluster">
<title>cluster_sensor_nodes</title>
<polygon fill="none" stroke="blue" stroke-dasharray="5,2" points="8,-314.83 8,-519.56 716,-519.56 716,-314.83 8,-314.83"/>
<text text-anchor="middle" x="362" y="-502.26" font-family="Times,serif" font-size="14.00">Ad&#45;hoc Network</text>
</g>
<!-- Sensor Nodes 1 -->
<g id="node1" class="node">
<title>Sensor Nodes 1</title>
<ellipse fill="lightgrey" stroke="lightgrey" cx="362" cy="-458.38" rx="109.42" ry="27.93"/>
<text text-anchor="middle" x="362" y="-460.83" font-family="Arial" font-size="14.00">ESP8266 Nodes</text>
<text text-anchor="middle" x="362" y="-445.08" font-family="Arial" font-size="14.00">(Temperature Sensors)</text>
</g>
<!-- Exit Node -->
<g id="node5" class="node">
<title>Exit Node</title>
<ellipse fill="lightgrey" stroke="lightgrey" cx="362" cy="-243.15" rx="59.04" ry="27.93"/>
<text text-anchor="middle" x="362" y="-245.6" font-family="Arial" font-size="14.00">ESP8266</text>
<text text-anchor="middle" x="362" y="-229.85" font-family="Arial" font-size="14.00">(Exit Node)</text>
</g>
<!-- Sensor Nodes 1&#45;&gt;Exit Node -->
<g id="edge1" class="edge">
<title>Sensor Nodes 1&#45;&gt;Exit Node</title>
<path fill="none" stroke="black" d="M362,-430.37C362,-392.98 362,-325.25 362,-282.6"/>
<polygon fill="black" stroke="black" points="365.5,-282.79 362,-272.79 358.5,-282.79 365.5,-282.79"/>
<text text-anchor="middle" x="397.25" y="-345.34" font-family="Arial" font-size="14.00">Sends Data</text>
</g>
<!-- Sensor Nodes 2 -->
<g id="node2" class="node">
<title>Sensor Nodes 2</title>
<ellipse fill="lightgrey" stroke="lightgrey" cx="599" cy="-458.38" rx="109.42" ry="27.93"/>
<text text-anchor="middle" x="599" y="-460.83" font-family="Arial" font-size="14.00">ESP8266 Nodes</text>
<text text-anchor="middle" x="599" y="-445.08" font-family="Arial" font-size="14.00">(Temperature Sensors)</text>
</g>
<!-- Sensor Nodes 2&#45;&gt;Exit Node -->
<g id="edge2" class="edge">
<title>Sensor Nodes 2&#45;&gt;Exit Node</title>
<path fill="none" stroke="black" d="M569.94,-431.23C526.3,-391.97 443.98,-317.91 397.07,-275.71"/>
<polygon fill="black" stroke="black" points="399.64,-273.31 389.87,-269.22 394.96,-278.51 399.64,-273.31"/>
<text text-anchor="middle" x="543.18" y="-345.34" font-family="Arial" font-size="14.00">Sends Data</text>
</g>
<!-- Sensor Nodes 3 -->
<g id="node3" class="node">
<title>Sensor Nodes 3</title>
<ellipse fill="lightgrey" stroke="lightgrey" cx="171" cy="-350.77" rx="109.42" ry="27.93"/>
<text text-anchor="middle" x="171" y="-353.22" font-family="Arial" font-size="14.00">ESP8266 Nodes</text>
<text text-anchor="middle" x="171" y="-337.47" font-family="Arial" font-size="14.00">(Temperature Sensors)</text>
</g>
<!-- Sensor Nodes 3&#45;&gt;Exit Node -->
<g id="edge3" class="edge">
<title>Sensor Nodes 3&#45;&gt;Exit Node</title>
<path fill="none" stroke="black" d="M214.36,-324.68C233.63,-313.63 256.62,-300.58 277.5,-289.08 288.98,-282.76 301.41,-276.07 313.12,-269.84"/>
<polygon fill="black" stroke="black" points="314.64,-272.99 321.83,-265.21 311.36,-266.8 314.64,-272.99"/>
<text text-anchor="middle" x="312.75" y="-291.53" font-family="Arial" font-size="14.00">Sends Data</text>
</g>
<!-- Sensor Nodes 4 -->
<g id="node4" class="node">
<title>Sensor Nodes 4</title>
<ellipse fill="lightgrey" stroke="lightgrey" cx="125" cy="-458.38" rx="109.42" ry="27.93"/>
<text text-anchor="middle" x="125" y="-460.83" font-family="Arial" font-size="14.00">ESP8266 Nodes</text>
<text text-anchor="middle" x="125" y="-445.08" font-family="Arial" font-size="14.00">(Temperature Sensors)</text>
</g>
<!-- Sensor Nodes 4&#45;&gt;Sensor Nodes 3 -->
<g id="edge4" class="edge">
<title>Sensor Nodes 4&#45;&gt;Sensor Nodes 3</title>
<path fill="none" stroke="black" d="M136.85,-430.18C142.27,-417.74 148.77,-402.79 154.65,-389.3"/>
<polygon fill="black" stroke="black" points="157.81,-390.82 158.59,-380.26 151.39,-388.03 157.81,-390.82"/>
<text text-anchor="middle" x="186" y="-399.15" font-family="Arial" font-size="14.00">Sends Data</text>
</g>
<!-- Backend Server -->
<g id="node6" class="node">
<title>Backend Server</title>
<ellipse fill="lightgrey" stroke="lightgrey" cx="362" cy="-135.54" rx="70.71" ry="27.93"/>
<text text-anchor="middle" x="362" y="-137.99" font-family="Arial" font-size="14.00">Rust Backend</text>
<text text-anchor="middle" x="362" y="-122.24" font-family="Arial" font-size="14.00">(on PC)</text>
</g>
<!-- Exit Node&#45;&gt;Backend Server -->
<g id="edge5" class="edge">
<title>Exit Node&#45;&gt;Backend Server</title>
<path fill="none" stroke="black" d="M362,-214.96C362,-202.76 362,-188.16 362,-174.88"/>
<polygon fill="black" stroke="black" points="365.5,-175.16 362,-165.16 358.5,-175.16 365.5,-175.16"/>
<text text-anchor="middle" x="434" y="-183.92" font-family="Arial" font-size="14.00">Sends Data over WLAN</text>
</g>
<!-- Postgres DB -->
<g id="node7" class="node">
<title>Postgres DB</title>
<ellipse fill="lightgrey" stroke="lightgrey" cx="301" cy="-27.93" rx="63.82" ry="27.93"/>
<text text-anchor="middle" x="301" y="-30.38" font-family="Arial" font-size="14.00">PostgreSQL</text>
<text text-anchor="middle" x="301" y="-14.63" font-family="Arial" font-size="14.00">Database</text>
</g>
<!-- Backend Server&#45;&gt;Postgres DB -->
<g id="edge6" class="edge">
<title>Backend Server&#45;&gt;Postgres DB</title>
<path fill="none" stroke="black" d="M321.4,-112.2C313.61,-105.96 306.5,-98.42 302,-89.61 298.56,-82.88 296.97,-75.16 296.46,-67.53"/>
<polygon fill="black" stroke="black" points="299.97,-67.66 296.43,-57.68 292.97,-67.69 299.97,-67.66"/>
<text text-anchor="middle" x="360.5" y="-76.31" font-family="Arial" font-size="14.00">Persists Data in DB</text>
</g>
<!-- API -->
<g id="node9" class="node">
<title>API</title>
<ellipse fill="lightgrey" stroke="lightgrey" cx="523" cy="-27.93" rx="27" ry="18"/>
<text text-anchor="middle" x="523" y="-22.51" font-family="Arial" font-size="14.00">API</text>
</g>
<!-- Backend Server&#45;&gt;API -->
<g id="edge7" class="edge">
<title>Backend Server&#45;&gt;API</title>
<path fill="none" stroke="black" d="M393.17,-110.2C401.59,-103.56 410.67,-96.34 419,-89.61 427.53,-82.72 428.88,-79.96 438,-73.86 454.73,-62.68 474.56,-52.06 490.86,-43.96"/>
<polygon fill="black" stroke="black" points="492.17,-47.21 499.63,-39.68 489.11,-40.92 492.17,-47.21"/>
<text text-anchor="middle" x="508.5" y="-76.31" font-family="Arial" font-size="14.00">Provides API Endpoints</text>
</g>
<!-- Frontend -->
<g id="node8" class="node">
<title>Frontend</title>
<ellipse fill="lightgrey" stroke="lightgrey" cx="605" cy="-135.54" rx="94.58" ry="27.93"/>
<text text-anchor="middle" x="605" y="-137.99" font-family="Arial" font-size="14.00">Frontend</text>
<text text-anchor="middle" x="605" y="-122.24" font-family="Arial" font-size="14.00">(Web Browser/App)</text>
</g>
<!-- Frontend&#45;&gt;API -->
<g id="edge8" class="edge">
<title>Frontend&#45;&gt;API</title>
<path fill="none" stroke="black" d="M598.76,-107.2C595.34,-96.13 590.27,-83.67 583,-73.86 574.99,-63.06 563.67,-53.65 553.01,-46.28"/>
<polygon fill="black" stroke="black" points="555.09,-43.45 544.8,-40.92 551.26,-49.32 555.09,-43.45"/>
<text text-anchor="middle" x="655.22" y="-76.31" font-family="Arial" font-size="14.00">API Calls to Backend</text>
</g>
<!-- User -->
<g id="node10" class="node">
<title>User</title>
<ellipse fill="lightgrey" stroke="lightgrey" cx="605" cy="-243.15" rx="29.61" ry="18"/>
<text text-anchor="middle" x="605" y="-237.73" font-family="Arial" font-size="14.00">User</text>
</g>
<!-- User&#45;&gt;Frontend -->
<g id="edge9" class="edge">
<title>User&#45;&gt;Frontend</title>
<path fill="none" stroke="black" d="M605,-224.71C605,-211.29 605,-192.22 605,-175.25"/>
<polygon fill="black" stroke="black" points="608.5,-175.45 605,-165.45 601.5,-175.45 608.5,-175.45"/>
<text text-anchor="middle" x="673.62" y="-183.92" font-family="Arial" font-size="14.00">Interacts with Frontend</text>
</g>
</g>
</svg>

After

Width:  |  Height:  |  Size: 8.3 KiB