python extension

Author: askuric

docs/installation/index.md

@@ -9,48 +9,90 @@ has_children: true
 
 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
+### Pre-requisites
 
-You can obtain the code by cloning the repository.
+Before you can build and run the code you need to have the following installed on your system:
 
-- Clone the repo
-```shell
-git clone [email protected]:pollen-robotics/poulpe_ethercat_controller.git
-```
+- Rust - [installation guide](https://www.rust-lang.org/tools/install)
+- EtherCAT IgH Master (for the EtherCAT communication) - [installation guide](installation_ethercat)
+
+###  Code version
 
-Check out the branches that you need, depending on the poulpe firmware version that you are using. 
+This crate is designed to work with the poulpe firmware version, so make sure to check the version of the firmware that you are using and check out the corresponding branch of the code.
 
 `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:
+
+### Poulpe board EtherCAT configuration
+
+Once when you have everything installed you and before you can run the code you need to configure the poulpe boards on the network if they are not already configured. The configuration is done with the EtherCAT network configuration files. The configuration files are located in the `config` directory. 
+
+Here is the [guide to configure the poulpe boards](configure_poulpe) on the network. 
+
+## Importing the crate
+
+The crate is designed to be used as a library in your project. You can include it in your `Cargo.toml` file as a dependency:
+
+```toml
+....
+[dependencies]
+...
+poulpe_ethercat_controller = { git = "https://github.com/pollen-robotics/poulpe_ethercat_controller.git", branch = "1.5.x" }
+```
+
+You can also include only sub-crates that you need. For example, if you only need the GRPC client
+
+```toml
+....
+[dependencies]
+...
+poulpe_ethercat_grpc = { git = "https://github.com/pollen-robotics/poulpe_ethercat_controller.git", branch = "1.5.x" }
+```
+
+## Python-only installation
+
+If you are using the python-only version of the code you can install the code directly from the repository. 
+Make sure to use the tag corresponding to the version of the firmware that you are using. For example, if we use the 1.5.4 tag: (see the [tags](https://github.com/pollen-robotics/poulpe_ethercat_controller/tags))
+
 ```shell
-git checkout 1.5.x
+pip install git+https://github.com/pollen-robotics/poulpe_ethercat_controller.git@1.5.4#subdirectory=python_client
 ```
 
+NOTE:
+This install procedure is available from the version 1.5.4 of the `poulpe_ethercat_controller`.
 
+Once this is installed you can use the python client to communicate with the poulpe board. 
 
-## Building the code
+```python
+import python_client
+```
 
-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.
+## Installing from source
 
-So the main dependencies are:
-- Rust - [installation guide](https://www.rust-lang.org/tools/install)
-- EtherCAT IgH Master (for the EtherCAT communication) - [installation guide](installation_ethercat)
+You can obtain the code by cloning the repository.
 
-Once you have all the dependencies installed you can build the code with:
+- 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.  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
+```
+
+- Once you have all the dependencies installed you can build the code with:
 ```shell
 cargo build --release
 ```
 
-## Configuration
+See how to [install the python bindings](python_client) from the source code.
 
-Once when you have everything installed you and before you can run the code you need to configure the poulpe boards on the network if they are not already configured. The configuration is done with the EtherCAT network configuration files. The configuration files are located in the `config` directory. 
 
-Here is the [guide to configure the poulpe boards](configure_poulpe) on the network. 
 
 
 ## Running the code

docs/installation/python_client.md

@@ -8,10 +8,22 @@ parent: Installation and configuration
 
 The `poulpe_ethercat_controller` crate provides a GRPC server and client interface that can be accessed by multiple clients at the same time, either in Rust or Python. The GRPC server is implemented in Rust and the client bindings are generated for both Rust and Python. The python bindings are implemented in `python_client` crate.
 
-## Installation
+The simplest way of obtaining the python client is to pip install the code directly from the git the repository, using the tag corresponding to the version of the firmware that you are using. For example, if we use the 1.5.4 tag: (see the [tags](https://github.com/pollen-robotics/poulpe_ethercat_controller/tags))
 
+```shell
+pip install git+https://github.com/pollen-robotics/[email protected]#subdirectory=python_client
+```
+
+NOTE:
+This install procedure is available from the version 1.5.4 of the `poulpe_ethercat_controller`.
+
+
+## Installation from source
+
+Provided that you already have the `poulpe_ethercat_controller` crate cloned and built, you can install the python client bindings from the source code. You can find more information on how to build the code in the <a href="../">installation and configuration</a> section.
 
-To use this client run the following command:
+
+First place yourself in the `python_client` directory, and then you can build the python client bindings you can use the `maturin` tool.
 
 ```bash
 maturin develop --release
@@ -23,6 +35,7 @@ INFO:
 ```bash
 conda create -n poulpe_ethercat python=3.10
 conda activate poulpe_ethercat
+pip install maturin
 ```
 
 Once you have the virtual environment activated you can run the following command:
@@ -32,30 +45,48 @@ maturin develop --release
 ```
 
 This will install the python client in the current environment.
-And then you can open the notebooks in the `notebooks` folder and scripts in the `scripts` folder to see how to use the client.
+And then you can open the notebooks in the `notebooks` folder and scripts in the `scripts` folder to see how to use the client. See the [notebooks](https://github.com/pollen-robotics/poulpe_ethercat_controller/tree/develop/python_client/notebooks) for more information.
 
 The client is a wrapper around the GRPC client generated from the `poulpe_ethercat_grpc/src/client.rs` folder.
 
-## Run the GRPC server
-Make sure to run the GRPC server before running the client.
-This can be done using the following command:
+## Simple example
 
-```bash
-cargo run --release ../config/file/here.yaml
+Create a simple config file `file_config.yaml` with the following content:
+```yaml
+ethercat:
+  master_id: 0
+  cycle_time_us: 1000 # us - cycle time of the ethercat 1/frequency
+  command_drop_time_us: 5000 # us (5ms default) 
+  watchdog_timeout_ms: 500 # ms (500ms default)
+  mailbox_wait_time_ms: 10000 #ms  (1s default)
 ```
 
-## Simple example
+And then you can run the following python script:
 
 ```python
-from python_client import PyPoulpeRemoteClient
+from python_client import PyPoulpeRemoteClient, launch_server, get_all_slaves_in_network
 import time
 
+# launch the server first
+address = launch_server("file_config.yaml")
+
+# wait for the server to start
+time.sleep(1.0)
+
+# print all slaves in the network
+devices = get_all_slaves_in_network(address)
+print("Devices connected in the network: ")
+for i,name in zip(devices[0],devices[1]):
+    print("Slave {}: {}".format(i,name))
+
+
+# connect to the server
 slave_id = 0
 no_axis = 3
 
 print('Connecting on slave: {}'.format(slave_id))
 # Create an instance of the client
-client = PyPoulpeRemoteClient("http://127.0.0.1:50098", [slave_id], 0.001)
+client = PyPoulpeRemoteClient(address, [slave_id], 0.001)
 
 time.sleep(1.0)
 
@@ -69,10 +100,11 @@ print("Slave {} current position: {}".format(slave_id, client.get_position_actua
 ```
 which might output something like:
 ```shell
-Connecting on slave: 0
+POULPE controller ready!
 Devices connected in the network: 
 Slave 1: RightWristOrbita3d
 Slave 0: RightShoulderOrbita2d
+Connecting on slave: 0
 Slave 0 compliancy is: True
 Slave 0 current position: [-0.0011222249595448375, 3.743586057680659e-05, 6.8065196501265746e-06]
 ```

ethercat_controller/examples/poulpe_sinus.rs

@@ -1,4 +1,3 @@
-use core::net;
 use ethercat_controller::EtherCatController;
 use log;
 use std::env;

ethercat_controller/examples/scan_network.rs

@@ -5,8 +5,6 @@ use std::time::Duration;
 fn main() {
     env_logger::init();
 
-    let id: u16 = 0;
-
     log::info!("Creating the EtherCAT master");
     let ec = EtherCatController::open(0, Duration::from_millis(2), 1000, 500, 1000).unwrap();
 

mkdocs.yaml

@@ -16,6 +16,7 @@ theme:
     - python
     - terminal
     - console
+    - toml
   hljs_style: github
   custom_dir: docs/custom_theme/
   logo: img/favicon.ico

python_client/notebooks/orbita2d_test_assembly.ipynb

@@ -21,21 +21,33 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 1,
    "id": "a4c135e1-94e8-4bd6-a40a-81f1827cd8ba",
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "POULPE controller ready!\n"
+      "POULPE controller ready!\n",
+      "Devices connected in the network: \n",
+      "Slave 0: RightShoulderOrbita2d\n"
      ]
     }
    ],
    "source": [
     "import python_client\n",
-    "python_client.launch_server(\"../../config/ethercat.yaml\")"
+    "import time\n",
+    "\n",
+    "# launch the server\n",
+    "address = python_client.launch_server(\"../../config/ethercat.yaml\")\n",
+    "time.sleep(1)\n",
+    "\n",
+    "# print all slaves in the network\n",
+    "devices = python_client.get_all_slaves_in_network(address)\n",
+    "print(\"Devices connected in the network: \")\n",
+    "for i,name in zip(devices[0],devices[1]):\n",
+    "    print(\"Slave {}: {}\".format(i,name))"
    ]
   },
   {
@@ -67,7 +79,7 @@
     "n_axis = 2 # 2 or 3\n",
     "\n",
     "# Create an instance of the client\n",
-    "client = PyPoulpeRemoteClient(\"http://127.0.0.1:50098\", [slave_id], 0.001)\n",
+    "client = PyPoulpeRemoteClient(address, [slave_id], 0.001)\n",
     "\n",
     "print(client.get_connected_devices())\n",
     "\n",

python_client/notebooks/orbita3d_test_assembly.ipynb

@@ -35,7 +35,17 @@
    ],
    "source": [
     "import python_client\n",
-    "python_client.launch_server(\"../../config/ethercat.yaml\")"
+    "import time\n",
+    "\n",
+    "# launch the server\n",
+    "address = python_client.launch_server(\"../../config/ethercat.yaml\")\n",
+    "time.sleep(1)\n",
+    "\n",
+    "# print all slaves in the network\n",
+    "devices = python_client.get_all_slaves_in_network(address)\n",
+    "print(\"Devices connected in the network: \")\n",
+    "for i,name in zip(devices[0],devices[1]):\n",
+    "    print(\"Slave {}: {}\".format(i,name))"
    ]
   },
   {
@@ -67,7 +77,7 @@
     "n_axis =  3# 2 or 3\n",
     "\n",
     "# Create an instance of the client\n",
-    "client = PyPoulpeRemoteClient(\"http://127.0.0.1:50098\", [slave_id], 0.001)\n",
+    "client = PyPoulpeRemoteClient(address, [slave_id], 0.001)\n",
     "\n",
     "print(client.get_connected_devices())\n",
     "\n",

python_client/notebooks/poulpe_test.ipynb

@@ -18,21 +18,33 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 1,
    "id": "45a55cd9-9ed1-43c7-9f18-63b4499ece82",
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "POULPE controller ready!\n"
+      "POULPE controller ready!\n",
+      "Devices connected in the network: \n",
+      "Slave 0: RightShoulderOrbita2d\n"
      ]
     }
    ],
    "source": [
     "import python_client\n",
-    "python_client.launch_server(\"../../config/ethercat.yaml\")"
+    "import time\n",
+    "\n",
+    "# launch the server\n",
+    "address = python_client.launch_server(\"../../config/ethercat.yaml\")\n",
+    "time.sleep(1)\n",
+    "\n",
+    "# print all slaves in the network\n",
+    "devices = python_client.get_all_slaves_in_network(address)\n",
+    "print(\"Devices connected in the network: \")\n",
+    "for i,name in zip(devices[0],devices[1]):\n",
+    "    print(\"Slave {}: {}\".format(i,name))"
    ]
   },
   {
@@ -67,7 +79,7 @@
     "\n",
     "print(\"Connecting to slave {}\".format(slave_id))\n",
     "# Create an instance of the client\n",
-    "client = PyPoulpeRemoteClient(\"http://127.0.0.1:50098\", [slave_id], 0.001)\n",
+    "client = PyPoulpeRemoteClient(address, [slave_id], 0.001)\n",
     "# print the connected clients\n",
     "devs = client.get_connected_devices()\n",
     "print(\"Connected to slaves | ids: {} , names: {}\".format(devs[0],devs[1]) )\n",

python_client/scripts/launch_server.py

@@ -1,9 +1,18 @@
 import python_client
+import time 
 
 print("Launching the EhterCAT server")
 
-# launch the server and allow ctrl-c to stop the server
-python_client.launch_server("../../config/ethercat.yaml")
+# launch the server
+address = python_client.launch_server("../../config/ethercat.yaml")
+time.sleep(1)
 
+# print all slaves in the network
+devices = python_client.get_all_slaves_in_network(address)
+print("Devices connected in the network: ")
+for i,name in zip(devices[0],devices[1]):
+    print("Slave {}: {}".format(i,name))
+    
+    
 while True:
     pass