BB.Transmission (bb v0.19.0)

Mechanical transmission math: convert quantities between joint-space and motor-space.

A transmission captures three properties of the linkage between a joint and its actuator:

reduction — the gear ratio. A reduction of n means the actuator rotates n times for one rotation of the joint, so motor angular motion is n times the joint motion, and motor torque is 1 / n times the joint torque.
offset — the joint-space value (radians for rotational joints, metres for linear joints) corresponding to the actuator's zero position. Applies to positions only — velocities and accelerations have no offset since they are rates.
reversed? — whether actuator motion is reversed relative to joint motion.

All values are floats in SI base units (radians, metres, rad/s, m/s, N·m, N).

Equations

Position (joint → motor): motor = sign × reduction × (joint − offset) Position (motor → joint): joint = sign × motor / reduction + offset Rate (velocity, acceleration): motor = sign × reduction × joint Effort (torque, force): motor = sign × joint / reduction

Where sign = -1 if reversed?, otherwise +1. Each pair of apply/unapply is an exact inverse within float precision.

Summary

Types

t()

Functions

apply_effort(value, map)

Convert a joint-space effort (torque for rotational, force for linear) into motor-space.

apply_position(value, map)

Convert a joint-space position into a motor-space position.

apply_rate(value, map)

Convert a joint-space rate (velocity or acceleration) into motor-space.

apply_to_command(message, transmission)

Apply a transmission to an actuator command message, returning a new message with the payload values transformed into motor-space.

unapply_effort(value, map)

Convert a motor-space effort into a joint-space effort.

unapply_position(value, map)

Convert a motor-space position into a joint-space position.

unapply_rate(value, map)

Convert a motor-space rate into a joint-space rate.

unapply_to_payload(message, transmission)

Unapply a transmission to a message published by an actuator, returning a new message with motor-space values transformed back into joint-space.

Types

t()

@type t() :: %{reduction: float(), offset: float(), reversed?: boolean()}

Functions

apply_effort(value, map)

@spec apply_effort(float(), t()) :: float()

Convert a joint-space effort (torque for rotational, force for linear) into motor-space.

A gear reduction multiplies position and velocity but divides effort: a 50:1 reduction means the motor needs 1 / 50 of the joint torque.

apply_position(value, map)

@spec apply_position(float(), t()) :: float()

Convert a joint-space position into a motor-space position.

apply_rate(value, map)

@spec apply_rate(float(), t()) :: float()

Convert a joint-space rate (velocity or acceleration) into motor-space.

No offset is applied since the offset is a constant in position space.

apply_to_command(message, transmission)

@spec apply_to_command(BB.Message.t(), t() | nil) :: BB.Message.t()

Apply a transmission to an actuator command message, returning a new message with the payload values transformed into motor-space.

Position, velocity, and effort commands are transformed; hold and stop commands have no values to transform and are returned unchanged. Trajectory waypoints are transformed pointwise.

When transmission is nil, the message is returned unchanged.

unapply_effort(value, map)

@spec unapply_effort(float(), t()) :: float()

Convert a motor-space effort into a joint-space effort.

unapply_position(value, map)

@spec unapply_position(float(), t()) :: float()

Convert a motor-space position into a joint-space position.

unapply_rate(value, map)

@spec unapply_rate(float(), t()) :: float()

Convert a motor-space rate into a joint-space rate.

unapply_to_payload(message, transmission)

@spec unapply_to_payload(BB.Message.t(), t() | nil) :: BB.Message.t()

Unapply a transmission to a message published by an actuator, returning a new message with motor-space values transformed back into joint-space.

BeginMotion and JointState payloads are supported. JointState messages must be single-joint — the same transmission is applied to every list element. Other payloads are returned unchanged.

peak_velocity and acceleration in BeginMotion are magnitudes, so their joint-space values are taken as the absolute value of the unapplied rate (a reversed transmission flips the sign but does not change the magnitude).

When transmission is nil, the message is returned unchanged.