KINOVA KORTEX™ API

The Kortex C++ API is organized into several functional modules. Developers can interact with the robot through these primary namespaces:

• ActuatorConfig: Configuration for individual actuators (e.g., AxisOffsets, ControlLoop, TorqueOffset).
• ActuatorCyclic: High-frequency cyclic communication for actuators (e.g., Command, Feedback).
• Api: Core API services and error handling (ErrorCodes, SubErrorCodes).
• Base: Fundamental robot operations, including Action management, ArmState, Gripper control, Joint limits, Mapping, ProtectionZone, and Sequence execution.
• BaseCyclic: Cyclic communication for base robot components.
• Common: Shared types and utilities like Connection, Timestamp, Unit, and ArmState.
• ControlConfig: Configuration for motion control, including KinematicLimits, PayloadInformation, and ToolConfiguration.
• DeviceConfig: Hardware-level configuration such as FirmwareVersion, SerialNumber, and SafetyConfiguration.
• DeviceManager: Management of connected devices and DeviceHandles.
• GripperConfig & GripperCyclic: Configuration and cyclic control for grippers.
• InterconnectConfig & InterconnectCyclic: Configuration and cyclic control for external interfaces like GPIO, I2C, UART, and Ethernet.
• ProductConfiguration: Hardware identity and assembly details (e.g., EndEffectorType, ArmLaterality).
• Session: Connection management and CreateSessionInfo.
• VisionConfig: Configuration for vision sensors, including IntrinsicParameters, ExtrinsicParameters, and SensorSettings.

The Kortex Python API is organized into several functional modules. Developers can interact with the robot through these primary namespaces:

• ActuatorConfig: Configuration for individual actuators (e.g., AxisOffsets, ControlLoop, TorqueOffset).
• ActuatorCyclic: High-frequency cyclic data for actuators (e.g., Command, Feedback).
• Api: Core API services and error handling (ErrorCodes, SubErrorCodes).
• Base: Fundamental robot abstractions including ArmState, Gripper commands, JointAngles, Pose, Waypoint, and Sequence management.
• BaseCyclic: High-frequency cyclic communication for base robot functions.
• Common: Shared data types like Timestamp, Connection, Unit, and ArmState.
• ControlConfig: Configuration for motion control, including PayloadInformation, KinematicLimits, and ToolConfiguration.
• DeviceConfig: Hardware-level configuration such as FirmwareVersion, SerialNumber, and SafetyStatus.
• DeviceManager: Management of device handles.
• GripperConfig & GripperCyclic: Configuration and high-frequency control for grippers.
• InterconnectConfig & InterconnectCyclic: Configuration and cyclic data for external interfaces like GPIO, I2C, and Ethernet.
• ProductConfiguration: Hardware identity and model information.
• Session: Connection and session management.
• VisionConfig: Configuration for vision sensors, including IntrinsicParameters and ExtrinsicParameters.

The robot base uses a Publish/Subscribe design pattern for unsolicited messages. Instead of polling, your application subscribes to specific topics. When a change occurs on a topic, the robot sends a notification to all active subscribers.

To receive notifications, implement a callback function and register it using the appropriate topic method on the base object (e.g., base.OnNotification<TopicName>).

# In this example, when a user is created `notification_callback` will be called because we register it as a
# handler for `ConfigurationChange` topic notifications.
def notification_callback(data):
	print("********************************")
	print("**  Callback function called  **")
	print(json_format.MessageToJson(data))
	print("********************************")

# Subscribe to ConfigurationChange notifications
notif_handle = base.OnNotificationConfigurationChangeTopic(notification_callback, Base_pb2.NotificationOptions())

The Action class uses a Protobuf oneof pattern for its action_parameters. This means an Action object can only hold one type of parameter at a time (e.g., either JointSpeeds, ConstrainedPose, or Snapshot). Setting a new parameter automatically clears the previous one.

To interact with these parameters in C++, use the following patterns:

1. Setting Complex Message Parameters

For parameters that are messages (like ConstrainedPose or Snapshot), use mutable_<field>() to get a pointer to the object you can modify, or set_allocated_<field>(ptr) to transfer ownership of an existing pointer.

2. Setting Primitive Parameters

For simple types like uint32 (e.g., toggle_admittance_mode), use set_<field>(value).

3. Checking the Active Parameter

Use action_parameters_case() to determine which parameter is currently set, or use the has_<field>() helper methods.

// Example: Setting a reach pose
Action action;
auto* pose = action.mutable_reach_pose();
// ... configure pose object ...

// Example: Checking what is set
if (action.action_parameters_case() == Action::kReach_pose) {
    const auto& pose = action.reach_pose();
    // ... use pose ...
}

The ConfigurationChangeNotification class uses a oneof structure to represent different types of configuration changes. Because it is a oneof, only one field can be set at a time. Setting a new field automatically clears the previous one.

Supported fields in the oneof include:

• user_profile_handle (kUser_profile_handle)
• protection_zone_handle (kProtection_zone_handle)
• safety_handle (kSafety_handle)
• network_handle (kNetwork_handle)
• ssid (kSsid)

To interact with these fields, use the following patterns:

Checking the current field

Use has_<field_name>() to check if a specific field is currently set. Use configuration_change_case() to determine which field is active.

Modifying fields

• mutable_<field_name>(): Returns a pointer to the field's object. If another field was previously set, it is cleared. This is the preferred way to modify an existing field's contents.
• set_allocated_<field_name>(pointer): Takes ownership of a pointer to a new object. If the pointer is NULL, it clears the oneof case.
• clear_<field_name>(): Frees the field and resets the oneof case to CONFIGURATION_CHANGE_NOT_SET.

Retrieving and releasing ownership

• const <field_name>() const: Returns a constant reference to the field if it is set.
• release_<field_name>(): Returns the pointer to the field and transfers ownership to the caller. The oneof case is cleared after this call.