MotionPlus URCap

URCap Design

The following diagram shows the architecture design of the MotionPlus URCap:

img

The MotionPlus URCap consists of:

  • MotionPlus Service Process - Hosts an EtherCAT Master Device Implementation and an XML-RPC server to help interface with the EtherCAT Master Device Implementation from the URScript program. Functionality provided through the XML-RPC interface is described here. The URCap provides an URScript API that interacts with the XML-RPC interface.

  • Installation Tab - Provides a GUI for configuring, starting, and stopping the MotionPlus Service Process. See here.

  • EtherCAT URScript API - Provides a URScript interface for lower-level EtherCAT functionality that is loaded into the Polyscope program preamble by the Installation Tab. The API abstracts much of the XML-RPC communication with the MotionPlus Service Process.

Terminology

EtherCAT Master

An EtherCAT* network is driven by an EtherCAT Master device. The master is the only device in an EtherCAT segment that is allowed to send messages - the slaves can add data and send the frame along, but they cannot create new messages on their own.

*EtherCAT is a registered trademark and patented technology, licensed by Beckhoff Automation

EtherCAT Slave

An external axis (an EtherCAT servo drive) is a slave device on an EtherCAT network. It reads commands and target joint positions from the EtherCAT frame sent by the EtherCAT master and sends the actual joint positions and status information back via the EtherCAT frame.

Installation

Remove MotionPlus URCap

If you are upgrading/downgrading, we recommend that you remove the existing version of MotionPlus URCap first:

  1. Navigate to the URCap Management page. img

  2. Select the target URCap, then click the Remove button.

  3. Click the Restart button to restart Polyscope. img

Install MotionPlus URCap

Follow the standard process of installing a URCap:

  1. Download and copy the URCap package to a USB drive, and connect the USB drive to the teach pendant.

  2. Navigate to the URCap Management page.

  3. Click the Add / Install button, select the target URCap from the USB drive, then click the Open button.

  4. Click the Restart button to restart Polyscope. img

Start MotionPlus Service

  1. Connect the USB-Ethernet adapter to one of the USB ports on the UR Controller. The SS USB port (USB3 port) is recommended. img

    img

  2. Navigate to the MotionPlus installation tab.

  3. Select the network interface corresponding to the connected Ethernet adapter (generally, “eth1”).

    1. You may see only “sim” if the connected no adapter has been added or the added Ethernet adapter isn’t compatible.

    2. Click the Refresh button, if the adapter doesn’t show up. Restart Polyscope, if the refresh doesn’t work.

  4. Click the Start button to start the MotionPlus Service.

  5. When the service has started, the Service State will display as RUNNING

    1. In case the status does not change to RUNNING within 10 seconds, the service may have crashed, and the reason may be recorded in the MotionPlus Service log file.

    img

Export MotionPlus Service Log

The log of the MotionPlus Service can be transferred to a USB drive and viewed as a text file on any computer:

  1. Navigate to the MotionPlus installation tab.

  2. Click the Export Log button and specify the file name.

  3. Select Save to USB, you can then view the log file on another computer. img

Installation Tab User Interface

img

The Installation Tab User Interface provides the following functions:

Service

  • show status of the MotionPlus Service

  • start/stop the MotionPlus Service

  • export log of the MotionPlus Service to a file

Network Devices

  • select network interface for EtherCAT communication

  • NOTE: the Simulated network interface implements a virtual EtherCAT network in which EtherCAT communication is entirely simulated.

EtherCAT Master

  • shows the EtherCAT Master status/error

XML-RPC Methods

The XML-RPC server hosted by the MotionPlus Service provides the set of methods as described below. In general, most applications will communicate with the MotionPlus service through the UR Script API. But it is possible for PS5 applications (written in Java) to communicate directly with the MotionPlus service via XML. This section documents the XML-RPC interface.

GetStatus

  • Purpose: get EtherCAT Master status

  • Precondition: none

Parameter: none

Return

Structure with the following members:

Name

Type

Description

timestamp

struct

System timestamp (in local time zone) when method was called. sec (int) - whole seconds elapsed since the UNIX epoch (1970-01-01, 00:00:00). nsec (int) - nanoseconds elapsed in addition to sec.

master_running

bool

Flag indicating whether EtherCAT Master is running.

master_error

struct

Current runtime error for the EtherCAT Master (may be cleared using ClearError method). error_code (int) - numeric code for the runtime error; zero, if there is no active error. error_message (string) - message describing the runtime error.

Typical Usage

ethercat_begin_status_monitor(): calls this method periodically to check whether timestamp is updating and any runtime error is present

ethercat_is_master_running(): calls this method and returns value of the master_running field

ethercat_stop(): calls this method continually to determine when the EtherCAT Master has stopped

URCap Installation Tab: calls this method periodically to update Service Status display

GetMasterState

  • Purpose: get EtherCAT Master state

  • Precondition: none

Parameter: none

Return

Structure with the following members:

Name

Type

Description

timestamp

struct

System timestamp (in local time zone) when method was called. sec (int) - whole seconds elapsed since the UNIX epoch (1970-01-01, 00:00:00). nsec (int) - nanoseconds elapsed in addition to sec.

state

string

Current state of EtherCAT Master; should be one of the following values:STANDBYINITPRE_OPSAFE_OPOP

Typical Usage

ethercat_start(): calls this method continually to determine when EtherCAT Master has reached OP

GetAxisPositions

  • Purpose: get current target and actual positions of the axes controlled by the EtherCAT Master

  • Precondition: EtherCAT Master must be running for the result to be valid

Parameter: none

Return

Structure with the following members:

Name

Type

Description

timestamp

struct

System timestamp (in local time zone) when method was called. sec (int) - whole seconds elapsed since the UNIX epoch (1970-01-01, 00:00:00). nsec (int) - nanoseconds elapsed in addition to sec.

axis_count

int

Number of configured axes.

axis_indices

int[]

Indices* for the configured axes.

target_positions

double[]

Target positions* for the configured axes (in radians).

actual_positions

double[]

Actual positions* for the configured axes (in radians).

target_position_counts

int[]

Target positions* for the configured axes (in encoder counts).

actual_position_counts

int[]

Actual positions* for the configured axes (in encoder counts).

*Only the first axis_count number of items in the array are valid.

Typical Usage

ethercat_get_axis_positions(): calls this method and returns the result

GetAxisErrors

  • Purpose: get current error codes for the axes controlled by the EtherCAT Master

  • Precondition: EtherCAT Master must be running for the result to be valid

Parameter: none

Return

Structure with the following members:

Name

Type

Description

timestamp

struct

System timestamp (in local time zone) when method was called. sec (int) - whole seconds elapsed since the UNIX epoch (1970-01-01, 00:00:00). nsec (int) - nanoseconds elapsed in addition to sec.

axis_count

int

Number of configured axes.

axis_indices

int[]

Indices* for the configured axes.

axis_errors

int[]

Error codes* for the configured axes. A zero error code indicates there is no fault with the drive. A non-zero error code indicates a particular fault, as described by the drive’s manual.

*Only the first axis_count number of items in the array are valid.

Typical Usage

ethercat_get_axis_errors(): calls this method and returns the result

SelectDevice

  • Purpose: set/change Ethernet interface used by the EtherCAT Master

  • Precondition: EtherCAT Master must be stopped

Parameter:

Name

Type

Description

device_name

string

Name of Ethernet interface. “SIMULATION” for virtual EtherCAT network, where EtherCAT communication is entirely simulated. Otherwise, it must match the name of network interface on the UR Controller (e.g. “eth1”).

Return

Structure with the following members:

Name

Type

Description

error_code

int

Numeric code for the error; zero, if there is no error.

error_message

string

Message describing the error.

Typical Usage

URCap Installation Tab: calls this method with selected network interface when Start button is clicked

ClearError

  • Purpose: clear any EtherCAT Master runtime error (as reported by GetStatus method result)

  • Precondition: none

Parameter: none

Return

Structure with the following members:

Name

Type

Description

error_code

int

Numeric code for the error; zero, if there is no error.

error_message

string

Message describing the error.

Typical Usage

ethercat_clear_error(): calls this method and halts program if result contains non-zero error code URCap Installation Tab: calls this method before each program

SetMasterParameter

  • Purpose: set parameter for the EtherCAT Master

  • Precondition: EtherCAT Master must be stopped

Parameter:

Name

Type

Description

key

string

Name of parameter to set.

value

string

New value for the selected parameter.

  • Detail

The following EtherCAT Master parameters are currently supported:

Key

Supported Values

Default Value

Description

dc_enable

“true”, “false”

“false”

Whether EtherCAT Distributed Clock should be enabled.

Return

Structure with the following members:

Name

Type

Description

error_code

int

Numeric code for the error; zero, if there is no error.

error_message

string

Message describing the error.

Typical Usage

ethercat_set_parameter(): calls this method and halts program if result contains non-zero error code

ConfigureAxis

  • Purpose: configure EtherCAT slave device for given external axis

  • Precondition:

    • EtherCAT Master must be stopped

    • The slave device must not have a preexisting configuration for another axis

    • There must not be a preexisting slave device configuration for the given axis

    • Important: As of Polyscope 5.16, only a single axis can be configured

Parameter:

Name

Type

Description

name

string

Name of external axis.

axis_index

int

Index of external axis (as reported by axis_group_get_axis_index(name) ).

station_address

int

Station address for EtherCAT slave device; must be 1 .. 65535.

counts_per_rev

int

Encoder counts* per revolution of external axis drive shaft; must be positive.

gear_ratio

double

Gear ratio* of external axis joint.

feed_constant

double

Feed constant* (in radians) for external axis joint (this is usually 2*pi ).

zero_offset_count

int

Zero offset* (in encoder counts) for external axis joint.

*Drive joint angles will be computed with the following formula:joint_angle = (feed_constant * (encoder_count - zero_offset_count)) / (counts_per_rev * gear_ratio)

Return

Structure with the following members:

Name

Type

Description

error_code

int

Numeric code for the error; zero, if there is no error.

error_message

string

Message describing the error.

Typical Usage

ethercat_config_axis(): calls this method with given arguments and halts program if result contains non-zero error code

ResetConfiguration

  • Purpose: delete all configurations for EtherCAT slave drives

  • Precondition(s): EtherCAT Master must be stopped

Parameter(s): none

Result

Structure with the following members:

Name

Type

Description

error_code

int

Numeric code for the error; zero, if there is no error.

error_message

string

Message describing the error.

Typical Usage

ethercat_stop(): calls this method when reset parameter is “true” and halts program if result contains non-zero error code

StartMaster

  • Purpose: start EtherCAT Master

  • Precondition

    • The EtherCAT Master must be stopped.

    • The Ethernet interface to be used by the EtherCAT aster must have been provided via the SelectDevice method.

    • An EtherCAT slave device must have been configured using the ConfigureAxis method.

    • Any configured slave device must be connected to the same network the EtherCAT Master will be using.

    • Any EtherCAT Master runtime error that occurred must have been cleared using the ClearError method.

Parameter: none

Return

Structure with the following members:

Name

Type

Description

error_code

int

Numeric code for the error; zero, if there is no error.

error_message

string

Message describing the error.

Typical Usage

ethercat_start(): calls this method and halts program if result contains non-zero error code

StopMaster

  • Purpose: Command EtherCAT Master to stop if it is running

NOTE: This method does not wait for the EtherCAT Master to stop before returning its result. If an XML-RPC client wants to know when the EtherCAT Master actually stops, it needs to monitor the master_running field in the GetStatus method result.

  • Precondition: none

Parameter: none

Return

Structure with the following members:

Name

Type

Description

error_code

int

Numeric code for the error; zero, if there is no error.

error_message

string

Message describing the error.

Typical Usage

ethercat_stop(): calls this method and halts program if result contains non-zero error code