# Examples

This section elaborates the practicality of the HRIM model trough its implementation on a real device. We have chosen the rotary servomotor since it is one of the most used components in robotics and sufficient to explain most of the HRIM details.

Rotary servomotor
 HRIM defines a rotary servomotor as A smart actuator that creates a circular movement and allows for precise control of position, velocity, effort and, sometimes acceleration.

So, apart from the common requirements (ID, Status, Power, Specs Communication and Simulation, detailed in HRIM component model section), all rotary servomotors will contain a topic referring to the circular movement.

The following table presents a summary of the HRIM rotary servomotor model on which the manufacturers will have to base themselves to configure their own rotary servomotor. The hardware maker must include, at least, the mandatory aspects. The optional parameters can be added if the module contains these additional features.

HRIM component model: RotaryServo
/hrim_actuator_rotaryservo_<instance_id>/id hrim_generic_msgs/msg/ID.msg topic (Sub) Mandatory Component identification.
/hrim_actuator_rotaryservo_<instance_id>/status hrim_generic_msgs/msg/Status.msg topic (Sub) Mandatory How the module is working.
/hrim_actuator_rotaryservo_<instance_id>/power hrim_generic_msgs/msg/Power.msg topic (Sub) Mandatory Describes the power supply type and give the information about the module power consumption.
/hrim_actuator_rotaryservo_<instance_id>/specs_comm hrim_generic_msgs/msg/SpecsCommunication.msg topic (Sub) Mandatory Published the capabilities in term of communicaction that the component offers.
/hrim_actuator_rotaryservo_<instance_id>/state_comm hrim_generic_msgs/msg/StateCommunication.msg topic (Sub) Mandatory Published the resources that the component is using at the moment.
/hrim_actuator_rotaryservo_<instance_id>/module_3d hrim_generic_msgs/msg/Simulation3D.msg topic (Sub) Mandatory Ask for the 3D model of the HRIM component.
/hrim_actuator_rotaryservo_<instance_id>/module_urdf hrim_generic_msgs/msg/SimulationURDF.msg topic (Sub) Mandatory Ask for the information of,3D model of the HRIM component.
/hrim_actuator_rotaryservo_<instance_id>/specs hrim_actuator_rotaryservo_msgs/msg/SpecsRotaryServo.msg topic (Sub) Mandatory Device features.
/hrim_actuator_rotaryservo_<instance_id>/goal hrim_actuator_rotaryservo_msgs/msg/GoalRotaryServo.msg topic (Sub) Mandatory Control the position, velocity or/and effort.
/hrim_actuator_rotaryservo_<instance_id>/state hrim_actuator_rotaryservo_msgs/msg/StateRotaryServo.msg topic (Sub) Optional Motor condition and the reason in case of error.
/hrim_actuator_rotaryservo_<instance_id>/acceleration hrim_actuator_rotaryservo_msgs/msg/GoalAngularAcceleration.msg topic (Sub) Optional Control the acceleration. The integration of the acceleration characteristic is needed.
/hrim_actuator_rotaryservo_<instance_id>/temperature hrim_sensor_thermometer_msgs/msg/Temperature.msg topic
Pub)
Optional Motor internal temperature. Also informs if there is temperature error. The integration of a temperature sensor is needed.
Parameters
frame_rate int Hz Mandatory Refresh rate.
origin float rad Mandatory Zero/Started point.
joint_name string - Mandatory Name of the joint, usefull to control robotic amrs.
min_temperature float ºC Optional Related to Temperature.msg
Minimum operating temperature.
NOTE: Mandatory if Temperature.msg is added.
max_temperature float ºC Optional Related to Temperature.msg
Maximum operating temperature.
NOTE: Mandatory if Temperature.msg is added.

The following paragraphs provide a walkthrough of the abstractions proposed for the HRIM RotaryServo model of a rotary servomotor. Servomotors always contain the common information defined for the actuator category. In the rotary servomotor case, it has four optional topics. The first two are additional capabilities that complement the rotary servomotor purpose. The rest are independent sensors that can appear integrated in the component, called optional hardware.

#### Specs

hrim_actuator_rotaryservo_msgs/msg/SpecsRotaryServo.msg describes all the necessary specifications for the implementation of a rotary servomotor.

std_msgs/Header header

# type of control that accepts the rotary servomotor
uint8 CONTROL_TYPE_NONE=0
uint8 CONTROL_TYPE_POSITION=1
uint8 CONTROL_TYPE_EFFORT=2
uint8 CONTROL_TYPE_VELOCITY=3
uint8 CONTROL_TYPE_POSITION_VELOCITY=4
uint8 CONTROL_TYPE_POSITION_EFFORT=5
uint8 CONTROL_TYPE_VELOCITY_EFFORT=6
uint8 CONTROL_TYPE_POSITION_VELOCITY_EFFORT=7
uint8 control_type                               # rotary servomotor control type

float64 range_min              # minimum work range (rad)
float64 range_max              # maximum work range (rad)
float64 precision              # angular precision (rad)
float64 rated_speed            # servomotor speed (rad/s)
float64 reachable_speed        # maximum speed (rad/s)
float64 rated_torque           # servomotor torque (Nm)
float64 reachable_torque       # peak torque (Nm)
float64 temperature_range_min  # minimum operational temperature (celsius)
float64 temperature_range_max  # maximum operational temperature (celsius)

#### Device purpose

Rotary servomotors belong to the actuator type classification. In this case, it is necessary to define an end goal (position) which can be achieved with different velocity or effort. hrim_actuator_rotaryservo_msgs/msg/GoalRotaryServo.msg

std_msgs/Header header

uint8 control_type             # servomotor control type, explained in SpecsRotaryServo.msg

float64 position               # Position to move (rad)
float32 velocity               # Velocity to move (rad/s)
float32 effort                 # Force to move (kg*cm3)

• State: through hrim_actuator_rotaryservo_msgs/msg/StateRotaryServo.msg, a rotary servomotor continuously publishes information regarding the motor condition, how is it working, and the reason in case of error.
std_msgs/Header header        # Motor state is at this time

float64 goal                  # commanded position (rad)
float64 position              # current position encoder (rad)
float64 error                 # difference between current and goal positions (rad)
float64 velocity              # current velocity (rad/s)
float64 effort                # current effort of the actuator (Nm)
bool moving                   # whether the motor is currently in motion

#Fault states which could cause the driver to be immobilized.

uint8 FAULT_NONE=0
uint8 FAULT_CURRENT=1
uint8 FAULT_TEMPERATURE=2
uint8 FAULT_BUS_VOLTAGE=3
uint8 FAULT_BRIDGE_DRIVER=4
uint8 fault                   # fault cause

uint8 control_type            # servomotor control type, explained in SpecsRotaryServo.msg
• Acceleration: some rotary servomotors have the option to control the acceleration. If that is the case, the manufacturer has to use the hrim_actuator_rotaryservo_msgs/msg/GoalAngularAcceleration.msg and expose the acceleration, so that the user can control this feature.
std_msgs/Header header

float32 acceleration        # angular acceleration (rad/s2)


#### Optional hardware

• Temperature: the temperature sensor is an independent sensor which can usually be integrated into other devices in order to know the interior temperature of the module. As you can see in table above, this topic goes hand in hand with two parameters that, in this case, are mandatory to be able to control the temperature in a correct way. The temperature topic use hrim_sensor_thermometer_msgs/msg/Temperature.msg
std_msgs/Header header

float64 temperature           # Current tempreture in Celsius
bool    temperature_error     # True: the component is working up to its operating temperature /
# False: The temperature is within the allowed range