From 8b08a0552bfa875b9850fcde42c02ddd24bb4bb5 Mon Sep 17 00:00:00 2001 From: Lars Toenning Date: Fri, 8 Sep 2023 11:08:31 +0200 Subject: [PATCH] docs(daisi): Add documentation Co-authored-by: Thorben Seeland Co-authored-by: Patrick Laskowski --- daisi/docs/getting_started.md | 25 - daisi/docs/glossary.md | 1 - daisi/docs/introduction.md | 16 - daisi/docs/logging.md | 21 - daisi/docs/minhton-ns3/esearch.md | 162 ----- daisi/docs/minhton-ns3/scenariofile.md | 126 ---- daisi/docs/natter-ns3/logging.md | 3 - daisi/docs/natter-ns3/scenariofile.md | 42 -- daisi/docs/network.md | 34 - daisi/docs/optimaflow-ns3/introduction.md | 3 - daisi/docs/optimaflow-ns3/logging.md | 0 daisi/docs/optimaflow-ns3/scenariofile.md | 0 daisi/docs/sola-ns3/environments.md | 20 - daisi/docs/sola-ns3/glossary.md | 0 daisi/docs/sola-ns3/introduction.md | 41 -- daisi/docs/sola-ns3/logging.md | 0 daisi/docs/sola-ns3/scenario_files.md | 32 - docs/daisi | 1 - docs/daisi/architecture.md | 120 ++++ docs/daisi/glossary.md | 3 + docs/daisi/img/logging_general.svg | 4 + docs/daisi/img/logging_minhton.svg | 4 + docs/daisi/img/logging_natter.svg | 4 + docs/daisi/img/logging_optimaflow.svg | 4 + docs/daisi/img/logging_sola.svg | 4 + docs/daisi/img/mobility_model_ns3.svg | 4 + docs/daisi/img/network_structure.svg | 4 + docs/daisi/img/node_placement_ns3.svg | 4 + docs/daisi/introduction.md | 12 + .../daisi}/minhton-ns3/logging.md | 50 +- docs/daisi/minhton-ns3/scenariofile.md | 649 ++++++++++++++++++ docs/daisi/natter-ns3/logging.md | 5 + docs/daisi/natter-ns3/scenariofile.md | 232 +++++++ docs/daisi/optimaflow-ns3/logging.md | 12 + docs/daisi/optimaflow-ns3/scenariofile.md | 405 +++++++++++ docs/daisi/optimaflow-ns3/specifics.md | 93 +++ docs/daisi/scenariofile_general.md | 94 +++ docs/daisi/sola-ns3/logging.md | 5 + docs/daisi/sola-ns3/scenariofile.md | 239 +++++++ docs/daisi/using.md | 56 ++ docs/getting_started.md | 9 +- docs/glossary.md | 6 +- docs/index.md | 10 +- docs/natter/{index.md => introduction.md} | 0 docs/optimaflow/glossary.md | 24 +- docs/optimaflow/introduction.md | 4 +- .../task_assignment/decentralized.md | 2 +- .../optimaflow/task_assignment/round_robin.md | 6 +- docs/sola/component_implementations.md | 6 +- docs/sola/logging.md | 3 +- docs/stylesheets/extra.css | 10 +- minhton/docs/algorithms/bootstrap.md | 2 +- minhton/docs/algorithms/index.md | 2 +- minhton/docs/algorithms/join.md | 2 +- minhton/docs/algorithms/leave.md | 28 +- minhton/docs/glossary.md | 26 +- .../docs/img/peer_discovery_forwarding.svg | 4 + minhton/docs/introduction.md | 8 +- minhton/docs/programmers/concept.md | 2 +- minhton/docs/using.md | 54 +- mkdocs.yml | 18 +- 61 files changed, 2100 insertions(+), 660 deletions(-) delete mode 100644 daisi/docs/getting_started.md delete mode 100644 daisi/docs/glossary.md delete mode 100644 daisi/docs/introduction.md delete mode 100644 daisi/docs/logging.md delete mode 100644 daisi/docs/minhton-ns3/esearch.md delete mode 100644 daisi/docs/minhton-ns3/scenariofile.md delete mode 100644 daisi/docs/natter-ns3/logging.md delete mode 100644 daisi/docs/natter-ns3/scenariofile.md delete mode 100644 daisi/docs/network.md delete mode 100644 daisi/docs/optimaflow-ns3/introduction.md delete mode 100644 daisi/docs/optimaflow-ns3/logging.md delete mode 100644 daisi/docs/optimaflow-ns3/scenariofile.md delete mode 100644 daisi/docs/sola-ns3/environments.md delete mode 100644 daisi/docs/sola-ns3/glossary.md delete mode 100644 daisi/docs/sola-ns3/introduction.md delete mode 100644 daisi/docs/sola-ns3/logging.md delete mode 100644 daisi/docs/sola-ns3/scenario_files.md delete mode 120000 docs/daisi create mode 100644 docs/daisi/architecture.md create mode 100644 docs/daisi/glossary.md create mode 100644 docs/daisi/img/logging_general.svg create mode 100644 docs/daisi/img/logging_minhton.svg create mode 100644 docs/daisi/img/logging_natter.svg create mode 100644 docs/daisi/img/logging_optimaflow.svg create mode 100644 docs/daisi/img/logging_sola.svg create mode 100644 docs/daisi/img/mobility_model_ns3.svg create mode 100644 docs/daisi/img/network_structure.svg create mode 100644 docs/daisi/img/node_placement_ns3.svg create mode 100644 docs/daisi/introduction.md rename {daisi/docs => docs/daisi}/minhton-ns3/logging.md (67%) create mode 100644 docs/daisi/minhton-ns3/scenariofile.md create mode 100644 docs/daisi/natter-ns3/logging.md create mode 100644 docs/daisi/natter-ns3/scenariofile.md create mode 100644 docs/daisi/optimaflow-ns3/logging.md create mode 100644 docs/daisi/optimaflow-ns3/scenariofile.md create mode 100644 docs/daisi/optimaflow-ns3/specifics.md create mode 100644 docs/daisi/scenariofile_general.md create mode 100644 docs/daisi/sola-ns3/logging.md create mode 100644 docs/daisi/sola-ns3/scenariofile.md create mode 100644 docs/daisi/using.md rename docs/natter/{index.md => introduction.md} (100%) create mode 100644 minhton/docs/img/peer_discovery_forwarding.svg diff --git a/daisi/docs/getting_started.md b/daisi/docs/getting_started.md deleted file mode 100644 index 43058171..00000000 --- a/daisi/docs/getting_started.md +++ /dev/null @@ -1,25 +0,0 @@ -After you have built the simulation executable, you can run the DAISI simulation. -We assume that we are at the root level of the repository folder now. -`daisi_exec` is located there if you used the commands from the [installation guide for the terminal](../installation.md#terminal). -Otherwise, please replace `daisi_exec` with the respective simulation executable or simply run DAISI from VS Code. -A requirement is to set the environment variables, at least the `LD_LIBRARY_PATH`, while running cpps or sola (standalone) additionally require setting the `MINHTONDIR`: - -```sh -export LD_LIBRARY_PATH=/work/ns3/ns3_installs/ns3_3_38_release_stripped/lib -export MINHTONDIR=`pwd`/minhton -``` - -Please make sure to adjust the specified `LD_LIBRARY_PATH` with your ns-3 installation location. - -It is required to set an `environment` and a corresponding `scenario` as parameters like in the following example: - -```sh -./daisi_exec --environment=cpps --scenario=daisi/scenarios/cpps/default.yml -``` - -You can replace the `scenario` option with `scenariostring` if you want to include the whole scenario content as an argument. -Another option is `disable-catch`, which disables catching fatal errors if set to `true`. - -Examples for other environments than cpps can be found [on the environments page](environments.md). - -# WHAT DOES IT INCLUDE diff --git a/daisi/docs/glossary.md b/daisi/docs/glossary.md deleted file mode 100644 index dcfca37b..00000000 --- a/daisi/docs/glossary.md +++ /dev/null @@ -1 +0,0 @@ -# Glossary DAISI diff --git a/daisi/docs/introduction.md b/daisi/docs/introduction.md deleted file mode 100644 index 50cc2152..00000000 --- a/daisi/docs/introduction.md +++ /dev/null @@ -1,16 +0,0 @@ -# Introduction - -# What is ns-3 -> ns-3 is a discrete-event network simulator for Internet systems, targeted primarily for research and educational use. The goal of the ns-3 project is to develop a preferred, open simulation environment for networking research: it should be aligned with the simulation needs of modern networking research and should encourage community contribution, peer review, and validation of the software. - -Our application runs on top of the [ns-3](https://www.nsnam.org/) network simulator and simulates the chosen scenario in an environment. - - - -- why ns-3 (testing, verification, holistic simulation, ...) -- modular testing of - - SOLA - - MINHTON - - NATTER - - Applications -- what it is not diff --git a/daisi/docs/logging.md b/daisi/docs/logging.md deleted file mode 100644 index 517addb4..00000000 --- a/daisi/docs/logging.md +++ /dev/null @@ -1,21 +0,0 @@ -# Logging - -AGNOSTIC Logging... - -DAISI implements loggers for ns-3 simulations that create a single SQLite database. -Independent of the simulation environment, a global logger manager (defined in `daisi/src/logging/logger_manager.h`) is created at the start of the simulation. -The `LoggerManager` also provides methods for creating the specific loggers (MINHTON, natter, Autonomous Mobile Robot (AMR), Transport Order (TO), Path Planning, and SOLA). - -Each specific logger includes `daisi/src/logging/definitions.h` where the functions are responsible for easily generating SQL `CREATE` and `INSERT` statements from structs. - -`SQLiteHelper` is the class (defined in`daisi/src/logging/sqlite/sqlite_helper.h`) which has the logic for creating and modifying the SQLite database. - -## Specify output path for simulation results - -The database output of a scenario can be specified either by setting ``outputPath`` within the scenario file or by setting the ``DAISI_OUTPUT_PATH`` environment variable. -If both ways are used simultaneously, ``outputPath`` from the scenario file is used - -## Deferred logging - -CMake option to disable deferred logging: `-DDAISI_SQLITE_DEFERRED_LOGGING=OFF` -When deferred logging is disabled, all SQLite statements are executed immediately, impacting the performance negatively. diff --git a/daisi/docs/minhton-ns3/esearch.md b/daisi/docs/minhton-ns3/esearch.md deleted file mode 100644 index 9406f81f..00000000 --- a/daisi/docs/minhton-ns3/esearch.md +++ /dev/null @@ -1,162 +0,0 @@ -# ESearch - -The Entity Search (ESearch) is a builtin functionality of MINHTON to search for specified data in the network. -For simulation purposes, you specify the ESearch executions in the scenario file used by MINHTON. - -## Initial Scenario File - -Below the [usual scenario file content](management-overlay.md), you can specify the ESearch find query inside a scenario sequence. -You initiate a find query with the requesting node (level:number). The scope can be `all` or `some` and the query must be a valid expression. -In the following example we define a find query from the requesting node 100:100 with an unrestricted scope and query the attribute `a01` and `a02` with a value over 5. - -```yaml -... -scenarioSequence: -... - - find-query: - level: 100 - number: 100 - scope: all - query: ((HAS a01) AND (a02 > 5)) - validity-threshold: 10000 -``` - -Periodically repeated requests are being counted down. After the countdown value has been reached, the simulation will wait until the last request has been processed and the simulation stop time will be set accordingly. - -```yaml -- request-countdown: 1000 -``` - -## Peer Discovery Commands - -Peer Discovery can be turned off by using - -```yaml -peerDiscoveryEnvironment: - attributes: - requests: -``` - -## Attributes / Values - -The name of an attribute (here a01, a02...) can be chosen arbitrarily, but must be unique. - -Each attribute needs a presence, content and update behavior. - -Presence behavior describes which nodes posses the attribute and which not. - -Content behavior describes the kinds of values an attribute can have. - -Update behavior describes how often the value of an attribute will be updated. - -```yaml -attributes: - a01: - presence_behavior: - ... - content_behavior: - ... - update_behavior: - ... - a02: - presence_behavior: - ... - content_behavior: - ... - update_behavior: - ... -``` - -### Presence Behavior - -Presence Behavior is simply described by the percentage of nodes who posses this attribute. The percentage has to be given as a float (100% -> 1.0). - -```yaml -presence_behavior: - percentage: 0.8 -``` - -### Content Behavior - -Uniform and Gaussian are only numerical values. -Choice and constant can be either integers, floats, booleans or strings. - -Uniform: - -```yaml -content_behavior: - type: uniform - min: 0 - max: 10 -``` - -Gaussian: - -```yaml -content_behavior: - type: gaussian - mean: 10 - variance: 2 -``` - -Constant: - -```yaml -content_behavior: - type: constant - value: 42 -``` - -Choice: - -```yaml -content_behavior: - type: choice - values: - - value1: - content: pallet - prob: 0.4 - - value2: - content: box - prob: 0.6 -``` - -### Update Behavior - -The update behavior is either dynamic or static. -If its static, the value will never be updated. -If its dynamic, values will be updated periodically. -The time period between updates is given in milliseconds, either by a constant or gaussian distribution. - -Constant: - -```yaml -update_behavior: - type: constant - value: 20000 # ms -``` - -Gaussian: - -```yaml -update_behavior: - type: gaussian - mean: 20000 # ms - variance: 5000 # ms -``` - -Uniform: - -```yaml -update_behavior: - type: uniform - min: 20000 # ms - max: 40000 # ms -``` - -Static: - -```yaml -update_behavior: - type: static -``` diff --git a/daisi/docs/minhton-ns3/scenariofile.md b/daisi/docs/minhton-ns3/scenariofile.md deleted file mode 100644 index e2866c57..00000000 --- a/daisi/docs/minhton-ns3/scenariofile.md +++ /dev/null @@ -1,126 +0,0 @@ -# Scenario File - -The Management Overlay (MO) allows to create a Peer-to-Peer (P2P) Network. -This creation and maintenance can be simulated by ns-3. -Scenario files are used for this purposes and describe what exactly will be simulated in the [YAML](https://yaml.org/) format. - -Currently, the MO supports the following creational pattern: - - -- `minhton` [[1]](#references) (MINHTON; complete-balanced tree with support for concurrent operations) - -The MINHTON algorithm is based on nBATON\* [[2]](#references), which in turn is based on BATON\* [[3]](#references). - -This **must** be declared in the scenario file under `algorithms:`. - -In addition, the simulation environment also requires a sequence, which instructs the simulator what happens in which order. - -- In the beginning the root node already exists. This does not need to be declared. -- Sequences are executed sequentially. - -## Initial Scenario File - -```yaml -# required -title: MINHTON_default -name: MO test with fanout 2 -stoptime: 10000000 -version: 0.1 -physicalLayer: ETH -fanout: 2 - -defaultDelay: 5000 -logLevel: info -randomSeed: 1 # 0 = random - -timeouts: - bootstrap_response: 500 - join_response: 500 - join_accept_ack_response: 500 - replacement_offer_response: 500 - replacement_ack_response: 500 - dsn_aggregation: 4000 - inquiry_aggregation: 1000 - -algorithms: - join: minhton - leave: minhton - search_exact: minhton - response: general - bootstrap: general - -peerDiscoveryEnvironment: - attributes: off - requests: off - -scenarioSequence: - ... -``` - -## Adding Nodes - -The following `scenarioSequence` let 100 nodes join the network. The following `scenarioSequence` let 100 nodes join the network. - -```yaml -scenarioSequence: - - join-many: - number: 100 - mode: random - delay: 1000 -``` - -## Removing Nodes - -The following `scenarioSequence` let 100 nodes join the network, and than 100 nodes are leaving the network. - -```yaml -scenarioSequence: - - join-many: - number: 100 - mode: random - delay: 1000 - - leave-many: - number: 100 - mode: random - delay: 1000 -``` - -## Searching Nodes - -The following `scenarioSequence` let 100 nodes join the network, and than 100 search-exact queries are executed. After 100 search-exact queries are executed, "search-all" is executed. - -```yaml -scenarioSequence: - - join-many: - number: 100 - mode: random - delay: 1000 - - search-many: - number: 100 - delay: 1000 - - search-all: - delay: 1000 -``` - -## Static P2P Build - -Building a network statically of 100 + 1 nodes without needing join. -It is only possible to execute this command once right in the beginning. -The event timestamp cannot be 0 - therefore you need to increase the time by a little bit. - -```yaml -- time: 100 -- static-build: - number: 100 - mode: random - delay: 1000 -``` - -## References - -[1] P. Laskowski, P. Detzner, und S. Bondorf, „Tree-structured Overlays with Minimal Height: Construction, Maintenance and Operation“, in DisCoTec 2023, Lisbon, Portugal. - -[2] P. Detzner, J. Gödeke, and S. Bondorf, “[Low-Cost search in Tree-Structured P2P overlays: The Null-Balance benefit](https://doi.org/10.1109/LCN52139.2021.9525004),” Edmonton, Canada, Oct. 2021. - -[3] H. V. Jagadish, B. C. Ooi, K.-L. Tan, Q. H. Vu, und R. Zhang, „Speeding up search in peer-to-peer networks with a multi-way tree structure“, in Proceedings of the 2006 ACM SIGMOD international conference on Management of data - SIGMOD ’06, Chicago, IL, USA, 2006, S. 1. doi: 10.1145/1142473.1142475. diff --git a/daisi/docs/natter-ns3/logging.md b/daisi/docs/natter-ns3/logging.md deleted file mode 100644 index d90ac7ad..00000000 --- a/daisi/docs/natter-ns3/logging.md +++ /dev/null @@ -1,3 +0,0 @@ -## natter - -Link to autogenerated doxygen docu diff --git a/daisi/docs/natter-ns3/scenariofile.md b/daisi/docs/natter-ns3/scenariofile.md deleted file mode 100644 index dbba6bc2..00000000 --- a/daisi/docs/natter-ns3/scenariofile.md +++ /dev/null @@ -1,42 +0,0 @@ -# Scenario File - -The Event Dissemination (ED) currently supports the following mode: - -- minhcast (MINHCAST) - -This **must** be declared in the scenario file. - -In addition, the simulation environment also requires a sequence, which instructs the simulator what happens in which order. - -- In the beginning the root node already exists. This does not need to be declared. -- Sequences are executed sequentially. - -## Initial Scenario File - -```yaml -# required: -title: Test -name: ED test with 5 publish operations -stoptime: 4294967296 -version: 0.1 -physicalLayer: ETH -fanout: 2 - -# optional -defaultDelay: 500 -logLevel: info -randomSeed: 1 # 0 random, otherwise... - -# required: -numberNodes: 20 -mode: minhcast - -scenarioSequence: - - join: - mode: minhton - - publish: - number: 5 - delay: 0 - mode: random # random, sequential - message_size: 100 # in bytes -``` diff --git a/daisi/docs/network.md b/daisi/docs/network.md deleted file mode 100644 index 7bbfcd0c..00000000 --- a/daisi/docs/network.md +++ /dev/null @@ -1,34 +0,0 @@ -# Network - -## General notes - -* Every switch can handle up to ``kNumberOfAppNodesPerSwitch`` nodes. -* Every WLAN AP can handle up to ``kMaxNumberAmrsPerAp`` nodes. -* The number of switches and routers are automatically scaled up with more nodes. - -## Network structure (Logical AGV connected via Wireless) - -```txt -[TO] --| )) [Physical and logical AGV] - | -- [Switch] -- [Core Router] -- [WLAN AP] ))) -[TO] --| )) [Physical and logical AGV] -``` - -* The ``[Physical and logical AGV]`` node is running two ns3 applications: - * Application 0: Logical AGV using TCP 127.0.0.1:3000 and UDP for communication to other nodes. - * Application 1: Physical AGV using TCP 127.0.0.1:4000 - -## IP ranges - -* Core routers IP always ends with ``.1`` - -* TO/L-AGVs connected via switch to core router: - * 1.1.0.0/16 - * 1.2.0.0/16 - * 1.3.0.0/16 - * ... -* Wireless network - * 192.168.0.0/16 - * 192.169.0.0/16 - * 192.170.0.0/16 - * ... diff --git a/daisi/docs/optimaflow-ns3/introduction.md b/daisi/docs/optimaflow-ns3/introduction.md deleted file mode 100644 index 4de752ec..00000000 --- a/daisi/docs/optimaflow-ns3/introduction.md +++ /dev/null @@ -1,3 +0,0 @@ -# Introduction - - diff --git a/daisi/docs/optimaflow-ns3/logging.md b/daisi/docs/optimaflow-ns3/logging.md deleted file mode 100644 index e69de29b..00000000 diff --git a/daisi/docs/optimaflow-ns3/scenariofile.md b/daisi/docs/optimaflow-ns3/scenariofile.md deleted file mode 100644 index e69de29b..00000000 diff --git a/daisi/docs/sola-ns3/environments.md b/daisi/docs/sola-ns3/environments.md deleted file mode 100644 index e63e0e15..00000000 --- a/daisi/docs/sola-ns3/environments.md +++ /dev/null @@ -1,20 +0,0 @@ -# Run Environments - - -The currently available environments (with an example command to run each) are: - -- `minhton` - - `./daisi_exec --environment=minhton --scenario=daisi/scenarios/nbaton/default.yml` -- `natter` - - `./daisi_exec --environment=natter --scenario=daisi/scenarios/natter/default.yml` -- `cpps` - - `./daisi_exec --environment=cpps --scenario=daisi/scenarios/cpps/default.yml` -- `path_planning` - - `./daisi_exec --environment=path_planning --scenario=daisi/scenarios/path_planning/default.yml` -- `sola` (Still in development) - - `./daisi_exec --environment=sola --scenario=daisi/scenarios/sola/default.yml` - -Each example command assumes that the simulation executable is located in the main folder, but can of course be adapted to other names and locations. -The default location is `build/daisi/src/main/Main`. -As shown, the environment for a simulation run can be selected with the `environment` parameter. -Additionally, a scenario has to be defined with the `scenario` parameter. diff --git a/daisi/docs/sola-ns3/glossary.md b/daisi/docs/sola-ns3/glossary.md deleted file mode 100644 index e69de29b..00000000 diff --git a/daisi/docs/sola-ns3/introduction.md b/daisi/docs/sola-ns3/introduction.md deleted file mode 100644 index 3367bb21..00000000 --- a/daisi/docs/sola-ns3/introduction.md +++ /dev/null @@ -1,41 +0,0 @@ -# SOLA - - - - -## Concept - -## Installation - -## Usage - - - -SOLA uses the [management overlay MINHTON](../minhton_lib/index.md) and the [event dissemination natter](../natter_lib/index.md). - -## Getting Started -TODO: add conent ;) - - - -## Academic Attribution - -If you use SOLA for research (or any other purposes), please include one of the following references in any resulting publication. - -```plain -@inproceedings{detznerSOLADecentralizedCommunication2023, - title = {{{SOLA}}: {{A Decentralized Communication Middleware Developed}} with ns-3}, - shorttitle = {{{SOLA}}}, - booktitle = {Proceedings of the 2023 {{Workshop}} on ns-3}, - author = {Detzner, Peter and Gödeke, Jana and Tönning, Lars and Laskowski, Patrick and Hörstrup, Maximilian and Stolz, Oliver and Brehler, Marius and Kerner, Sören}, - date = {2023-06-28}, - series = {{{WNS3}} '23}, - pages = {78--85}, - publisher = {{Association for Computing Machinery}}, - location = {{New York, NY, USA}}, - url = {https://dl.acm.org/doi/10.1145/3592149.3592151}, - abstract = {The transformation from static production facilities into a flexible and decentralized cyber-physical production system (CPPS) is part of the current ongoing Industry 4.0. A CPPS will enable and support communication between people, machines and virtual objects, e.g., as material flow or products, alike. However, communication in CPPS relies often on centralized approaches using a message broker or is not considered at all. We present in this paper the decentralized communication middleware called SOLA with an emphasis on, but not limited to, CPPS. SOLA uses the inherent given capability to communicate of participating nodes and eliminates the need for a central instance. A structured overlay network is created and managed, which appears to its users as a single coherent system. The main building blocks of SOLA are the management overlay and the event dissemination. Within this building blocks, no single peer has a global view and all operations are based on each peer’s local view. The local view represents some selected links to a subset of all peers in the network. In addition to this, we also present how SOLA was developed with the help of the discrete-event simulator ns-3. Finally, we also show how we have used ns-3 to simulate a self-organizing material flow where participants use SOLA to communicate.}, - isbn = {9798400707476}, - keywords = {balanced tree,cyber-physical production system,decentral organized communication,peer-to-peer network} -} -``` diff --git a/daisi/docs/sola-ns3/logging.md b/daisi/docs/sola-ns3/logging.md deleted file mode 100644 index e69de29b..00000000 diff --git a/daisi/docs/sola-ns3/scenario_files.md b/daisi/docs/sola-ns3/scenario_files.md deleted file mode 100644 index 5c7a567d..00000000 --- a/daisi/docs/sola-ns3/scenario_files.md +++ /dev/null @@ -1,32 +0,0 @@ -# Scenario Files - -No matter what [run environment](../sola/environments.md) is chosen when running DAISI, all environments use a scenario file with some fields that are always required. - -```yaml -# required -title: Title -name: Test with fanout 2 -stoptime: 10000000 -version: 0.1 -physicalLayer: ETH -fanout: 2 - -# optional -defaultDelay: 5000 -logLevel: info -randomSeed: 1 - -# required -scenarioSequence: - ... -``` - -The `title` and `name` fields are purely descriptive at the moment and not further used. -`stoptime` defines at which simulation time in milliseconds the simulation will be aborted if it does not finish earlier. -The `version` field can be used to differentiate different implementation versions. -With `physicalLayer` we define the protocol for connecting the nodes to each other, by default we use Ethernet (`ETH`), but keep in mind that some simulation parts are unaffected from this setting and use Wi-Fi. -Since we build tree structures, we also have to define the `fanout` for them, which must be in the range m >= 2. - -The optional fields include `defaultDelay` for the delay between each simulation step in milliseconds, the `logLevel` that can be either `debug`, `info`, `warning`, or `critical`, as well as the `randomSeed` (0 for random) used for reproducible simulations. - -Below those mentioned fields the `scenarioSequence` is required, but what it can contain differs based on the run environment. Please refer to the specific components for details about the `scenarioSequence` ([MINHTON](../daisi_lib/minhton-ns3/management-overlay.md), [natter](../daisi_lib/natter-ns3/event-distribution.md), [CPPS](../daisi_lib/applications/cpps/index.md), [Path Planning](../daisi_lib/applications/path-planning/index.md)). diff --git a/docs/daisi b/docs/daisi deleted file mode 120000 index 763f2401..00000000 --- a/docs/daisi +++ /dev/null @@ -1 +0,0 @@ -../daisi/docs \ No newline at end of file diff --git a/docs/daisi/architecture.md b/docs/daisi/architecture.md new file mode 100644 index 00000000..5e9b2c78 --- /dev/null +++ b/docs/daisi/architecture.md @@ -0,0 +1,120 @@ +## Logging + +To capture data output from all SOLA components, loggers for the components were implemented that log the data into a SQLite database. +SQLite databases typically reside in files. +Using SQLite allows to inspect the output of the distributed system in a single file and directly allows querying the data with SQL for evaluation. +Further, it eases the evaluation of multiple independent simulation runs as one file only contains data from one simulation run. +As multiple SOLA components share a simulation run (for example SOLA with MINHTON and natter subcomponents), all components log into the same database. + +A global instance of the `daisi::LoggerManager` class holds the SQLite database connection and allows creating loggers for each SOLA component. +All those loggers use this connection. + +Some general data about the simulation is logged with every SOLA component (see Figure 1 for the tables and their columns). +This gives an overview about which SOLA components or applications are running on which device. +With every SOLA component and application having its own UUID, the mapping of the component's or application's UUID to the device it is running on is logged once. +This allows for example the evaluation of the load per node/device, that is running multiple components or applications. +The naming of the tables and columns (including the unit prefixes) follows [our SQL Styleguide](). + +
+ + ![LoggingGeneral](img/logging_general.svg) +
**Figure 1:** Structure of general logging information
+
+ +Additional data, that is specific to SOLA components and applications, is logged into the database as well. +The structure and content of this data is described under the "Logging" section for each SOLA component or application in the left sidebar. + +### Specify output path for simulation results + +The path where the output database file should be stored can either be specified by setting the `outputPath` key within the scenario file (see "Scenariofile" sections in the left sidebar) or by setting the `DAISI_OUTPUT_PATH` environment variable. +If both are set, `outputPath` from the scenariofile is used. + +The name for the database file is automatically generated and contains the name of the application or SOLA component, a timestamp and a random six-character string. +Database files from simulations using the MINHTON component also include the fanout and number of nodes in its filename. +If the simulation fails, the database will be labeld with a `.fail` postfix, except if catching fatal errors is disabled with the `--disable-catch` flag (used for debugging only). +While the simulation is running and writing to the datbase, the file is postfixed with `.tmp`. + +!!! danger "Wait until the simulation finishes!" + + Do not open ``.tmp`` databases while the simulation is running as they may become corruped. + +### Deferred logging + +As the simulated time usually runs way faster than the real time, much data must be logged within a small amount of time. +This results in a heavy I/O workload. +To avoid slowing down the simulation due to this high I/O (single SQL statements to insert a single row), DAISI supports deferred logging. +This can be enabled with the CMake option `DAISI_SQLITE_DEFERRED_LOGGING`. +When using deferred logging, the SQL command to insert data is not executed directly but first buffered in memory. +When the buffer gets full, all buffered commands are executed in a separate thread, not blocking the main simulation thread with logging I/O. +One drawback of this approach is, that when the simulation crashes, it is possible that not all data is logged to the database. + +## Reproducability + +Reproducability of the simulation is important for re-evaluating results and allowing easier debugging of programming or algorithmic flaws. +For this, a seed must be set in the scenariofile (see "Scenariofile" sections in the left sidebar) which is used to initialze a global random generator (`daisi::global_random_engine`). +This random generator can be accessed by all parts that require randomness, resulting in a deterministic simulation. + +## Decoupling ns-3 and real world code + +One of the main development goals is to let the application run in simulation but also in a real world deployment. +Hence special care must be taken to decouple simulation specific code to allow an easy switch between these environments. +These parts mostly concern: + +- Threading: In ns-3 simulation, only a single thread is available for the entire simulation. To call a function after a period of time or async, it can simply be scheduled. + In a real world deployment however, multiple threads may exist even for a single node, which must be handled correctly. +- Networking: For simulation the ns-3 specific networking functionality like `ns3::Socket` must be used. + For real world deployment, real sockets must be used, which might also behave slightly different. +- Randomness: For simulation, a random engine is available to provide global randomness but in a reproducable and deterministic way (see [Reproducability](#reproducability)). + But for real world deployment every node must use its own random generator which should be seeded uniquely for every node. + One example of what could happen otherwise is, that every node on startup will generate the same UUID for itself, as they are using the same seed independently of each other. + +This was solved by providing two different implementations of the same class, where one implementation uses the ns-3 simulator functionalities and the other uses "real-world" functionalities. +When building SOLA, most components are therefore built twice and the required one (simulation or real world) is linked into the resulting simulation executable or real-world library. +If classes need something specific to simulation or real world deployment in their declaration (for example members or private methods taking specific objects), they are further encapsulated using the PImpl idiom. + +## Network structure + +A device is called "node" within the ns-3 context. +A ns-3 node can run one or multiple (user) applications. +Such nodes are in the following called application nodes. +Currently DAISI supports application nodes to either be connected via the ns-3 CSMA model (ethernet-like connections) or the ns-3 Wi-Fi model (IEEE 802.11). + +Application nodes, that should connect to the network via CSMA, are connected to a separate ns-3 node representing a L2 switch. +Every L2 switch can handle a specific number of connections to application nodes, specifiable with the `kNumberOfAppNodesPerSwitch` constant. + +Application nodes, that should connect to the network via Wi-Fi, are attached to an access point. +Every access point can handle a specific number of connections to application nodes, specifiable with the `kMaxNumberAmrsPerAp` constant. + +The number of L2 switches and access points are automatically scaled up accordingly to the number of application nodes. +The L2 switches and access points are connected through CSMA links to a central ns-3 node representing a L3 IP router. +This setup forms a star topology as shown in Fig. 2. + +
+ + ![DAISI network structure](img/network_structure.svg) +
**Figure 2:** Example DAISI network structure with nodes connected via CSMA and nodes connected via Wi-Fi. The number of application nodes per switch/access point is set to 3.
+
+ +The specific network parameters (throughput, delay, ...) are currently hardcodeded within the network setup code. + +As most of the applications used with DAISI are not handling network failures yet, ns-3 traces are installed to automatically stop the application if network failures happen (packet lost, connection lost, ...). + +To avoid such cases and to speed up simulation, the ARP table of every node is prefilled. +This avoids execcsive ARP traffic that could be caused by Peer-To-Peer applications if all nodes within the same subnet communicate with each other. + +### IP address ranges + +- Core routers IP always ends with `.1` + +- Wired networks: + + - 1.1.0.0/16 + - 1.2.0.0/16 + - 1.3.0.0/16 + - ... + +- Wireless network + - 192.168.0.0/16 + - 192.169.0.0/16 + - 192.170.0.0/16 + - ... diff --git a/docs/daisi/glossary.md b/docs/daisi/glossary.md new file mode 100644 index 00000000..a8d91583 --- /dev/null +++ b/docs/daisi/glossary.md @@ -0,0 +1,3 @@ +!!! danger "This is work in progress!" + +# Glossary DAISI diff --git a/docs/daisi/img/logging_general.svg b/docs/daisi/img/logging_general.svg new file mode 100644 index 00000000..65df5bf1 --- /dev/null +++ b/docs/daisi/img/logging_general.svg @@ -0,0 +1,4 @@ + + + +
Minhton
Minhton+MO (Management Overlay)
Minhton+ED:<topicName> (Event Dissemination
Natter
Sola
AMR
TO
Minhton...
DeviceApplication
DeviceApplication
ApplicationUuid: integer
ApplicationUuid: integer
ApplicationName: varchar
ApplicationName: varchar
DeviceUuid: integer
DeviceUuid: integer
StartTime_ms: integer
StartTime_ms: integer
StopTime_ms: integer
StopTime_ms: integer
Device
Device
Id: integer
Id: integer
General
General
StartTime_ut: integer
StartTime_ut: integer
StopTime_ut: integer
StopTime_ut: integer
NumberOfEvents: integer
NumberOfEvents: integer
Exception: varchar
Exception: varchar
Config: varchar
Config: varchar
AdditionalParameters: varchar
AdditionalParameters: varchar
Event
Event
Id: Integer
Id: Integer
Uuid: varchar
Uuid: varchar
Timestamp_ms: integer
Timestamp_ms: integer
Type: integer
Type: integer
ApplicationUuid: varchar
ApplicationUuid: varchar
ns-3 node ID
ns-3 node IDText is not SVG - cannot display \ No newline at end of file diff --git a/docs/daisi/img/logging_minhton.svg b/docs/daisi/img/logging_minhton.svg new file mode 100644 index 00000000..76890e7a --- /dev/null +++ b/docs/daisi/img/logging_minhton.svg @@ -0,0 +1,4 @@ + + + +
MinhtonSearchContent
MinhtonSearchContent
Id: Integer
Id: Integer
Timestamp_ms: integer
Timestamp_ms: integer
NodeUuid: varchar
NodeUuid: varchar
State: integer
State: integer
AttributeName: varchar
AttributeName: varchar
Type: integer
Type: integer
Text: varchar
Text: varchar
MinhtonNode
MinhtonNode
ApplicationUuid: varchar
ApplicationUuid: varchar
PositionUuid: varchar
PositionUuid: varchar
Level: integer
Level: integer
Number: integer
Number: integer
Fanout: integer
Fanout: integer
minhton::ContentStatus
0: Insert
1: Remove
minhton::ContentStatu...
minhton::NodeData::ValueType
0: Dynamic
1: Static
minhton::NodeData::ValueType...
MinhtonSearchTest
MinhtonSearchTest
Id: Integer
Id: Integer
Timestamp_ms: integer
Timestamp_ms: integer
State: integer
State: integer
EventId: integer
EventId: integer
SenderLevel: integer
SenderLevel: integer
SenderNumber: integer
SenderNumber: integer
TargetLevel: integer
TargetLevel: integer
TargetNumber: integer
TargetNumber: integer
HopLevel: integer
HopLevel: integer
HopNumber: integer
HopNumber: integer
MinhtonFindQuery
MinhtonFindQuery
Id: Integer
Id: Integer
Timestamp_ms: integer
Timestamp_ms: integer
EventId: Integer
EventId: Integer
NodeUuid: varchar
NodeUuid: varchar
Query: varchar
Query: varchar
MinhtonFindQueryResult
MinhtonFindQueryResult
Id: Integer
Id: Integer
Timestamp_ms: integer
Timestamp_ms: integer
NodeUuid: varchar
NodeUuid: varchar
EventId: Integer
EventId: Integer
MinhtonNodeState
MinhtonNodeState
Id: Integer
Id: Integer
PositionUuid: varchar
PositionUuid: varchar
Timestamp_ms: Integer
Timestamp_ms: Integer
State: Integer
State: Integer
EventId: Integer
EventId: Integer
0: Uninit
1: Running
0: Uninit...
MinhtonRoutingInfo
MinhtonRoutingInfo
Id: integer
Id: integer
Timestamp_ms: integer
Timestamp_ms: integer
NodeUuid: varchar
NodeUuid: varchar
NeighborNodeUuid: varchar
NeighborNodeUuid: varchar
EventId: integer
EventId: integer
Relationsship: integer
Relationsship: integer
minhton::NeighborRelationship
See Doxygen
minhton::NeighborRelationship...
DeviceApplication (General)
DeviceApplication (General)
ApplicationUuid: integer
ApplicationUuid: integer
ApplicationName: varchar
ApplicationName: varchar
DeviceUuid: integer
DeviceUuid: integer
StartTime_ms: integer
StartTime_ms: integer
StopTime_ms: integer
StopTime_ms: integer
Event (General)
Event (General)
Id: Integer
Id: Integer
Uuid: varchar
Uuid: varchar
Timestamp_ms: integer
Timestamp_ms: integer
Type: integer
Type: integer
ApplicationUuid: varchar
ApplicationUuid: varchar
=0 (no valid event) initially
=0 (no valid event...
MinhtonPhysicalNodeInfo
MinhtonPhysicalNodeInfo
ApplicationUuid varchar
ApplicationUuid varchar
Ip: varchar
Ip: varchar
Port: integer
Port: integer
MinhtonTraffic
MinhtonTraffic
Id: integer
Id: integer
Timestamp_ms: integer
Timestamp_ms: integer
MsgType: integer
MsgType: integer
Mode: Integer
Mode: Integer
SenderNodeUuid: varchar
SenderNodeUuid: varchar
TargeNodeUuid: varchar
TargeNodeUuid: varchar
PrimaryOtherNodeUuid: varchar
PrimaryOtherNodeUuid: varchar
SecondaryOtherNodeUuid: varchar
SecondaryOtherNodeUuid: varchar
EventId: integer
EventId: integer
RefEventId: integer
RefEventId: integer
Content: varchar
Content: varchar
minhton::MessageType
See Doxgen
minhton::MessageType...
minhton::SearchExactTestEntryTypes
0: Start
1: Hop
2: Success
3: Failure
minhton::SearchExactTestEntryType...
minhton::MessageProcessingModes
0: Receive
1: Sending
minhton::MessageProcessingModes...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/daisi/img/logging_natter.svg b/docs/daisi/img/logging_natter.svg new file mode 100644 index 00000000..a7e65bb6 --- /dev/null +++ b/docs/daisi/img/logging_natter.svg @@ -0,0 +1,4 @@ + + + +
NatterMessage
NatterMessage
Id: Integer
Id: Integer
Uuid: varchar
Uuid: varchar
Topic: varchar
Topic: varchar
NatterDeliveredTopicMessage
NatterDeliveredTopicMessage
Id: Integer
Id: Integer
Timestamp_us: Integer
Timestamp_us: Integer
NodeId: integer
NodeId: integer
InitialSenderNodeId: integer
InitialSenderNodeId: integer
MessageId: integer
MessageId: integer
Round: integer
Round: integer
NatterConnection
NatterConnection
Id: Integer
Id: Integer
Timestamp_ms: Integer
Timestamp_ms: Integer
Active: bit
Active: bit
NodeId: Integer
NodeId: Integer
NewNodeId: Integer
NewNodeId: Integer
NatterControlMessage
NatterControlMessage
Id: Integer
Id: Integer
Timestamp_ms: Integer
Timestamp_ms: Integer
Type: integer
Type: integer
Mode: integer
Mode: integer
SenderNodeId: Integer
SenderNodeId: Integer
TargetNodeId: Integer
TargetNodeId: Integer
MessageId: Integer
MessageId: Integer
NatterNode
NatterNode
Id: Integer
Id: Integer
ApplicationUuid: varchar
ApplicationUuid: varchar
Timestamp_ms: Integer
Timestamp_ms: Integer
Level: integer
Level: integer
Number: integer
Number: integer
Ip: varchar
Ip: varchar
Port: integer
Port: integer
1: MINHCAST msg
1: MINHCAST msg
0: Send
1: Receive
0: Send...
DeviceApplication (General)
DeviceApplication (General)
ApplicationUuid: integer
ApplicationUuid: integer
ApplicationName: varchar
ApplicationName: varchar
DeviceUuid: integer
DeviceUuid: integer
StartTime_ms: integer
StartTime_ms: integer
StopTime_ms: integer
StopTime_ms: integer
257: Join MINHTON
258: Publish msg
257: Join MINHTON...
Event (General)
Event (General)
Id: Integer
Id: Integer
Uuid: varchar
Uuid: varchar
Timestamp_ms: integer
Timestamp_ms: integer
Type: integer
Type: integer
ApplicationUuid: varchar
ApplicationUuid: varchar
Information about each natter node/instance
Information abou...
Log of all messages exchanged between natter nodes (low level)
Log of all messa...
Information for each published message
Information for...
Information about each message delivered to the application
Information abou...
Log of connections for each node.
 Connection between NodeId and NewNodeId.
Active = 1 (new connection)
Active = 0 (deleted connection)
Log of connections for each no...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/daisi/img/logging_optimaflow.svg b/docs/daisi/img/logging_optimaflow.svg new file mode 100644 index 00000000..97103b81 --- /dev/null +++ b/docs/daisi/img/logging_optimaflow.svg @@ -0,0 +1,4 @@ + + + +
CppsNegotiationTraffic
CppsNegotiationTraffic
Id: Integer
Id: Integer
TransportOrderId: Integer
TransportOrderId: Integer
Timestamp_ms: Integer
Timestamp_ms: Integer
SenderAmrId: Integer
SenderAmrId: Integer
TargetAmrId: integer
TargetAmrId: integer
MsgType: integer
MsgType: integer
Content: varchar
Content: varchar
CppsExecutedOrderUtility
CppsExecutedOrderUtility
CppsService
CppsService
Uuid: varchar
Uuid: varchar
StartTime_ms: integer
StartTime_ms: integer
Type: integer
Type: integer
CppsServiceTransport
CppsServiceTransport
Id: Integer
Id: Integer
Uuid: varchar
Uuid: varchar
AmrId: Integer
AmrId: Integer
LoadCarrierType: varchar
LoadCarrierType: varchar
MaxWeightPayload_kg: real
MaxWeightPayload_kg: real
CppsAMRHistory
CppsAMRHistory
Id: Integer
Id: Integer
Timestamp_ms: Integer
Timestamp_ms: Integer
AmrId: Integer
AmrId: Integer
PosX_m: Real
PosX_m: Real
PosY_m: Real
PosY_m: Real
State: integer
State: integer
daisi::cpps::AmrState
0: kIdle
1: kWorking
2: kCharging
3: kError
daisi::cpps::AmrState...
CppsAutonoumousMobileRobot
CppsAutonoumousMobileRobot
Id: Integer
Id: Integer
Timestamp_ms: Integer
Timestamp_ms: Integer
ApplicationUuid: varchar
ApplicationUuid: varchar
FriendlyName: varchar
FriendlyName: varchar
ModelName: varchar
ModelName: varchar
IpLogicalService: varchar
IpLogicalService: varchar
PortLogicalService: integer
PortLogicalService: integer
IpPhysicalAsset: varchar
IpPhysicalAsset: varchar
PortPhysicalAsset: integer
PortPhysicalAsset: integer
IpLogicalAsset: varchar
IpLogicalAsset: varchar
PortLogicalAsset: integer
PortLogicalAsset: integer
LoadTime_ms: Integer
LoadTime_ms: Integer
UnloadTime_ms: Integer
UnloadTime_ms: Integer
MaxWeight_kg: Real
MaxWeight_kg: Real
EmptyWeight_kg: Real
EmptyWeight_kg: Real
Max_Velocity_mps: Real
Max_Velocity_mps: Real
Min_Velocity_mps: Real
Min_Velocity_mps: Real
MaxAcceleration_mpss: Real
MaxAcceleration_mpss: Real
MaxDecelleration_mpss: Real
MaxDecelleration_mpss: Real
CppsMaterialFlowOrderHistory
CppsMaterialFlowOrderHistory
Id: Integer
Id: Integer
AmrId: Integer
AmrId: Integer
State: Integer
State: Integer
MaterialFlowOrderId: Integer
MaterialFlowOrderId: Integer
MaterialFlowTaskId: Integer
MaterialFlowTaskId: Integer
Timestamp_ms: Integer
Timestamp_ms: Integer
PosX_m: Integer
PosX_m: Integer
PosY_m: Integer
PosY_m: Integer
daisi::cpps::OrderState
0: Created
1: Queued
2: Started
3: GoToPickUpLocation
4: ReachedPickUpLocation
5: Load
6: Loaded
7: GoToDeliveryLocation
8: ReachedDeliveryLocation
9: Unload
10: Unloaded
11: Finished
12: Error
13: Invalid
daisi::cpps::OrderState...
CppsMaterialFlow
CppsMaterialFlow
Id: Integer
Id: Integer
Timestamp_ms: Integer
Timestamp_ms: Integer
Uuid: varchar
Uuid: varchar
IpLogicalCore: varchar
IpLogicalCore: varchar
PortLogicalCore: integer
PortLogicalCore: integer
State: integer
State: integer
CppsTopicMessage
CppsTopicMessage
Id: Integer
Id: Integer
MessageUuid: varchar
MessageUuid: varchar
Content: varchar
Content: varchar
0: Transport Service
0: Transport Servi...
DeviceApplication (General)
DeviceApplication (General)
ApplicationUuid: integer
ApplicationUuid: integer
ApplicationName: varchar
ApplicationName: varchar
DeviceUuid: integer
DeviceUuid: integer
StartTime_ms: integer
StartTime_ms: integer
StopTime_ms: integer
StopTime_ms: integer
CppsMaterialFlowOrder
CppsMaterialFlowOrder
Id: Integer
Id: Integer
OrderUuid: varchar
OrderUuid: varchar
TaskId: Integer
TaskId: Integer
Step1_Name: varchar
Step1_Name: varchar
Step1_Parameters: varchar
Step1_Parameters: varchar
Step2_Name: varchar
Step2_Name: varchar
Step2_Parameters: varchar
Step2_Parameters: varchar
CppsMaterialFlowTask
CppsMaterialFlowTask
Id: Integer
Id: Integer
TaskUuid: varchar
TaskUuid: varchar
TaskName: varchar
TaskName: varchar
MaterialFlowId: Integer
MaterialFlowId: Integer
FollowUpTaskUuids: varchar
FollowUpTaskUuids: varchar
LoadCarrierRequirements: varchar
LoadCarrierRequirements: varchar
PayloadRequirement_kg: Real
PayloadRequirement_kg: Real
SolaTopicMessage (SOLA)
SolaTopicMessage (SOLA)
Id: Integer
Id: Integer
Timestamp_ms: Integer
Timestamp_ms: Integer
Topic: varchar
Topic: varchar
SolaApplicationId: varchar
SolaApplicationId: varchar
MessageUuid: varchar
MessageUuid: varchar
Receive: Integer
Receive: Integer
0: Receive
1: Send
0: Receive...
Currently not used
Currently not used
Currently not used
Currently not usedText is not SVG - cannot display \ No newline at end of file diff --git a/docs/daisi/img/logging_sola.svg b/docs/daisi/img/logging_sola.svg new file mode 100644 index 00000000..c3cd3580 --- /dev/null +++ b/docs/daisi/img/logging_sola.svg @@ -0,0 +1,4 @@ + + + +
DeviceApplication (General)
DeviceApplication (General)
ApplicationUuid: integer
ApplicationUuid: integer
ApplicationName: varchar
ApplicationName: varchar
DeviceUuid: integer
DeviceUuid: integer
StartTime_ms: integer
StartTime_ms: integer
StopTime_ms: integer
StopTime_ms: integer
SolaMessageIdMapping
SolaMessageIdMapping
Id: integer
Id: integer
SolaMessageUuid: varchar
SolaMessageUuid: varchar
EventDisseminationMessageUuid: varchar
EventDisseminationMessageUuid: varchar
SolaTopicEvent
SolaTopicEvent
Id: integer
Id: integer
Timestamp_ms: Integer
Timestamp_ms: Integer
Topic: varchar
Topic: varchar
SolaApplicationId: varchar
SolaApplicationId: varchar
Subscribe: Integer
Subscribe: Integer
SolaTopicMessage
SolaTopicMessage
Id: Integer
Id: Integer
Timestamp_ms: Integer
Timestamp_ms: Integer
Topic: varchar
Topic: varchar
MessageUuid: varchar
MessageUuid: varchar
SolaApplicationId: varchar
SolaApplicationId: varchar
Receive: Integer
Receive: Integer
NatterMessage (natter)
NatterMessage (natter)
Id: Integer
Id: Integer
Uuid: varchar
Uuid: varchar
Topic: varchar
Topic: varchar
0: Unsubscribe
1: Subscribe
0: Unsubscribe...
Mapping from SOLA Message IDs to message IDs used by the event dissemination component. May be empty if no mapping is required. This could for example happen if the EventDissemination component has no concept of message IDs. natter is used here as an example where a mapping is required.
Mapping from SOLA Message IDs to message ID...
0: Send
1: Receive
0: Send...
All subscribe and unsubscribe events on topics
All subscribe and...
Information about all published and delivered messages.
For each call to publish(..), this table will contain at least one entry.
Information about all publish...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/daisi/img/mobility_model_ns3.svg b/docs/daisi/img/mobility_model_ns3.svg new file mode 100644 index 00000000..86a7c6ed --- /dev/null +++ b/docs/daisi/img/mobility_model_ns3.svg @@ -0,0 +1,4 @@ + + + +
Component implementation
dependency
Component implementation...
AMR Mobility Model ns-3
AMR Mobility Model ns-3
get Position
get Position
AMR Physical Asset
AMR Physical Asset
AMR Asset Connector ns-3
AMR Asset Connector...
execute (Functionality)
execute (Functionali...
ns-3 Simulator Modules
ns-3 Simulator Modules
AMR Mobility Helper
AMR Mobility Helper
calculate Mobility Status
calculate Mobility S...
get Velocity / get Acceleration / get Pose
get Velocity / get A...
calculate Phases
calculate PhasesText is not SVG - cannot display \ No newline at end of file diff --git a/docs/daisi/img/network_structure.svg b/docs/daisi/img/network_structure.svg new file mode 100644 index 00000000..23c5a7b4 --- /dev/null +++ b/docs/daisi/img/network_structure.svg @@ -0,0 +1,4 @@ + + + +
Subnet:
192.169.0.1/16
Subnet:192.169.0.1/16
Subnet:
192.168.0.1/16
Subnet:192.168.0.1/16
Subnet:
1.2.0.1/16
Subnet:1.2.0.1/16
ns-3 node
ns-...
ns-3 node
ns-...
ns-3 node
ns-...
Subnet:
1.1.0.1/16
Subnet:1.1.0.1/16
Wi-Fi
Wi-Fi
Wi-Fi
Wi-Fi
Wi-Fi
Wi-Fi
CSMA
CSMA
Access Point
Acces...
CSMA
CSMA
L2 Switch
L2 Swi...
CSMA
CSMA
CSMA
CSMA
L2 Switch
L2 Swi...
CSMA
CSMA
Access Point
Acces...
L3 Router
L3 Router
ns-3 node
ns-...
ns-3 node
ns-...
ns-3 node
ns-...
CSMA
CSMA
CSMA
CSMA
ns-3 node
ns-...
ns-3 node
ns-...
ns-3 node
ns-...
Wi-Fi
Wi-Fi
Wi-Fi
Wi-Fi
Wi-Fi
Wi-Fi
CSMA
CSMA
ns-3 node
ns-...
ns-3 node
ns-...
ns-3 node
ns-...
CSMA
CSMA
CSMA
CSMAText is not SVG - cannot display \ No newline at end of file diff --git a/docs/daisi/img/node_placement_ns3.svg b/docs/daisi/img/node_placement_ns3.svg new file mode 100644 index 00000000..58d19ade --- /dev/null +++ b/docs/daisi/img/node_placement_ns3.svg @@ -0,0 +1,4 @@ + + + +
Wired
Wired

Wireless
Wireless
Wireless
Wireless
AMR: ns-3 Node
AMR: ns-3 Node
AMR Logical Agent
AMR Logical Agent
TCP
TCP
AMR Physical Asset
AMR Physical Asset
ns-3 Node
ns-3 Node
Material Flow Logical Agent
Material Flow Logical...
AMR: ns-3 Node
AMR: ns-3 Node
AMR Logical Agent
AMR Logical Agent
TCP
TCP
AMR Physical Asset
AMR Physical Asset
ns-3 Node
ns-3 Node
Material Flow Logical Agent
Material Flow Logical...
CSMA
CSMA
Access Point
Acces...
CSMA
CSMA
CSMA
CSMA
Switch
Switch
CSMA
CSMA
CSMA
CSMA
Switch
Switch
CSMA
CSMA
Access Point
Acces...
Wi-Fi
Wi-Fi
Wi-Fi
Wi-Fi
Router
RouterText is not SVG - cannot display \ No newline at end of file diff --git a/docs/daisi/introduction.md b/docs/daisi/introduction.md new file mode 100644 index 00000000..7e7d4fe7 --- /dev/null +++ b/docs/daisi/introduction.md @@ -0,0 +1,12 @@ +!!! danger "This is work in progress!" + +# Introduction + +> ns-3 is a discrete-event network simulator for Internet systems, targeted primarily for research and educational use. [...] The goal of the ns-3 project is to develop a preferred, open simulation environment for networking research: it should be aligned with the simulation needs of modern networking research and should encourage community contribution, peer review, and validation of the software. +> +> -- From the [ns-3 documentation](https://www.nsnam.org/about/) + +This project benefits on ns-3 being a discrete-event simulator because it simplifies logging and debugging in distributed systems and can reduce simulation time compared to real time simulators. +ns-3 is not a physics simulation but it is able to do continuous/real time simulation so it can be used in combination with other simulators. + +The simulator is used for modular testing and verification of SOLA, MINHTON, NATTER and OptiMaFlow as well as for holistic simulation of those applications. diff --git a/daisi/docs/minhton-ns3/logging.md b/docs/daisi/minhton-ns3/logging.md similarity index 67% rename from daisi/docs/minhton-ns3/logging.md rename to docs/daisi/minhton-ns3/logging.md index f8409a9e..ec94d133 100644 --- a/daisi/docs/minhton-ns3/logging.md +++ b/docs/daisi/minhton-ns3/logging.md @@ -1,37 +1,20 @@ -# MINHTON Logging +## Database structure -We are using a single SQLite database while running simulations with ns-3. -Here the logging messages from each peer get put into one sqlite database from a given simulation run. +
+ + ![DAISI SOLA logging](../img/logging_minhton.svg) +
**Figure 1:** Database structure for logging MINTHON data with ns-3.
+
-## General Side Notes - -Further details about the database structure are explained in the [main logging documentation](../logging.md). - -### IP Address - -The IP address of a physical peer will never change in the simulation, whereas the tree position of a physical peer might change multiple times through e.g. leaves, replacements or other restructuring of the network. -Therefore to determine the actual load of a peer it is necessary to compare the IP addresses and not the tree position. -The used IP addresses are based on the IPv4 standard and will be logged as a string, e.g., "1.1.0.2". -MINHTON is an application running on the physical peers, by default on port 2000. - -### Timestamp - -In the ns-3 simulation the timestamps are logged in the unit milliseconds. -But it is easy to change the unit in the simulator to even higher resolutions. - -## Tables - -The database tables related to MINHTON are: - -- **FindQuery**: Logs find queries -- **FindQueryResult**: Logs only finished find queries +- **MinhtonFindQuery**: Logs find queries +- **MinhtonFindQueryResult**: Logs only finished find queries - **MinhtonNetworkInfo**: Associates the network information consisting of an IP address and a port with an application UUID for each node. Each node exists exactly once in this table. - **MinhtonNode**: Provides a position UUID that combines the application UUID of a node with its tree position. - **MinhtonNodeState**: When the state of a node changes an entry is added. This happens when 1) a node gets accepted into the network, 2) a node leaves the network (because the status changes to *left*), and 3) a node replaces another node (because the position changes). - **MinhtonTraffic**: Each message that a node receives or sends will be logged in the MinhtonTraffic table. -- **SearchContent**: Logs the content of Search Exact requests with their attribute name and type. -- **SearchTest**: Only used for testing Search Exact with empty messages. -- **RoutingInfo**: When the routing information about a neighbor of any node changes, a new entry is added. This happens when 1) a node gets a new neighbor, 2) the network information about neighbor gets updated, and 3) a neighbor leaves the network. +- **MinhtonSearchContent**: Logs the content of Search Exact requests with their attribute name and type. +- **MinhtonSearchTest**: Only used for testing Search Exact with empty messages. +- **MinhtonRoutingInfo**: When the routing information about a neighbor of any node changes, a new entry is added. This happens when 1) a node gets a new neighbor, 2) the network information about neighbor gets updated, and 3) a neighbor leaves the network. ## Views @@ -40,20 +23,13 @@ The views are named after their originating tables: - **viewMinhtonNodeState** - **viewMinhtonTraffic** -- **viewRoutingInfo** +- **viewMinhtonRoutingInfo** ## Further Information ### MinhtonTraffic -Mode means either that the message got sent or received. - -| Mode | Interpretation | -|------|----------------| -| 0 | Receiving | -| 1 | Sending | - -Every other field represents information about the content of the message. +Most of the fields represent information about the content of the message. Sender and target must always be set. Depending on the message type the other fields might also be set. In most cases only two additional fields for nodes are necessary. diff --git a/docs/daisi/minhton-ns3/scenariofile.md b/docs/daisi/minhton-ns3/scenariofile.md new file mode 100644 index 00000000..caad4b77 --- /dev/null +++ b/docs/daisi/minhton-ns3/scenariofile.md @@ -0,0 +1,649 @@ +# Scenariofile + +!!! danger "This is work in progress!" + + +The scenariofile is a YAML-based file to specifiy the simulation setup. +It can contain the following keys: + +#### ``title`` + +Can be any string, purely descriptive at the moment. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `ScenarioTitle` + - Data type: ``std::string`` + +#### ``name`` + +Can be any string, purely descriptive at the moment. + +??? properties + + - Required: + - Reasonable default: `ScenarioName` + - Data type: ``std::string`` + +#### ``stoptime`` + + +Defines at which simulation time in milliseconds the simulation will be aborted if it does not finish earlier. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `10000000` + - Data type: ``uint64_t`` + +#### ``version`` + + +Can be used to differentiate different implementation versions. +Currently not used. + +??? properties + + - Required: + - Reasonable default: `0.1` + - Data type: ``std::string`` + +#### ``defaultDelay`` + + +Delay between each simulation step (operations defined in the `scenarioSequence`, respectively between each step for *x*-many operations) in milliseconds. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `5000` + - Data type: ``uint64_t`` + +#### ``randomSeed`` + + +Seed used for reproducable simulations. +If ``=0`` random results are produced. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `1` + - Data type: ``uint64_t`` + +#### ``logLevel`` + + +Level used for logging. + +??? properties + + - Required: + - Reasonable default: `info` + - Data type: ``std::string`` + - Possible values: ``debug``, ``info``, ``warning``, ``critical`` + +#### ``outputPath`` + + +Directory path for the resulting logging output. + +??? properties + + - Required: Only if environment variable `DAISI_OUTPUT_PATH` is not set. This yml paramater takes precedence if both are set. + - Reasonable default: `/work/ns3/results/` + - Data type: ``std::string`` + + + +#### ``fanout`` + +The [fanout](../../management_overlay/glossary.md#f) of the MINHTON tree. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `2` + - Data type: ``uint64_t`` + - Possible values: any integer ``>= 2`` + +#### `timeouts` + +Map to configure timeouts of different algorithms. +Values are in miliseconds. +For information about the different keys, see the [Doxygen page](https://iml130.github.io/sola/doxygen/structminhton_1_1TimeoutLengthsContainer.html). + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: see [Doxygen](https://iml130.github.io/sola/doxygen/structminhton_1_1TimeoutLengthsContainer.html) + +#### `algorithms` + +Map to configure which algorithms should be used. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``join``, ``leave``, ``search_exact``, ``response``, ``bootstrap`` + +#### `algorithms.join` + +Algorithm to use for joining the network. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: `minthon` + - Data type: ``std::string`` + +#### `algorithms.leave` + +Algorithm to use for leaving the network. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: `minthon` + - Data type: ``std::string`` + +#### `algorithms.search_exact` + +Algorithm to use to search for a specific node. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: `minthon` + - Data type: ``std::string`` + +#### `algorithms.response` + +Algorithm to use for responding to general messages. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: `general` + - Data type: ``std::string`` + +#### `algorithms.bootstrap` + +Algorithm to use for bootstrapping (finding entry point to network). + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: `general` + - Data type: ``std::string`` + +#### `peer_discovery_environment` + +Configuration for Peer Discovery. +Please refer to the [examples below](#peer-discovery) for detailed information on how to configure Peer Discovery. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``attributes``, ``requests`` + +#### `peer_discovery_environment.attributes` + + + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``off``, ``on``, or a list of attributes with more keys like in the [example scenariofile for entity search](https://github.com/iml130/sola/blob/main/daisi/scenarios/entity_search/example.yml). + +#### `peer_discovery_environment.requests` + + + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``off``, ``on``, or a list of attributes with more keys like in the [example scenariofile for entity search](https://github.com/iml130/sola/blob/main/daisi/scenarios/entity_search/example.yml). + +#### ``scenario_sequence`` + +A dictionary containing a list of possible scenario sequence steps. +The steps are executed in the same order as they appear in the sequence. +In the beginning the root node already exists. +This does not need to be declared. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``join-one``, ``join-many``, ``leave-one``, ``leave-many``, ``search-many``, ``search-all``, ``fail-one``, ``fail-many``, ``mixed-execution``, ``validate-leave``, ``find-query``, ``time``, ``static-build``, ``request-countdown`` + +#### `scenario_sequence.join-one` + +Creates a new node that joins the network on a specified existing node defined by its ``index`` or by ``level`` and ``number``. +When ``level`` + ``number`` and ``index`` are both defined, ``level`` + ``number`` take precedence. + +??? properties + + - ``delay`` + - Required: + - Data type: ``uint32_t`` + - ``level`` + - Required: :fontawesome-solid-star-of-life: (Together with ``number``. Alternatively define the ``index``.) + - Data type: ``uint32_t`` + - ``number`` + - Required: :fontawesome-solid-star-of-life: (Together with ``level``. Alternatively define the ``index``.) + - Data type: ``uint32_t`` + - ``index`` + - Required: :fontawesome-solid-star-of-life: (Alternatively define ``level`` and ``number``.) + - Data type: ``uint32_t`` + +#### `scenario_sequence.join-many` + +Creates multiple new nodes (with the amount given by `number`) that join the network. +Depending on the ``mode``, the new nodes either join on a node randomly selected each time, always on the root node, or they use the discover functionality to find an existing node. + +??? properties + + - ``delay`` + - Required: + - Data type: ``uint32_t`` + - ``number`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + - ``mode`` + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``random``, ``root``, ``discover`` + - Data type: ``string`` + +#### `scenario_sequence.leave-one` + +Selects an existing node by its ``index`` or by ``level`` and ``number`` and initiates its leaving procedure. +When ``level`` + ``number`` and ``index`` are defined, ``level`` + ``number`` take precedence. + +??? properties + + - ``delay`` + - Required: + - Data type: ``uint32_t`` + - ``level`` + - Required: :fontawesome-solid-star-of-life: (Together with ``number``. Alternatively define the ``index``.) + - Data type: ``uint32_t`` + - ``number`` + - Required: :fontawesome-solid-star-of-life: (Together with ``level``. Alternatively define the ``index``.) + - Data type: ``uint32_t`` + - ``index`` + - Required: :fontawesome-solid-star-of-life: (Alternatively define ``level`` and ``number``.) + - Data type: ``uint32_t`` + +#### `scenario_sequence.leave-many` + +Initiates the leave procedure on multiple existing nodes (with the amount given by `number`). +Depending on the ``mode``, the nodes are either randomly selected each time, or the leave is always initiated on the root node at the given time. + +??? properties + + - ``delay`` + - Required: + - Data type: ``uint32_t`` + - ``number`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + - ``mode`` + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``random``, ``root`` + - Data type: ``string`` + +#### `scenario_sequence.search-many` + +Searches for multiple nodes (with the amount given by `number`). + +??? properties + + - ``delay`` + - Required: + - Data type: ``uint32_t`` + - ``number`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + +#### `scenario_sequence.search-all` + +Searches for all nodes from all nodes, meaning that for `N` existing nodes this leads to `N^2 - N` initiated searches. +Warning: Can quickly congest the network! + +??? properties + + - ``delay`` + - Required: + - Data type: ``uint32_t`` + +#### `scenario_sequence.fail-one` + +Initiates a failure an existing node specified by its ``index`` or by ``level`` and ``number``. +When ``level`` + ``number`` and ``index`` are defined, ``level`` + ``number`` take precedence. + +??? properties + + - ``delay`` + - Required: + - Data type: ``uint32_t`` + - ``level`` + - Required: :fontawesome-solid-star-of-life: (Together with ``number``. Alternatively define the ``index``.) + - Data type: ``uint32_t`` + - ``number`` + - Required: :fontawesome-solid-star-of-life: (Together with ``level``. Alternatively define the ``index``.) + - Data type: ``uint32_t`` + - ``index`` + - Required: :fontawesome-solid-star-of-life: (Alternatively define ``level`` and ``number``.) + - Data type: ``uint32_t`` + +#### `scenario_sequence.fail-many` + +Initiates a failure on multiple nodes (with the amount given by `number`). + +??? properties + + - ``delay`` + - Required: + - Data type: ``uint32_t`` + - ``number`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + +#### `scenario_sequence.mixed-execution` + +Schedules a mixed execution with joins (with the amount given by ``join-number``), leaves (with the amount given by ``leave-number``), and searches (with the amount given by ``search-number``) that are randomly shuffled. + +??? properties + + - ``delay`` + - Required: + - Data type: ``uint32_t`` + - ``join-number`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + - ``leave-number`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + - ``search-number`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + +#### `scenario_sequence.validate-leave` + +Iterates over all nodes and lets them leave, followed by them joining the network again in the mode ``random``. + +??? properties + + - ``delay`` + - Required: + - Data type: ``uint32_t`` + +#### `scenario_sequence.find-query` + +Selects a requesting node by its ``level`` and ``number`` that sends a find query. +The find query is specified by ``scope``, ``query``, and ``validity-threshold``. + +??? properties + + - ``level`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + - ``number`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + - ``scope`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``string`` + - ``query`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``string`` + - ``validity-threshold`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + +#### `scenario_sequence.time` + +Waits the specificed amount of ``time`` (miliseconds). + +??? properties + + - ``time`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + +#### `scenario_sequence.static-build` + +Creates a network with multiple nodes (with the amount given by ``number``) statically without using the join algorithm. + +??? properties + + - ``number`` + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint32_t`` + +#### `scenario_sequence.request-countdown` + + + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint64_t`` + +## Examples + +### Adding Nodes + +The following `scenario_sequence` lets 100 nodes join the network. + +```yaml +scenario_sequence: + - type: join-many: + number: 100 + mode: random + delay: 1000 +``` + +### Removing Nodes + +The following `scenario_sequence` lets 100 nodes join the network, and than 100 nodes are leaving the network. + +```yaml +scenario_sequence: + - type: join-many: + number: 100 + mode: random + delay: 1000 + - type: leave-many: + number: 100 + mode: random + delay: 1000 +``` + +### Searching Nodes + +The following `scenario_sequence` lets 100 nodes join the network, and than 100 search-exact queries are executed. +After 100 search-exact queries are executed, "search-all" is executed (Warning: search-all can congest the network quickly). + +```yaml +scenario_sequence: + - type: join-many: + number: 100 + mode: random + delay: 1000 + - type: search-many: + number: 100 + delay: 1000 + - type: search-all: + delay: 1000 +``` + +### Static P2P Build + +Building a network statically of 100 nodes + 1 root node without needing join. +It is only possible to execute this command once right in the beginning. +The event timestamp cannot be 0 - therefore you need to increase the time by a little bit. + +```yaml +scenario_sequence: + - type: time + time: 100 + - type: static-build: + number: 100 + mode: random + delay: 1000 +``` + +### Peer Discovery + +Inside the scenario sequence, [ESearch](../../management_overlay/using.md#peer-discovery-entity-search-esearch) find queries can be specified, after you have created a network as [shown above](#adding-nodes). +You initiate a find query with the requesting node (level:number). +The scope can be `all` or `some` and the query must be a valid expression. +In the following example we define a find query from the requesting node 100:100 with an unrestricted scope and query the attribute `a01` and `a02` with a value over 5. + +```yaml +... +scenario_sequence: +... + - type: find-query + level: 100 + number: 100 + scope: all + query: ((HAS a01) AND (a02 > 5)) + validity-threshold: 10000 +``` + +Periodically repeated requests are being counted down. +After the countdown value has been reached, the simulation will wait until the last request has been processed and the simulation stop time will be set accordingly. + +```yaml +scenario_sequence: +... + - type: request-countdown + number: 100 +``` + +Peer Discovery can be turned off by using + +```yaml +peer_discovery_environment: + attributes: off + requests: off +``` + +To enable Peer Discovery, you need to specify the attributes. +The name of an attribute (here a01, a02...) can be chosen arbitrarily, but must be unique. + +Each attribute needs a presence, content and update behavior like this: + +```yaml +attributes: + a01: + presence_behavior: + percentage: 0.8 + content_behavior: + ... + update_behavior: + ... + a02: + presence_behavior: + ... + content_behavior: + ... + update_behavior: + ... +``` + +**Presence Behavior:** + +Presence behavior describes the percentage of nodes who posses this attribute. +The percentage has to be given as a float (100% -> 1.0). + +**Content Behavior:** + +Content behavior describes the kinds of values an attribute can have. +With the types `uniform` and `gaussian` you can only use numerical values. +With the types `choice` and `constant` the values can be either integers, floats, booleans or strings. + +Uniform: + +```yaml +content_behavior: + type: uniform + min: 0 + max: 10 +``` + +Gaussian: + +```yaml +content_behavior: + type: gaussian + mean: 10 + variance: 2 +``` + +Constant: + +```yaml +content_behavior: + type: constant + value: 42 +``` + +Choice: + +```yaml +content_behavior: + type: choice + values: + - value1: + content: pallet + prob: 0.4 + - value2: + content: box + prob: 0.6 +``` + +**Update Behavior:** + +Update behavior describes how often the value of an attribute will be updated. +The update behavior is either dynamic or static. +If its static, the value will never be updated. +If its dynamic, values will be updated periodically. +The time period between updates is given in milliseconds, either by a constant or gaussian distribution. + +Constant: + +```yaml +update_behavior: + type: constant + value: 20000 # ms +``` + +Gaussian: + +```yaml +update_behavior: + type: gaussian + mean: 20000 # ms + variance: 5000 # ms +``` + +Uniform: + +```yaml +update_behavior: + type: uniform + min: 20000 # ms + max: 40000 # ms +``` + +Static: + +```yaml +update_behavior: + type: static +``` diff --git a/docs/daisi/natter-ns3/logging.md b/docs/daisi/natter-ns3/logging.md new file mode 100644 index 00000000..21396901 --- /dev/null +++ b/docs/daisi/natter-ns3/logging.md @@ -0,0 +1,5 @@ +
+ + ![DAISI natter logging](../img/logging_natter.svg) +
**Figure 1:** Database structure for logging natter data with ns-3. Red boxes contain descriptions for the corresponding table.
+
diff --git a/docs/daisi/natter-ns3/scenariofile.md b/docs/daisi/natter-ns3/scenariofile.md new file mode 100644 index 00000000..79bb0fcd --- /dev/null +++ b/docs/daisi/natter-ns3/scenariofile.md @@ -0,0 +1,232 @@ +# Scenariofile + + +The scenariofile is a YAML-based file to specifiy the simulation setup. +It can contain the following keys: + +#### ``title`` + +Can be any string, purely descriptive at the moment. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `ScenarioTitle` + - Data type: ``std::string`` + +#### ``name`` + +Can be any string, purely descriptive at the moment. + +??? properties + + - Required: + - Reasonable default: `ScenarioName` + - Data type: ``std::string`` + +#### ``stoptime`` + + +Defines at which simulation time in milliseconds the simulation will be aborted if it does not finish earlier. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `10000000` + - Data type: ``uint64_t`` + +#### ``version`` + + +Can be used to differentiate different implementation versions. +Currently not used. + +??? properties + + - Required: + - Reasonable default: `0.1` + - Data type: ``std::string`` + +#### ``defaultDelay`` + + +Delay between each simulation step (operations defined in the `scenarioSequence`, respectively between each step for *x*-many operations) in milliseconds. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `5000` + - Data type: ``uint64_t`` + +#### ``randomSeed`` + + +Seed used for reproducable simulations. +If ``=0`` random results are produced. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `1` + - Data type: ``uint64_t`` + +#### ``logLevel`` + + +Level used for logging. + +??? properties + + - Required: + - Reasonable default: `info` + - Data type: ``std::string`` + - Possible values: ``debug``, ``info``, ``warning``, ``critical`` + +#### ``outputPath`` + + +Directory path for the resulting logging output. + +??? properties + + - Required: Only if environment variable `DAISI_OUTPUT_PATH` is not set. This yml paramater takes precedence if both are set. + - Reasonable default: `/work/ns3/results/` + - Data type: ``std::string`` + + + +#### ``fanout`` + +The fanout of the underlying MINHTON tree used for broadcasting. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `2` + - Data type: ``uint64_t`` + - Possible values: any integer ``>= 2`` + +#### ``number_nodes`` + +The number of nodes in the MINHTON tree used for broadcasting. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `20` + - Data type: ``uint32_t`` + +#### ``mode`` + +The natter algorithm used for broadcasting. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `minhcast` + - Data type: ``std::string`` + - Possible values: ``minhcast`` + +#### ``scenario_sequence`` + +A dictionary containing a list of possible scenario sequence steps. +The steps are executed in the same order as they appear in the sequence. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``join``, ``publish`` + +#### ``scenario_sequence.join`` + +A scenario step to let nodes join the MINHTON tree. +When executing this step, all nodes (as specified by ``numberNodes``) will join the network. + +This is a dictionary containing key, value pairs, that further specify this step. + +??? properties + + - Required: + - Possible values: ``mode``, ``delay`` + +#### ``scenario_sequence.join.mode`` + +Specify which type of join should be used to join the tree. + +With the MINHCAST join, all connections are statically calculated and inserted into the nodes. +The [actual MINHTON join algorithm](../../management_overlay/algorithms/join.md) is not executed. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``minhcast`` + +#### ``scenario_sequence.join.delay`` + +Specifies **additional** delay (added to ``default_delay``) that is added **before** executing the MINHTON static join. + +??? properties + + - Required: + - Reasonable default: `5000` + - Data type: ``uint64_t`` + +#### ``scenario_sequence.publish`` + +A scenario step to let nodes publish a message. + +This is a dictionary containing key, value pairs, that further specify this step. + +??? properties + + - Required: + - Possible values: ``number``, ``delay``, ``mode``, ``message_size`` + +#### ``scenario_sequence.publish.number`` + +Specifies the number of nodes that should publish a message in this step. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `1` + - Data type: ``uint64_t`` + +#### ``scenario_sequence.publish.delay`` + +Specifies **additional** delay (added to ``default_delay``) that is added **before** before publishing a message. + +When more than one node should publish a message in the same step, this delay is added before each publish. + +??? properties + + - Required: + - Reasonable default: `5000` + - Data type: ``uint64_t`` + +#### ``scenario_sequence.publish.mode`` + +Specifies which node(s) should publish a message. + +In mode ``random``, the nodes are selected completely randomly. + +With mode ``sequential``, the nodes are selected by their ID one after another, starting with ID 0. +For MINHTON, this results in publishing level-wise from left to right, starting with node 0:0, then 1:0, 1:1, 2:0, 2:1 and so forth. +For each ``publish`` step, this procedure starts again from ID 0. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `random` + - Data type: ``string`` + - Possible values: ``random``, ``sequential`` + +#### ``scenario_sequence.publish.message_size`` + +The size of the message that should be published in bytes. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `100` + - Data type: ``uint64_t`` diff --git a/docs/daisi/optimaflow-ns3/logging.md b/docs/daisi/optimaflow-ns3/logging.md new file mode 100644 index 00000000..df40fd98 --- /dev/null +++ b/docs/daisi/optimaflow-ns3/logging.md @@ -0,0 +1,12 @@ +!!! danger "This is work in progress!" + +# Logging + +
+ + ![DAISI OptiMaFlow logging](../img/logging_optimaflow.svg) +
**Figure 1:** Database structure for logging OptiMaFlow data with ns-3.
+
+ + + diff --git a/docs/daisi/optimaflow-ns3/scenariofile.md b/docs/daisi/optimaflow-ns3/scenariofile.md new file mode 100644 index 00000000..6dfd8370 --- /dev/null +++ b/docs/daisi/optimaflow-ns3/scenariofile.md @@ -0,0 +1,405 @@ +# Scenariofile + + +The scenariofile is a YAML-based file to specifiy the simulation setup. +It can contain the following keys: + +#### ``title`` + +Can be any string, purely descriptive at the moment. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `ScenarioTitle` + - Data type: ``std::string`` + +#### ``name`` + +Can be any string, purely descriptive at the moment. + +??? properties + + - Required: + - Reasonable default: `ScenarioName` + - Data type: ``std::string`` + +#### ``stoptime`` + + +Defines at which simulation time in milliseconds the simulation will be aborted if it does not finish earlier. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `10000000` + - Data type: ``uint64_t`` + +#### ``version`` + + +Can be used to differentiate different implementation versions. +Currently not used. + +??? properties + + - Required: + - Reasonable default: `0.1` + - Data type: ``std::string`` + +#### ``defaultDelay`` + + +Delay between each simulation step (operations defined in the `scenarioSequence`, respectively between each step for *x*-many operations) in milliseconds. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `5000` + - Data type: ``uint64_t`` + +#### ``randomSeed`` + + +Seed used for reproducable simulations. +If ``=0`` random results are produced. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `1` + - Data type: ``uint64_t`` + +#### ``logLevel`` + + +Level used for logging. + +??? properties + + - Required: + - Reasonable default: `info` + - Data type: ``std::string`` + - Possible values: ``debug``, ``info``, ``warning``, ``critical`` + +#### ``outputPath`` + + +Directory path for the resulting logging output. + +??? properties + + - Required: Only if environment variable `DAISI_OUTPUT_PATH` is not set. This yml paramater takes precedence if both are set. + - Reasonable default: `/work/ns3/results/` + - Data type: ``std::string`` + + + +#### ``stop_time`` + +Defines at which simulation time in seconds the simulation will be aborted if it does not finish earlier. +This is the successor of ``stoptime`` which is not used by OptiMaFlow. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `5000` + - Data type: ``uint64_t`` + +#### ``random_seed`` + +Seed used for reproducable simulations. +If ``=0`` random results are produced. +This is the successor of ``randomSeed`` which is not used by OptiMaFlow. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `1` + - Data type: ``uint64_t`` + +#### ``default_delay`` + +Delay between each simulation step (operations defined in the `scenarioSequence`, respectively between each step for *x*-many operations) in seconds. +This is the successor of ``defaultDelay`` which is not used by OptiMaFlow. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `5` + - Data type: ``uint64_t`` + +#### ``topology`` + +Start of a sequence of mappings to define the topology of the simulation area (for example a factory hall). +Details about all possible properties can be found [on the Doxygen page](https://iml130.github.io/sola/doxygen/structdaisi_1_1cpps_1_1TopologyScenario.html). + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: see [Doxygen](https://iml130.github.io/sola/doxygen/structdaisi_1_1cpps_1_1TopologyScenario.html) + +``` +topology: + width: 50 + height: 20 + depth: 0 +``` + +#### ``initial_number_of_amrs`` + +Number of AMRs spawned in the simulation. +One AMR consists of two applications (logical AMR agent and physical AMR) running on a single ns-3 node. +Currently the number of AMRs cannot be changed at runtime, hence this is the total number of AMRs during the entire simulation. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `12` + - Data type: ``uint64_t`` + +#### ``number_of_material_flows`` + +Currently unused. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `5` + - Data type: ``uint64_t`` + +#### ``number_of_material_flow_agents`` + +Number of Material flow agents that should be spawned. +For each agent a separate ns-3 node is created. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `5` + - Data type: ``uint64_t`` + +#### ``do_material_flow_agents_leave_after_finish`` + +Specifies whether a Material Flow agent should shutdown (disconnect from all network functionalities) after the material flow was finished. +If set to ``false``, the Material Flow agent stays connected and can be reused for another material flow. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `false` + - Data type: ``bool`` + +#### ``algorithm`` + +Start of a sequence of mappings to specify the algorithms used by the logical agents. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``assignment_strategy`` + +#### ``algorithm.assignment_strategy`` + +The algorithm used to assign tasks/orders. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``iterated_auction``, ``round_robin`` + +#### ``autonomous_mobile_robots`` + +Map containing the description of different types of AMRs. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``description`` + +#### ``autonomous_mobile_robots.description`` + +Map containing the description of a single type of AMR. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``properties``, ``kinematics``, ``load_handling`` + +#### ``autonomous_mobile_robots.description.properties`` + +Basic properties about the AMR. +Details about all possible properties can be found [on the Doxygen page](https://iml130.github.io/sola/doxygen/structdaisi_1_1cpps_1_1AmrPropertiesScenario.html). + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: see [Doxygen](https://iml130.github.io/sola/doxygen/structdaisi_1_1cpps_1_1AmrPropertiesScenario.html) + + +#### ``autonomous_mobile_robots.description.kinematic`` + +Information about the kinematics of the AMR. +Details about all possible keys can be found [on the Doxygen page](https://iml130.github.io/sola/doxygen/structdaisi_1_1cpps_1_1AmrKinematicsScenario.html). + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: see [Doxygen](https://iml130.github.io/sola/doxygen/structdaisi_1_1cpps_1_1AmrKinematicsScenario.html) + +#### ``autonomous_mobile_robots.description.load_handling`` + +Information about the load handling units of the AMR. +Details about all possible keys can be found [on the Doxygen page](https://iml130.github.io/sola/doxygen/structdaisi_1_1cpps_1_1AmrLoadHandlingScenario.html). + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: see [Doxygen](https://iml130.github.io/sola/doxygen/structdaisi_1_1cpps_1_1AmrLoadHandlingScenario.html) + +#### ``material_flows`` + +Start of a sequence of mapping to specify the material flows. + +Currently only placeholder. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``mf`` + +#### ``material_flows.mf`` + +Map of information about a specific material flow. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``mfdl_program``, ``friendly_name`` + +#### ``material_flows.mf.mfdl_program`` + +Currently unused. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``std::string`` + + +#### ``material_flows.mf.friendly_name`` + +Human readable name of this material flow. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``std::string`` + +#### ``scenario_sequence`` + +A dictionary containing a list of possible scenario sequence steps. +The steps are executed in the same order as they appear in the sequence. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``spawnInfo`` + +#### ``scenario_sequence.spawnInfo`` + +Scenario step to initialize and start entities. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``entity``, ``friendly_name``, ``start_time``, ``spawn_distribution`` + +#### ``scenario_sequence.spawnInfo.entity`` + +The general type of entity to initialize. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible value: ``amr``, ``mf`` + - Data type: ``std::string`` + +#### ``scenario_sequence.spawnInfo.friendly_name`` + +The specific typ of the entity to initialize (for example the friendly name of a AMR type specified with ``autonomous_mobile_robots``) + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``std::string`` + +#### ``scenario_sequence.spawnInfo.start_time`` + + + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint64_t`` + +#### ``scenario_sequence.spawnInfo.spawn_distribution`` + +Map containing information about the spawn distribution. + + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``type``, ``number``, ``mean``, ``sigma``, ``percentage`` + +#### ``scenario_sequence.spawnInfo.spawn_distribution.type`` + + + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: ``absolute``, ``gaussian``, ``relative`` + - Data type: ``std::string`` + +#### ``scenario_sequence.spawnInfo.spawn_distribution.number`` + +For absolute distribution. + + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint16_t`` + +#### ``scenario_sequence.spawnInfo.spawn_distribution.mean`` + +Mean for gaussian distribution. + + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``double`` + +#### ``scenario_sequence.spawnInfo.spawn_distribution.sigma`` + +Standard deviation for gaussian distribution. + + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``double`` + +#### ``scenario_sequence.spawnInfo.spawn_distribution.percentage`` + +Percentage for relative distribution. + + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``double`` + diff --git a/docs/daisi/optimaflow-ns3/specifics.md b/docs/daisi/optimaflow-ns3/specifics.md new file mode 100644 index 00000000..f575c849 --- /dev/null +++ b/docs/daisi/optimaflow-ns3/specifics.md @@ -0,0 +1,93 @@ +!!! danger "This is work in progress!" + +# Implementation Specifics + +This page contains information about ns-3 specific implementation details. + +If you want to learn more about OptiMaFlow go to the [OptiMaFlow tab](../../optimaflow/introduction.md). + +## AMR Mobility Model + +There is exactly one AMR Mobility Model for every AMR Physical Asset. +The AMR Physical Asset is connected to the AMR Mobility Model through its AMR Asset Connector. + +The ns-3 Simulator also uses get Position to do i. e. signal strength calculations. + +AMR Mobility Model offers the abilities to + +- execute a Functionality +- get Position +- get Pose +- get Velocity +- get Acceleration + +The AMR Mobility Model's abilities use the [AMR Mobility Helper](../../optimaflow/participants/amr.md#amr-mobility-helper) to calculate the AMR's status. + + + +
+ ![**Figure 1:** Dependencies related to AMR Mobility Model ns-3](../img/mobility_model_ns3.svg) +
**Figure 1:** Dependencies related to AMR Mobility Model ns-3
+
+ +### Event driven movement simulation + +Each [Functionality](../../optimaflow/participants/amr.md#functionality) will be represented by a sequence of AMR Mobility Status. +An AMR Mobility Status that consists of + +- an AMR Movement State (_Accelerating, ConstSpeedTraveling, Decelerating, Stationary, Idle_; _Stationary_ means that the AMR is stationary while doing something else in contrast to being _Idle_) +- an acceleration vector +- a velocity vector +- a position +- a timestamp that marks the instance when the AMR Mobility Status is entered + +Each AMR Mobility Status in the sequence marks the beginning of a phase during which the AMR has a constant AMR Movement State. +The next AMR Mobility Status in the sequence also marks the end of the previous phase. +The last AMR Mobility Status in a sequence is always an _Idle_ phase. + +The AMR Mobility Helper calculates those phases for a given Functionality. + +For a Move To Functionality the [AMR Mobility Helper](../../optimaflow/participants/amr.md#amr-mobility-helper) uses a trapezoid velocity model that has three phases: + +- _Accelerating_, +- _ConstSpeedTraveling_, +- _Decelerating_. + +Load and Unload Functionalities only have a _Stationary_ phase. + +The ns-3 Simulator Modules check the AMR's position for different purposes at different times. +To be able to calculate the position or status at a specific time the AMR Mobility Model ns-3 holds the current phase in an AMR Mobility Status variable and calculates the current status using the phases AMR Mobility Status as the base of the calculation. + +If for example the current phase is a _ConstSpeedTraveling_ phase, the current position `c.position` is the phase's AMR Mobility Status position `p.position` plus the distance vector travelled until the current timestamp `c.timestamp`. + +``` +c.position = p.position + p.velocity * (c.timestamp - p.timestamp) +``` + +To change the phases at the right time an event is scheduled in the simulator at the timestamp of the next phase. + +## AMR Asset Connector + +The ns-3 specific implementaion of the AMR Asset Connector is the "AMR Asset Connector ns-3". +Since the AMR Mobility Model ns-3 offers equivalent functions, the AMR Asset Connector ns-3 simply delegates the ns-3 dependent functions as shown in [Figure 1](#fig1). + +## Networking + +OptiMaFlow does not specify where a component runs but for the simulation a decision had to be made. +There are three components: + +- Material Flow Logical Agent +- AMR Logical Agent +- AMR Physical Asset + +and each instance of those runs in its own ns-3 application. +ns-3 applications run on ns-3 Nodes which are simulated devices with a network connection of some description. + +While different configurations would be possible in the current implementation each Material Flow Logical Agent application runs on its own ns-3 Node, while each AMR Logical Agent and AMR Physical Asset application pair shares one ns-3 Node. +Material Flow Logical Agent Nodes use a wired network connection and AMR Nodes connect to the network via Wi-Fi. +AMR Logical Agents and AMR Physical Assets that run on the same Node are connected via a direct TCP connection. + +
+ ![**Figure 2:** Components, Devices and Connections](../img/node_placement_ns3.svg) +
**Figure 2:** Components, Devices and Connections
+
diff --git a/docs/daisi/scenariofile_general.md b/docs/daisi/scenariofile_general.md new file mode 100644 index 00000000..fdb42542 --- /dev/null +++ b/docs/daisi/scenariofile_general.md @@ -0,0 +1,94 @@ + + +The scenariofile is a YAML-based file to specifiy the simulation setup. +It can contain the following keys: + +#### ``title`` + +Can be any string, purely descriptive at the moment. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `ScenarioTitle` + - Data type: ``std::string`` + +#### ``name`` + +Can be any string, purely descriptive at the moment. + +??? properties + + - Required: + - Reasonable default: `ScenarioName` + - Data type: ``std::string`` + +#### ``stoptime`` + + +Defines at which simulation time in milliseconds the simulation will be aborted if it does not finish earlier. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `10000000` + - Data type: ``uint64_t`` + +#### ``version`` + + +Can be used to differentiate different implementation versions. +Currently not used. + +??? properties + + - Required: + - Reasonable default: `0.1` + - Data type: ``std::string`` + +#### ``defaultDelay`` + + +Delay between each simulation step (operations defined in the `scenarioSequence`, respectively between each step for *x*-many operations) in milliseconds. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `5000` + - Data type: ``uint64_t`` + +#### ``randomSeed`` + + +Seed used for reproducable simulations. +If ``=0`` random results are produced. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `1` + - Data type: ``uint64_t`` + +#### ``logLevel`` + + +Level used for logging. + +??? properties + + - Required: + - Reasonable default: `info` + - Data type: ``std::string`` + - Possible values: ``debug``, ``info``, ``warning``, ``critical`` + +#### ``outputPath`` + + +Directory path for the resulting logging output. + +??? properties + + - Required: Only if environment variable `DAISI_OUTPUT_PATH` is not set. This yml paramater takes precedence if both are set. + - Reasonable default: `/work/ns3/results/` + - Data type: ``std::string`` diff --git a/docs/daisi/sola-ns3/logging.md b/docs/daisi/sola-ns3/logging.md new file mode 100644 index 00000000..45088aaf --- /dev/null +++ b/docs/daisi/sola-ns3/logging.md @@ -0,0 +1,5 @@ +
+ + ![DAISI SOLA logging](../img/logging_sola.svg) +
**Figure 1:** Database structure for logging SOLA data with ns-3. Red boxes contain descriptions for the corresponding table.
+
diff --git a/docs/daisi/sola-ns3/scenariofile.md b/docs/daisi/sola-ns3/scenariofile.md new file mode 100644 index 00000000..39cd5340 --- /dev/null +++ b/docs/daisi/sola-ns3/scenariofile.md @@ -0,0 +1,239 @@ +# Scenariofile + + +The scenariofile is a YAML-based file to specifiy the simulation setup. +It can contain the following keys: + +#### ``title`` + +Can be any string, purely descriptive at the moment. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `ScenarioTitle` + - Data type: ``std::string`` + +#### ``name`` + +Can be any string, purely descriptive at the moment. + +??? properties + + - Required: + - Reasonable default: `ScenarioName` + - Data type: ``std::string`` + +#### ``stoptime`` + + +Defines at which simulation time in milliseconds the simulation will be aborted if it does not finish earlier. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `10000000` + - Data type: ``uint64_t`` + +#### ``version`` + + +Can be used to differentiate different implementation versions. +Currently not used. + +??? properties + + - Required: + - Reasonable default: `0.1` + - Data type: ``std::string`` + +#### ``defaultDelay`` + + +Delay between each simulation step (operations defined in the `scenarioSequence`, respectively between each step for *x*-many operations) in milliseconds. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `5000` + - Data type: ``uint64_t`` + +#### ``randomSeed`` + + +Seed used for reproducable simulations. +If ``=0`` random results are produced. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `1` + - Data type: ``uint64_t`` + +#### ``logLevel`` + + +Level used for logging. + +??? properties + + - Required: + - Reasonable default: `info` + - Data type: ``std::string`` + - Possible values: ``debug``, ``info``, ``warning``, ``critical`` + +#### ``outputPath`` + + +Directory path for the resulting logging output. + +??? properties + + - Required: Only if environment variable `DAISI_OUTPUT_PATH` is not set. This yml paramater takes precedence if both are set. + - Reasonable default: `/work/ns3/results/` + - Data type: ``std::string`` + + + +#### ``number_nodes`` + +The number of SOLA nodes available in the simulation. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `3` + - Data type: ``uint64_t`` + +#### ``scenario_sequence`` + +A dictionary containing a list of possible scenario sequence steps. +The steps are executed in the same order as they appear in the sequence. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Possible values: `start_sola`, `subscribe_topic`, `delay`, `publish` + +#### ``scenario_sequence.start_sola`` + +Start and initialize SOLA on **all nodes**. +Starting SOLA means, depending on the selected SOLA components, to connect to other nodes. + +This is a dictionary containing key, value pairs, that further specify this step. + +??? properties + + - Required: + - Possible values: `delay` + +#### ``scenario_sequence.start_sola.delay`` + +Delay between the nodes joining the SOLA network. + +!!! danger "Default delay not added" + + Only the delay specified with `delay` is added between the start of SOLA on different nodes. + The default delay is not added! + Further, this delay is not added after the last schedule of start! + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `1000` + - Data type: ``uint64_t`` + +#### ``scenario_sequence.subscribe_topic`` + +Specifies that **all** nodes should subscribe to a topic. + +This is a dictionary containing key, value pairs, that further specify this step. + +??? properties + + - Required: + - Possible values: `topic`, `delay` + +#### ``scenario_sequence.subscribe_topic.topic`` + +The name of the topic to subscribe to. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `helloworld` + - Data type: ``std::string`` + +#### ``scenario_sequence.subscribe_topic.delay`` + +Delay between the nodes joining the SOLA network. + +!!! danger "Default delay not added" + + Only the delay specified with `delay` is added between the subscription process of different nodes. + The default delay is not added! + Further, this delay is not added after the last scheduling of a subscribe event! + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Reasonable default: `1000` + - Data type: ``uint64_t`` + +#### ``scenario_sequence.delay`` + +This step allows to add delay between steps. + +This is a dictionary containing key, value pairs, that further specify this step. + +??? properties + + - Required: + - Possible values: `delay` + +#### ``scenario_sequence.delay.delay`` + +The delay in miliseconds. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint64_t`` + +#### ``scenario_sequence.publish`` + +This step allows to let a node publish a message on a topic. + +This is a dictionary containing key, value pairs, that further specify this step. + +??? properties + + - Required: + - Possible values: `topic`, `message_size`, `node_id` + +#### ``scenario_sequence.publish.topic`` + +The name of the topic to which the message should be published to. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``std::string`` + +#### ``scenario_sequence.publish.message_size`` + +The size of the message to publish in bytes. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint64_t`` + +#### ``scenario_sequence.publish.node_id`` + +The node that should publish a message. + +??? properties + + - Required: :fontawesome-solid-star-of-life: + - Data type: ``uint64_t`` diff --git a/docs/daisi/using.md b/docs/daisi/using.md new file mode 100644 index 00000000..ceef12ea --- /dev/null +++ b/docs/daisi/using.md @@ -0,0 +1,56 @@ +!!! danger "This is work in progress!" + +First you need to build SOLA with the ns-3 integration as described in [Getting Started](../getting_started.md). +Following these steps, all components are integrated into a single ns-3 simulation executable that is located at ``/build/main/Main``. + +### Specify logging output path + +Before running the simulation, the path where the SQLite database file should be created must be specified. +This database is used for logging simulation events, states and other simulation relevant data. +To specify the path, set the environment variable ``DAISI_OUTPUT_PATH`` to the desired output path, like ``export DAISI_OUTPUT_PATH=``. + + +### Specifiy application + +The name of the application that should run in the simulation must be passed to the executable with ``--environment=``. +The following applications are supported: + +- [``minhton``](../management_overlay/introduction.md) +- [``natter``](../natter/introduction.md) +- [``sola``](../index.md) +- [``cpps`` (OptiMaFlow)](../optimaflow/introduction.md) + +!!! warning "Running OptiMaFlow" + + To run OptiMaFlow, the ``MINHTON_DIR`` environment variable needs to be set. + It should contain the path of ``/minhton``. + This path is used to read MINHTON config files. + +### Specify the scenariofile + +The simulation is controlled by a YAML-based scenariofile. +Default scenariofiles for all applications are provided in the ``/daisi/scenarios`` folder. +The structure of the scenariofile is described in the "Scenariofile" section of each application's ns-3 integration documentation (see left sidebar). + +The path to the scenariofile must be passed to the executable with ``--scenario=``. +This path must either be a absolute path or a path relative to the current working directory. + +### Run the simulation + +For example to start a OptiMaFlow simulation with your current working directory being ````, run: + +```build/main/Main --environment=cpps --scenario=daisi/scenarios/cpps/default.yml``` + +To start a different application, just pass a different environment and scenariofile path. + +### Inspecting the output + +While running the simulation, a SQLite database file is created at ``DAISI_OUTPUT_PATH``. +After the simulation finishes, you can inspect the database to get insights of the application behavior. + +!!! danger "Wait until the simulation finishes!" + + Do not open this SQLite database file while the simulation is running! + Otherwise the database might become corrupted! + +Information about which data is logged to the database can be found under the "Logging" section of each application's ns-3 integration documentation (see left sidebar). diff --git a/docs/getting_started.md b/docs/getting_started.md index 7be02dc3..00e02544 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -7,7 +7,7 @@ An instruction to install all dependencies with Ubuntu 22.04 is given below. Some dependencies are already included in the SOLA repository and are not listed here. -**Be advised that DAISI depends on all other components and all components depend on SolaNet.** +**Be advised that DAISI depends on all other components and all components depend on SolaNet.** | External dependency | DAISI | MINHTON | natter | SolaNet | @@ -65,7 +65,6 @@ For example to only build the MINHTON library (and all its internal dependencies ``` cmake --build . --target minhton_core_node - ``` ### Build with ns-3 integration @@ -99,7 +98,7 @@ This problem only appears on [Linux kernels prior to version 5.11 or low-perform To execute a ns-3 simulation or integrating components (SOLA, MINHTON, natter) into your application, visit the following pages: -* [Execute DAISI simulation](daisi/getting_started.md) +* [Execute DAISI simulation](daisi/using.md) * [Using SOLA](sola/usage.md) -* [Using MINHTON](management_overlay/getting_started.md) -* [Using natter](natter_lib/using.md) +* [Using MINHTON](management_overlay/using.md) +* [Using natter](natter/using.md) diff --git a/docs/glossary.md b/docs/glossary.md index 04cc5daa..db053b49 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -2,10 +2,10 @@ [MINHTON](management_overlay/glossary.md) -[NATTER](natter_lib/glossary.md) +[NATTER](natter/glossary.md) -[ns-3 Integration](ns3-integration/glossary.md) +[OptiMaFlow](optimaflow/glossary.md) -[Applications](applications/glossary.md) +[ns-3 Integration](daisi/glossary.md) [DAISI](daisi/glossary.md) diff --git a/docs/index.md b/docs/index.md index 44892627..0470a66a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,12 +8,12 @@ !!! info "This documentation is currently incomplete!" Any feedback on this documentation is highly welcome, including bug reports, - typos or stuff you think should be included but is not. + typos or stuff you think should be included but is not. Thanks in advance! **SOLA** is a framework providing Service Discovery and Publish-Subscribe functionalities. Different components can be used to implement these functionalities. -Initially SOLA was used with distributed peer-to-peer network structures and algorithms as the components, like [MINHTON](management_overlay/introduction.md) and [MINHCAST](natter_lib/introduction.html). +Initially SOLA was used with distributed peer-to-peer network structures and algorithms as the components, like [MINHTON](management_overlay/introduction.md) and [MINHCAST](natter/introduction.md). Hence, it omits the need for a dedicated communication instance like a message broker. But due to the flexibility of SOLA, centralized approaches are supported as well. All supported components and their SOLA-specific implementations ("connectors" between the components and SOLA) are described [here](sola/component_implementations.md). @@ -36,12 +36,12 @@ For instructions on how to build and run SOLA and its components, see [Getting S The SOLA repository contains multiple subprojects: - **SOLA (Standalone)** is the framework that initializes and uses different components to offer a Service Discovery and Publish-Subscribe API. -- **[MINHTON](management_overlay/introduction.md)** is a peer-to-peer management overlay which organizes peers in an optimized tree structure. MINHTON is a SOLA component for service discovery. -- **[natter](natter_lib/introduction.md)** is a framework for peer-to-peer Publish-Subscribe algorithms. +- **[MINHTON](management_overlay/introduction.md)** is a peer-to-peer management overlay which organizes peers in an optimized tree structure. MINHTON is a SOLA component for service discovery. +- **[natter](natter/introduction.md)** is a framework for peer-to-peer Publish-Subscribe algorithms. The MINHCAST algorithm to broadcast a message to all nodes in a MINHTON network is included in natter. natter is a SOLA component for Publish-Subscribe. - **SolaNet** is a basic asynchronous UDP networking and utility library. -- **[OptiMaFlow](applications/optimaflow/getting_started.md)** is an application in the domain of intralogistics that uses SOLA to schedule transport tasks to autonomous mobile robots. +- **[OptiMaFlow](optimaflow/introduction.md)** is an application in the domain of intralogistics that uses SOLA to schedule transport tasks to autonomous mobile robots. - **[DAISI](daisi/introduction.md)** provides the integration of the aforementioned components into the network simulator ns-3, a discrete-event network simulator for Internet systems. We are using ns-3 as the development and simulation environment for SOLA and its components. diff --git a/docs/natter/index.md b/docs/natter/introduction.md similarity index 100% rename from docs/natter/index.md rename to docs/natter/introduction.md diff --git a/docs/optimaflow/glossary.md b/docs/optimaflow/glossary.md index 780a8e06..722ab454 100644 --- a/docs/optimaflow/glossary.md +++ b/docs/optimaflow/glossary.md @@ -5,18 +5,18 @@ ## A **Action Order**:
-See [Material Flow](./optimaflow/material_flow.md#structure) +See [Material Flow](participants/material_flow.md#structure) **Action Order Step**:
-See [Material Flow](./optimaflow/material_flow.md#structure) +See [Material Flow](participants/material_flow.md#structure) **Autonomous Mobile Robot (AMR)**:
-See [Autonomous Mobile Robot](./optimaflow/amr.md#autonomous-mobile-robot-amr) +See [Autonomous Mobile Robot](participants/amr.md#autonomous-mobile-robot-amr) ## F **Functionality**:
-See [Functionality](./optimaflow/amr.md#functionality) +See [Functionality](participants/amr.md#functionality) ## M @@ -24,26 +24,26 @@ See [Functionality](./optimaflow/amr.md#functionality) See [Topology](#t) **Material Flow**:
-See [Material Flow](./optimaflow/material_flow.md) +See [Material Flow](participants/material_flow.md) **Move Order**:
-See [Material Flow](./optimaflow/material_flow.md#structure) +See [Material Flow](participants/material_flow.md#structure) **Move Order Step**:
-See [Material Flow](./optimaflow/material_flow.md#structure) +See [Material Flow](participants/material_flow.md#structure) ## O **Order**:
-See [Material Flow](./optimaflow/material_flow.md#structure) +See [Material Flow](participants/material_flow.md#structure) **Order Step**:
-See [Material Flow](./optimaflow/material_flow.md#structure) +See [Material Flow](participants/material_flow.md#structure) ## T **Task**:
-See [Task](./optimaflow/material_flow.md#task) +See [Task](participants/material_flow.md#task) **Topology**:
A Topology is used for navigation. @@ -52,7 +52,7 @@ The dimensions are the borders of the traversable area. The nodes of the graph are positions on the traversable area. **Transport Order**:
-See [Material Flow](./optimaflow/material_flow.md#structure) +See [Material Flow](participants/material_flow.md#structure) **Transport Order Step**:
-See [Material Flow](./optimaflow/material_flow.md#structure) +See [Material Flow](participants/material_flow.md#structure) diff --git a/docs/optimaflow/introduction.md b/docs/optimaflow/introduction.md index 6bb7718b..b3f2cd5e 100644 --- a/docs/optimaflow/introduction.md +++ b/docs/optimaflow/introduction.md @@ -4,8 +4,8 @@ ## Getting started -To run OptiMaFlow please download and build the repository as described [here](../../docs/getting_started.md). -Afterwards follow the instructions for [OptiMaFlow](../../daisi/docs/optimaflow-ns3/introduction.md) in the ns3-Integration tab. +To run OptiMaFlow please download and build the repository as described [here](../getting_started.md). +Afterwards, follow the instructions for [OptiMaFlow](../daisi/using.md) in the ns-3 Integration tab. ### Intralogistics diff --git a/docs/optimaflow/task_assignment/decentralized.md b/docs/optimaflow/task_assignment/decentralized.md index c0012a24..10d68d72 100644 --- a/docs/optimaflow/task_assignment/decentralized.md +++ b/docs/optimaflow/task_assignment/decentralized.md @@ -42,7 +42,7 @@ The transformation of the material flow into a precedence graph allows the TePSS ### Interaction Efficient communication is crucial for scalability in large CPPS applications. -In the context of OptiMaFlow, the aim of minimizing communication overhead is addressed through a combination of one-to-one communication and publishing on topics via SOLA with [MINHTON](TODO) for interactions involving multiple participants. +In the context of OptiMaFlow, the aim of minimizing communication overhead is addressed through a combination of one-to-one communication and publishing on topics via SOLA with [MINHTON](../../management_overlay/introduction.md) for interactions involving multiple participants. #### One-to-One Communication diff --git a/docs/optimaflow/task_assignment/round_robin.md b/docs/optimaflow/task_assignment/round_robin.md index abec3110..4684d664 100644 --- a/docs/optimaflow/task_assignment/round_robin.md +++ b/docs/optimaflow/task_assignment/round_robin.md @@ -13,9 +13,11 @@ In the centralized scenario, the participants only have to communicate with the The real logic of the task assignment procedure belongs to the central optimizer. Figure 1 shows the general architecture, where a [Material Flow](../participants/material_flow.md) contains the new tasks to be scheduled while the [AMR Logical Agents](../participants/amr.md)s represent the participants waiting for task assignments. + +
- ![Figure_1](../img/central_optimizer_architecture.svg "Overview of the central task assignment architecture.") -
**Figure 1:** Overview of the central task assignment architecture.
+ ![Figure_1](../img/central_optimizer_architecture.svg) +
**Figure 1:** Overview of the central task assignment architecture.
### Message Types diff --git a/docs/sola/component_implementations.md b/docs/sola/component_implementations.md index 84f4206c..725cd4ed 100644 --- a/docs/sola/component_implementations.md +++ b/docs/sola/component_implementations.md @@ -25,14 +25,14 @@ A description on how the Service Discovery with MINHTON works will be published The API for Publish-Subscribe component implementations is documented [here](https://iml130.github.io/sola/doxygen/classsola_1_1EventDissemination.html). ### MINHCAST -The MINHCAST algorithm is integrated into the [natter](../natter_lib/introduction.md) framework. +The MINHCAST algorithm is integrated into the [natter](../natter/introduction.md) framework. It uses the MINHTON structure to send messages to all nodes in the tree by using unicasts. -Futher information about the concept of MINHCAST can be found [here](../natter_lib/programmers/minhcast.md). +Futher information about the concept of MINHCAST can be found [here](../natter/programmers/minhcast.md). The component implementation ``EventDisseminationMinhcast`` creates separate MINHTON networks (separate trees) for every topic in the Publish-Subscribe environment. As only nodes interested in a particular topic are part of a topic tree, only they are receiving messages published for this topic. The connection between nodes in the MINHTON topic trees are forwarded to MINHCAST together with the corresponding topic and are used for publishing the message. -By invoking the method ``subscribeTopic(..)``, the component implementation must also pass its own node info (MINHTON level and number) for its topic tree node. +By invoking the method ``subscribeTopic(..)``, the component implementation must also pass its own node info (MINHTON level and number) for its topic tree node. The connection information (IP address and port) of node in the topic tree must be known to join into an existing MINHTON topic tree (see [MINHTONs Join Procedure](../management_overlay/algorithms/join.md)). The component implementation uses the Service Discovery to discover these information. By using the Service Discovery like a key-value database, the component implementation searches for a key with the name of the topic. diff --git a/docs/sola/logging.md b/docs/sola/logging.md index 5bc28c2e..451aa287 100644 --- a/docs/sola/logging.md +++ b/docs/sola/logging.md @@ -1,2 +1 @@ -# Logging -!!! danger "SOLAs logging component is work in progress!" +Currently SOLA does not have a separate logger. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index c0e1b9fd..f767479b 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -36,12 +36,14 @@ } figcaption p { - display: flex; + padding-left: 9ch; + position: relative; } -figcaption strong { - flex-shrink: 0; - padding-right: 1ch; +figcaption p strong { + display: block; + left: 0; + position: absolute; } /* End: Figures */ diff --git a/minhton/docs/algorithms/bootstrap.md b/minhton/docs/algorithms/bootstrap.md index d1c68f2a..3056ac97 100644 --- a/minhton/docs/algorithms/bootstrap.md +++ b/minhton/docs/algorithms/bootstrap.md @@ -9,5 +9,5 @@ The new node will then continue to join the network using the node of the first Currently, three modes can be used which define which nodes will be "bootstrap nodes". - **All nodes**: All nodes will become bootstrap nodes. This will likely cause much network traffic! (k_MULTICAST_STRATEGY = 0) -- **Prio-Nodes**: All [prio-nodes](../other/glossary.md) become bootstrap nodes (k_MULTICAST_STRATEGY = 1) +- **Prio-Nodes**: All [prio-nodes](../glossary.md) become bootstrap nodes (k_MULTICAST_STRATEGY = 1) - **Nodes with free children**: Nodes with place for new childs become bootstrap nodes (k_MULTICAST_STRATEGY = 2) diff --git a/minhton/docs/algorithms/index.md b/minhton/docs/algorithms/index.md index d77ff279..4d6f93c1 100644 --- a/minhton/docs/algorithms/index.md +++ b/minhton/docs/algorithms/index.md @@ -21,7 +21,7 @@ We will later present you how to avoid this kind of created tree. Internal name: ``nbaton_star`` -We extend the functionality by introducing bootstrapping nodes (further described as Dominating Set Nodes (DSNs)) with a more sophisticated *Join* procedure. +We extend the functionality by introducing bootstrapping nodes (further described as dominating set nodes (DSNs)) with a more sophisticated *Join* procedure. Those DSNs handle the forwarding of *Join*-request specifically to keep a null balanced tree [[3]](#references). Therefore, we tighten the condition of a balanced tree to: diff --git a/minhton/docs/algorithms/join.md b/minhton/docs/algorithms/join.md index 97be4526..a67c6556 100644 --- a/minhton/docs/algorithms/join.md +++ b/minhton/docs/algorithms/join.md @@ -10,7 +10,7 @@ The node that receives a JOIN Message executes the processJoin method. A node wh ## Finding the correct position Figure 1 illustrates how the MINHTON algorithm consists of three parts in sequence to find the correct position for a joining node. -First, a null node (compare [glossary](../other/glossary.md)) has to be found. +First, a null node (compare [glossary](../glossary.md)) has to be found. When the first reached node is not a null node, we use the adjacent to reach a null node with a single hop. Second, based on the routing table entries we determine whether we arrived on the last level or the one before it. Additional hops may be necessary to finish this process. diff --git a/minhton/docs/algorithms/leave.md b/minhton/docs/algorithms/leave.md index 62c772ef..46d35447 100644 --- a/minhton/docs/algorithms/leave.md +++ b/minhton/docs/algorithms/leave.md @@ -1,10 +1,10 @@ # Leave Procedure If a node wants to leave the network it first has to call the `initiateSelfDeparture` method. -It nay need a successor, which it can find using `FIND_REPLACEMENT` messages. +It nay need a [successor node](../glossary.md#s), which it can find using `FIND_REPLACEMENT` messages. `FIND_REPLACEMENT` messages are directed in an equivalent way as described for the [join algorithm](join.md#finding-the-correct-position). -When a node notices that it can leave its position without any violations, it sends a `REPLACEMENT_OFFER` message to the leaving node. +When a node notices that it can leave its position without any violations, it sends a `REPLACEMENT_OFFER` message to the [leaving node](../glossary.md#l). The leaving node accepts the offer by sending back a `REPLACEMENT_ACK` to the replacing node. This message contains all routing information about the leaving node, so that the replacing node can reconstruct the routing information without any additional messages. @@ -19,8 +19,8 @@ Then the replacing node has the reponsibility to rebuild everything by firstly l ## Message sequence for a successful leave procedure (MINHTON Algorithm) -0. (Leaving Node *l* sends **Find Replacement (80)**) (If successor necessary) -1. (**Find Replacement (80)** eventually reaches successor *s*) (*s* can be *l* --> No successor necessary) +0. ([Leaving node *l*](../glossary.md#l) sends **Find Replacement (80)**) (If successor necessary) +1. (**Find Replacement (80)** eventually reaches [successor node *s*](../glossary.md#s)) (*s* can be *l* --> No successor necessary) 2. *s* sends **Sign Off Parent Request (82)** to its parent *ps* 3. *ps* sends **Lock Neighbor Request (84)** to its right neighbor *rn_ps* 4. *rn_ps* replies with **Lock Neighbor Response (86)** to *ps* @@ -44,29 +44,17 @@ Then the replacing node has the reponsibility to rebuild everything by firstly l 22. *s* sends **Unlock Neighbor (96)** to *ps* 23. *ps* sends **Unlock Neighbor (96)** to *rn_ps* and *ln_ps* -## Terminology - -*leaving/left node*: the node who leaves the network - -*replacing node*: the node who is replacing the position of the leaving node - -*replaced position*: the position where the leaving node was, which is now being replaced - -*removed position*: the position where the replacing node was, but which is becoming empty now as the replacing node replaces the leaving node - -*routing table neighbor parents*: the parents of our routing table neighbors. those neighbors have the current node as a routing table neighbor child, and need to be informed about the leaving too, although the current node does not have a direct connection to them. we can calculate the positions locally. - ## Updating Network for Leave without Replacement -The leaving node must handle the updating of the network itself. For this the node has to send `REMOVE_NEIGHBOR` messages to each neighbor who knows the node (not its routing table neighbor children, but also its routing table neighbor parents). +The leaving node must handle the updating of the network itself. For this the node has to send `REMOVE_NEIGHBOR` messages to each neighbor who knows the node (not its routing table neighbor children, but also its [routing table neighbor parents](../glossary.md#r)). To the routing table neighbor parents has to be sent via `SearchExact`, because the network information is not known. After that the adjacent information has to be updated by linking the adjacent left and adjacent right of the leaving node together. ## Updating Network for Leave with Replacement -The replacing node must handle the updating of the network. -For this the nodes who know the replacing position and those who know the removing position are crucial. +The [replacing node](../glossary.md#r) must handle the updating of the network. +For this the nodes who know the replacing position and those who know the [removing position](../glossary.md#r) are crucial. Firstly we need to send `REMOVE_NEIGHBOR` messages to those nodes who know the removing position, but not the replacing position. They only need to remove their entry of the removing position. @@ -77,7 +65,7 @@ Those who know both need to update their Network Information and at the same tim After that the adjacent information has to be updated. For the adjacents of the removed position the adjacent left and adjacent right need to be linked together. -We do not need to update the adjacents of the replaced position separately, because this will already be done through the `REPLACEMENT_UPDATE` messages. +We do not need to update the adjacents of the [replaced position](../glossary.md#r) separately, because this will already be done through the `REPLACEMENT_UPDATE` messages.
diff --git a/minhton/docs/glossary.md b/minhton/docs/glossary.md index 17f3bbef..4ab510cc 100644 --- a/minhton/docs/glossary.md +++ b/minhton/docs/glossary.md @@ -8,8 +8,8 @@ This means the new node inhabits the position of one of *m* children on the leve ## D -**Dominating Set Node (DSN)**:
-DSNs are a subset of nodes establishing a Dominating Set (DS) on each level. +**Dominating set node (DSN)**:
+DSNs are a subset of nodes establishing a dominating set (DS) on each level. Using only DSNs, every node in the network can be reached by just another hop from the right DSN at maximum. ## F @@ -33,7 +33,7 @@ E.g. in a network consisting of the nodes 0:0, 1:0, 1:1, 1:2, and 1:3, this is 1 A process in which the overlay network is reduced by a node. The node is currently part of the network but will leave the network during the process. -**Leaving Node**:
+**Leaving node**:
A node that wants to leave the network. **Level**:
@@ -69,19 +69,33 @@ Physical information about a node like networking information. ## R +**Removed position**:
+The position where the replacing node was, but which is becoming empty when the replacing node replaces the leaving node. + +**Replaced position**:
+The position where the leaving node was, which is being replaced. + +**Replacing node**:
+The node who is replacing the position of the leaving node. + **Root node**:
This node is 0:0 and must always exist, otherwise, there is no starting point for the overlay structure. -**Routing Table (RT)**:
+**Routing table (RT)**:
Each node has a routing table that contains (the position and network address of) other nodes on the same level. The other nodes are selected based on a formula from the BATON / BATON\* paper. Nodes nearby are more likely to be included. +**Routing table (RT) neighbor parents**:
+The parents of our routing table neighbors. +Those neighbors have the current node as a routing table neighbor child, and need to be informed about it joining / leaving too, although the current node does not have a direct connection to them. +We can calculate the positions locally. + ## S -**Successor Node**:
+**Successor node**:
A node that is found with ``FindReplacement`` is proposed to be the last node in the network (rightmost on the lowest level). -This node will be used to replace the *Leaving Node*. +This node will be used to replace the [*leaving node*](#l). ## T diff --git a/minhton/docs/img/peer_discovery_forwarding.svg b/minhton/docs/img/peer_discovery_forwarding.svg new file mode 100644 index 00000000..bfdf3292 --- /dev/null +++ b/minhton/docs/img/peer_discovery_forwarding.svg @@ -0,0 +1,4 @@ + + + +
0:0
0:0
1:0
1:0
1:1
1:1
2:0
2:0
Φ
Φ
Φ
Φ
Φ
Φ
2:1
2:1
2:2
2:2
2:3
2:3
3:0
3:0
3:1
3:1
3:2
3:2
3:3
3:3
3:4
3:4
3:5
3:5
3:6
3:6
3:7
3:7
4:0
4:0
4:1
4:1
4:2
4:2
4:3
4:3
4:4
4:4
4:5
4:5
Φ
Φ
Φ
Φ
4:6
4:6
4:7
4:7
4:8
4:8
4:9
4:9
4:10
4:10
4:11
4:11
4:12
4:12
Cover Area
Cover...
Dominating Set Node
Dominating...
Example Node
Example No...
Φ
Φ
Peer Discovery Request
Peer Disco...
Peer Discovery Result
Peer Disco...
Φ
Φ
Forward Peer Discovery Request
Forward Peer D...Text is not SVG - cannot display \ No newline at end of file diff --git a/minhton/docs/introduction.md b/minhton/docs/introduction.md index b2c167df..7acd95c5 100644 --- a/minhton/docs/introduction.md +++ b/minhton/docs/introduction.md @@ -1,4 +1,4 @@ -# Minimal Height Tree Overlay Network (MINHTON) +# Introduction

@@ -10,9 +10,9 @@ Distributed systems, potentially growing large and consisting of heterogeneous n It becomes imperative that a P2P network is paired with efficient protocols for each phase of its life cycle: construction as well as maintenance and operation. Three operations are fundamental for a P2P network: nodes must be able to a) join, b) be located, c) leave. The main challenge for efficient protocols is that a single node will only possess limited information about the network, also known as the local view. -The minimal height tree overlay network (MINHTON) is such a P2P overlay architecture featuring several beneficial structural properties added over existing tree-structured networks. +The minimal height tree overlay network (**MINHTON**) is such a P2P overlay architecture featuring several beneficial structural properties added over existing tree-structured networks. The minimal height guarantees a global tree balance, yet, it must be retained at all times, even though the P2P network may change dynamically. -MINHTON provides efficient protocols for node Join and Departure in logarithmic order, comparable to tree overlays with less strict structural guarantees, both retaining a minimal height tree. +**MINHTON** provides efficient protocols for node Join and Departure in logarithmic order, comparable to tree overlays with less strict structural guarantees, both retaining a minimal height tree. ![Figure 1](img/cpps.png "An interconnected cyber-physical production system, representing an P2P network") **Figure 1:** An interconnected cyber-physical production system, representing a P2P network. @@ -39,7 +39,7 @@ If you use it for research, please include one of the following references in an } ``` -MINHTON is based on few other publications: +**MINHTON** is based on few other publications:

Peer Discovery in Tree-Structured P2P Overlay Networks by Means of Connected Dominating Sets diff --git a/minhton/docs/programmers/concept.md b/minhton/docs/programmers/concept.md index 3be2aabc..349a51f1 100644 --- a/minhton/docs/programmers/concept.md +++ b/minhton/docs/programmers/concept.md @@ -111,7 +111,7 @@ Because NodeInfo uses the comparison operators of LogicalNodeInfo, we can use fu
- ![Routing Table Example](../img/example_routing_table.svg) + ![Routing table Example](../img/example_routing_table.svg)
**Figure 2:** The node 3:3 in the example tree with fanout 2 maintains bidirectional links to the blue highlighted nodes on the same level in its routing table. One-directional links exist to the nodes on the level below highlighted in light blue.
diff --git a/minhton/docs/using.md b/minhton/docs/using.md index ffd3f058..5a495005 100644 --- a/minhton/docs/using.md +++ b/minhton/docs/using.md @@ -144,29 +144,53 @@ Since the node that was previously located at 2:1 moved to 1:1 to replace it, bo
**Figure 4:** The entries in the routing information of the 4 nodes in the network. The updated entries after the node, which was previously at 1:1 left, are highlighted in blue.
-## Entity Search / Peer Discovery - -Each node in the constructed peer-to-peer network may have different capabilities and properties. -To find peers with specific capabilities and properties, we use a practical solution to the problem of peer discovery, which is finding peers in the network according to a specified query. -We contribute a peer discovery for an m-ary tree-structured P2P network by utilizing a connected dominating set (CDS), a technique that is typically used in unstructured networks. -Our approach to constructing the CDS requires no additional communication cost, while nodes can insert, update and remove data within O(1). - -A peer discovery query description is given according to boolean algebra consisting of logical *and*-, *or*- and *not*-operators. -Literals are comparisons with the key-value pairs (KVPs). -The peer discovery query result is expected to contain information about each peer whose KVPs satisfy the peer discovery query. - ## Routing links
![Routing links example](./img/minhton_links.svg) -
**Figure 5:** The node 3:4 in the example tree with fanout 2 maintains several types of links.
+
**Figure 6:** The node 3:4 in the example tree with fanout 2 maintains several types of links.
Each MINHTON node individually maintains links to selected nodes in the network based on the tree structure and its position in the tree for its local view as follows: -- a link to its parent node (unless it is the root node 0:0). +- a link to its parent node (unless it is the root node (0:0)). - links to up to *m* children nodes (*m* also denotes the fanout of the tree). - a link to a left and right adjacent node based on an in-order traversal. -- links to selected same-level [neighbor nodes in routing tables (RT)](./programmers/concept.md#routingtable). -- links to all children of each same-level neighbor. +- links to selected same-level [routing table (RT) neighbors](./programmers/concept.md#routingtable). +- links to all children of each same-level neighbor (RT children). + +## Peer Discovery / Entity Search (ESearch) + +Each node in the constructed peer-to-peer network may have different capabilities and properties. +To find peers which meet specific requirements, we use a practical solution to the problem of peer discovery, which is finding peers in the network according to a specified query. +We contribute a peer discovery for an m-ary tree-structured P2P network by utilizing a connected dominating set (CDS), a technique that is typically used in unstructured networks. +Our solution is also known as Entity Search (ESearch). +Our approach to constructing the CDS requires no additional communication cost, while nodes can insert, update and remove data within O(1). + +Each CDS maintains up to two levels at the same time and consists of a number of dominating set nodes (DSNs). +Furthermore, each DSN is responsible for several nodes and their key-value pairs (KVPs) within its cover area (CA) as seen in [Figure 5](#fig_peer_discovery). +A CA includes, if present, the DSN itself, its *m* RT neighbors to the left and right, its own *m* children, and the RT children. +If a DSN has a neighboring DSN to its left, only *m − 1* in-level neighbors to the left are included in its CA. +It concludes that the CAs of all DSNs are disjoint sets, including up to *(2m + 1) · m* nodes. + +
+ + ![Routing links example](./img/peer_discovery_forwarding.svg) +
**Figure 5:** Peer Discovery example where node (2:1) sends the peer discovery request φ to one dominating set node (DSN) on each level, where at least one DSN exists. + Each DSN forwards the request to other DSNs on the same level and returns the discovery result to the requesting node.
+
+ +The peer discovery consists of two phases. +In the first phase of the example from [Figure 5](#fig_peer_discovery), node (2:1) sends its discovery request φ to one DSN on each even level, e.g., (0:0), (2:2), and (4:6). +Any node p can estimate the tree’s height with its adjacent links since at least one adjacent of p is located either on the highest level *h − 1* or one level below the highest level, *h − 2*. +However, after sending the discovery request to one DSN per level, these DSNs are responsible for forwarding φ among each DSN on their level. +For example, the DSN (4:6) forwards the request to the other DSNs on level 4, i.e., (4:2) and (4:10). +This request gets forwarded until all DSNs of the CDS have received it. +The second phase includes an evaluation of the peer discovery query φ. +Each DSN evaluates the maintained CA either by using its stored or requesting new information from the nodes assigned to it. +Any result is returned by each DSN to the requester node (2:1). + +A peer discovery query description is given according to boolean algebra consisting of logical *and*-, *or*- and *not*-operators. +Literals are comparisons with the KVPs. +The peer discovery query result is expected to contain information about each peer whose KVPs satisfy the peer discovery query. diff --git a/mkdocs.yml b/mkdocs.yml index 707c27a4..259522fd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,6 +20,7 @@ nav: - "Example: Decentralized Communication": sola/decentralized_communication.md - Logging: sola/logging.md - Glossary: sola/glossary.md + - MINHTON: - Introduction: management_overlay/introduction.md - Using MINHTON: management_overlay/using.md @@ -36,9 +37,9 @@ nav: - TreeMapper: management_overlay/algorithms/treemapper.md - FSM: management_overlay/programmers/fsm.md - Glossary: management_overlay/glossary.md + - NATTER: - - Index: natter/index.md - - Introduction: natter/index.md + - Introduction: natter/introduction.md - Using natter: natter/using.md - Programmers Manual: - Architecture: natter/programmers/architecture.md @@ -47,6 +48,7 @@ nav: - MINHCAST: natter/programmers/minhcast.md - Known Limitations: natter/known-limitations.md - Glossary: natter/glossary.md + - OptiMaFlow: - Introduction: optimaflow/introduction.md - Participants: @@ -61,25 +63,24 @@ nav: - ns-3 Integration: - Introduction: daisi/introduction.md - - Getting started: daisi/getting_started.md - - Logging: daisi/logging.md - - Network: daisi/network.md + - Using DAISI: daisi/using.md + - Architecture: daisi/architecture.md - SOLA: - - Scenariofile: daisi/sola-ns3/scenario_files.md - - Environments: daisi/sola-ns3/environments.md + - Scenariofile: daisi/sola-ns3/scenariofile.md - Logging: daisi/sola-ns3/logging.md - MINHTON: - Scenariofile: daisi/minhton-ns3/scenariofile.md - Logging: daisi/minhton-ns3/logging.md - - ESearch: daisi/minhton-ns3/esearch.md - NATTER: - Scenariofile: daisi/natter-ns3/scenariofile.md - Logging: daisi/natter-ns3/logging.md - OptiMaFlow: - Scenariofile: daisi/optimaflow-ns3/scenariofile.md - Logging: daisi/optimaflow-ns3/logging.md + - Specifics: daisi/optimaflow-ns3/specifics.md - Doxygen: doxygen/index.html + - Glossary: glossary.md theme: @@ -125,6 +126,7 @@ markdown_extensions: - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences + - pymdownx.details - admonition - attr_list - pymdownx.emoji: