HRIM component model

As in mentioned in general structure section, HRIM is composed by of all the components that are standardized. Each one is represented by its own HRIM component model, for example: HRIM RotaryServo model, HRIM Camera model and so on.

This section explains in detail what each HRIM component model is composed, in order to complement the general structure section and make more understable each standadized module.

Each HRIM component model will be summarized through the following template, which is divided in two main categories: the first category includes the topics, services, actions and the second, the parameters, all of them labeled with mandatory (M) or optional (O). Furthermore, the color code used in the figure of the general structure section has been respected.

HRIM component model: <DeviceName>
NAME XML MODEL ABSTRACTION CLASS (M/O) SHORT DESCRIPTION
id generic/id.xml topic (Pub) M Component identification.
power generic/power.xml topic (Pub) M Describes the power supply type and give the information about the module power consumption.
status generic/status.xml topic (Pub) M How the module is working.
specs_comm generic/specs_comm.xml topic (Pub) M Describes the communication aspects of the component.
state_comm generic/state_comm.xml topic (Pub) M Published the resources that the component is using at the moment
module_3d generic/module_3d.xml topic (Pub) M Ask for the 3D model of the HRIM component.
module_urdf generic/module_urdf.xml topic (Pub) M Ask for the information of, 3D model of the HRIM component.
specs Specs<DeviceName>.xml topic (Pub) M Device features. <Each device described by the DeviceName has a customize message.>
<device_purpose> <DevicePurpose>.xml topic/service/action
(Pub/Sub)
M <Control the essence of the device.>
Minimum amount:1
<additional_capability> <AdditionalCapability>.xml topic/service/action
(Pub/Sub)
O <Additional characteristics that the device can contain related to the objective.>
Minimum amount: 0
<optional_hardware> <OptionalHardware>.xml topic/service/action
(Pub/Sub)
O <Extra characteristics given by integrated hardware that by itself has no relation with the principle device.>
Minimum amount: 0
Parameters
PARAMETER NAME DATA TYPE UNIT CLASS (M/O) SHORT DESCRIPTION
<parameter_name> <data_type> <unit> M/O <description>

where:

HRIM component model: <DeviceName>
<topic_name>
<service_name>
<action_name>
<FileName>.<platform_extension> topic/service/action
(Published (Pub) / Subscribed (Sub))
Mandatory (M) / Optional (O) <description>
Parameters
<parameter_name> <data_type> <unit> Mandatory (M) / Optional (O) <description>

The ABSTRACTION table column above represents one of the communication patterns HRIM contemplates:

  • topic: a publisher-subscriber messaging pattern (indicating which one it'd fulfill, Pub indicating the component publishes this information and Sub indicating the component subscribes for that information).
  • service: a client-server messaging pattern where the module acts as the server that returns a response.
  • action: a client-server messaging pattern where the module acts as the server that returns a response, which also provides status information during the process and enables the cancelation of the goal.

Note: the {HEADER} wildcard references a property containing the time at which each message was sent and the frame_id from which it was sent. It's definition can be found here:

<property name="header" type="header" fileName="Header">
  <property name="time" type="time" fileName="Time">
    <property name="sec" type="int32" unit="second">
      <value></value>
    </property>
    <property name="nanosec" type="uint32" unit="nanosecond">
      <value></value>
    </property>
  </property>
  <property name="frame_id" type="string" description="transform frame with which this data is associated">
    <value></value>
  </property>
</property>

The first seven topics listed in the HRIM component model, are the common topics that use generic messages. The next items discuss the general concept of the common topics with the proposed messages:

generic/id.xml is the identification of each module. It is designed to inform the user and also the system about the component itself. The /id topic should be programmed to be released only when the user requires it.

<topic name="id" type="publish" fileName="ID">
  {HEADER}
  <property name="device_kind_id" type="uint8" unit="enum" enum='{"HRIM_COMM": 0, "HRIM_SENSOR": 1, "HRIM_ACTUATOR": 2, "HRIM_COGNITION": 3, "HRIM_UI": 4, "HRIM_POWER": 5, "HRIM_COMPOSITE": 6}' description="device classification">
    <value></value>
  </property>
  <property name="device_name" type="string" description="sub-type">
    <value></value>
  </property>
  <property name="vendor_id" type="uint32" description="vendor identifier">
    <value></value>
  </property>
  <property name="product_id" type="uint32" description="part number">
    <value></value>
  </property>
  <property name="instance_id" type="uint32" description="module unique identifier">
    <value></value>
  </property>
  <property name="hrim_version" type="string" description="used hrim version">
    <value></value>
  </property>
  <property name="hros_version" type="string" description="used h-ros version">
    <value></value>
  </property>
</topic>

generic/power.xml is the power information of each module. The /power topic provides continuous information regarding the power consumption and requirements of each module, allowing the easy construction of modular robots. Link to file

<topic name="power" type="publish" fileName="Power">
  {HEADER}
  <property name="voltage" type="float32" unit="volt">
    <value></value>
  </property>
  <property name="current_consumption" type="float32" unit="ampere">
    <value></value>
  </property>
  <property name="current_surplus" type="float32" unit="ampere" description="current injection for the whole system">
    <value></value>
  </property>
  <property name="power_consumption" type="float32" unit="watt">
    <value></value>
  </property>
  <property name="power_surplus" type="float32" unit="watt" description="power injection for the whole system">
    <value></value>
  </property>
</topic>

generic/status.xml is designed to inform about the resources that are being used by each component. Similar to the /power topic, it should be programmed to publish continuously in order to simplify the robot building process. Link to file

<topic name="status" type="publish" fileName="Status">
  {HEADER}
  <property name="instance_id" type="uint32">
    <value></value>
  </property>
  <property name="system_cpu" type="float32" unit="percentage" description="total cpu utilization">
    <value></value>
  </property>
  <property name="core_temperature" type="float32" unit="celsius" description="cpu temperature">
    <value></value>
  </property>
  <property name="system_ram_total" type="uint32" unit="megabyte" description="total ram">
    <value></value>
  </property>
  <property name="system_ram_used" type="uint32" unit="megabyte" description="used ram">
    <value></value>
  </property>
  <property name="system_ram_free" type="uint32" unit="megabyte" description="free ram">
    <value></value>
  </property>
  <property name="system_io_in" type="float32" unit="kilobytes per second" description="disk input speed">
    <value></value>
  </property>
  <property name="system_io_out" type="float32" unit="kilobytes per second" description="disk output speed">
    <value></value>
  </property>
  <property name="system_ipv4_ip" type="string[]" unit="ip" description="ipv4 address">
    <value></value>
  </property>
  <property name="system_ipv4_received" type="float32" unit="kilobytes per second" description="ipv4 received bandwidth">
    <value></value>
  </property>
  <property name="system_ipv4_sent" type="float32" unit="kilobytes per second" description="ipv4 sent bandwidth">
    <value></value>
  </property>
  <property name="ipv4_tcpsock" type="uint16" description="number of tcp active connections">
    <value></value>
  </property>
  <property name="ipv4_tcppackets_received" type="float32" description="number of tcp received packages">
    <value></value>
  </property>
  <property name="ipv4_tcppackets_sent" type="float32" description="number of tcp sent packages">
    <value></value>
  </property>
  <property name="ipv4_tcp_errors" type="float32" description="number of tcp error packages">
    <value></value>
  </property>
  <property name="ipv4_udppackets_received" type="float32" description="number of udp received packages">
    <value></value>
  </property>
  <property name="ipv4_udppackets_sent" type="float32" description="number of udp sent packages">
    <value></value>
  </property>
  <property name="ipv4_udp_errors" type="float32" description="number of udp error packages">
    <value></value>
  </property>
  <property name="cpu_interrupts" type="float32">
    <value></value>
  </property>
  <property name="cpu_context_switches" type="float32">
    <value></value>
  </property>
  <property name="softnet_processed" type="uint32">
    <value></value>
  </property>
  <property name="softnet_dropped" type="uint32">
    <value></value>
  </property>
  <property name="softnet_squeezed" type="uint32">
    <value></value>
  </property>
  <property name="softnet_received_rps" type="uint32">
    <value></value>
  </property>
  <property name="softnet_flow_limit_count" type="uint32">
    <value></value>
  </property>
  <property name="softirqs_hi" type="uint64">
    <value></value>
  </property>
  <property name="softirqs_timer" type="uint64">
    <value></value>
  </property>
  <property name="softirqs_net_tx" type="uint64">
    <value></value>
  </property>
  <property name="softirqs_net_rx" type="uint64">
    <value></value>
  </property>
  <property name="softirqs_block" type="uint64">
    <value></value>
  </property>
  <property name="softirqs_irq_poll" type="uint64">
    <value></value>
  </property>
  <property name="softirqs_tasklet" type="uint64">
    <value></value>
  </property>
  <property name="softirqs_sched" type="uint64">
    <value></value>
  </property>
  <property name="softirqs_hrtimer" type="uint64">
    <value></value>
  </property>
  <property name="softirqs_rcu" type="uint64">
    <value></value>
  </property>
  <property name="load1" type="float32">
    <value></value>
  </property>
  <property name="load5" type="float32">
    <value></value>
  </property>
  <property name="load15" type="float32">
    <value></value>
</property>
</topic>

generic/specs_comm.xml and generic/state_comm.xml define a way for the user to obtain information about the communication aspects of each component.

generic/specs_comm.xml informs on the capabilities in terms of communicaction that the component offers. Link to file

<topic name="specs_comm" type="publish" fileName="SpecsCommunication">
  {HEADER}
  <property name="min_comm_rate" type="double" unit="hertz" description="minimum frequency at which the component can work">
    <value></value>
  </property>
  <property name="max_comm_rate" type="double" unit="hertz" description="maximum frequency at which the component can work">
    <value></value>
  </property>
  <property name="max_size_msgs" type="double" unit="megabit" description="maximum amount of megabits the component will send">
    <value></value>
  </property>
</topic>

generic/state_comm.xml informs on the resources that the component is using at the moment.

<topic name="state_comm" type="publish" fileName="StateCommunication">
  {HEADER}
  <property name="comm_rate" type="double" unit="hertz" description="frequency at which the component is working">
    <value></value>
  </property>
  <property name="size_msgs" type="double" unit="megabit" description="amount of megabits the component is sending">
    <value></value>
  </property>
</topic>

generic/module_3d.xml and generic/module_urdf.xml define a way for the user to obtain the 3D model and a URDF fragment of each module in order to build a virtual robot which then can be easily used in simulation frameworks, such as Gazebo or MoveIt. The simulation topics should not start publishing until they detect a user interface or a simulation framework connected to the system.

<topic name="module_3d" type="publish" fileName="Simulation3D">
  {HEADER}
  <property name="3d_model" type="byte[]" unit="stl" description=".stl of the component">
    <value></value>
  </property>
</topic>
<topic name="module_urdf" type="publish" fileName="SimulationURDF">
  {HEADER}
  <property name="urdf_model" type="string" unit="urdf" description="the urdf corresponding to the component's .stl">
    <value></value>
  </property>
</topic>

The rest of the HRIM component model abstractions, such as specs or device purpose, are specifically designed and customized for each component. To give a better understanding of these concepts, a practical example is given by one of the most used module: HRIM rotary servomotor model.

You can also enter directly into any of standardized component, however, unlike the example they are not detailed step by step.