bam.actuator#

Classes#

`Actuator`	Abstract base class for all BAM actuator models.
`DCMotorActuator`	Base class for DC motor actuators with a supply voltage and a P-gain.
`VoltageControlledActuator`	Voltage-controlled servo with a firmware P-position controller.
`CurrentControlledActuator`	Current-controlled servo with a firmware P-position controller.

Module Contents#

class bam.actuator.Actuator(testbench_class: bam.testbench.Testbench)#

Abstract base class for all BAM actuator models.

Subclasses implement the firmware control law and the motor torque equation for a specific actuator family. An actuator is always attached to a Model via set_actuator(), which calls initialize() to create the motor parameters (kt, R, …) on the model.

Parameters:: testbench_class – Class used to instantiate the testbench when a log is loaded (typically Pendulum).

testbench_class#

testbench: bam.testbench.Testbench | None = None#

set_model(model)#

Attach this actuator to a model and run initialize().

Parameters:: model – Model instance to attach to.

reset()#

load_log(log: dict)#

Called when a log is loaded.

Instantiates the testbench from the log metadata (mass, length, …) and updates actuator settings (kp, vin) from the log.

Parameters:: log – Log dict as loaded from a processed JSON file.

abstractmethod initialize()#

Create motor parameters on the attached model.

Called automatically by set_model(). Must create at minimum self.model.kt and self.model.R as Parameter instances.

abstractmethod control_unit() → str#: Return the physical unit of the control signal (e.g. "volts", "amps").

abstractmethod compute_control(q_target: float, q: float, dq: float, dt: float) → float | None#

Compute the control signal from the current state and target.

Parameters:

q_target – Target joint angle [rad].
q – Current joint angle [rad].
dq – Current joint velocity [rad/s].
dt – Timestep [s].

Returns:

Control signal in the unit given by control_unit().

abstractmethod compute_torque(control: float | None, torque_enable: bool, q: float, dq: float) → float#

Compute the motor torque from the control signal and current state.

Parameters:

control – Control signal (volts, amps, or Nm depending on the actuator).
torque_enable – Whether the actuator is powered.
q – Current joint angle [rad].
dq – Current joint velocity [rad/s].

Returns:

Motor torque [Nm].

abstractmethod get_extra_inertia() → float#: Return the actuator’s apparent inertia added to the load [kg·m²].

abstractmethod to_mujoco()#

class bam.actuator.DCMotorActuator(testbench_class: bam.testbench.Testbench, vin: float, kp: float)#

Bases: Actuator

Base class for DC motor actuators with a supply voltage and a P-gain.

Loads kp and vin from the log metadata when load_log() is called.

Parameters:

testbench_class – Testbench class (see Actuator).
vin – Default supply voltage [V].
kp – Default firmware proportional gain.

vin#

kp#

load_log(log: dict)#

Called when a log is loaded.

Instantiates the testbench from the log metadata (mass, length, …) and updates actuator settings (kp, vin) from the log.

Parameters:: log – Log dict as loaded from a processed JSON file.

initialize()#: Create kt and R parameters on the attached model.

class bam.actuator.VoltageControlledActuator(testbench_class: bam.testbench.Testbench, vin: float, kp: float, error_gain: float, max_pwm: float = 1.0)#

Bases: DCMotorActuator

Voltage-controlled servo with a firmware P-position controller.

Implements the control law duty_cycle = clip(error_gain * kp * Δq, -max_pwm, max_pwm) and the DC motor torque equation with back-EMF.

Parameters:

testbench_class – Testbench class (see Actuator).
vin – Supply voltage [V].
kp – Firmware proportional gain.
error_gain – Converts kp * Δq to a duty cycle in [−1, 1]. Depends on the servo’s internal encoder resolution and gain scaling.
max_pwm – Maximum duty cycle magnitude (default 1.0).

error_gain#

max_pwm = 1.0#

control_unit() → str#: Return the physical unit of the control signal (e.g. "volts", "amps").

compute_control(q_target: float, q: float, dq: float, dt: float) → float | None#

Compute the voltage command from position error.

Parameters:

q_target – Target joint angle [rad].
q – Current joint angle [rad].
dq – Current joint velocity [rad/s] (unused here).
dt – Timestep [s] (unused here).

Returns:

Voltage [V] sent to the motor.

compute_torque(control: float | None, torque_enable: bool, q: float, dq: float) → float#

Compute motor torque using the DC motor equation with back-EMF.

\(\tau = k_t V / R - k_t^2 \dot{q} / R\)

Parameters:

control – Voltage [V].
torque_enable – If False, returns zero torque.
q – Current joint angle [rad] (unused here).
dq – Current joint velocity [rad/s].

Returns:

Motor torque [Nm].

to_mujoco()#

class bam.actuator.CurrentControlledActuator(testbench_class: bam.testbench.Testbench, vin: float, kp: float, error_gain: float)#

Bases: DCMotorActuator

Current-controlled servo with a firmware P-position controller.

The controller outputs a target current proportional to position error, clipped by both the voltage limits and a user-configurable current cap.

Parameters:

testbench_class – Testbench class (see Actuator).
vin – Supply voltage [V], used to compute the current saturation.
kp – Firmware proportional gain.
error_gain – Converts kp * Δq to a target current [A].

error_gain#

control_unit() → str#: Return the physical unit of the control signal (e.g. "volts", "amps").

initialize()#: Create kt and R parameters on the attached model.

compute_control(q_target: float, q: float, dq: float, dt: float) → float | None#

Compute the current command from position error.

Clips the P-controller output by both the back-EMF voltage limit and the current_limit parameter.

Parameters:

q_target – Target joint angle [rad].
q – Current joint angle [rad].
dq – Current joint velocity [rad/s].
dt – Timestep [s] (unused here).

Returns:

Target current [A].

compute_torque(control: float | None, torque_enable: bool, q: float, dq: float) → float#

Compute motor torque from current command.

\(\tau = k_t I - b_{\text{active}} \dot{q}\)

Parameters:

control – Current command [A].
torque_enable – If False, returns zero torque.
q – Current joint angle [rad] (unused here).
dq – Current joint velocity [rad/s].

Returns:

Motor torque [Nm].

to_mujoco()#