Firmware API Reference

ROS 2 Topic Layout

Each TK actuator exposes the following topics under the namespace /tk_joint_N/ where N is the node ID (default: 0).

Topic	Type	Direction	Rate
joint_state	tknd_msgs/JointState	Publish	100 Hz
cmd_pos	std_msgs/Float64	Subscribe	async
cmd_vel	std_msgs/Float64	Subscribe	async
cmd_torque	std_msgs/Float64	Subscribe	async
impedance_params	tknd_msgs/ImpedanceParams	Subscribe	async
diagnostics	diagnostic_msgs/DiagnosticArray	Publish	1 Hz

The JointState message fields:

float64 position     # rad, output flange angle
float64 velocity     # rad/s, output flange angular velocity
float64 torque       # Nm, measured output torque
float64 temperature  # degC, motor winding temperature
uint8   mode         # current control mode (see modes below)
uint16  fault_code   # 0 = no fault

Control Modes

Set the control mode via the cmd_pos, cmd_vel, or cmd_torque topic. The firmware switches modes on the first command received on each topic. Over CiA 402, set 0x6060 (modes of operation):

Mode	ROS 2 Topic	CiA 402 Object 0x6060 Value	Notes
Position	`cmd_pos`	8 (cyclic sync position)	Profile trapezoidal by default
Velocity	`cmd_vel`	9 (cyclic sync velocity)	Velocity in rad/s
Torque	`cmd_torque`	10 (cyclic sync torque)	Torque in Nm, FOC loop at 400 Hz
Impedance	`impedance_params`	Custom: 0x20 via 0x2020	Spring-damper at output

Impedance Control

Impedance mode runs a spring-damper equation at the output: τ = Kp * (θ_ref - θ) - Kd * dθ/dt. Parameters are set via:

ros2 topic pub /tk_joint_0/impedance_params \
  tknd_msgs/ImpedanceParams \
  '{kp: 20.0, kd: 1.5, theta_ref: 0.0}'

Or via SDO:

Parameter	Object	Type	Default	Range
Stiffness Kp	0x2010	FLOAT32	20.0	0 – 500 Nm/rad
Damping Kd	0x2011	FLOAT32	1.5	0 – 50 Nm·s/rad
Reference angle	0x2012	FLOAT32	0.0	–π to +π rad
Torque saturation	0x2013	FLOAT32	model max	0 – rated torque

Register Map (Tendonkindle Custom Objects)

These are extensions beyond the CiA 402 standard. All are accessible via SDO in CANopen and CoE in EtherCAT.

Index	Name	Type	Notes
0x2000	Firmware version	UINT32	Read-only
0x2001	Node ID	UINT8	Write + EEPROM save; range 1–63
0x2002	Baud rate index	UINT8	0=250k, 1=500k, 2=1Mbit
0x2010	Impedance Kp	FLOAT32	Stiffness in Nm/rad
0x2011	Impedance Kd	FLOAT32	Damping in Nm·s/rad
0x2012	Impedance θ_ref	FLOAT32	Reference angle in rad
0x2013	Impedance τ_sat	FLOAT32	Torque saturation in Nm
0x2020	Control mode	UINT8	8=pos, 9=vel, 10=torque, 32=impedance
0x2030	Winding temperature	FLOAT32	Read-only, degC
0x2031	Housing temperature	FLOAT32	Read-only, degC
0x2040	Error history (0)	UINT16	Most recent fault code

Error Codes

Error codes are returned in joint_state.fault_code and in 0x2040. A value of 0x0000 means no fault.

Code	Name	Likely Cause	Recovery
0x1000	Over-temperature	Winding temp > 85°C	Allow 5 min cool-down; reduce duty cycle
0x2000	Over-voltage	Supply > 56 VDC	Check power supply regulation
0x2001	Under-voltage	Supply < 36 VDC	Check supply voltage at connector
0x3000	Over-current	Phase current > rated peak	Reduce peak torque command; check wiring
0x4000	Encoder fault	Encoder communication lost	Check encoder connector; power-cycle
0x5000	Fieldbus timeout	No command received for > 500 ms	Check network link; increase heartbeat rate
0x6000	Position limit	Output angle hit software hard stop	Command to within ±π rad from zero

To clear a latched fault: write 0x6040 (control word) with bits 7+4+3+1+0 set (fault reset sequence), or send:

ros2 topic pub --once /tk_joint_0/cmd_pos \
  std_msgs/Float64 '{data: 0.0}'