XML-RPC Interface
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 |
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 |
zero_offset_count |
int |
Zero offset* (in encoder counts) for external axis joint. |
*Drive joint angles will be computed with the following formula: |
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
WriteSdo
Purpose: write SDO to EtherCAT axis
Precondition
The EtherCAT Master must be running.
Parameter
Name |
Type |
Description |
|---|---|---|
name |
string |
Name of external axis. |
index |
int |
CoE index of the SDO entry. Will be converted to [0x0000~0xffff]. |
subindex |
int |
CoE subindex of the SDO entry. Will be converted to [0x00~0xff]. |
type |
string |
Type of the SDO entry. May be “U8”, “U16”, “U32”, “I8”, “I16”, “I32”, and “STR”. |
value |
string |
Value of the SDO entry. For type “U8”, “U16”, and “U32”, hexadecimal strings start with “0x” are also supported. |
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_write_axis_sdo() calls this method and halts program if result contains non-zero error code
ReadSdo
Purpose: read SDO from EtherCAT axis
Precondition
The EtherCAT Master must be running.
Parameter
Name |
Type |
Description |
|---|---|---|
name |
string |
Name of external axis. |
index |
int |
CoE index of the SDO entry. Will be converted to [0x0000~0xffff]. |
subindex |
int |
CoE subindex of the SDO entry. Will be converted to [0x00~0xff]. |
type |
string |
Type of the SDO entry. May be “U8”, “U16”, “U32”, “I8”, “I16”, “I32”, and “STR”. |
Return
Structure with the following members:
Name |
Type |
Description |
|---|---|---|
rpc_error.error_code |
int |
Numeric code for the error; zero, if there is no error. |
rpc_error.error_message |
string |
Message describing the error. |
is_str |
bool |
Whether the returned value is string or not. |
value_num |
double |
Returned value if the SDO is a number type. |
value_str |
string |
Returned value if the SDO is a string type. |
Typical Usage
ethercat_read_axis_sdo() calls this method and halts program if result contains non-zero error code