Crate rrtk

Rust Robotics ToolKit

A set of algorithms and other tools for robotics in Rust.

It is almost entirely no_std and most things work without alloc. It does not currently integrate with any API directly. This may be added in the future, probably through another crate.

Feature Flags

• alloc - Enable items requiring dynamic allocation through Rust’s builtin alloc crate.
• std - Enable items requiring the Rust standard library. Requires alloc feature. Enabled by default.
• devices - Enable RRTK’s graph-based device system.
• dim_check_debug - Enable dimension checking in debug mode. Enabled by default.
• dim_check_release - Enable dimension checking in both debug mode and release mode. Requires dim_check_debug feature.
• libm - Use libm for float exponentiation when std is not available.
• micromath - Use micromath for float exponentiation when std and libm are unavailable.

RRTK prefers std over libm and libm over micromath when multiple are available.

Re-exports

pub use reference::rc_ref_cell_reference;

pub use reference::Reference;

pub use reference::arc_mutex_reference;

pub use reference::arc_rw_lock_reference;

pub use dimensions::*;

Modules

devices

RRTK’s device system works through a graph-like structure where each device holds objects called terminals in RefCells. Terminals represent anywhere that a device can connect to another. Connected terminals hold references to eachother’s RefCells. This module holds builtin devices.

dimensions

This module contains types related to RRTK’s dimensional analysis system. RRTK uses nanoseconds for time because they typically work nicely with computer clocks and are still precise when stored in an integer, which is important because exponentially losing precision for time is bad, and float time does that. However, floats are used for other quantities, including quantities derived from time. These use seconds instead because numbers of the magnitude of nanoseconds cause floats to lose precision. RRTK should handle the conversion mostly seamlessly for you, but keep it in mind when thinking about how time-related types should work. The reasoning behind this unorthodox system using both nanoseconds and seconds becomes more apparent when you know how floating point numbers work. Everything in this module is reexported at the crate level.

reference

Reference is a container holding an enum with variants containing different kinds of references, the availability of some of which depends on crate features. Reference is borrowed like a RefCell. This module contains it and its related types. Reference is also reexported at the crate level.

streams

Getters that do data processing and have other getters as inputs are called streams. These are some helpful builtin streams for controlling your robot. See the pid example to learn more about how to use the stream system.

Macros

static_mutex_reference

Create a new static Mutex of something and return a PtrMutex-variant Reference to it.

static_reference

Create a static of something and return a Ptr-variant Reference to it. This contains a raw mutable pointer. It will never use-after-free because its target is static, but be careful if you’re doing multiprocessing where multiple things could mutate it at once.

static_rw_lock_reference

Create a static RwLock of something and return a PtrRwLock-variant Reference to it.

to_dyn

If you have a Reference<Foo> where Foo implements the Bar trait, you may end up wanting a Reference<dyn Bar>. To convert it, you would do this:

Structs

ConstantGetter

Getter for returning a constant value.

Datum

A container for a time and something else, usually an f32 or a State.

GetterFromHistory

As histories return values at times, we can ask them to return values at the time of now or now with a delta. This makes that much easier and is the recommended way of following MotionProfiles.

MotionProfile

A motion profile for getting from one state to another.

NoneGetter

Getter always returning Ok(None).

PIDKValues

Coefficients for a PID controller.

PositionDerivativeDependentPIDKValues

A set of PID k-values for controlling each position derivative.

SettableData

Internal data needed for following a Getter with a Settable.

State

A one-dimensional motion state with position, velocity, and acceleration.

Terminal

A place where a device can connect to another.

TerminalData

Data that are sent between terminals: A timestamp, an optional command, and a state.

TimeGetterFromGetter

Because Getters always return a timestamp (as long as they don’t return Err(_) or Ok(None)), we can use this to treat them like TimeGetters.

Enums

Command

A command for a motor to perform: go to a position, run at a velocity, or accelerate at a rate.

Error

RRTK follows the enum style of error handling. This is the error type returned from nearly all RRTK types, but you can add your own custom error type using Other(O). It is strongly recommended that you use a single O type across your crate.

MotionProfilePiece

Where you are in following a motion profile.

PositionDerivative

A derivative of position: position, velocity, or acceleration.

Traits

Device

A mechanical device.

Getter

Something with a get method. Structs implementing this will often be chained for easier data processing, with a struct having other implementors in fields which will have some operation performed on their output before it being passed on. Data processing Getters with other Getters as fields can be referred to as streams, though this is only in naming and trait-wise there is no distinction. The other common use for this trait is encoders. These should not be called streams.

History

An object that can return a value, like a Getter, for a given time.

OptionDatumExt

Extension trait for Option<Datum<T>>.

Settable

Something with a set method. Usually used for motors and other mechanical components and systems. This trait too is fairly broad.

TimeGetter

An object for getting the absolute time.

Updatable

Something with an update method. Mostly for subtraiting.

Functions

connect

Connect two terminals. Connected terminals should represent a physical connection between mechanical devices. This function will automatically disconnect the specified terminals if they are connected. You can manually disconnect terminals by calling the disconnect method on either of them.

latest

Get the newer of two Datum objects.

Type Aliases

NothingOrError

Returned when something may return either nothing or an error.

Output

A generic output type when something may return an error, nothing, or something with a timestamp.

TimeOutput

Returned from TimeGetter objects, which may return either a time or an error.