Work on doc.

Author: pierre-rouanet

README.md

@@ -1,4 +1,4 @@
-# Rustypot: a Rust package to communicate with Dynamixel motors
+# Rustypot: a Rust package to communicate with Dynamixel/Feetech motors
 
 [![Build Status]][actions] [![Latest Version]][crates.io]
 
@@ -10,7 +10,7 @@
 
 ## Getting started
 
-Rustypot is yet another communication library for robotis Dynamixel motors. It is currently used in the [Reachy project](https://www.pollen-robotics.com/reachy/).
+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.
 
 ## Feature Overview
 
@@ -20,9 +20,19 @@ Rustypot is yet another communication library for robotis Dynamixel motors. It i
 * 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
 
+To add new servo, please refer to the [Servo documentation](./servo/README.md).
+
+## APIs
+
+It exposes two APIs:
+* `DynamixelProtocolHandler`: low-level API. It handles the serial communication and the Dynamixel protocol parsing. It can be used for fine-grained control of the shared bus with other communication.
+* `Controller`: high-level API for the Dynamixel protocol. Simpler and cleaner API but it takes full ownership of the io (it can still be shared if wrapped with a mutex for instance).
+
+See the examples below for usage.
+
 ### Examples
 ```rust
-use rustypot::{device::mx, DynamixelSerialIO};
+use rustypot::{DynamixelProtocolHandler, servo::dynamixel::mx};
 use std::time::Duration;
 
 fn main() {
@@ -31,16 +41,36 @@ fn main() {
         .open()
         .expect("Failed to open port");
 
-    let io = DynamixelSerialIO::v1();
+    let dph = DynamixelProtocolHandler::v1();
 
     loop {
         let pos =
-            mx::read_present_position(&io, serial_port.as_mut(), 11).expect("Communication error");
+            mx::read_present_position(&dph, serial_port.as_mut(), 11).expect("Communication error");
         println!("Motor 11 present position: {:?}", pos);
     }
 }
 ```
 
+```rust
+use rustypot::servo::feetech::sts3215::STS3215Controller;
+
+fn main() {
+    let serial_port = serialport::new("/dev/ttyUSB0", 1_000_000)
+        .timeout(Duration::from_millis(1000))
+        .open()
+        .unwrap();
+
+    let mut c = STS3215Controller::new()
+            .with_protocol_v1()
+            .with_serial_port(serial_port);
+
+    let pos = c.read_present_position(&vec![1, 2]).unwrap();
+    println!("Motors present position: {:?}", pos);
+
+    c.write_goal_position(&vec![1, 2], &vec![1000, 2000]).unwrap();
+}
+```
+
 ## Documentation
 
 See https://docs.rs/rustypot for more information on APIs and examples.

src/lib.rs

@@ -1,18 +1,26 @@
-//! Yet another communication library for robotis Dynamixel motors.
+//! A low-level communication library for servo (Dynamixel and Feetech motors).
 //!
 //! ## Feature Overview
 //!
 //! * Relies on [serialport] for serial communication
-//! * Support for dynamixel protocol v1 and v2 (can also use both on the same io)
+//! * Support for dynamixel protocol v1 and v2 (both can be used on the same io)
 //! * Support for sync read and sync write operations
 //! * Easy support for new type of motors (register definition through macros)
 //! * Pure Rust
 //!
-//! *Note: this version use std and Vec extensively.*
+//! ## APIs
+//!
+//! It exposes two APIs:
+//! * `DynamixelProtocolHandler`: low-level API. It handles the serial communication and the Dynamixel protocol parsing. It can be used for fine-grained control of the shared bus with other communication.
+//! * `Controller`: high-level API for the Dynamixel protocol. Simpler and cleaner API but it takes full ownership of the io (it can still be shared if wrapped with a mutex for instance).
+//!
+//! See the examples below for usage.
 //!
 //! ## Examples
+//!
+//! ### With the low-level API
 //! ```no_run
-//! use rustypot::{DynamixelProtocolHandler, device::mx};
+//! use rustypot::{DynamixelProtocolHandler, servo::dynamixel::mx};
 //! use std::time::Duration;
 //!
 //! let mut serial_port = serialport::new("/dev/ttyACM0", 1_000_000)
@@ -26,6 +34,24 @@
 //!     mx::read_present_position(&dph, serial_port.as_mut(), 11).expect("Communication error");
 //! println!("Motor 11 present position: {:?}", pos);
 //! ```
+//!
+//! ### With the high-level API
+//! ```no_run
+//! use rustypot::servo::feetech::sts3215::STS3215Controller;
+//!
+//! let serial_port = serialport::new(serialportname, baudrate)
+//!     .timeout(Duration::from_millis(1000))
+//!     .open()?;
+//!
+//! let mut c = STS3215Controller::new()
+//!         .with_protocol_v1()
+//!         .with_serial_port(serial_port);
+//!
+//! let pos = c.read_present_position(&vec![1, 2])?;
+//! println!("Motors present position: {:?}", pos);
+//!
+//! c.write_goal_position(&vec![1, 2], &vec![1000, 2000])?;
+//! ```
 
 pub mod servo;
 

src/servo/README.md

@@ -0,0 +1,12 @@
+## Adding support for a new servo
+
+> ⚠️ **Warning:** This documentation is only intended for servos that communicate via the Dynamixel Protocol (v1 or v2), such as the Robotis Dynamixel or Feetech servos.
+
+* Create a new file in the service folder (or a subfolder such as feetech or dynamixel), for instance [sts3215.rs](./servo/feetech/sts3215.rs) in the feetech folder. Make sure to add its declaration in the parent module (for instance in [./servo/feetech/mod.rs]) as they must be explicitly declared in Rust. Something like this: 
+```rust
+pub mod sts3215.rs
+```
+
+* Add the servo definition in the new file. You can use the [XL430](./servo/dynamixel/xl430.rs) as a template. The macro should defined the `name` of the servo, the `protocol version` used and then a list of all registers with their name, address, access and type. 
+
+* Finally, add the servo registration in the servo root module [./servo/mod.rs]. You can specify all variants supported by your servo definition. This registration allows for the scan function to detect your new kind of servo.