RPC Interface Overview¶

The following explains how the gateway’s RPC interface functions in general. In this section, the term “RPC request” refers to a single element contained within the <do_command> field of an RCI request. As explained in the previous section, SCI and RCI wrappers are used to route RPC requests to the RPC interfaces of gateways, and a single RCI request may contain multiple RPC requests.

Conversion to Method Call¶

RPC requests convert from XML into method calls on the gateway in a straightforward manner. The top-level tag should be thought of as the method name, and tags one level below that should be thought of as named parameters of the method. For example, here is an RPC request:

<request_name>
    <param1>value1</param1>
    <param2>value2</param2>
    <param3>value3</param3>
</request_name>

And here is the resulting method call after being processed by the gateway’s RPC interface:

request_name(param1 = value1, param2 = value2, param3 = value3)

RPC responses generated by the gateways are formatted in the same fashion as RPC requests, with the top-level tag indicating the type of response and tags one level below being named parameters of the response. Here is an example RPC response:

<response_name>
    <param1>value1</param1>
    <param2>value2</param2>
    <param3>value3</param3>
</response_name>

Note

Because parameters are passed by name, the ordering of parameters in RPC requests is not significant. Similarly, the ordering of parameters in RPC responses is not guaranteed.

Parameter Type Overview¶

The type of a parameter is specified by the attribute “type” in its tag. When the RPC interface converts from XML to a method call, the given type of a parameter determines how the value of the parameter will be interpreted by the interface. Here is an example of a parameter that is specified as being of type “string”:

<param1 type="string">My favorite color is blue.</param1>

If no type is specified, the value will be converted to a bool, int or float, in that order of preference.

<param1>TRUE</param1>       #param1 is a bool
<param1>1</param1>          #param1 is an int
<param1>1.0</param1>        #param1 is a float

For responses, the types of parameters will always be specified even if they are one of the above three types.

If no value nor type is specified for a parameter, the type of the parameter is assumed to be of type “none.” This can be used when the existence of the parameter, but not its value, is significant for a given method.

Note

The “none” type does not appear in RPC response messages.

Simple Parameter Types¶

Type Example

int <param type=”int”>42</param> or <param type=”int”>0xFF</param>

float <param type=”float”>3.14159</param>

bool <param type=”bool”>TRUE</param>

string <param type=”string”>I am a string.</param>

MAC <param type=”MAC”>00:11:22:33:44:55:66:77</param>

base16 <param type=”base16”>0123456789ABCDEF</param>

base64 <param type=”base64”>3q2+78r+</param>

cron <param type=”cron”>0 */5 * * * *</param> (As of 1.6.0)

none <param/>

Type bool must have the value “TRUE” or “FALSE” and is not case sensitive.

Type MAC is intended for use with hexadecimal address strings and may contain non-hexadecimal delimiter characters.

Type base16 must have an even number of characters in order to produce a whole number of bytes. If the number of characters provided is odd, a leading zero will be prepended to the string before it is processed.

Type cron must be of a valid cron string format. Note that the leading value is seconds, not minutes as is the case with some cron implementations. Additionally, the special cron characters ‘L’, ‘W’, and ‘#’ are not supported and will cause an error if used.

Complex Parameter Types¶

Some parameters are containers for other subparameters. Also, it is legal for a subparameter of a complex parameter to itself be a complex parameter, i.e. a list of records is allowed.

list¶

An anonymous list of subparameters. Elements in a list are not required to be of the same type. Note that because a list is an anonymous data structure, the tag names of subparameters are ignored.

This XML:

<param type="list">
    <item>42</item>
    <item>FALSE</item>
    <item type="string">Hello</item>
</param>

would generate:

param = [42, False, "Hello"]

Note

When an RPC response contains a parameter of type list, elements of the list will always have the tag name “item”.

dict¶

A dictionary of subparameters. The tag names of the subparameters will become the keys of the dictionary.

This XML:

<param type="dict">
    <first>1</first>
    <second>TRUE</second>
    <third type="string">It's only a model.</third>
</param>

would generate:

param = {"first" : 1, "second" : True, "third" : "It's only a model."}

record¶

A record object with specific subparameters. The subparameters will be passed by name to the record object’s constructor. Note that parameter’s type is the class name of the record type to be instantiated.

This XML:

<param type="SomeRecordClass">
    <foo>9000</foo>
    <bar type="string">You must bring us...</bar>
    <a_shrubbery>TRUE</a_shrubbery>
</param>

would generate:

param = SomeRecordClass(foo = 9000, bar = "You must bring us...", a_shrubbery = True)

XML Parameter Type¶

Specifying a parameter’s type as “XML” indicates that it represents a complete XML tree. For example, this type is used when creating aliases (see add_alias).

Note

The “XML” type may not accept arbitrary XML, but must conform to the format specified by Digi’s RPC interface. This can include multiple RPC commands, a single parameter tag, or something in-between.

Here is an example of an RPC request with a parameter of type XML:

<request>
    <param type="xml">
        <dead>
            <parrot type="string">This is a late parrot! It's a stiff! Bereft of life, it rests in peace!</parrot>
        </dead>
    </param>
</request>

The parameter “param” would become the following XML tree, with the parameter’s tag as the root element of the tree:

<param type="xml">
    <dead>
        <parrot type="string">This is a late parrot! It's a stiff! Bereft of life, it rests in peace!</parrot>
    </dead>
</param>

Before 1.5.0:: XML parameters are stored internally as ElementTree objects. The ElementTree library is used by the RPC interface to parse XML, where parsing an XML string results in an ElementTree object.
As of 1.5.0:: XML parameters are stored internally as Tree objects. The TreeParser library is used by the RPC interface to both parse and compress XML, where parsing an XML string results in an Tree object.

Alias Parameter Type¶

RPC requests can be abstracted using aliases. Aliases are intended to be useful when communicating with multiple gateways, where parameters of a given command sent to each gateway are similar but not identical. By aliasing parameters, the gateways themselves can convert from a generic alias name to the needed XML prior to calling their appropriate RPC methods. Putting this conversion logic on the gateways simplifies the XML of requests sent to them, which in turn can reduce the complexity of the head end application and reduce the size of SCI requests sent to Device Cloud.

An alias may contain any valid XML and does not need to be a complete tree (i.e. a single root element is not required). To use an alias which has been defined on the gateway, use a parameter of type “alias”, where the tag name of the parameter is the name of the alias. To manage aliases defined on a gateway, use the aliasing commands defined by Aliasing Interface.

Parameter Replacement Examples¶

If there was an alias named “EXAMPLE_ALIAS” defined with the following XML content:

<param1>value1</param1>
<param2>value2</param2>
<param3>value3</param3>

The following XML:

<request_name>
    <EXAMPLE_ALIAS type="alias"/>
</request_name>

would become:

<request_name>
    <param1>value1</param1>
    <param2>value2</param2>
    <param3>value3</param3>
</request_name>

As another example, let’s say there are two gateways with the alias “THERMOSTAT” defined:

Gateway 1:

<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>

Gateway 2:

<destination_address type="MAC">00:11:22:33:AA:BB:CC:DD</destination_address>

The request that needs to be executed has the following structure:

<request_name>
    <destination_address type="MAC">value</destination_address>
    <param1>value1</param1>
    <param2>value2</param2>
</request_name>

Without aliases, a different SCI request would need to be sent to each gateway. This is because the thermostat addresses on the two ZigBee networks are different, so the RPC requests would need to be different. However, since a THERMOSTAT alias is defined on each gateway for the address of its thermostat, the same request can be sent to both, like so:

<sci_request version="1.0">
    <send_message>
        <targets>
            <device id="00000000-00000000-001122FF-FF334455"/>
            <device id="00000000-00000000-001122FF-FF334456"/>
        </targets>
        <rci_request version="1.1">
            <do_command target="RPC_request">
                <request_name>
                    <THERMOSTAT type="alias"/>
                    <param1>value1</param1>
                    <param2>value2</param2>
                </request_name>
            </do_command>
        </rci_request>
    </send_message>
</sci_request>

Gateway 1 will see this RPC request:

<request_name>
    <destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
    <param1>value1</param1>
    <param2>value2</param2>
</request_name>

Gateway 2 will see this RPC request:

<request_name>
    <destination_address type="MAC">00:11:22:33:AA:BB:CC:DD</destination_address>
    <param1>value1</param1>
    <param2>value2</param2>
</request_name>

Method Replacement Example¶

Because aliases can represent any valid XML, you can use them to replace entire method calls as well. For example, if every minute the head end application needs to call method1, method2 and method3 on every gateway, you could define an alias for these operations and greatly simplify the SCI requests being sent.

If the alias “RUN_METHODS” is defined to be:

<method1>
    <param1>value1</param1>
    <param2>value2</param2>
</method1>
<method2/>
<method3>
    <param>value</param>
</method3>

The following request:

<sci_request version="1.0">
    <send_message>
        <targets>
            <device id="00000000-00000000-001122FF-FF334455"/>
            <device id="00000000-00000000-001122FF-FF334456"/>
        </targets>
        <rci_request version="1.1">
            <do_command target="RPC_request">
                <RUN_METHODS type="alias"/>
            </do_command>
        </rci_request>
    </send_message>
</sci_request>

would result in the three methods being executed on the two given gateways, just like normal RPC requests.

Note

Alias replacement happens prior to method invocation. As a result, if the alias contents specify that a method call should be synchronous, it will be treated like any other synchronous request, with the RPC response message included in the SCI response. See Synchronous Requests and Responses for details on synchronous requests.

Request Identifier¶

All RPC requests take an optional request_identifier parameter which can be used to match requests with later responses. A request identifier can be of any simple type but typically is an integer.

Broadcasts¶

RPC requests that specify a destination address can sometimes send the corresponding ZigBee command as a broadcast rather than a unicast. For example, the ZCL Identify command can be either unicast to a single device or broadcast to all devices on the network. To specify a broadcast, set the destination address to the special value 00:00:00:00:00:00:FF:FF.

Type	Example
int	<param type=”int”>42</param> or <param type=”int”>0xFF</param>
float	<param type=”float”>3.14159</param>
bool	<param type=”bool”>TRUE</param>
string	<param type=”string”>I am a string.</param>
MAC	<param type=”MAC”>00:11:22:33:44:55:66:77</param>
base16	<param type=”base16”>0123456789ABCDEF</param>
base64	<param type=”base64”>3q2+78r+</param>
cron	<param type=”cron”>0 /5 * * </param> (As of* 1.6.0)
none	<param/>