robotics_api.utils package

Submodules

robotics_api.utils.base_utils module

robotics_api.utils.base_utils.get_testing_mass(init_mass, added_volume, soln_density=786, adding=True)[source]
robotics_api.utils.base_utils.is_mass_unit(unit)[source]
robotics_api.utils.base_utils.rdkit_smiles(smiles)[source]
robotics_api.utils.base_utils.send_arduino_cmd(station: str, command: str, address: str = 'COM4', return_txt: bool = False)[source]

Sends a command to the Arduino controlling a specific station.

Parameters:

  • station (str) – The station identifier (e.g., “E1”, “P1”).

  • command (str or float) – The command to send (e.g., “0”, “1”, “500”).

  • address (str) – Address of the Arduino port (default is ARDUINO_PORT).

  • return_txt (bool) – Whether to return the Arduino response text (default is False).

Returns:

True if the command succeeded, the response text if return_txt is True, otherwise False on failure.

Return type:

bool or str

Raises:

Exception – If unable to connect to the Arduino.

robotics_api.utils.base_utils.sig_figs(number: float, num_sig_figs=5)[source]

Round a number to the specified number of significant figures.

Parameters:

  • number (float) – The number to round.

  • num_sig_figs (int) – The number of significant figures to retain.

Returns:

The number rounded to the given significant figures.

Return type:

float

robotics_api.utils.base_utils.unit_conversion(measurement, default_unit: str, density=None, return_dict=False)[source]

Convert a measurement into a default unit using pint.

Parameters:

  • measurement – Measurements can be pint object, int or float(in which case it will be assumed to already be in the default unit), string of magnitude and unit, or a measurement dictionary (EX: {“value”: 0.5, “unit”: “eV”}

  • default_unit – default unit / unit to be converted to

  • return_dict

  • density – molecular density (in case needed for conversion)

Returns:

float magnitude for the converted measurement

robotics_api.utils.base_utils.write_test(file_path, test_type='')[source]

Writes test data to a file based on the test type.

Parameters:

  • file_path (str) – Path to the output file.

  • test_type (str) – Type of test data to write. Options are “cv”, “ca”, or “ircomp”.

robotics_api.utils.kinova_gripper module

class robotics_api.utils.kinova_gripper.GripperMove(router, router_real_time, proportional_gain=2.0, verbose=0)[source]

Bases: object

__init__(router, router_real_time, proportional_gain=2.0, verbose=0)[source]

GripperMove class constructor.

Inputs:

kortex_api.RouterClient router: TCP router kortex_api.RouterClient router_real_time: Real-time UDP router float proportional_gain: Proportional gain used in control loop (default value is 2.0)

Outputs:

None

Notes

  • Actuators and gripper initial position are retrieved to set initial positions

  • Actuator and gripper cyclic command objects are created in constructor. Their references are used to update position and speed.

cleanup()[source]

Restore arm’s servoing mode to the one that was effective before running the example.

gripper_move(target_position)[source]

Position gripper to a requested target position using a simple proportional feedback loop which changes speed according to error between target position and current gripper position

Inputs:

float target_position: position (0% - 100%) to send gripper to.

Outputs:

Returns True if gripper was positioned successfully, returns False otherwise.

Notes

  • This function blocks until position is reached.

  • If target position exceeds 100.0, its value is changed to 100.0.

  • If target position is below 0.0, its value is set to 0.0.

robotics_api.utils.kinova_move module

robotics_api.utils.kinova_move.check_for_end_or_abort(e)[source]

Return a closure checking for END or ABORT notifications

Parameters:

e – event to signal when the action is completed (will be set when an END or ABORT occurs)

robotics_api.utils.kinova_move.get_current_zone(zone_dividers=[30, 180, 328])[source]

Moves a given joint a specified range (in degrees).

Parameters:

zone_dividers (list) – A list of zone divider angles in ascending order.

Returns:

The zone index (starting from 1) that the angle belongs to.

Return type:

int

robotics_api.utils.kinova_move.get_place_vial(station, action_type='get', go=True, leave=True, release_vial=True, raise_error=True, pre_position_only=False, move_to_zone=True)[source]

Executes an action to get or place a vial using snapshot movements.

Parameters:

  • station (StationStatus)

  • action_type (str) – Action type, either ‘get’ (to retrieve the vial) or ‘place’ (to place the vial).

  • go (bool) – Whether to move to the snapshot file location (default is True).

  • leave (bool) – Whether to leave the snapshot file location after the action (default is True).

  • release_vial (bool) – Whether to release the vial after placing (default is True).

  • raise_error (bool) – Whether to raise an error if movement fails (default is True).

  • pre_position_only (bool) – Only move to “above” position if True (default is True).

  • move_to_zone (bool)

Returns:

True if the action was successful, False otherwise.

Return type:

bool

Raises:

Exception – If the movement fails and raise_error is True.

robotics_api.utils.kinova_move.get_zone(angle, zone_dividers=[30, 180, 328])[source]

Moves a given joint a specified range (in degrees).

Parameters:

  • angle (float) – The angle in degrees.

  • zone_dividers (list) – A list of zone divider angles in ascending order.

Returns:

The zone index (starting from 1) that the angle belongs to.

Return type:

int

robotics_api.utils.kinova_move.move_gripper(target_position=None, max_gripper_attempts=5)[source]

Move gripper :param target_position: target position for the gripper: open, closed, or percentage closed (e.g., 90) :return: bool, True if action a success

robotics_api.utils.kinova_move.move_hand(linear_x: float = 0, linear_y: float = 0, linear_z: float = 0, angular_x: float = 0, angular_y: float = 0, angular_z: float = 0)[source]

Function to move the robotic hand by linear and angular x, y, and z

Parameters:

  • linear_x (float) – increment of linear x movement

  • linear_y (float) – increment of linear y movement

  • linear_z (float) – increment of linear z movement

  • angular_x (float) – increment of angular x movement

  • angular_y (float) – increment of angular y movement

  • angular_z (float) – increment of angular z movement

Returns: boolean indicating success of action

robotics_api.utils.kinova_move.perturb_angular(reverse=False, wait_time=None, **joint_deltas)[source]

Moves a given joint a specified range (in degrees).

Parameters:

  • reverse – Reverse all joint deltas if True

  • wait_time – Wait time after move

  • joint_deltas – Key word arguments

Returns:

True if the movement completed successfully, False otherwise.

Return type:

bool

robotics_api.utils.kinova_move.perturbed_snapshot(snapshot_file, perturb_amount: float = 0.07, axis='z')[source]

Creates a perturbed snapshot by modifying the specified axis position in the given snapshot file.

Parameters:

  • snapshot_file (str) – Path to the snapshot JSON file.

  • perturb_amount (float) – Amount to perturb the position along the specified axis (default is PERTURB_AMOUNT).

  • axis (str) – Axis to apply the perturbation to, defaults to “z”.

Returns:

Path to the new perturbed snapshot file.

Return type:

str

robotics_api.utils.kinova_move.screw_lid(screw=True, starting_position='vial-screw_test.json', linear_z=3e-05, angular_z=120)[source]

Screws or unscrews the vial lid by controlling the robot arm’s movement.

Parameters:

  • screw (bool) – True to screw the lid on, False to unscrew it (default is True).

  • starting_position (str) – Path to the starting snapshot position file.

  • linear_z (float) – Amount of linear movement along the z-axis per iteration (default is 0.00003).

  • angular_z (float) – Amount of rotational movement along the z-axis in degrees (default is 120).

Returns:

True if the action was successful, False otherwise.

Return type:

bool

robotics_api.utils.kinova_move.snapshot_move(snapshot_file: str | None = None, target_position: str | None = None, raise_error: bool = True, angle_error: float = 0.2, position_error: float = 0.1)[source]
Parameters:

  • snapshot_file – str, path to snapshot file (JSON)

  • target_position – target position for the gripper: open, closed, or percentage closed (e.g., 90)

  • raise_error

  • angle_error

  • position_error

  • angle_error

  • position_error

Returns:

bool, True if movement was a success

robotics_api.utils.kinova_move.snapshot_move_angular(base: BaseClient, joint_angle_values)[source]
robotics_api.utils.kinova_move.snapshot_move_cartesian(base: BaseClient, coordinate_values: dict)[source]
robotics_api.utils.kinova_move.snapshot_zone(snapshot_file, zone_dividers=[30, 180, 328])[source]

Moves a given joint a specified range (in degrees).

Parameters:

  • snapshot_file (str) – A list of zone divider angles in ascending order.

  • zone_dividers (list) – A list of zone divider angles in ascending order.

Returns:

The zone index (starting from 1) that the angle belongs to.

Return type:

int

robotics_api.utils.kinova_utils module

class robotics_api.utils.kinova_utils.DeviceConnection(ipAddress, port=10000, credentials=('', ''))[source]

Bases: object

TCP_PORT = 10000
UDP_PORT = 10001
__init__(ipAddress, port=10000, credentials=('', ''))[source]
static createTcpConnection(args)[source]

returns RouterClient required to create services and send requests to device or sub-devices,

static createUdpConnection(args)[source]

returns RouterClient that allows to create services and send requests to a device or its sub-devices @ 1khz.

robotics_api.utils.kinova_utils.parseConnectionArguments(parser=ArgumentParser(prog='sphinx-build', usage=None, description=None, formatter_class=<class 'argparse.HelpFormatter'>, conflict_handler='error', add_help=True))[source]

robotics_api.utils.mongo_dbs module

class robotics_api.utils.mongo_dbs.DBconnector(db_information: dict)[source]

Bases: object

Class to retrieve a collection from a database and insert new entry. Requires a db_infos.json file with credentials Copyright 2021, University of Kentucky

__init__(db_information: dict)[source]

Initializes the DBconnector object with database information.

Parameters:

db_information (dict) – Dictionary containing database information.

get_collection(coll_name=None)[source]

Returns a collection from the database.

Parameters:

coll_name (str, optional) – Name of the collection. Defaults to None.

Returns:

The collection object.

Return type:

pymongo.collection.Collection

get_database(**kwargs)[source]

Returns a database object.

Returns:

A database object.

Return type:

pymongo.database.Database

class robotics_api.utils.mongo_dbs.MongoDatabase(database=None, collection_name=None, instance=None, schema_layer='', schema_directory=None, public=None, schema_db=None, default_id=None, validate_schema=True, verbose=1, schema_version=None)[source]

Bases: object

Base class for connecting to a database Copyright 2021, University of Kentucky

__init__(database=None, collection_name=None, instance=None, schema_layer='', schema_directory=None, public=None, schema_db=None, default_id=None, validate_schema=True, verbose=1, schema_version=None)[source]

Initializes the MongoDatabase object.

Parameters:

  • database (str, optional) – Name of the database. Defaults to None.

  • collection_name (str, optional) – Name of the collection. Defaults to None.

  • instance (dict, optional) – Instance to insert or validate. Defaults to None.

  • schema_layer (str, optional) – Schema layer. Defaults to “”.

  • schema_directory (str, optional) – Directory of the schema. Defaults to None.

  • public (bool, optional) – Marks instance as public if True. Defaults to None.

  • schema_db (str, optional) – Database containing the schema. Defaults to None.

  • default_id (str, optional) – Default instance ID. Defaults to None.

  • validate_schema (bool, optional) – Validates schema if True. Defaults to True.

  • verbose (int, optional) – Verbosity level. Defaults to 1.

  • schema_version (str, optional) – Version of the schema. Defaults to None.

array_checker(field_path, _id)[source]

Checks if the field at the path is an array and prepares for set insertion.

Parameters:

  • field_path (str) – Path to check.

  • _id (str) – Instance ID.

static dot2dict(dot_dict)[source]

Converts dot notation keys to nested dictionary.

Parameters:

dot_not (dict) – Dictionary with dot notation keys.

Returns:

Nested dictionary.

Return type:

dict

field_checker(entry, field)[source]

Checks if a field exists in the collection and returns the result.

Parameters:

  • entry – Value to check.

  • field (str) – Name of the field.

Returns:

True if the field exists, False otherwise.

Return type:

bool

insert(_id, nested=False, update_public=True, instance=None, override_lists=True)[source]

Upserts a dictionary into a MongoDB collection.

Parameters:

  • _id (str) – ID for insertion.

  • nested (bool, optional) – Inserts nested attributes if True. Defaults to False.

  • update_public (bool, optional) – Updates the public status if True. Defaults to True.

  • instance (dict, optional) – Instance to be inserted. Defaults to None.

  • override_lists (bool, optional) – Overrides existing lists in insertion if True. Defaults to True.

make_query(query: dict | None = None, projection: dict | None = None, output='pandas', multi=True, limit=200)[source]

Executes a MongoDB database query.

Parameters:

  • query (dict, optional) – Query parameters. Defaults to an empty dictionary.

  • projection (dict, optional) – Fields to include or exclude. Defaults to an empty dictionary.

  • output (str, optional) – Output type, can be “pandas”, “json”, or list. Defaults to “pandas”.

  • multi (bool, optional) – If True, returns multiple query responses. If False, returns a single result. Defaults to True.

  • limit (int, optional) – Maximum number of responses to return. Defaults to 200.

Returns:

  1. A dataframe if output=”pandas”

  2. A list if multi=False and a pymongo dursor if multi=True; output != “pandas

path_insert(_id, path, value)[source]

Inserts a value at a specific path in the collection.

Parameters:

  • _id (str) – Instance ID.

  • path (str) – Path for insertion.

  • value – Value to insert.

class robotics_api.utils.mongo_dbs.RobotStatusDB(apparatus_type: str, _id: str | None = None, instance: dict | None = None, override_lists: bool = True, wflow_name: str | None = None, validate_schema=False)[source]

Bases: MongoDatabase

Provides access to the Robot Status database.

This class is used to interact with the status database for a specific type of apparatus. Copyright 2021, University of Kentucky.

__init__(apparatus_type: str, _id: str | None = None, instance: dict | None = None, override_lists: bool = True, wflow_name: str | None = None, validate_schema=False)[source]

Initializes the RobotStatusDB class.

Parameters:

  • apparatus_type (str) – Name of the apparatus.

  • _id (str, optional) – Unique identifier for the status entry. Defaults to None.

  • instance (dict, optional) – Instance to insert or validate in the database. Defaults to None.

  • override_lists (bool, optional) – Whether to override existing lists in the database. Defaults to True.

  • wflow_name (str, optional) – Name of the active workflow. If set, verifies that the instance has the appropriate workflow name. Defaults to None.

  • validate_schema (bool, optional) – If True, validates the instance against the schema. Defaults to False.

Raises:

IOError – If no ID is provided for the status database insertion.

check_wflow_name()[source]

Checks if the workflow name matches the instance’s current workflow name.

Raises:

NameError – If the workflow name does not match the current instance’s workflow name.

property exists

Checks if an entry with the given ID exists in the database.

Returns:

True if the entry exists, False otherwise.

Return type:

bool

get_prop(prop: str)[source]

Retrieves a property from the database for the instance with the given ID.

Parameters:

prop (str) – Name of the property to retrieve.

Returns:

The value of the property, or None if the property does not exist.

Return type:

Any

update_status(new_status: str, status_name: str = 'location')[source]

Updates the status for a vial location or station vial.

Parameters:

  • new_status (str or float) – New status, such as the new vial location or new vial in the station.

  • status_name (str, optional) – Name of the status property. Defaults to “location”.

class robotics_api.utils.mongo_dbs.Schema2Class(database=None, schema_name=None, schema_directory=None, named_only=False, schema_version=None)[source]

Bases: object

Get D3TaLES schema from GitHub and load it to a class Copyright 2021, University of Kentucky

__init__(database=None, schema_name=None, schema_directory=None, named_only=False, schema_version=None)[source]

Initializes the Schema2Class object and retrieves the schema.

Parameters:

  • database (str, optional) – Database name. Defaults to None.

  • schema_name (str, optional) – Schema name. Defaults to None.

  • schema_directory (str, optional) – Directory of the schema. Defaults to None.

  • named_only (bool, optional) – If True, only properties with a title attribute will be included in the resulting namespace. Defaults to False.

  • schema_version (str, optional) – Schema version. Defaults to None.

robotics_api.utils.mongo_dbs.db_info_generator(db_file=WindowsPath('C:/Users/Lab/D3talesRobotics/roboticsUI/db_infos.json'))[source]

Generates information about database connections.

This function requires either a db_file argument or a DB_INFO_FILE environment variable. The argument or environment variable should be a path to a JSON file containing connection information for the databases. The keys should be the database names such as frontend, backend, expflow, and fireworks.

Parameters:

db_file (str, optional) – Path to the database info JSON file. Defaults to None.

Returns:

JSON object containing information about database connections.

Return type:

dict

robotics_api.utils.processing_utils module

Module contents