rby1_sdk.ImpedanceControlCommandBuilder#

class ImpedanceControlCommandBuilder#

Bases: pybind11_object

Cartesian impedance control command builder.

Builds a Cartesian impedance command for a given link in a reference frame. The control is formulated in the se(3) space with a 6D error \(\xi = [\,\Delta x;\,\Delta\phi\,] \in \mathbb{R}^6\) (translation and rotation in the Lie algebra), yielding the wrench:

\[w = K\,\xi \;+\; D\,\dot{\xi}\]

where \(K \in \mathbb{R}^{6\times 6}\) is the stiffness matrix and \(D \in \mathbb{R}^{6\times 6}\) is the damping matrix.

Notes

The stiffness matrix \(K\) is assumed block-diagonal:

\[K \;=\; \mathrm{diag}(K_t,\; K_r), \qquad K_t, K_r \in \mathbb{R}^{3\times 3}\ \text{(diagonal)}\]

set_translation_weight([k_x,k_y,k_z]) fills \(K_t=\mathrm{diag}(k_x,k_y,k_z)\), and set_rotation_weight([k_{rx},k_{ry},k_{rz}]) fills \(K_r=\mathrm{diag}(k_{rx},k_{ry},k_{rz})\).
Damping is derived from a dimensionless ratio \(\zeta\):

\[D \;=\; \zeta \left(\sqrt{M}\sqrt{K} \;+\; \sqrt{K}\sqrt{M}\right),\]

with \(M \in \mathbb{R}^{6\times 6}\) the Cartesian inertia matrix.
set_reference_link_name and set_link_name must be set before applying the target pose (set_transformation).

Examples

>>> import numpy as np, rby1_sdk as rby
>>> T = np.eye(4); T[0,3] = 0.30  # desired pose, 30 cm forward
>>> cmd = (
...   rby.ImpedanceControlCommandBuilder()
...   .set_reference_link_name("base_link")
...   .set_link_name("right_wrist")
...   .set_transformation(T)
...   .set_translation_weight(np.array([1200.0, 1200.0, 1600.0]))  # N/m
...   .set_rotation_weight(np.array([60.0, 60.0, 60.0]))           # Nm/rad
...   .set_damping_ratio(0.7)
... )

__init__(self: rby1_sdk.ImpedanceControlCommandBuilder) → None#

Methods

`__init__`(self)
`set_command_header`(self, command_header_builder)	Attach a command header.
`set_damping_ratio`(self, damping_ratio)	Set the (dimensionless) damping ratio used to build the 6×6 damping matrix.
`set_link_name`(self, link_name)	Set the controlled link name.
`set_reference_link_name`(self, ...)	Set the reference frame (link) name in which the pose is expressed.
`set_rotation_weight`(self, weight)	Set rotational stiffness (fills the rotational block of K).
`set_transformation`(self, T)	Set the desired Cartesian pose (homogeneous transform).
`set_translation_weight`(self, weight)	Set translational stiffness (fills the translational block of K).

set_command_header(self: rby1_sdk.ImpedanceControlCommandBuilder, command_header_builder: rby1_sdk.CommandHeaderBuilder) → rby1_sdk.ImpedanceControlCommandBuilder#

Attach a command header.

Parameters:: command_header_builder (CommandHeaderBuilder) – Command header configuration (e.g., control hold time).
Returns:: Self reference for method chaining.
Return type:: ImpedanceControlCommandBuilder

set_damping_ratio(self: rby1_sdk.ImpedanceControlCommandBuilder, damping_ratio: float) → rby1_sdk.ImpedanceControlCommandBuilder#

Set the (dimensionless) damping ratio used to build the 6×6 damping matrix.

Parameters:: damping_ratio (float) – Damping ratio \(\zeta\) (typically \(0 < \zeta \le 1.5\)).
Returns:: Self reference for method chaining.
Return type:: ImpedanceControlCommandBuilder

Notes

Damping in se(3) space is computed from \(K\) and the Cartesian inertia (reflective inertia) \(M\) as:

\[D \;=\; \zeta \left(\sqrt{M}\sqrt{K} \;+\; \sqrt{K}\sqrt{M}\right).\]
\(\zeta=1\) approximates critical damping; lower/higher values yield under/over-damped responses.

set_link_name(self: rby1_sdk.ImpedanceControlCommandBuilder, link_name: str) → rby1_sdk.ImpedanceControlCommandBuilder#

Set the controlled link name.

Parameters:: link_name (str) – Name of the robot link to be regulated in Cartesian impedance.
Returns:: Self reference for method chaining.
Return type:: ImpedanceControlCommandBuilder

set_reference_link_name(self: rby1_sdk.ImpedanceControlCommandBuilder, reference_link_name: str) → rby1_sdk.ImpedanceControlCommandBuilder#

Set the reference frame (link) name in which the pose is expressed.

Parameters:: reference_link_name (str) – Reference link/frame name.
Returns:: Self reference for method chaining.
Return type:: ImpedanceControlCommandBuilder

set_rotation_weight(self: rby1_sdk.ImpedanceControlCommandBuilder, weight: numpy.ndarray[numpy.float64[3, 1]]) → rby1_sdk.ImpedanceControlCommandBuilder#

Set rotational stiffness (fills the rotational block of K).

Parameters:: weight (numpy.ndarray, shape (3,), dtype=float64) – Per-axis rotational stiffness (Nm/rad), used to form \(K_r=\mathrm{diag}(k_{rx},k_{ry},k_{rz})\).
Returns:: Self reference for method chaining.
Return type:: ImpedanceControlCommandBuilder

Notes

The rotational wrench component is \(\tau = K_r\,\Delta\phi\).

set_transformation(self: rby1_sdk.ImpedanceControlCommandBuilder, T: numpy.ndarray[numpy.float64[4, 4]]) → rby1_sdk.ImpedanceControlCommandBuilder#

Set the desired Cartesian pose (homogeneous transform).

Parameters:: T (numpy.ndarray, shape (4,4), dtype=float64) – Desired pose \({}^{ref}\!T^{link}_d\).
Returns:: Self reference for method chaining.
Return type:: ImpedanceControlCommandBuilder

Notes

The se(3) error \(\xi = [\Delta x;\Delta\phi]\) is computed from \(T_d\) and the current pose.

set_translation_weight(self: rby1_sdk.ImpedanceControlCommandBuilder, weight: numpy.ndarray[numpy.float64[3, 1]]) → rby1_sdk.ImpedanceControlCommandBuilder#

Set translational stiffness (fills the translational block of K).

Parameters:: weight (numpy.ndarray, shape (3,), dtype=float64) – Per-axis translational stiffness (N/m), used to form \(K_t=\mathrm{diag}(k_x,k_y,k_z)\).
Returns:: Self reference for method chaining.
Return type:: ImpedanceControlCommandBuilder

Notes

The 6×6 stiffness matrix is \(K=\mathrm{diag}(K_t,K_r)\).
The translational wrench component is \(F = K_t\,\Delta x\).