/robotraconteur_companion_python

Primary LanguagePythonApache License 2.0Apache-2.0

Robot Raconteur Companion Python

The Robot Raconteur companion library contains utilities for working with Robot Raconteur services and devices. This companion library is intended to be used with the Robot Raconteur Core library (https://github.com/robotraconteur/robotraconteur). This version of the companion library is for Python. Other language versions are available at https://github.com/robotraconteur.

Robot Raconteur Core focuses on the core capabilities of Robot Raconteur, such as transport, discovery, and communication. The companion contains a number of miscelanous utilities that are useful for working with other libraries such as numpy, and for working with standard Robot Raconteur service types (https://github.com/robotraconteur/robotraconteur_standard_robdef).

The companion library is not required to use Robot Raconteur, but is recommended for most users.

The companion is intended to evolve faster than the core library, and accept contributions from the community.

The companion library is licensed under the Apache 2.0 license.

The Robot Raconteur Companion library contains the following utilities:

  • Standard Service Definition (robdef) types
  • YAML parsers for device info structures
  • Service attribute utilities
  • Geometry type converters
  • Image type converters
  • Date/time converters
  • Identifier utilities
  • UUID utilities
  • Miscellaneous support utilities

Installation

The Robot Raconteur companion library is available on PyPI. It can be installed using pip:

pip install RobotRaconteurCompanion

Documentation

Documentation for the Robot Raconteur companion library is available at https://robot-raconteur-companion-python.readthedocs.io/en/latest/

Standard Service Types

The companion library contains the standard service types available at https://github.com/robotraconteur/robotraconteur_standard_robdef . These types can be registered with the local Node using the following code:

import RobotRaconteur as RR
RRN = RR.RobotRaconteurNode.s
import RobotRaconteurCompanion as RRC
RRC.RegisterStdRobDefServiceTypes(RRN)

Registering the standard service types is not required for clients since they will be pulled from the service.

Device Info Structure YAML Parsers and Attributes Util

Device Info structures are used to describe devices and their capabilities. The structures are provided to clients at runtime, typically through a property of a device service. For example, the com.robotraconteur.device.Device standard type defines the device_info property. The com.robotraconteur.robotics.robot.Robot standard type defines both device_info and robot_info properties. These structures can be used to describe a wide variety of devices, including robots, sensors, and other devices. YAML files are used to store the contents of these structures to make it easier to create and edit them. The Robot Raconteur companion library contains parsers for these YAML files. The following device info structure types are supported:

  • com.robotraconteur.actuator.ActuatorInfo
  • com.robotraconteur.clock.ClockDeviceInfo
  • com.robotraconteur.isoch.IsochDeviceInfo
  • com.robotraconteur.device.DeviceInfo
  • com.robotraconteur.eventlog.EventLogInfo
  • com.robotraconteur.fiducial.FiducialInfo
  • com.robotraconteur.fiducial.FiducialSensorInfo
  • com.robotraconteur.hid.joystick.JoystickInfo
  • com.robotraconteur.image.ImageInfo
  • com.robotraconteur.image.FreeformImageInfo
  • com.robotraconteur.imaging.camerainfo.PlumbBobDistortionInfo
  • com.robotraconteur.imaging.camerainfo.CameraInfo
  • com.robotraconteur.imaging.camerainfo.MultiCameraInfo
  • com.robotraconteur.laserscan.LaserScanInfo
  • com.robotraconteur.laserscan.LaserScanInfof
  • com.robotraconteur.laserscan.LaserScanSensorInfo
  • com.robotraconteur.lighting.LightInfo
  • com.robotraconteur.objectrecognition.ObjectRecognitionSensorInfo
  • com.robotraconteur.octree.OcTreeInfo
  • com.robotraconteur.param.ParameterInfo
  • com.robotraconteur.pointcloud.sensor.PointCloudSensorInfo
  • com.robotraconteur.resource.BucketInfo
  • com.robotraconteur.resource.ResourceInfo
  • com.robotraconteur.robotics.joint.JointInfo
  • com.robotraconteur.robotics.payload.PayloadInfo
  • com.robotraconteur.robotics.robot.RobotInfo
  • com.robotraconteur.robotics.robot.RobotKinChainInfo
  • com.robotraconteur.robotics.tool.ToolInfo
  • com.robotraconteur.sensor.SensorInfo
  • com.robotraconteur.sensordata.SensorDataSourceInfo
  • com.robotraconteur.servo.ServoInfo
  • com.robotraconteur.signal.SignalInfo
  • com.robotraconteur.signal.SignalGroupInfo

The attributes utility class can be used to generate the attributes for a registered service. These attributes are used by clients to locate a desired service.

Device info files can be parsed using the RobotRaconteurCompanion.Util.InfoFileLoader class. The following example parses a device info file and prints the device name:

import RobotRaconteur as RR
RRN = RR.RobotRaconteurNode.s
import RobotRaconteurCompanion as RRC
from RobotRaconteurCompanion.Util.InfoFileLoader import InfoFileLoader
from RobotRaconteurCompanion.Util.AttributesUtil import AttributesUtil

RRC.RegisterStdRobDefServiceTypes(RRN)
info_loader = InfoFileLoader(RRN)
camera_info, camera_ident_fd = info_loader.LoadInfoFileFromString(camera_info_text, "com.robotraconteur.imaging.camerainfo.CameraInfo", "camera")
attributes_util = AttributesUtil(RRN)
camera_attributes = attributes_util.GetDefaultServiceAttributesFromDeviceInfo(camera_info.device_info)

# Register a service and set attributes
service_ctx = RRN.RegisterService("camera","com.robotraconteur.imaging.Camera",camera)
service_ctx.SetServiceAttributes(camera_attributes)

Geometry Type Converters

The Robot Raconteur companion library contains type converters for geometry types defined in, com.robotraconteur.geometry, com.robotraconteur.geometryf, and com.robotraconteur.geometryi. These types can be converted to and from the corresponding Python types.

An example of converting a few types:

from RobotRaconteur.Client import *
from RobotRaconteur.Companion.Util import GeometryUtil

c = RRN.ConnectService('rr+tcp://localhost:22222?service=MyRobot')
geom_util = GeometryUtil(client_obj=c)

# Create GeometryUtil using the connected object

# Get a position vector
v = c.getf_position()

# Convert to numpy array
v2 = vector3_to_xyz(v)

# Convert a rpy xyz to a Robot Raconteur com.robotraconteur.geometry.Transform
t = rpy_xyz_to_transform(np.deg2rad([10,20,30],[0.1,0.2,0.3]))

Image Type Converters

The image utilities provide functions to convert between Robot Raconteur image structures and OpenCV numpy arrays.

An example of converting a few types:

 from RobotRaconteur.Client import *
from RobotRaconteurCompanion.Util.ImageUtil import ImageUtil

c = RRN.ConnectService('rr+tcp://localhost:2355?service=camera')
im = c.capture_frame()

im_util = ImageUtil(client_obj=c)
im_mat = im_util.image_to_numpy(im)

# Do something with the image

# Create a random image
im_mat = np.random.randint(0,255,(480,640,3),dtype=np.uint8)
rr_img = im_util.array_to_image(im_mat, "bgr888")

# Send the image
c.send_frame(rr_img)

Date/Time Utilities

The date/time utilities provide functions for populating Robot Raconteur date/time structures.

An example of using the date/time utilities:

import RobotRaconteur as RR
RRN = RR.RobotRaconteurNode.s
import RobotRaconteurCompanion as RRC
from RobotRaconeteurCompanion.Util.DateTimeUtil import DateTimeUtil

RRC.RegisterStdRobDefServiceTypes(RRN)

# Create a DateTimeUtil object
dt_util = DateTimeUtil(RRN)

# Create a Robot Raconteur TimeSpec2
now_timespec2 = dt_util.NowTimeSpec()

# Create a Robot Raconteur TimeSpec3
now_timespec3 = dt_util.NowTimeSpec3()

# Create a Robot Raconteur DateTimeUTC
now_datetimeutc = dt_util.NowDateTimeUTC()

Identifier and UUID Utilities

The identifier utilities provide functions for creating and parsing Robot Raconteur identifiers and UUIDs.

An example of using the identifier utilities:

import RobotRaconteur as RR
RRN = RR.RobotRaconteurNode.s
import RobotRaconteurCompanion as RRC
from RobotRaconeteurCompanion.Util.IdentifierUtil import IdentifierUtil

RRC.RegisterStdRobDefServiceTypes(RRN)

# Create an IdentifierUtil
id_util = IdentifierUtil(RRN)

# Create an identifier from a name
my_device_identifier = id_util.CreateIdentifierFromName("my_device")

# Convert the identifier to a string
my_device_identifier_str = id_util.IdentifierToString(my_device_identifier)

# Convert the identifier string back to an identifier
my_device_identifier2 = id_util.StringToIdentifier(my_device_identifier_str)

# Compare identifiers
assert id_util.IsIdentifierMatch(my_device_identifier, my_device_identifier2)

Miscellaneous Utilities

Other utility classes are provided for various purposes. These include populating com.robotraconteur.sensordata.SensorData structures, periodically calling a function, and loading Robot Raconteur service info files from packages. See the documentation for more information.

License

Apache 2.0