XML RPC API

XML-RPC API

The built-in XML-RPC server is the main Universal Robots client contract. XmlRpcServer::registerStandardMethods() registers 52 active methods.

Endpoint

Setting	Default
Protocol	HTTP + XML-RPC
Bind address	0.0.0.0
Port	8080
Robot URL	http://192.168.0.10:8080/RPC2
HTTP method	POST
Content type	text/xml

Method names are case-sensitive. The request path is conventionally /RPC2; the server parses the XML-RPC body and returns HTTP 200 OK for normal XML-RPC responses and XML-RPC faults.

sequenceDiagram
    participant R as "UR Robot"
    participant X as "XmlRpcServer"
    participant G as "GlobalState"
    participant D as "DatabaseManager"

    R->>X: "HTTP XML-RPC method call"
    X->>X: "Parse method and params"
    X->>G: "Check readiness and state"
    X->>D: "Load persisted plan when requested"
    X-->>R: "XML-RPC response or fault"

Loading

Value Types

Inbound parsing supports:

XML-RPC type	Runtime value
<int> / <i4>	integer
<double>	double
<boolean>0</boolean> / <boolean>1</boolean>	boolean
<string>	string
<array><data>...</data></array>	array
Plain untyped value text	string

Outbound responses can contain integers, doubles, booleans, strings, arrays, structs, or nil values. Doubles are serialized with 6 decimal places.

Readiness Contract

The XML-RPC server can be listening before palette data is loaded. A robot client must call get_status() or UR_GetStatus() and wait for ready == true before calling operational methods.

Operational calls before readiness return an XML-RPC fault:

faultCode: 503
faultString: Application not ready: load a palette first. Poll get_status until ready is true.

Readiness-exempt methods:

Method
get_status
UR_GetStatus
get_available_functions
UR_SetFileName
UR_ReadDataFromUsbStick

Recommended URScript Flow

rpc = rpc_factory("xmlrpc", "http://192.168.0.10:8080/RPC2")

status = rpc.get_status()
while status["ready"] == False:
  sleep(0.5)
  status = rpc.get_status()

palette = rpc.UR_Palette()
carton = rpc.UR_Karton()
layer_count = rpc.UR_AnzLagen()
package_count = rpc.UR_AnzPakete()

To select and load a plan by article number:

rpc.UR_SetFileName("123456")
load_result = rpc.UR_ReadDataFromUsbStick()

if load_result == 0:
  status = rpc.get_status()

UR_SetFileName("123456") stores 123456.rob as the requested plan name. UR_ReadDataFromUsbStick() loads that palette from SQLite into live GlobalState.

Error Behavior

Case	Behavior
Malformed XML-RPC request	XML-RPC fault with code -1 and message Invalid request.
Operational call before readiness	XML-RPC fault with code 503.
Unknown method after readiness	String response Unknown method: <name>.
Missing or invalid parameters	Method-specific sentinel return such as 0, -1, 1, 404, 503, false, or an empty array.

Response Shapes

Status Struct

get_status() and UR_GetStatus() return:

Field	Type	Meaning
ready	bool	true when a palette file is loaded and layer count is greater than zero.
file	string	Current loaded/requested file name.
message	string	ready or XML-RPC listening; palette data not ready.

Common Arrays

Array	Format
Palette dimensions	[length, width, height] in mm.
Package dimensions	[length, width, height, gap] in mm.
Package position	[xPick, yPick, anglePick, xDrop, yDrop, angleDrop, count, xVector, yVector].
Scanner override	[scanner1, scanner2, scanner3] booleans.

UR_PaketPos(index) uses a zero-based package-position index. When label invert is enabled in the HMI, the returned drop angle is rotated by 180 degrees. When the active UR20 palette is palette 2, drop X/Y and vector X/Y are swapped and rotations of 0 or 180 degrees are flipped by 180 degrees.

Active Methods

Use get_available_functions() at runtime to confirm the active method set. The tables below declare every method currently registered by the standard server.

Status and Loading

Method	Parameters	Return	Notes
get_status	none	struct	Readiness and current file status.
UR_GetStatus	none	struct	Alias for get_status.
get_available_functions	none	string array	Registered method names.
UR_SetFileName	articleNumber: string	string	Stores <articleNumber>.rob as the current file. Empty input returns empty string.
UR_ReadDataFromUsbStick	none	int	0 on successful database load, 1 if no state/database/current file/palette exists.

Pallet and Package Data

Method	Parameters	Return	Notes
UR_Palette	none	int array	[paletteLength, paletteWidth, paletteHeight].
getPalettenDaten	none	int array	Alias for UR_Palette.
UR_Karton	none	int array	[packageLength, packageWidth, packageHeight, packageGap].
getPaketDaten	none	int array	Alias for UR_Karton.
UR_Paket_hoehe	none	int	Package height.
getKartonhoehe	none	int	Alias for UR_Paket_hoehe.
UR_MasseGeschaetzt	none	double	Package weight from database/package settings.
getGewicht	none	double	Alias for UR_MasseGeschaetzt.
UR_Quergreifen	none	bool	Current einzelpaketLaengs flag.
getEinzelpaketLaengs	none	bool	Alias for UR_Quergreifen.
UR_CoG	massePaket: double, masseGreifer: double, optional anzahlPakete: int	double array	Returns [y, z, 0.0] center-of-gravity offset. If anzahlPakete is 0, package mass is treated as 0.

Layer Data

Method	Parameters	Return	Notes
UR_Lagen	none	int array	Layer type assignment per layer.
getLageZuordnung	none	int array	Alias for UR_Lagen.
UR_Zwischenlagen	none	int array	Intermediate layer flags per layer.
getZwischenlagen	none	int array	Alias for UR_Zwischenlagen.
UR_AnzLagen	none	int	Total number of layers.
getAnzLagen	none	int	Alias for UR_AnzLagen.
UR_AnzPakete	none	int	Total package/pick count stored for the palette.
getAnzPakete	none	int	Alias for UR_AnzPakete.
UR_PaketeZuordnung	none	int array	Package count per layer type.
getPaketeZuordnung	none	int array	Alias for UR_PaketeZuordnung.
UR_Startlage	none	int	Start layer, default 1.
getStartlage	none	int	Alias for UR_Startlage.
getLageArten	none	int	Number of different layer types.
setLage	layer: int	bool	Updates current layer in HMI state. Returns false when missing the layer parameter.

Package Positions and Pick Offsets

Method	Parameters	Return	Notes
UR_PaketPos	index: int	int array	Package position at zero-based index. Empty array if missing or invalid.
getPaketPos	index: int	int array	Alias for UR_PaketPos.
UR_PickOffsetX	none	int	Pick offset X from state, default 0.
getVerschiebungX	none	int	Alias for UR_PickOffsetX.
UR_PickOffsetY	none	int	Pick offset Y from state, default 0.
getVerschiebungY	none	int	Alias for UR_PickOffsetY.
getLabelInvert	none	bool	Whether HMI label inversion is active.
getData	optional index: int	array, int array, or nil	No parameter returns [paletteDims, packageDims, [layerTypeCount], [numberOfLayers]]. Index 0..3 returns one item. Other indexes return nil.

Clamp and Scanner State

Method	Parameters	Return	Notes
getKlemmungAktiv	none	bool	Current clamp-active state.
UR_GetKlemmungAktiv	none	bool	Alias for clamp-active state.
UR_scanner1and2niobild	none	int	UR10 scanner 1+2 NIO image/status value from HMI state.
UR_scanner1bild	none	int	UR10 scanner 1 image/status value.
UR_scanner2bild	none	int	UR10 scanner 2 image/status value.
UR_scanner1and2iobild	none	int	UR10 scanner 1+2 IO image/status value.
UR_scannerStatus	status: string	int	UR20 scanner status update. Expected format like True,True,True. Returns 0; returns -1 if missing status or state.
UR_GetScannerOverwrite	none	bool array	[scanner1, scanner2, scanner3] override values. Kept with current spelling for compatibility.
UR_GetScannerOverride	none	bool array	Alias for UR_GetScannerOverwrite.

UR20 Palette Management

Method	Parameters	Return	Notes
UR_SetActivePalette	paletteNumber: int	int	Success returns 1 or 2; 404 for missing/invalid palette; 503 if requested palette is not empty. Successful call marks the palette as not empty.
UR_RequestPaletteChange	oldPalette: int, newPalette: int	int	Returns 1 when change is approved, 0 when the new palette is not empty, 404 for missing/invalid parameters. Successful call marks the new palette as not empty.
UR_GetActivePaletteNumber	none	int	Returns 1 or 2 only when the active palette is currently empty, then marks it not empty. Returns 0 when already not empty or no valid active palette exists.
UR_GetPaletteStatus	paletteNumber: int	int	1 means empty, 0 means not empty, -1 means missing/invalid palette.
UR_SetZwischenLageLegen	aktiv: bool	int	Sets the UR20 intermediate-layer flag. Returns 1 on success, 0 on missing parameter/state.

Registry-Only Source Helpers

The source tree also contains UR10ServerFunctions and UR20ServerFunctions helpers that register names such as UR10_scanner1bild or UR20_SetActivePalette into RpcMethodRegistry. The current standard server does not call those helper registrars, so a deployed client should not assume those names are active unless get_available_functions() reports them.

Use the active UR_... names from the tables above for the current application.

Raw Request Examples

<?xml version="1.0"?>
<methodCall>
  <methodName>UR_Palette</methodName>
</methodCall>

<?xml version="1.0"?>
<methodCall>
  <methodName>UR_PaketPos</methodName>
  <params>
    <param>
      <value><int>0</int></value>
    </param>
  </params>
</methodCall>

---

<- Previous: Updates | Home | Next: Architecture ->