From 985776c8bcfe5186726e7fc44c180e3cfd137c8d Mon Sep 17 00:00:00 2001 From: Luis Date: Wed, 4 Dec 2024 18:09:07 +0100 Subject: [PATCH] beautify overview page & image (#1529) --- docs/framework/communication.md | 22 +-- ....drawio.png => communication_dataflow.png} | 0 ...aflow.drawio.png => database_dataflow.png} | 0 .../{dataflow.drawio.png => dataflow.png} | 0 .../{node.drawio-dark.png => node-dark.png} | 0 .../{node.drawio-light.png => node-light.png} | 0 docs/framework/nodes.md | 4 +- docs/framework/overview-dark.png | 3 + docs/framework/overview-light.png | 3 + docs/framework/overview.drawio | 164 ++++++++++-------- docs/framework/overview.drawio.png | 3 - docs/framework/overview.md | 9 +- docs/framework/runtime.md | 2 +- 13 files changed, 122 insertions(+), 88 deletions(-) rename docs/framework/{communication_dataflow.drawio.png => communication_dataflow.png} (100%) rename docs/framework/{database_dataflow.drawio.png => database_dataflow.png} (100%) rename docs/framework/{dataflow.drawio.png => dataflow.png} (100%) rename docs/framework/{node.drawio-dark.png => node-dark.png} (100%) rename docs/framework/{node.drawio-light.png => node-light.png} (100%) create mode 100644 docs/framework/overview-dark.png create mode 100644 docs/framework/overview-light.png delete mode 100644 docs/framework/overview.drawio.png diff --git a/docs/framework/communication.md b/docs/framework/communication.md index db4cb08c4d..89433c6fdd 100644 --- a/docs/framework/communication.md +++ b/docs/framework/communication.md @@ -15,7 +15,7 @@ Since communication deals with I/O and is idle most of the time waiting for I/O, The parts of communication are executed as asynchronous tasks which are then connected together via message passing channels. The following drawing shows all tasks in communication as square boxes (except the cycler threads, but they can be seen as task-like as well). -![communication_dataflow](./communication_dataflow.drawio.png) +![communication_dataflow](./communication_dataflow.png) Solid connections represent dataflow implemented with channels and dashed connections show the startup behavior of the tasks. @@ -24,22 +24,22 @@ Solid connections represent dataflow implemented with channels and dashed connec The entrypoint is the Communication Runtime which is a thread running a Tokio asynchronous runtime. This thread is started from the framework's [Runtime](./runtime.md), similar to the cycler threads. The communication runtime spawns three tasks and connects them with channels. -The *accepter* task listens for new connections on the socket and spawns a new *connection* task for each incoming connection. -The *connection* task is a short-lived task which splits the connection socket into a sending and receiving half and spawns a long-lived task for each half, the *sender* and *receiver* tasks. -This splitting allows the *sender* and *receiver* to act as multiplexing/demultiplexing tasks if viewed in terms of their channel attachment points. -The *receiver* interprets incoming messages from the socket and forwards them to the appropriate processing task (e.g. *database_subscription_manager* or *parameter_modificator*). -The *sender* gathers all messages from the connected tasks and sends them to the connected socket. +The _accepter_ task listens for new connections on the socket and spawns a new _connection_ task for each incoming connection. +The _connection_ task is a short-lived task which splits the connection socket into a sending and receiving half and spawns a long-lived task for each half, the _sender_ and _receiver_ tasks. +This splitting allows the _sender_ and _receiver_ to act as multiplexing/demultiplexing tasks if viewed in terms of their channel attachment points. +The _receiver_ interprets incoming messages from the socket and forwards them to the appropriate processing task (e.g. _database_subscription_manager_ or _parameter_modificator_). +The _sender_ gathers all messages from the connected tasks and sends them to the connected socket. ## Database Subscriptions Communication allows connected clients to subscribe to databases from cyclers and receive selected fields from them. -Subscriptions are managed in the *database_subscription_manager* task. -The *receiver* task forwards (un-)subscription requests from the client to the *database_subscription_manager*. -If a connection is closed, the *receiver* sends an `UnsubscribeEverything` request to the manager task. +Subscriptions are managed in the _database_subscription_manager_ task. +The _receiver_ task forwards (un-)subscription requests from the client to the _database_subscription_manager_. +If a connection is closed, the _receiver_ sends an `UnsubscribeEverything` request to the manager task. Since all interaction between the tasks happens via channels, in some requests it is necessary to include other channel endpoints (e.g. for transferring back results). Subscriptions always contain a cycler, output type, and data path. If cyclers complete their execution of all modules, the written database is completed and freed. -Afterwards, the cycler notifies a [`Notify`](https://docs.rs/tokio/latest/tokio/sync/struct.Notify.html) which is shared between the cycler and the *database_subscription_manager* task in communication. +Afterwards, the cycler notifies a [`Notify`](https://docs.rs/tokio/latest/tokio/sync/struct.Notify.html) which is shared between the cycler and the _database_subscription_manager_ task in communication. This allows the manager task to wait for newly available databases from any cycler. When a new database is ready, the manager task iterates all relevant subscriptions to extract subscribed types and images to construct messages for the subscribed clients. Additional outputs that have been subscribed are sent to the cycler s.t. it can instruct modules to generate the additional outputs. @@ -47,7 +47,7 @@ Additional outputs that have been subscribed are sent to the cycler s.t. it can ## Parameter Subscriptions & Updates Communication allows connected clients to subscribe to configuration parameters, receive changed ones, and update them. -Similar to database subscriptions, parameter subscriptions are processed from the *receiver* task. +Similar to database subscriptions, parameter subscriptions are processed from the _receiver_ task. TODO: diff --git a/docs/framework/communication_dataflow.drawio.png b/docs/framework/communication_dataflow.png similarity index 100% rename from docs/framework/communication_dataflow.drawio.png rename to docs/framework/communication_dataflow.png diff --git a/docs/framework/database_dataflow.drawio.png b/docs/framework/database_dataflow.png similarity index 100% rename from docs/framework/database_dataflow.drawio.png rename to docs/framework/database_dataflow.png diff --git a/docs/framework/dataflow.drawio.png b/docs/framework/dataflow.png similarity index 100% rename from docs/framework/dataflow.drawio.png rename to docs/framework/dataflow.png diff --git a/docs/framework/node.drawio-dark.png b/docs/framework/node-dark.png similarity index 100% rename from docs/framework/node.drawio-dark.png rename to docs/framework/node-dark.png diff --git a/docs/framework/node.drawio-light.png b/docs/framework/node-light.png similarity index 100% rename from docs/framework/node.drawio-light.png rename to docs/framework/node-light.png diff --git a/docs/framework/nodes.md b/docs/framework/nodes.md index f606f83200..685affd0ca 100644 --- a/docs/framework/nodes.md +++ b/docs/framework/nodes.md @@ -6,8 +6,8 @@ The function gets other node's inputs as parameters to the `cycle()` function an In addition, nodes may contain a state which is preserved between cycles.
- ![node](./node.drawio-light.png#only-light) - ![node](./node.drawio-dark.png#only-dark) + ![node](./node-light.png#only-light) + ![node](./node-dark.png#only-dark)
Nodes are normal Rust structs where the struct's fields represent the state and a method called `cycle()` in the `impl` of the node represents the `cycle()` function. diff --git a/docs/framework/overview-dark.png b/docs/framework/overview-dark.png new file mode 100644 index 0000000000..ae286387b7 --- /dev/null +++ b/docs/framework/overview-dark.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:af041d9cb87dd558b7f7d19507bfa495aa5e20fda7918ccfbed11b8ae9618dac +size 71561 diff --git a/docs/framework/overview-light.png b/docs/framework/overview-light.png new file mode 100644 index 0000000000..052bd59436 --- /dev/null +++ b/docs/framework/overview-light.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e6bbfcc13acc28ad5cf25d87e628ab9587b9abc6497e7bdd2b280e260192f2c1 +size 70246 diff --git a/docs/framework/overview.drawio b/docs/framework/overview.drawio index 2af3a39f4d..d31b53bd30 100644 --- a/docs/framework/overview.drawio +++ b/docs/framework/overview.drawio @@ -1,107 +1,135 @@ - + - + - - + + - - + + - - + + - - + + + + - - + + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/framework/overview.drawio.png b/docs/framework/overview.drawio.png deleted file mode 100644 index de7ba82fb8..0000000000 --- a/docs/framework/overview.drawio.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:8e305b60f6b240cf281000827fba2154f286353130c9b59ef8b4c334a39e1ad2 -size 69377 diff --git a/docs/framework/overview.md b/docs/framework/overview.md index 2198701696..0b33076018 100644 --- a/docs/framework/overview.md +++ b/docs/framework/overview.md @@ -1,7 +1,5 @@ # Overview -TODO: Mention unit testing - This section explains the framework of our NAO software. The chapters walk through various features in a top-down approach starting with a general overview. More advanced topics are covered later. @@ -25,9 +23,14 @@ The framework provides the fundamentals needed to execute robotics specific code It has a modular design to allow for convenient development and replacement of individual nodes. The framework consists of four fundamental components: +![overview](./overview-light.png#only-light) +![overview](./overview-dark.png#only-dark) + - [Runtime](./runtime.md): Encapsulates all subcomponents by starting and initializing them - [Hardware Interface](./hardware_interface.md): Abstracts hardware away and is the interaction point for cyclers with the outside world - [Cyclers](./cyclers.md): Cycle through nodes, process data from hardware and produce outputs (see e.g. _control_ or _vision_top_) - [Communication](./communication.md): Exchanges data between framework and other resources e.g. file system and network -![overview](./overview.drawio.png) +!!! Info "Todo" + + Mention unit testing diff --git a/docs/framework/runtime.md b/docs/framework/runtime.md index 4394fb7a80..44e69844e3 100644 --- a/docs/framework/runtime.md +++ b/docs/framework/runtime.md @@ -3,7 +3,7 @@ The runtime is the component in the robotic control software that encapsulates all subcomponents e.g. the hardware interface, cyclers, and communication. Here is a more detailed overview extending the drawing from [Overview](./overview.md): -![dataflow](./dataflow.drawio.png) +![dataflow](./dataflow.png) This section and following ones will cover this drawing in more detail. Many dataflow connections are still left out to improve readability.