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.
• internal_enhanced_float - Do not enable this yourself.

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

Re-exports

pub use reference::Reference;

pub use reference::rc_ref_cell_reference;

pub use reference::arc_mutex_reference;

pub use reference::arc_rw_lock_reference;

pub use dimensions::*;

Modules

compile_time_dimensions

RRTK’s compile-time dimensional analysis system. This system is simpler than ones like uom, but it serves a similar purpose: to protect users from dimension mismatch errors at compile time without runtime overhead. This is done through a semi-hack representing integers as types and adding type parameters to a special struct called Quantity, which is a transparent struct holding only a value at runtime.

compile_time_integer

RRTK’s compile-time integer system. This is basically a simpler version of Typenum. It is used for compile-time dimensional analysis. 0 is represented by the Zero struct. Positive integers are created by wrapping Zero with with OnePlus a given number of times, e.g., 2 is represented by OnePlus<OnePlus<Zero>>. Negative numbers are created similarly but with NegativeOnePlus instead of OnePlus: -2 is NegativeOnePlus<NegativeOnePlus<Zero>>. You should be able to read a number’s type left-to-right and get a mathematical expression that will evaluate to the number. Using both OnePlus and NegativeOnePlus in the same number is discouraged, e.g., using NegativeOnePlus<OnePlus<Zero>> for 0.

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

div

Gets the resulting type from dividing quantities of two types. Basically an alias for <$a as Div<$b>>::Output. This is an important thing to be able to do when writing code that is generic over units as, since quantities of different units are technically different types, the fully qualified syntax gets unwieldy quickly when performing multiplication and division. Rust’s scoping rules for macros is a bit odd, but you should be able to use rrtk::div! and rrtk::compile_time_dimensions::div! interchangably.

mul

Gets the resulting type from multiplying quantities of two types. Basically an alias for <$a as Mul<$b>>::Output. This is an important thing to be able to do when writing code that is generic over units as, since quantities of different units are technically different types, the fully qualified syntax gets unwieldy quickly when performing multiplication and division. Rust’s scoping rules for macros is a bit odd, but you should be able to use rrtk::mul! and rrtk::compile_time_dimensions::mul! interchangably.

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

CannotConvert

The error type used when a TryFrom fails.

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.

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.