docs update

Author: askuric

docs/_config.yaml

@@ -31,6 +31,9 @@ exclude:
 
 
 callouts:
+  note:
+    title: Note
+    color: green
   info:
     title: Info
     color: blue

docs/ethercat/index.md

@@ -1,7 +1,49 @@
 --- 
-title: EtherCAT communication
+title: EtherCAT protocols
 layout: default
 has_children: true
+nav_order: 4
 ---
 
 
+# EtherCAT communication
+
+This crate enable communicating over EtherCAT network in few different ways. 
+
+##  Real-time communication
+
+The real-time variables are exchanged over the network at a high frequency (typically 1kHz) using the PDO communication. There are two types of PDO communication supported by the crate
+
+- Cyclic PDOs - buffered
+- Mailbox PDOs - (optional)
+
+{: .info }
+> - **PDO** - Process Data Object
+
+Cyclic PDOs are the most common way of exchanging the data over the network. The data is exchanged at a fixed frequency and the data is buffered, ensuring the continuitiy. If the data is not read in time, the data is overwritten with the new data. 
+
+Mailbox PDOs are used to ensure that the data is read and written properly. Mailbox enables a handshake between the master and the slave, ensuring that the data is read and written properly. If the data is not written in time, the master will not read the old data but will read zeros. 
+
+{: .note}
+In order to ensure the continuity, mailbox PDOs are buffered in software in the `ethercat_controller` crate, with a timeout of 1s. If the data is not written in time, the master will consider the slave not operational and will fail. This procedure is enabled by default and can be disabled using the feature `verify_mailbox_pdos` in its `Cargo.toml` file.
+
+##  Non real-time communication
+
+The non real-time variables are exchanged over the network using the Mailbox protocol, based on CoE. There are two types of communication supported by the crate.
+
+- SDO communication (Mailbox protocol with CoE)
+- FoE communication for file upload - (Mailbox protocol with CoE)
+
+{: .info }
+> - **SDO** - Service Data Object
+> - **CoE** - Can Over Ethercat
+> - **FoE** - Fiile over Ethercat
+
+
+The SDO communication is used to read and write the data to the slave devices with a handshake. It is mostly used for configuring the slave devices and before starting the real-time communication. In poulpe firmware, it is supported by the `firmware_Poulpe` version 1.5.x and the boards only respond to the SDO communication if they are in the `PREOP` (pre-operational) state.
+
+The FoE communication is used to upload the files to the slave devices, in particular to upload the firmware to the slave devices. In poulpe firmware, it is supported by the `firmware_Poulpe` version 1.5.x and only in `PREOP` (pre-operational) state.
+
+## Communication configuration
+
+The crate determins which kind of communication is available from the ESI XML file downloaded from the slave, and sets up the necessary infrastructure for the communication. See the [poulpe configuration docs](../installation/configure_poulpe) for more info on how to configure the poulpe boards for the EtherCAT network.

docs/examples/grpc.md

@@ -66,6 +66,8 @@ $ RUST_LOG=info cargo run --release -- config/my_network_config.yaml # or config
 
 </details>
 
+## Running the GRPC clients
+
 ### Rust GRPC client examples
 
 - The simplest example is the `client_listener` example. This example connects to the server and listens for the states of the poulpe boards connected to the network.
@@ -96,10 +98,9 @@ RUST_LOG=info cargo run --release --example client_sinus # add the slave id (ex.
 
 ### Python GRPC client
 
-- The `poulpe_ethercat_grpc` crate has a python client that can be used to connect to the GRPC server and read the states of the poulpe boards connected to the network. The python client is a wrapper around the GRPC client that is generated in the `python_client` crate. See the [python_client/README.md](python_client/README.md) for more info.
+- The `poulpe_ethercat_grpc` crate has a python client that can be used to connect to the GRPC server and read the states of the poulpe boards connected to the network. The python client is a wrapper around the GRPC client that is generated in the `python_client` crate. 
 - The python client uses the `maturin` package to build the python wheel.
-- See the [python_client/README.md](python_client/README.md) for instructions on how to build the python client.
-
+- See the [python_client docs](../../installation/python_client) for instructions on how to build the python client.
 
 Once you have your python bindings you can run the examples from the `python_client/scripts` directory or notebooks from the `python_client/notebooks` directory.
 

docs/examples/index.md

@@ -5,11 +5,12 @@ back_to_top: true
 back_to_top_text: "Back to top"
 has_children: true
 has_toc: false
+nav_order: 3
 ---
 
 # Running the code
 
 The code in the `poulpe_ethercat_controller` crate can be run in multiple ways. The main ways are:
 
-- [Standalone examples](examples/standalone.md): The examples are standalone and do not require the GRPC server to be running.
-- [GRPC server and client](examples/grpc.md): The `poulp_ethercat_grpc` crate is a GRPC server that can be used to communicate with the poulpe boards connected to the network. The server can be accessed by multiple clients at the same time. The server is written in Rust and the clients can be written in Rust or Python.
+- [Standalone examples](standalone): The examples are standalone and do not require the GRPC server to be running.
+- [GRPC server and client](grpc): The `poulp_ethercat_grpc` crate is a GRPC server that can be used to communicate with the poulpe boards connected to the network. The server can be accessed by multiple clients at the same time. The server is written in Rust and the clients can be written in Rust or Python.

docs/index.md

@@ -3,40 +3,19 @@ title: Home
 layout: default
 nav_order: 1
 ---
-# Poulpe ehtercat controller
+# Poulpe EhterCAT stack
 
-This is the code that manages the communication between the orbita2d and orbita3d actuators and the ethercat master. The code is written in rust. It is intended to communicate with poulpe boards running the [firmware_Poulpe](https://github.com/pollen-robotics/firmware_Poulpe).
+This is the full EtherCAT stack that manages the communication with the poulpe boards through EtherCAT network. The code is written in rust. 
+It is intended to communicate with poulpe boards running the [firmware_Poulpe](https://github.com/pollen-robotics/firmware_Poulpe).
 
+## Crate structure
 
+The code is based on the [EtherCAT IgH stack](https://gitlab.com/etherlab.org/ethercat). The EtherCAT master is implemented in the `ethercat_controller` crate. The `poulpe_ethercat_controller` crate is the main crate that manages the communication with the poulpe boards. The `poulpe_ethercat_grpc` crate is the crate that manages the communication with the GRPC server. Read more about the crate structure in [Crates docs](software)
 
 ## Safety features
 
-Each layer of the code has its own safety features. The `ethercat_controller` deals with the EtherCAT communication safety features (see more in the [ethercat_controller/README.md](ethercat_controller/README.md#main-features)). The `poulpe_ethercat_controller` crate has its own safety features that are specific to the poulpe boards (see more in the [poulpe_ethercat_controller/README.md](poulpe_ethercat_controller/README.md#safety-features)). The `poulpe_ethercat_grpc` crate has its own safety features that are specific to the GRPC communication (see more in the [poulpe_ethercat_grpc/README.md](poulpe_ethercat_grpc/README.md#safety-features)).
-
-`ethercat_controller` crate has the following safety features:
-- At the statup
-    - Checks if the master and all the slaves are oprational
-    - Checks if all the slaves are configured properly
-- During the operation
-    - Checks if the master and all the slaves are oprational
-    - Checks if all the slaves are connected to the master
-    - Checks if new slaves are connected to the master
-
-`poulpe_ethercat_controller` crate has the following safety features:
-- At the statup
-    - Checks if ethercat network is operational and the topology is correct
-    - Checks if all the boards are in the correct state
-- During the operation
-    - Checks if the boards are in the correct state and only allows turning them on if they are in the correct state
-
-`poulpe_ethercat_grpc` crate has the following safety features:
-- Real-time communication
-    - All server and client messages are time stamped to ensure that the communication is real-time
-    - The server discards all the client messages that are too old
-    - The client that receives the messages that are too old will not process them and consider that the server is down
-- Safety features
-    - The server checks if the boards are in the fault state and if any of them is it sends the emergency stop signal to all the boards
-    - The server continues the operation, reading the baoards states but not sending any commands to the boards
+The code implements many safety features in order to ensure the safe operation of the boards. Read more about the safety features in the [Safety features](safety_features) docs.
+
 
 ## Install and build the `poulpe_ethercat_controller` code
 
@@ -47,12 +26,7 @@ Now that you have the ethercat master running and the poulpe board configured, y
 git clone [email protected]:pollen-robotics/poulpe_ethercat_controller.git
 ```
 
-- Build the code
-```shell
-cargo build --release
-```
-If the build passes that means that the code is working properly.
-
+For more information on how to install and build the code read the [Installation and configuration](installation) docs.
 
 ## Support
 

docs/installation/configure_poulpe.md

@@ -139,7 +139,7 @@ SM2: PhysAddr 0x1300, DefaultSize    0, ControlRegister 0x20, Enable 1
 
 </details>
 
-<details markdown="1"><summary>Example for version v1.0.x</summary>
+<details markdown="1"><summary>Example for version v1.5.x</summary>
 
 ```shell
 $ ethercat pdos

docs/installation/index.md

@@ -1,26 +1,41 @@
 ---
 title: Installation and configuration
 layout: default
-position: 2
+nav_order: 2
 has_children: true
 ---
 
 # Installation and configuration
 
-The `poulpe_ethercat_controller` crate is intended to be used with the poulpe boards that are connected to the network. The crate can be used to communicate with the poulpe boards, read and write the SDO and PDO objects, and update the firmware over the EtherCAT network.
+The crate is written in Rust and is communicating difectly wit the **EtherCAT IgH** Master. It uses the rust wrapper crate `ethercat-rs` and builds on top of it to provide a more user friendly interface to the user. 
 
 ## Downoload the code
 
-Now that you have the ethercat master running and the poulpe board configured, you can run the code.
+You can obtain the code by cloning the repository.
 
 - Clone the repo
 ```shell
 git clone [email protected]:pollen-robotics/poulpe_ethercat_controller.git
 ```
 
+Check out the branches that you need, depending on the poulpe firmware version that you are using. 
+
+`firmware_poulpe` version | `poulpe_etehract_controller` version
+--- | ---
+v0.9.x | 0.9.x
+v1.0.x | 1.0.x or higher
+v1.5.x | 1.5.x 
+
+For example if you are using the v1.5.x firmware version you should check out the 1.5.x branch:
+```shell
+git checkout 1.5.x
+```
+
+
+
 ## Building the code
 
-The crate is written in Rust and is communicating difectly wit the EtherCAT IgH Master. It uses the rust wrapper crate `ethercat-rs` and builds on top of it to provide a more user friendly interface to the user. The endpoint interface is a GRPC server and client interface that can be accessed by multiple clients at the same time, either in rust or python.
+The crate is written in Rust and uses the `cargo` build system. All the dependencies are managed by the `cargo` build system, except for the EtherCAT IgH Master.
 
 So the main dependencies are:
 - Rust - [installation guide](https://www.rust-lang.org/tools/install)
@@ -37,3 +52,7 @@ Once when you have everything installed you and before you can run the code you
 
 Here is the [guide to configure the poulpe boards](configure_poulpe) on the network. 
 
+
+## Running the code
+
+Once you have the ethercat master running and you connected your poulpe board to the network, you can run the code. See the [Running the code](../examples) docs for more info.

docs/installation/installation_ethercat.md

@@ -30,13 +30,19 @@ sudo apt-get install -y protobuf-compiler libprotobuf-dev
 - Install the [ethercat master](https://etherlab.org/en/ethercat/)
     - `git clone https://gitlab.com/etherlab.org/ethercat.git`
     - `cd ethercat`
-    - use the `stable-1.6` branch `git checkout stable-1.6`
+    - use the `stable-1.6` branch `git checkout stable-1.6` 
+        - if needed `stable-1.5` will work too
     - `./bootstrap`
     - `./configure --enable-generic --disable-8139too`
     - `make all modules`
     - `sudo make modules_install install`
     - `sudo depmod`
-    - add the path to the `ethercat` binary to the `ETHERCAT_PATH` variable (ex. `export ETHERCAT_PATH=$HOME/ethercat`)
+
+{: .info}
+>  Rust stack will need to know where the `ethercat` binary is located.
+>  So add the path to the `ethercat` binary to the `ETHERCAT_PATH` variable  
+>  - either by: `export ETHERCAT_PATH=$HOME/ethercat` 
+>  - or add it to the `.bashrc` file
 
 ## Configure EtherCAT master
 In order configure the `ethercat` we need to give the master the MAC address of the PC/ehternet port.
@@ -57,6 +63,7 @@ In order configure the `ethercat` we need to give the master the MAC address of
     - reload the rules:
     `sudo udevadm control --reload-rules && sudo udevadm trigger`
 
+{: .info}
 > There are some helpful notion pages with a bit more info on the ethercat setup:
 > -  [Setup EtherCAT](https://www.notion.so/pollen-robotics/Setup-EtherCAT-1ecce786847e495bb1b4b399740727af)
 > - [Integration to Bedrock](https://www.notion.so/pollen-robotics/EtherCAT-9864e7348e0341b592b2cf95acaf1bc2?pvs=4#f3a010c9cd474eea92a9f0dfe609a203) (a bit more recent)
@@ -66,8 +73,15 @@ In order configure the `ethercat` we need to give the master the MAC address of
 
 ## Start the EtherCAT master
 
-- `sudo ethercatctl start`
-- verify that `/dev/EtherCAT0` exists (`ls /dev/EtherCAT0`).
+Start the `ethercat` master:
+```
+sudo ethercatctl start
+```
+
+Verify that `/dev/EtherCAT0` exists 
+```shell
+ls /dev/EtherCAT0
+```
 
 The output should be something like:
 ```shell

docs/installation/python_client.md

@@ -17,13 +17,17 @@ To use this client run the following command:
 maturin develop --release
 ```
 
-{: .note }
-> IMPORTANT: We suggest using a conda environment to install the client. 
+{: .info }
+> You will hav to use a virtual environment to install the client with the `maturin` command. So make sure to activate the virtual environment before running the command. We suggest using `conda` to create the virtual environment, but you can use `venv` or `virtualenv` as well. 
+> 
+```bash
+conda create -n poulpe_ethercat python=3.10
+conda activate poulpe_ethercat
+```
 
+Once you have the virtual environment activated you can run the following command:
 ```bash
-conda create -n poulpe_ethercat python=3.8
 pip install maturin
-conda activate poulpe_ethercat
 maturin develop --release
 ```
 

docs/safety_features.md

@@ -0,0 +1,50 @@
+---
+title: Safety features
+layout: default
+---
+
+
+# Safety features
+
+Each layer of the code has its own safety features. The `ethercat_controller` deals with the EtherCAT communication safety features (see more in the [ethercat_controller docs](../software/ethercat_controller#safety-features)). The `poulpe_ethercat_controller` crate has its own safety features that are specific to the poulpe boards (see more in the [poulpe_ethercat_controller docs](../software/poulpe_ethercat_controller#safety-features)). The `poulpe_ethercat_grpc` crate has its own safety features that are specific to the GRPC communication (see more in the [poulpe_ethercat_grpc docs](../software/poulpe_ethercat_grpc#safety-features)).
+
+`ethercat_controller` crate has the following safety features:
+- At the statup
+    - Checks if the master and all the slaves are oprational
+    - Checks if all the slaves are configured properly
+- During the operation
+    - Checks if the master and all the slaves are oprational
+    - Checks if all the slaves are connected to the master
+    - Checks if new slaves are connected to the master
+
+`poulpe_ethercat_controller` crate has the following safety features:
+- At the statup
+    - Checks if ethercat network is operational and the topology is correct
+    - Checks if all the boards are in the correct state
+- During the operation
+    - Checks if the boards are in the correct state and only allows turning them on if they are in the correct state
+
+`poulpe_ethercat_grpc` crate has the following safety features:
+- Real-time communication
+    - All server and client messages are time stamped to ensure that the communication is real-time
+    - The server discards all the client messages that are too old
+    - The client that receives the messages that are too old will not process them and consider that the server is down
+- Safety features
+    - The server checks if the boards are in the fault state and if any of them is it sends the emergency stop signal to all the boards
+    - The server continues the operation, reading the baoards states but not sending any commands to the boards
+
+
+If any of the above safety features fails, the master will send an emergency stop signal (CiA402 QuickStop) to all the boards and stop the operation. The boards will go into the shut-down state. 
+
+
+## Emergency stop
+
+Additionally, anytime the ethercat master stops the operation, either in [standalone](../examples/standalone) or in the [GRPC server](../examples/grpc) mode, the poulpe boards will stop their operation and go into the shut-down state. 
+
+However, if the GRPC server is up and running, there is another way to send the emergency stop command to the boards without killing the server, using the emergency stop script. This usage is useful in order to enable providing the applications built on top of the GRPC server with the state data of the boards even after the emergency stop signal is sent. The code contains the precompiled script that sends the emergency stop (CiA402 QuickStop command) signal to all the boards connected to the ethercat network.
+
+To run the script, navigate to the main directory and run the following command:
+
+```shell
+sh emergency_stop_all.sh
+```