I2SE XPL devices API documentation¶

XPL device’s REST API documentation¶

Preamble¶

A single XPL device varies within the XPL device family in it’s hardware configuration, i.e. there are various product variants available, for different usage scenarios and/or different mounting options.

However, all device variants feature a common device API to access the device’s data and configure it to customer needs. This API is available as a RESTful HTTP service on every single device.

And this document describes the resources that make up this official API.

Device modelling¶

Before describing the API itself, it necessary to agree on a common wording and to understand some basic concepts which are implemented within the XPL device family. The following chapters describe these concepts and introduce some terms used within this document and on the web front-end of each device.

Physical channel¶

A physical channel is the base of the whole device, i.e. it is the representation of the screw terminals which form a usable unit. In other words, a XPL Rail IO6 device has 6 physical channels. The numbering of this channels is fixed and represents the physical numbering. It is identical to the device printing/labels etc.

There exists two classes of physical channels: serial and io. As expected, the class serial is used for COM port like channels, e.g. RS-232 or CAN interfaces, whereas an io physical channel represents two/three screw terminals to connect a sensor and/or a relais and so on. These two classes are independently numbered from each other, because the devices printing/labeling will also start anew while enumerating this interfaces.

A physical channel can have multiple capabilities, e.g. an io channel can be configured as input or output, but there might be devices, which can not be switch-able and thus are limited to output only. Also, a serial physical channel is usually bound to its hardware driver (e.g. CAN vs. RS-485...).

Virtual channel¶

A virtual channel is a logical unit which is created in software. It requires at least one physical channel as input source, and can have multiple physical outputs. The main identification property is a unique virtual channel id, which is a simple positive integer number between 1 and 65535. By design, the virtual channel id zero is invalid.

Three different types of virtual channels exist:

digital virtual channels

analog virtual channels

serial virtual channels

This three type exist independently from each other, that means a digital virtual channel with id 1 can exist in parallel to an analog virtual channel with id 1. Both channel does not interfere in this case and cannot be mixed.

A virtual channel can only have one value at the moment, therefore it must be given that only one input is active on each virtual channel for sane behaviour. This concept is only disregarded in case of serial virtual channels: since these channels does not really have a single value at any time, but are intended to transfer data streams, multiple physical channels can be combined into one serial virtual channel. In this case, the virtual channels act like a bus system: the input of each physical channel is transferred to all other physical channels attached. Note, that there is no attempt to ensure time or other synchronisations: as soon as one device recognises input data, it is sent out to the other devices. So it is also not possible to detect collisions as on a real physical UART interface. Upper layers must be prepared to handle both situations smoothly.

Another important point is, that this concept makes it very easy to build physical bus system converters, e.g. you could feed CAN data into a serial virtual channel and output it via a RS-485 physical channel. Please keep in mind, that no logical protocol conversation is made, so this example might make only limited sense, but demonstrates the capabilities best.

Put it all together¶

As stated above, only physical channels are always available on a device. The existence of virtual channels depends on the configuration of physical channels.

You can assign a virtual channel to a physical channel, and thus create this virtual channel. Then then physical channel acts as a value source for this channel or is driven by the virtual channel’s value.

Virtual channel data is exchanged via HTTP over UDP multicast packets. When assigning virtual channel to a physical one, then you enable the generation and receiving of such multicast packets for this virtual (and thus physical) channel.

However, you are not required to assign a virtual channel to a physical one. In this case, the physical channel can not be controlled via multicast packets, nor generate multicast packet itself upon e.g. state changes.

Please also note, that the state of a virtual channel can only be queried from the device sourcing the virtual channel. This is important in the case, where packages were lost during network transmission, so it’s not possible to query a stale virtual channel state, but only get the real, actual value from the source of information. However, you can always read back the state of an assigned physical channel.

Basics¶

Depending on the firmware of the device, it might support multiple API versions.

At the moment, there exists only one API version: version 1.0.

All data is sent and received as JSON.

Root entry point¶

The root entry point for the API within the XPL devices’ URL space, is http://<device>/api.

The root entry point is used to obtain information about the API itself.

At the moment it is only possible to query the API version number. You have to issue a GET request to the root entry point to get this information:

$ curl http://<device>/api

You will receive a JSON response as follows:

{
  "version": "1.0"
}

RESTful URL mapping¶

Physical/virtual channels¶

Since our basic concept to access the device are channels, the both channel classes are reachable with http://<device>/api/channel/physical resp. http://<device>/api/channel/virtual.

So this results in the following URLs (for a device with 2 IO port, 1 CAN interface and 1 RS-232):

http://<device>/api/channel/physical

http://<device>/api/channel/physical/io

http://<device>/api/channel/physical/io/1

http://<device>/api/channel/physical/io/2

http://<device>/api/channel/physical/serial

http://<device>/api/channel/physical/serial/1

http://<device>/api/channel/physical/serial/2

Or in other words:

http://<device>/api/channel/physical/{physical_channel_class}/{physical_channel_id}

The physical URL space is always available since it reflects the hardware of a device, thus providing a way to configure the hardware and to determine its capabilities. The user has always the possibility to access an dedicated individual object or to query ‘all’ objects within the requested class.

The available virtual URL space depends on the configuration of the device:

http://<device>/api/channel/virtual/{virtual_channel_type}/{virtual_channel_id}

e.g.

http://<device>/api/channel/virtual/digital/1

http://<device>/api/channel/virtual/analog/4711

http://<device>/api/channel/virtual/serial/19

Please note, that accessing e.g. http://<device>/api/channel/virtual includes all JSON objects which could also be accessed individually via their own URL.

Note

As mentioned before, this is not true for http://<device>/api, as this URL is handled special.

Device information¶

Beside the data about channels etc., there is another API entry point to obtain data about the XPL device itself. This information is read-only and can be queried by a GET request to the URL: http://<device>/api/device

The JSON response looks like:

{
    "product": "I2XPLR4-IO600",
    "modelname": "XPL Rail",
    "hardware_version": "1.0",
    "software_version": "0.12",
    "hostname": "xpltest2",
    "mac_address": "00:01:87:FF:FF:27",
    "mac_address_plc": "00:01:87:FF:FF:26",
    "serial": "0000004711",
    "uuid": "444d5314-1000-4400-9500-000187ffff27"
}

A details description of this JSON object is given in section Device information.

Powerline network status/configuration¶

As the XPL devices are powerline devices, it’s possible to obtain some details of the powerline network from the device and to trigger some powerline related actions. This information is bundled in the ‘’/api/powerline’’ hierarchy, which consists of four sub-elements:

http://<device>/api/powerline/network

http://<device>/api/powerline/local

http://<device>/api/powerline/stations

http://<device>/api/powerline/neighbors

The ‘’network’’ property is an object which contains information about the powerline network itself. Details are explained in Powerline Network Details.

The ‘’local’’ property is a an object which contains detailed information about the current device’s powerline controller, see Powerline Local Device Details.

The ‘’stations’’ property is a an list of detected remote powerline stations. Each list entry is a powerline station object, described in Powerline Station Details.

The ‘’neighbor’’ property is a an object which accumulates all XPL neighbors, i.e. other XPL devices found in the same powerline network. See Neighbor Details.

HTTP verbs¶

The RESTful approach strives to use appropriate HTTP verbs for each action. For a XPL device, this only make limited sense: we have a fixed number of physical channels which can be configured and/or their state can be queried. However, it is not possible to delete and or create such a physical channel.

It important to realize, that only physical channels can be configured. The properties of virtual channels, or the existence of virtual channels at all, is always the result of the configuration of a physical channel. While querying properties of virtual channels is a valid access pattern, a configuration of a virtual channel is not possible.

According to the REST paradigm, querying REST objects is done via HTTP GET requests. Modifying a REST object is normally done with PUT method. On a XPL device, PUT and POST methods are handled equally.

So, to configure a dedicated physical channel, issue a PUT request to its URL.

Example to configure physical io channel 2: http://<device>/api/channel/physical/io/2

PUT /api/channel/physical/io/2 HTTP/1.1
Content-Length: 165
Content-Type: application/json
Accept: application/json

{
    "label": "My Label 2",
    "type": "do",
    "mode": "normal",
    "virtual_channel": 17,
    "level": "inverted",
    "delay_on": 0,
    "delay_off": 0,
}

On success, you will receive a JSON object in the same manner, as a GET request would give you, already with the updated configuration. If an error occurs, you’ll get a JSON error object, see below for details.

Parameters¶

When querying a RESTful object, it’s possible to filter out and/or request properties of the object. For this, a property class has been assigned to some properties.

For the JSON objects that are part of the ‘’/api/channel’’ hierarchy, there exists the property classes structual, config, state and caps (for capabilities) at the moment.

The default object view includes the classes config and state, but hides structural. You get this default view when you do not supply any of the following, optional parameters.

Parameter	Value	Meaning
filter	structural, config, state or caps	This hides the properties of the given class.
unfilter	structural, config, state or caps	This forces the properties of the given class to appear.

So for example to only query the current states of all physical channels, issue the following GET request:

$ curl http://192.168.55.57/api/channel/physical?filter=config

Another use case could be to retrieve the whole physical channel configuration (configuration backup):

$ curl http://192.168.55.57/api/channel/physical?filter=state

For the JSON objects that are part of the ‘’/api/powerline/neighbors’’ hierarchy, a property class details has been defined which is not included by default. To include these properties, supply the optional ‘’unfilter’’ parameter as described above:

$ curl http://192.168.55.57/api/powerline/neighbors?unfilter=details

JSON property details¶

Physical channels¶

As stated above, a physical channel is of a dedicated class and has an unique id. These both properties/attributes uniquely identify this channel. The channel id is defined as a unsigned integer value in the range 1-65535, because humans tend to number the natural way, e.g. starting with 1 and thus expecting the device label to number the first serial interface with 1, not as 0. So by definition, a physical channel of 0 is none-existent.

As already described above, the channel class has only two valid values: io and serial.

The possible physical channel types depend on the physical channel class:

for class serial: this is one of the strings rs485, rs422, rs232, can, mbus, wmbus, enocean

for class io: this is one of the strings di, do, s0, ai, ao

The possible physical channel modes depends on the physical channel class and type:

for class io:

type di: normal, flipflop

type do: normal, pulse

type ai: 0-10 V, 1-10 V, 0-20 mA, 4-20 mA

type ao: 0-10 V, 1-10 V

for class serial:

This is a integer, where each bit reflects whether a given service is enabled for this physical serial channel.

The property label is common to all physical channels, all other properties depend on the channel type and the hardware capabilities of the individual channel. The following list is an overview of the actual available properties:

class

Property class: structural

Availability: always

JSON datatype: string

Description: Channel class, that is serial or io.

id

Property class: structural

Availability: always

JSON datatype: number

Description: Channel’s unique ID (1-65535).

label

Property class: config

Availability: always

JSON datatype: string

Description: User-defined name/label to associate the channel with, used e.g. in the web frontend. Up to 16 characters (bytes) can be stored.

enabled

Property class: config

Availability: class serial or class io

JSON datatype: number

Description: Indicator whether this channel is used at all.

virtual_channel

Property class: config

Availability: class serial or class io

JSON datatype: number

Description: The virtual channel id of the linked virtual channel; zero by default, which menas that no virtual channel is assigned.

type

Property class: config

Availability: class serial or class io

JSON datatype: string

Description: Channel type (depends on class, see above).

supported_types

Property class: caps

Availability: class serial or class io

JSON datatype: array

Description: This array contains a list of strings which reports the hardware capabilities of the corresponding channel. This depends on the XPL device variant. The strings in this list are valid strings for the type property.

mode

Property class: config

Availability: class serial or class io

JSON datatype: string

Description: Operation mode (depends on class and type, see above).

pullup

Property class: config

Availability: class io and type di

JSON datatype: number

Description: Disable/enable an internal pull-up resistor on this channel. At the moment, the only valid values are 0 or 1.

level

Property class: config

Availability: class io and ((type di and mode normal) or (type do))

JSON datatype: string

Description: Value direct means, that a HIGH level on the wire is mapped to logical 1 (aka active high); whereas inverted means the that HIGH level is mapped to logical 0 (aka active low).

edge

Property class: config

Availability: class io and type di and mode flipflop

JSON datatype: string

Description: Edge of the signal to trigger: falling or rising.

delay_on

Property class: config

Availability: class io and type do

JSON datatype: number

Description: Delay on time (in ms).

delay_off

Property class: config

Availability: class io and type do and mode normal

JSON datatype: number

Description: Delay off time (in ms).

width

Property class: config

Availability: class io and type do and mode pulse

JSON datatype: number

Description: Pulse width (in ms).

threshold

Property class: config

Availability: class io and ((type ai) or (type di and pullup 0))

JSON datatype: number

Description: Voltage level (normalized 16-bit value) to detect the input as logical 1.

pulses_per_unit

Property class: config

Availability: class io and type s0

JSON datatype: number

Description: User-supplied value to calculate the current energy reading.

unit

Property class: config (for class io and type s0), state else

Availability: class io and (type s0 or type ai or type ao)

JSON datatype: string

Description: For a channel configured as S0 input, this is a user-supplied string up to 16 characters (bytes); for an channel configured as analog input, this is a fixed string mA or V depending on the physical capabilities/configuration of the channel.

value

Property class: state (for class io and type s0 additionally config)

Availability: class io

JSON datatype: number

Description: This is the current/actual value of this channel. For an analog or S0 channel, this is a floating point number which must be interpreted together with unit; for a digital channel, this can only have the values 0 or 1.

Note: When configuring a S0 channel and both pulse_counter and value are contained within the request, then both values must correspond to each other, otherwise the request will fail.

normalized_value

Property class: state

Availability: class io and (type ai or type ao)

JSON datatype: number

Description: This is the current/actual value of this channel, mapped into a 16-bit value, i.e. 0-65535. This way it is possible to interconnect different analog types.

pulse_counter

Property class: state and config

Availability: class io and type s0

JSON datatype: number

Description: Contains the raw value of the internal impulse counter. Note: When configuring a S0 channel and both pulse_counter and value are contained within the request, then both values must correspond to each other, otherwise the request will fail.

baudrate

Property class: config