HRIM tooling examples

All commands should be executed at the HRIM's repository's root

To generate a specific module, all of the following ways to specify the model path are valid:

hrim generate $(pwd)/models/sensor/torque/torque.xml
hrim generate ./models/sensor/torque/torque.xml
hrim generate models/sensor/torque/torque.xml

All of these commands will generate the torque module's implementation plus the generic interfaces, which always get generated.

The following shorthands exist for the generate command.

all will generate the implementation of all existing models:

hrim generate all

actuators will generate the implementation of all existing actuator modules:

hrim generate actuators

composites will generate the implementation of all existing composite modules:

hrim generate composites

powers will generate the implementation of all existing power modules:

hrim generate powers

sensors will generate the implementation of all existing sensor modules:

hrim generate sensors

Generated implementations are located inside a generated directory at the repository's root, in a type/subtype structure. A full implementation generation results in:

generated/
├── actuator
│   ├── electricmotor
│   │   ├── hrim_actuator_electricmotor_msgs
│   │   └── hrim_actuator_electricmotor_srvs
│   ├── gripper
│   │   ├── hrim_actuator_gripper_msgs
│   │   └── hrim_actuator_gripper_srvs
│   └── rotaryservo
│       ├── hrim_actuator_rotaryservo_msgs
│       └── hrim_actuator_rotaryservo_srvs
├── composite
│   ├── arm
│   │   ├── hrim_composite_arm_msgs
│   │   └── hrim_composite_arm_srvs
│   ├── conveyor
│   │   ├── hrim_composite_conveyor_msgs
│   │   └── hrim_composite_conveyor_srvs
│   └── mobilebase
│       ├── hrim_composite_mobilebase_msgs
│       └── hrim_composite_mobilebase_srvs
├── generic
│   ├── hrim_generic_msgs
│   └── hrim_generic_srvs
├── power
│   └── battery
│       ├── hrim_power_battery_msgs
│       └── hrim_power_battery_srvs
└── sensor
    ├── 3dcameradepth
    │   ├── hrim_sensor_3dcameradepth_msgs
    │   └── hrim_sensor_3dcameradepth_srvs
    ├── 3dcamerastereo
    │   ├── hrim_sensor_3dcamerastereo_msgs
    │   └── hrim_sensor_3dcamerastereo_srvs
    ├── 3dcameratof
    │   ├── hrim_sensor_3dcameratof_msgs
    │   └── hrim_sensor_3dcameratof_srvs
    ├── camera
    │   ├── hrim_sensor_camera_msgs
    │   └── hrim_sensor_camera_srvs
    ├── encoder
    │   ├── hrim_sensor_encoder_msgs
    │   └── hrim_sensor_encoder_srvs
    ├── force
    │   ├── hrim_sensor_force_msgs
    │   └── hrim_sensor_force_srvs
    ├── forcetorque
    │   ├── hrim_sensor_forcetorque_msgs
    │   └── hrim_sensor_forcetorque_srvs
    ├── gasdetector
    │   ├── hrim_sensor_gasdetector_msgs
    │   └── hrim_sensor_gasdetector_srvs
    ├── gps
    │   ├── hrim_sensor_gps_msgs
    │   └── hrim_sensor_gps_srvs
    ├── hygrometer
    │   ├── hrim_sensor_hygrometer_msgs
    │   └── hrim_sensor_hygrometer_srvs
    ├── imu
    │   ├── hrim_sensor_imu_msgs
    │   └── hrim_sensor_imu_srvs
    ├── lidar
    │   ├── hrim_sensor_lidar_msgs
    │   └── hrim_sensor_lidar_srvs
    ├── microphone
    │   ├── hrim_sensor_microphone_msgs
    │   └── hrim_sensor_microphone_srvs
    ├── rangefinder
    │   ├── hrim_sensor_rangefinder_msgs
    │   └── hrim_sensor_rangefinder_srvs
    ├── thermometer
    │   ├── hrim_sensor_thermometer_msgs
    │   └── hrim_sensor_thermometer_srvs
    └── torque
        ├── hrim_sensor_torque_msgs
        └── hrim_sensor_torque_srvs

The target platform of these implementations can be specified through the -p/--platform optional argument.

The following ways to specify the plaftorm are all valid:

hrim generate all
hrim generate --platform ros2 all
hrim generate all -p ros2

The list command can be used to show a list of the current models or your generated implementations.

hrim list models

Will return:

actuator/electricmotor/electricmotor
actuator/gripper/gripper
actuator/servo/servo
composite/arm/arm
composite/conveyor/conveyor
composite/mobilebase/mobilebase
power/battery/battery
sensor/3dcamera/3dcamera_depth
sensor/3dcamera/3dcamera_stereo
sensor/3dcamera/3dcamera_tof
sensor/camera/camera
sensor/encoder/encoder
sensor/force/force
sensor/forcetorque/forcetorque
sensor/gasdetector/gasdetector
sensor/gps/gps
sensor/hygrometer/hygrometer
sensor/imu/imu
sensor/lidar/lidar
sensor/microphone/microphone
sensor/rangefinder/rangefinder
sensor/thermometer/thermometer
sensor/torque/torque

While

hrim list implementations

Will, when all implementations have been generated, return:

actuator/electricmotor
actuator/gripper
actuator/rotaryservo
composite/arm
composite/conveyor
composite/mobilebase
generic
power/battery
sensor/3dcameradepth
sensor/3dcamerastereo
sensor/3dcameratof
sensor/camera
sensor/encoder
sensor/force
sensor/forcetorque
sensor/gasdetector
sensor/gps
sensor/hygrometer
sensor/imu
sensor/lidar
sensor/microphone
sensor/rangefinder
sensor/thermometer
sensor/torque

The clear command can be used to delete currently generated implementations, either selectively or en masse through the all shorthand.

hrim clear all

Will delete all implementations found under the generated directory.

Alternatively, the results of running hrim list implementations can be used to delete specific implementations:

hrim clear composite/mobilebase
hrim clear generic
hrim clear power/battery
hrim clear sensor/3dcameradepth

Finally, component types can also be used to delete multiple implementations selectively:

hrim clear sensor
hrim clear composite

The functions mentioned in this subsection are a work in progress. Still, they are part of the core functions of HRIM's tooling and are therefore explained here. Do take into account that this process is subject to changes as it's still in development.

As explained in our Meta-model section, the capabilities of a robot module might fall under multiple models. That's what we need the model composition for.

First, you'd indicate to the tool that you want to generate a composite model and it's parts. Following the example above of an arm with an integrated camera:

hrim compose composite/arm sensor/camera

This will generate an XML file (model.xml by default) in the repository's root with a structure like the following, where each of those component's shows all it's optional capabilities (the mandatory ones are, well, mandatory, so the tool won't let you choose between those):

<composition name="defaultName">
    <model type="composite" subtype="arm" path="models/composite/arm/arm.xml">
        <topic name="multi_joint_states"/>
        <topic name="multi_joint_trajectory"/>
        <topic name="multi_joint_trajectory_goal"/>
        <topic name="rc"/>
        <topic name="reconfiguration"/>
        <param name="rc_max_velocity"/>
        <param name="rc_max_yaw"/>
    </model>
    <model type="sensor" subtype="camera" path="models/sensor/camera/camera.xml">
        <topic name="audio_raw"/>
        <topic name="compressed"/>
        <topic name="image_camera_info"/>
        <topic name="image_color"/>
        <topic name="image_mono"/>
        <topic name="image_rect"/>
        <topic name="image_rect_color"/>
        <topic name="ptz"/>
        <topic name="reconfiguration"/>
        <topic name="set_camera_info"/>
        <param name="auto_binning"/>
        <param name="auto_brightness"/>
        <param name="auto_contrast"/>
        <param name="auto_exposure"/>
        <param name="auto_focus"/>
        <param name="auto_gain"/>
        <param name="auto_gamma"/>
        <param name="auto_hue"/>
        <param name="auto_iris"/>
        <param name="auto_iso"/>
        <param name="auto_saturation"/>
        <param name="auto_sharpness"/>
        <param name="auto_shutter"/>
        <param name="auto_white_balance"/>
        <param name="auto_zoom"/>
        <param name="binning_x"/>
        <param name="binning_y"/>
        <param name="brightness"/>
        <param name="contrast"/>
        <param name="exposure"/>
        <param name="focus"/>
        <param name="frecuency_rate"/>
        <param name="gain"/>
        <param name="gain_blue"/>
        <param name="gain_green"/>
        <param name="gain_red"/>
        <param name="gamma"/>
        <param name="hue"/>
        <param name="iris"/>
        <param name="iso"/>
        <param name="pan_angle_end"/>
        <param name="pan_angle_start"/>
        <param name="pan_speed"/>
        <param name="password"/>
        <param name="saturation"/>
        <param name="sharpness "/>
        <param name="shutter"/>
        <param name="tild_angle_end"/>
        <param name="tild_angle_start"/>
        <param name="tild_speed"/>
        <param name="username"/>
        <param name="white_balance_blue"/>
        <param name="white_balance_red"/>
    </model>
</composition>

Moving forward, now is when you remove the optional capabilities your component doesn't support. You might be left with something like:

<composition name="myOwnModule">
  <model type="composite" subtype="arm" path="models/composite/arm/arm.xml">
    <topic name="rc"/>
  </model>
  <model type="sensor" subtype="camera" path="models/sensor/camera/camera.xml">
    <topic name="image_color"/>
    <topic name="image_rect_color"/>
    <param name="auto_binning">
    <param name="binning_x">
    <param name="binning_y">
  </model>
</composition>

After saving the changes you'd now "compile" the model of your composed component. That is to say, the tool will parse the composition XML and each of the module models (indicated by the path attribute), and generate the necessary packages containing the files needed to communicate with your component (now module!). These packages and files will come from the components' mandatory topics and parameters and the indicated optional ones.

hrim compile model.xml

You can find the generated files under the composition folder, in a directory with the composition name you indicated on the passed composition XML (myOwnModule in the example).

While positioned at the repository's root all of the following are valid command executions:

  • hrim generate $(pwd)/models/sensor/torque/torque.xml
  • hrim generate ./models/sensor/torque/torque.xml
  • hrim -p ros2 generate /models/sensor/torque/torque.xml
  • hrim generate models/sensor/torque/torque.xml
  • hrim generate --platform ros2 all
  • hrim generate all
  • hrim generate sensors
  • hrim list models
  • hrim list implementations
  • hrim clear all
  • hrim clear sensor
  • hrim clear sensor/imu
  • hrim compose composite/arm sensor/imu actuator/gripper/gripper sensor/3dcamera/3dcamera_stereo
  • hrim compile model.xml
  • hrim compile validComposition.xml