OSCAR API Documentation

This API documentation provides a detailed description of all the components that make up the OSCAR robot interface for the e-MDB Cognitive Architecture. OSCAR is a robot simulated in Gazebo that enables robotic manipulation and sensory perception for cognitive learning and exploration.

OSCAR Server

Python script which implements the interface between the OSCAR robot and the e-MDB Cognitive Architecture. It provides high-level manipulation capabilities like grasping or placing objects. This module also manages the environment state, perceptions, and reward functions, enabling robots to interact with objects in a simulated environment.

class oscar_emdb.oscar_emdb_server.OscarMDB(*args: Any, **kwargs: Any)

Bases: Node

This class provides a node that interfaces the OSCAR robot with the eMDB Cognitive Architecture

approximated_object_reward()

Checks if the object was brought closer to the robot with the button. Returns a reward with value of 0.25, otherwise returns 0.

Returns:

Reward value based on whether the object was approximated.

Return type:

float

ball_in_box_reward()

Checks if the object is in the basket. Returns a reward with value of 1.0, otherwise returns 0.0

Returns:

Reward value based on the position of the object relative to the basket.

Return type:

float

async bring_object_near()

This method randomly moves the object so that it is within the reach of the robot and not inside the basket.

static cartesian_to_polar(point: geometry_msgs.msg.Point)

Helper method that transforms a point (referenced to the base of the robot) to a polar representation.

Parameters:

point (geometry_msgs.msg.Point) – Point to be transformed

Returns:

Tuple with the distance and angle values.

Return type:

tuple

async change_hands_policy()

This policy makes OSCAR exchange the object from one arm to the other.

async grasp_left_policy()

This policy grasps the object with the left arm if it is within reach.

async grasp_right_policy()

This policy grasps the object with the right arm if it is within reach.

grasped_object_reward()

Checks if the object was grasped. Returns a reward with value of 0.5, otherwise returns 0.

Returns:

Reward value based on whether the object was grasped.

Return type:

float

async init_oscar()

Moves OSCAR to home position with the grippers open.

load_configuration()

Load configuration from a file.

load_experiment_file_in_commander()

Load the configuration file in the commander node.

Returns:

Response from the commander node indicating the success of the loading.

Return type:

core_interfaces.srv.LoadConfig.Response

async new_command_callback(data)

Process a command received

Parameters:

data (ROS msg defined in the config file. Typically cognitive_processes_interfaces.msg.ControlMsg) – The message that contais the command received.

async place_object_left_policy()

This policy makes OSCAR place the object in the box, given that it has the object in the left arm and the basket is within reach.

async place_object_right_policy()

This policy makes OSCAR place the object in the box, given that it has the object in the right arm and the basket is within reach.

async policy_callback(data)

Generic method that executes a policy according to the data published in a topic.

Parameters:

data (ROS msg defined in the config file.) – Message with the name of the policy to be executed.

async policy_service(request, response)

Generic method that executes a policy according to a service request.

Parameters:

• request (cognitive_node_interfaces.srv.Policy.Request) – Message with the name of the policy to be executed.

• response (cognitive_node_interfaces.srv.Policy.Response) – Message with execution success information.

Returns:

Message with execution success information.

Return type:

cognitive_node_interfaces.srv.Policy.Response

async press_button_policy()

This policy makes OSCAR press the button on the left. If the object is out of reach it is moved closer to the robot.

publish_perception_reward()

Method that publishes the current perceptions and the reward values.

publish_perceptions(perceptions)

This method iterates the list of publishers and publishes the corresponding value from the perception input.

Parameters:

perceptions (dict) – Dictionary with perceptions.

publish_perceptions_callback(msg: oscar_emdb_interfaces.msg.PerceptionMultiObj)

Method that publishes the current perceptions and the reward value in the appropriate topics.

Parameters:

msg (cognitive_processes_interfaces.msg.Perception) – Perception message with the latest perceptions.

publish_reward()

Publishes the reward value.

async random_positions()

This method randomly places the basket and the object so that they are not coliding.

async reset_world()

This method initializes the world. Moves the robot to home position and randomizes the position of the objects.

reward_ball_in_box_goal()

Updates the ball_in_box_goal sensor with the reward value. If the object is in the basket, the reward is 1.0, otherwise 0.0

setup_control_channel(simulation)

Configure the ROS topic/service where listen for commands to be executed.

Parameters:

simulation (dict) – The params from the config file to setup the control channel.

setup_perceptions(perceptions)

This method creates publishers for each element of the perception list passed.

Parameters:

perceptions (list) – List of perceptions.

async switched_hands_reward()

Checks if the object was switched to the correct arm when the original arm can’t reach the basket. Returns a reward with value of 0.75, otherwise returns 0.

Returns:

Reward value based on whether the object was switched to the correct arm.

Return type:

float

async update_perceptions()

This method requests the latest perceptions from the sensory system.

Returns:

None if the maximum number of trials is reached.

Return type:

None

update_reward_sensor()

Update goal sensors’ values.

async world_reset_service_callback(request, response)

Callback for the world reset service.

Parameters:

• request (ROS msg defined in the config file Typically cognitive_processes_interfaces.srv.WorldReset.Request) – The message that contains the request to reset the world.

• response (ROS msg defined in the config file. Typically cognitive_processes_interfaces.srv.WorldReset.Response) – Response of the world reset service.

Returns:

Response indicating the success of the world reset.

Return type:

ROS msg defined in the config file. Typically cognitive_processes_interfaces.srv.WorldReset.Response

class oscar_emdb.oscar_emdb_server.OscarMDB_LLM(*args: Any, **kwargs: Any)

Bases: OscarMDB

Child class of OscarMDB that implements the LLM alignment experiment.

publish_perceptions_callback(msg: oscar_emdb_interfaces.msg.PerceptionMultiObj)

Method that publishes the current perceptions and the reward value in the appropriate topics.

Parameters:

msg (cognitive_processes_interfaces.msg.Perception) – Perception message with the latest perceptions.

OSCAR Perception

Python script which implements the perception system for the OSCAR robot. It processes raw sensory data from cameras and grippers in the Gazebo simulation, transforming them into high-level representations. This module handles visual object recognition, position calculation, and tactile feedback processing, enabling robots to perceive and understand their environment.