Merge pull request #78 from pollen-robotics/python-bindings

Python bindings

Author: pierre-rouanet

.gitignore

@@ -1,2 +1,4 @@
 /target
 /Cargo.lock
+
+__pycache__

Cargo.toml

@@ -11,6 +11,12 @@ readme = "README.md"
 keywords = ["robotics", "dynamixel", "feetech"]
 categories = ["science::robotics"]
 
+[lib]
+crate-type = ["lib", "cdylib"]
+
+[features]
+default = []
+python = ["dep:pyo3", "dep:pyo3-log"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
@@ -22,6 +28,8 @@ clap = { version = "4.0.32", features = ["derive"] }
 proc-macro2 = { version = "=1.0.89", features=["default", "proc-macro"] }
 signal-hook = "0.3.4"
 num_enum = "0.7.3"
+pyo3 = { version = "0.24.1", optional = true, features = ["multiple-pymethods"] }
+pyo3-log = { version = "0.12.3", optional = true }
 
 [dev-dependencies]
 env_logger = "0.10.0"

Changelog.md

@@ -1,3 +1,12 @@
+## version 1.0.0
+
+- Cleanup APIs to offer two interfaces:
+  - high-level interface (Controller) with a simple API for the most common use cases.
+  - low-level interface (DynamixelProtocolHandler) for direct access to the protocol and fine-grained control of the bus ownership.
+- Add Python bindings for the library (controller API).
+- Add support for the feetech servo.
+- Define register conversion at the macro level to simplify the code.
+
 ## Version 0.6.0
 
 - Add dxl XL330 support

README.md

@@ -10,15 +10,15 @@
 
 ## Getting started
 
-Rustypot is a communication library for Dynamixel/Feetech motors. It is used in the [Reachy project](https://www.pollen-robotics.com/reachy/). More types of servo can be added in the future.
+Rustypot is a communication library for Dynamixel/Feetech motors. It is notably used in the [Reachy project](https://www.pollen-robotics.com/reachy/). More types of servo can be added in the future.
 
 ## Feature Overview
 
 * Relies on [serialport](https://docs.rs/serialport/latest/serialport/) for serial communication
 * Support for dynamixel protocol v1 and v2 (can also use both on the same bus)
 * Support for sync read and sync write operations
 * Easy support for new type of motors (register definition through macros). Currently support for dynamixel XL320, XL330, XL430, XM430, MX*, Orbita 2D & 3D.
-* Pure Rust
+* Pure Rust plus python bindings (using [pyo3](https://pyo3.rs/)).
 
 To add new servo, please refer to the [Servo documentation](./servo/README.md).
 
@@ -76,11 +76,36 @@ fn main() {
 
 See https://docs.rs/rustypot for more information on APIs and examples.
 
+See [python/README.md](./python/README.md) for information on how to use the python bindings.
+
+## Python bindings
+
+The python bindings are generated using [pyo3](https://pyo3.rs/). They are available on `pypi`(https://pypi.org/project/rustypot/). You can install them using pip, pix, uv, etc.
+
+To build them locally, you can use [maturin](https://www.maturin.rs).
+
+```bash
+maturin build --release --features python
+```
+
+or, if you want to install them in your local python environment: 
+
+```bash
+maturin develop --release --features python
+```
+
+See [maturin official documentation](https://maturin.rs) for more information on how to use it.
+
+## Contributing
+
+If you want to contribute to Rustypot, please fork the repository and create a pull request. We welcome any contributions, including bug fixes, new features, and documentation improvements.
+We especially appreciate support for new servos. If you want to add support for a new servo, please follow the instructions in the [Servo documentation](./servo/README.md).
+
 ## License
 
 This library is licensed under the [Apache License 2.0](./LICENSE).
 
 ## Support
 
-Rustypot is developed and maintained by [Pollen-Robotics](https://pollen-robotics.com). They developped open-source tools for robotics manipulation.
+Rustypot is developed and maintained by [Pollen-Robotics](https://pollen-robotics.com). They developed open-source hardware and tools for robotics.
 Visit https://pollen-robotics.com to learn more or join the [Discord community](https://discord.com/invite/Kg3mZHTKgs) if you have any questions or want to share your projects. 

examples/dxl_mx_example.rs

@@ -10,21 +10,21 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     let io = DynamixelProtocolHandler::v1();
 
-    let _x: i16 = mx::read_present_position(&io, serial_port.as_mut(), 11)?;
-    let _x: Vec<i16> = mx::sync_read_present_position(&io, serial_port.as_mut(), &[11, 12])?;
+    let _x: f64 = mx::read_present_position(&io, serial_port.as_mut(), 11)?;
+    let _x: Vec<f64> = mx::sync_read_present_position(&io, serial_port.as_mut(), &[11, 12])?;
 
-    mx::sync_write_goal_position(&io, serial_port.as_mut(), &[11, 12], &[2048, 2048])?;
+    mx::sync_write_raw_goal_position(&io, serial_port.as_mut(), &[11, 12], &[2048, 2048])?;
 
     loop {
-        mx::sync_write_goal_position(&io, serial_port.as_mut(), &[11], &[2048])?;
+        mx::sync_write_raw_goal_position(&io, serial_port.as_mut(), &[11], &[2048])?;
 
         let temp = mx::read_present_temperature(&io, serial_port.as_mut(), 11)?;
         println!("{:?}", temp);
 
         thread::sleep(Duration::from_millis(500));
 
-        mx::sync_write_goal_position(&io, serial_port.as_mut(), &[11], &[1000])?;
-        let pos = mx::read_present_position(&io, serial_port.as_mut(), 11)?;
+        mx::sync_write_raw_goal_position(&io, serial_port.as_mut(), &[11], &[1000])?;
+        let pos = mx::read_raw_present_position(&io, serial_port.as_mut(), 11)?;
         println!("{:?}", pos);
 
         thread::sleep(Duration::from_millis(500));

examples/dxl_sinus.rs

@@ -1,8 +1,8 @@
-use std::f32::consts::PI;
+use std::f64::consts::PI;
 use std::time::SystemTime;
 use std::{error::Error, thread, time::Duration};
 
-use rustypot::servo::dynamixel::mx::{self, conv};
+use rustypot::servo::dynamixel::mx;
 use rustypot::DynamixelProtocolHandler;
 
 use clap::Parser;
@@ -28,20 +28,20 @@ struct Args {
 
     ///sinus amplitude (f64)
     #[arg(short, long, default_value_t = 10.0)]
-    amplitude: f32,
+    amplitude: f64,
 
     ///sinus frequency (f64)
     #[arg(short, long, default_value_t = 1.0)]
-    frequency: f32,
+    frequency: f64,
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
     let args = Args::parse();
     let serialportname: String = args.serialport;
     let baudrate: u32 = args.baudrate;
     let id: u8 = args.id;
-    let amplitude: f32 = args.amplitude;
-    let frequency: f32 = args.frequency;
+    let amplitude: f64 = args.amplitude;
+    let frequency: f64 = args.frequency;
 
     //print all the argument values
     println!("serialport: {}", serialportname);
@@ -60,22 +60,17 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     let io = DynamixelProtocolHandler::v1();
 
-    let x: i16 = mx::read_present_position(&io, serial_port.as_mut(), id)?;
+    let x = mx::read_present_position(&io, serial_port.as_mut(), id)?;
     println!("present pos: {}", x);
 
     mx::write_torque_enable(&io, serial_port.as_mut(), id, 1)?;
 
     let now = SystemTime::now();
     while !term.load(Ordering::Relaxed) {
-        let t = now.elapsed().unwrap().as_secs_f32();
+        let t = now.elapsed().unwrap().as_secs_f64();
         let target = amplitude * (2.0 * PI * frequency * t).sin().to_radians();
         println!("target: {}", target);
-        mx::write_goal_position(
-            &io,
-            serial_port.as_mut(),
-            id,
-            conv::radians_to_dxl_pos(target.into()),
-        )?;
+        mx::write_goal_position(&io, serial_port.as_mut(), id, target)?;
 
         thread::sleep(Duration::from_millis(10));
     }

examples/feetech_controller.rs

@@ -1,6 +1,6 @@
 use std::{error::Error, thread, time::Duration};
 
-use rustypot::servo::feetech::sts3215::STS3215Controller;
+use rustypot::servo::feetech::sts3215::Sts3215Controller;
 fn main() -> Result<(), Box<dyn Error>> {
     let serialportname: String = "/dev/tty.usbmodem58FA0822621".to_string();
     let baudrate: u32 = 1_000_000;
@@ -11,7 +11,7 @@ fn main() -> Result<(), Box<dyn Error>> {
         .open()?;
     println!("serial port opened");
 
-    let mut c = STS3215Controller::new()
+    let mut c = Sts3215Controller::new()
         .with_protocol_v1()
         .with_serial_port(serial_port);
 

examples/feetech_lowlevel_api.rs

@@ -20,13 +20,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     while start_overall.elapsed() < duration {
         let start_time = std::time::Instant::now();
 
-        let _x: i16 = sts3215::read_present_position(&io, serial_port.as_mut(), ids[0])?;
+        let _x: i16 = sts3215::read_raw_present_position(&io, serial_port.as_mut(), ids[0])?;
         let x = sts3215::sync_read_present_position(&io, serial_port.as_mut(), &ids)?;
-        let x: Vec<f64> = x
-            .iter()
-            .map(|p| sts3215::conv::dxl_pos_to_radians(*p))
-            .map(f64::to_degrees)
-            .collect();
         println!("present pos: {:?}", x);
 
         let elapsed_time = start_time.elapsed();

pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["maturin>=1.8,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "rustypot"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+]
+dynamic = ["version"]
+[project.optional-dependencies]
+tests = [
+    "pytest",
+]
+[tool.maturin]
+python-source = "python"
+features = ["pyo3/extension-module"]

python/README.md

@@ -0,0 +1,44 @@
+# Rustypot python bindings
+
+## Installation
+
+Rustypot bindings are available on PyPI. You can install them using pip:
+
+```bash
+pip install rustypot
+```
+
+### Building the bindings
+
+If you want to build the bindings from source, you can clone the repository and run the following command:
+
+```bash
+maturin develop --release --features python
+```
+
+## Usage
+
+The Python bindings exposes the same API as the Controller API in the rust crate. 
+
+You first need to create a Controller object. For instance, to communicate with a serial port to Feetech STS3215 motors, you can do the following:
+
+```python
+from rustypot.servo import Sts3215SyncController
+
+c = Sts3215SyncController(serial_port='/dev/ttyUSB0', baudrate=100000, timeout=0.1)
+```
+
+Then, you can directly read/write any register of the motor. For instance, to read the present position of the motors with id 1 and 2, you can do:
+
+```python
+
+pos = c.read_present_position([1, 2])
+print(pos)
+```
+
+You can also write to the motors. For instance, to set the goal position of the motors with id 1 and 2 to 0.0 and 90° respectively, you can do:
+
+```python
+import numpy as np
+c.write_goal_position([1, 2], [0.0, np.deg2rad(90.0)])
+```