H-ROS API

This section will introduce the H-ROS CLI utility:

This CLI will communicate with the API available in each of the H-ROS modules.

This CLI will allow to configure some basic aspects related to our H-ROS SoM, this documentations corespond to the H-ROS-cli-v.0.04 version. The supported actions are the next:

  • Get the actual information of the SoM (Version, hostname...)
  • Start/Stop the lifecycle that is running
  • Get and set the RMW_IMPLEMENTATION running
  • Get and set the ROS_DOMAIN_ID running
  • Modular Joints specific:
    • Set the actual position as zero

The CLI can be downloaded from the official github repository or via pip:

git clone https://github.com/AcutronicRobotics/H-ROS-cli
cd H-ROS-cli
pip3 install -r requirements.txt
python3 setup.py install

Via pip:

pip3 install hros

After installing the H-ROS CLI the hros command will be available, use hros -h to get all the available commands.

usage: hros [-h] {module,configure} ...

hros

positional arguments:
  {module,configure}  commands
    module            Get and Set module related data
    configure         Get and Set module specific configuration data

optional arguments:
  -h, --help          show this help message and exit

The module option will allow to get infortmation related to the SoM, also will allow to stop, start or reset the H-ROS SoM

usage: hros module [-h] {list,info,start,stop,reset} ...

positional arguments:
  {list,info,start,stop,reset}
                        commands
    list                Print a list of modules available
    info                Print information of selected module
    start               Start the build-in lifecycle service
    stop                Stop the build-in lifecycle service
    reset               Set default configuration for module

optional arguments:
  -h, --help            show this help message and exit

Returns information related with the H-ROS SoM

hros module info 192.168.1.61
{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": {
        "info": {
            "hostname": "hros-actuation-servomotor-70B3D521A00E",
            "type": "H-ROS SoM"
        }
    },
    "valid": true,
    "warnings": {}
}

Starts the lifecycle service available in the H-ROS SoM

hros module start 192.168.1.61
{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": "start",
    "valid": true,
    "warnings": {}
}

Stops the lifecycle service available in the H-ROS SoM

hros module stop 192.168.1.61
{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": "stop",
    "valid": true,
    "warnings": {}
}

The configure option will allow to configure the target H-ROS SoM, things like rmw_implementatio, ros_domain_id, module type of set motors zero (only in some compatible devices)

usage: hros configure [-h]
                      {rmw_implementation,ros_domain_id,type,zero,security}
                      ...

positional arguments:
  {rmw_implementation,ros_domain_id,type,zero,security}
                        commands
    rmw_implementation  Get or Set rmw_implementation
    ros_domain_id       Get or Set ros_domain_id
    type                Get or Set the type of module this SoM can act as
    zero                Set the actual servomotor position as zero
    security            Security related commands

optional arguments:
  -h, --help            show this help message and exit

The rmw_implementation sub-command will allow to get or set the rmw_implementation configuration in the H-ROS SoM.


hros configure rmw_implementation 192.168.1.61
{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": {
        "rmw_implementation": "rmw_opensplice_cpp"
    },
    "valid": true,
    "warnings": {
        "NOT_APPLIED": "The service have not been restarted after some value changed"
    }
}

Use the --set option to set a new value.

hros configure rmw_implementation 192.168.1.61 --set rmw_fastrtps_cpp
{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": {
        "rmw_implementation": "rmw_fastrtps_cpp"
    },
    "valid": true,
    "warnings": {
        "NOT_APPLIED": "The service have not been restarted after some value changed"
    }
}

This action requires to stop and start the lifecycle of a H-ROS SoM.

The ros_domain_id sub-command will allow to get or set the ros_domain_id configuration in the H-ROS SoM.

hros configure ros_domain_id 192.168.1.61
{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": {
        "ros_domain_id": 40
    },
    "valid": true,
    "warnings": {}
}

Use the --set option to set a new value.

hros configure ros_domain_id --set 41 192.168.1.61
{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": {
        "ros_domain_id": 41
    },
    "valid": true,
    "warnings": {
        "NOT_APPLIED": "The service have not been restarted after some value changed"
    }
}

This action requires to stop and start the lifecycle of a H-ROS SoM.

This option will allow to set the actual position of a servomotor to zero, this option is only available in devices that support to set relative zeros.

 hros configure zero 192.168.1.61 --set true
{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": {
        "set_zero": true
    },
    "valid": true,
    "warnings": {}
}

This option require to stop the lifecycle of the H-ROS SoM.

After executing a command an json output will be prompt, these are some examples of the types of output.

This is a valid request to stop a lifecycle

{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": "stop",
    "valid": true,
    "warnings": {}
}

This is a valid response of a request of a ros_domain_id

{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": {
        "ros_domain_id": 40
    },
    "valid": true,
    "warnings": {}
}

This means that the request was perform but the SoM now have some warnings, the most common warning is NO_CHANGES. Check the request state list section for more type of warnings

{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": {
        "ros_domain_id": 40
    },
    "valid": true,
    "warnings": {
        "NO_CHANGES": "The new value and actual value is the same"
    }
}
{
    "api": {
        "version": 0.04
    },
    "errors": {},
    "response": {
        "ros_domain_id": 41
    },
    "valid": true,
    "warnings": {
        "NOT_APPLIED": "The service have not been restarted after some value changed"
    }
}

Not valid request means that the request made is not valid and cannot be executed. Check request state list section for more type of warnings

{
    "api": {
        "version": 0.04
    },
    "errors": {
        "SOM_TYPE_ERROR": "The selected type does not exist in target H-ROS SoM"
    },
    "response": {
        "available": [
            "MARA_T5.4",
            "MARA_T49",
            "MARA_T30"
        ]
    },
    "valid": false,
    "warnings": {}
}

  • NOT_APPLIED: The service have not been restarted after some value changed
  • NOT_IMPLEMENTED: The requested call is not implemented yet
  • ERR_BADREQUEST: The call to the API is not well formed
  • RMW_BADIMPLEMENTATION: The selected implementation does not exist
  • SOM_TYPE_ERROR: The selected type does not exist in target H-ROS SoM
  • NO_CHANGES: The new value and actual value is the same
  • ERR_SERVICERNEEDSSTOP: You need stop service before