General

Warning

The AI Accelerator requires ROS 2 Humble, so PolyScope X 10.12.1 is the latest compatible release. PolyScope X 10.13 and later use ROS 2 Jazzy and are not currently supported.

Shared conventions for all AI Accelerator URScript APIs:

  • ArkError: struct(error=<bool>, message=""). Many functions return this directly, or nest it as .error inside a larger struct. error=False means success.

  • ARK_ROS2Namespace: Prefix for every ROS service and topic name below. Set by the AI Accelerator URCap when the robot IP / namespace is configured.

  • Lifecycle: Call ark_init() before detection, classification, TF, tags, overlay, or logging. Call ark_path_planning_init() before path-planning moves (see Path Planning). Pair with ark_close() / ark_path_planning_close() when finished.

  • Model paths: ark_load_detection_model and ark_load_classification_model prepend /workspaces/isaac_ros-dev/data/models/ to the model argument.

ark_init()

ark_init()

Creates the ROS 2 service clients used by most AI Accelerator APIs. Takes several seconds (the preamble sleeps between each client factory call).

Arguments

  • None

Returns

  • ArkError — typically ArkError(False) on success

Errors / failure modes

  • Fails at runtime if ROS clients cannot be created (namespace wrong, services not running, URCap not configured)

ROS

Clients created under ARK_ROS2Namespace:

Relative name

Type

/trigger_detection

ur_ark_ros_common_msgs/srv/TriggerDetection

/wait_detection

ur_ark_ros_common_msgs/srv/WaitDetection

/publish_transform

ur_ark_ros_common_msgs/srv/PublishTransform

/set_transformur

ur_ark_ros_common_msgs/srv/SetTransformUR

/get_transformur

ur_ark_ros_common_msgs/srv/GetTransformUR

/load_model

ur_ark_ros_common_msgs/srv/LoadModel

/infer_classification

ur_ark_ros_common_msgs/srv/InferClassification

/pipeline_tag

ur_ark_ros_common_msgs/srv/PipelineTag

/log_event

ur_ark_ros_common_msgs/srv/LogEvent

Call order

Call once in Before Start (or equivalent) before other general/detection/classification/TF/tag APIs.

Example

ark_init()
ark_set_overlay("detection")
# ... detection / classification / TF / tags ...
ark_close()

ark_close()

ark_close()

Closes ROS service clients created by ark_init().

Arguments

  • None

Returns

  • ArkError — typically ArkError(False)

Errors / failure modes

  • Undefined if called without a prior successful ark_init()

ROS

Closes: /trigger_detection, /wait_detection, /publish_transform, /set_transformur, /load_model, /infer_classification, /pipeline_tag, /log_event.

Note

As implemented in the SDK preamble, ark_close() does not close the /get_transformur client created by ark_init().

Call order

Call when the program no longer needs AI Accelerator APIs that depend on ark_init().

Example

ark_close()

ark_set_overlay(view_name)

ark_set_overlay(view_name)

Selects which overlay is shown on the teach pendant image stream from the AI Accelerator.

Arguments

  • view_name (string): Overlay selector. Documented values: detection, classification, tags, none. The string is published as-is.

Returns

  • ArkError — typically ArkError(False)

Errors / failure modes

  • Unknown values may result in no useful overlay (passed through to the selector topic)

ROS

  • Topic: ARK_ROS2Namespace + "/selected_view/selector"

  • Type: std_msgs/String (data = view_name)

Call order

Requires a running overlay pipeline on the compute module. Usually called after ark_init().

Example

ark_init()
ark_set_overlay("classification")

ark_log_event(_log_type, _message)

ark_log_event(_log_type, _message)

Logs a message through the AI Accelerator backend log-event service.

Arguments

  • _log_type (string): Message / log type

  • _message (string): Log message body

Returns

  • struct(error=ArkError(...)) — error.error is taken from the service error_state

Errors / failure modes

  • Requires the ur_ark_ros_common log event node. If it is not running, the service call fails.

  • By default, logs are saved under /workspaces/isaac_ros-dev/log_event on the compute module.

ROS

  • Service: ARK_ROS2Namespace + "/log_event"

  • Type: ur_ark_ros_common_msgs/srv/LogEvent

Call order

Requires ark_init() (creates handle_log_event).

Example

ark_init()
res = ark_log_event("info", "Starting pick cycle")
if res.error.error:
  popup("log failed", blocking=True)
end