motorcortex-rust

Motorcortex Rust is a communication library designed for developing client applications in Rust for the Motorcortex Core. It provides an efficient and type-safe implementation of the low-level API defined in motorcortex.proto. A core feature of this API is its ability to interact with the Parameter Tree. The library allows developers to query, retrieve, and modify parameters within a hierarchical structure.

Features

• Implements the low-level API defined in motorcortex.proto.
• Req/Rep requests for the Parameter Tree
• Pub/Sub (To be done...)
• Secure communication via Websocket Security protocol.

Getting Started

Follow the steps below to install and run the project.

Prerequisites

• Rust (Install via rustup)
• Cargo (comes bundled with Rust)

Installation

Clone the repository:

git clone https://git.vectioneer.com/pub/motorcortex-rust
cd motorcortex-rust

Build the project:

cargo build

Run the project:

cargo run

Run the tests:

cargo test

Example Usage

Simple example of how to use your project:

Note: mcx.cert.crt can be downloaded from here https://docs.motorcortex.io/mcx.cert.crt

use motorcortex_rust::{ConnectionOptions, Request};

fn main() {
  // Create a new request instance to interact with the Motorcortex server
  let mut request = Request::new();
  // Define connection options (certificate and timeouts)
  // Note: mcx.cert.crt can be downloaded from here https://docs.motorcortex.io/mcx.cert.crt
  let conn_options = ConnectionOptions::new("mcx.cert.crt".to_string(), 1000, 1000);
  // Establish a WebSocket connection to the Motorcortex server
  request
    .connect("wss://127.0.0.1:5568", conn_options)
    .unwrap();
  // Request the parameter tree from the Motorcortex server
  request.request_parameter_tree().unwrap();

  // --- Modify and Retrieve a Single Scalar Value ---
  // Set a parameter value (scalar) on the server
  request
    .set_parameter("root/Control/dummyDouble", 2.345)
    .unwrap();
  println!("Modified parameter value");

  // --- Retrieve the Same Parameter in Different Types (Type Casting) ---
  // Note: The actual server value must be convertible to the requested type.
  // Retrieve the parameter value as a 32-bit float (f32)
  let parameter: f32 = request.get_parameter("root/Control/dummyDouble").unwrap();
  println!("Retrieved parameter as f32: {}", parameter);
  // Retrieve the parameter value as a String
  let parameter: String = request.get_parameter("root/Control/dummyDouble").unwrap();
  println!("Retrieved parameter as a string: {}", parameter);
  // Retrieve the parameter value as a 64-bit integer (i64)
  let parameter: i64 = request.get_parameter("root/Control/dummyDouble").unwrap();
  println!("Retrieved parameter as int64: {}", parameter);

  // --- Modify and Retrieve a Fixed-Size Array ---
  // Set a parameter value as a fixed-size array ([f64; 3]) on the server
  request
    .set_parameter("root/Control/dummyDoubleVec", [1, 2, 3])
    .unwrap();
  println!("Modified parameter as a fixed-size array");
  // Retrieve the parameter value as a fixed-size array ([f64; 3])
  let parameter: [f64; 3] = request
    .get_parameter("root/Control/dummyDoubleVec")
    .unwrap();
  println!("Retrieved parameter as a fixed-size array: {:?}", parameter);

  // --- Modify and Retrieve a Dynamically-Sized Vector ---
  // Set a parameter value as a dynamically-sized vector (Vec<f64>) on the server
  request
    .set_parameter("root/Control/dummyDoubleVec", vec![1.35, 2.34, 3.45])
    .unwrap();
  println!("Modified parameter as a dynamically-sized vector");
  // Retrieve the parameter value as a dynamically-sized vector (Vec<f64>)
  let parameter: Vec<f64> = request
    .get_parameter("root/Control/dummyDoubleVec")
    .unwrap();
  println!(
    "Retrieved parameter as a dynamically-sized vector: {:?}",
    parameter
  );
}

Documentation

The project has inline documentation, but you can also generate a comprehensive HTML documentation view using cargo doc:

cargo doc --open

License

This project is licensed under the MIT License. You are free to use, modify, and distribute it as per the license terms.