Endpoint definition file format (XML)

Endpoint definition file format (XML)

All endpoint devices that conform to the DoIP standard publish a so-called definition file that specifies the methods, or messages, that the endpoint supports. The definition file also contains a list of possible methods a client can use to send a message to the endpoint. An example of a definition file is displayed below.

<?xml version="1.0" standalone="no" ?>
<endpoint id="CE378847" namespace="com.tjshow.leds.usp3" friendly-name="LED-strip" version="" mediation-level="0">
    <methods>
        <method id="off" friendly-name="Turn off device">
            <description></description>
            <path>/ep/basic/power/off</path>
        </method>
 
        <method id="dim" friendly-name="Dim light">
            <description></description>
            <path>/ep/basic/dim</path>
            <parameter friendly-name="Value" type="double" min="0" max="1" default="1" nature="default" />
        </method>
 
        <method id="setColor" friendly-name="Set color">
            <description></description>
            <path>/ep/basic/color/set</path>
            <parameter friendly-name="Red" type="int32" min="0" max="255" default="255" nature="default" />
            <parameter friendly-name="Green" type="int32" min="0" max="255" default="200" nature="default" />
            <parameter friendly-name="Blue" type="int32" min="0" max="255" default="9" nature="default" />
        </method>
    </methods>
 
    <transports>
        <transport type="udp" format="osc" address="" framing="" port="56271" />
    </transports>
</endpoint>

Endpoint properties

As you can see, the file is a plain XML file with an <endpoint> tag as root element. The endpoint tag describes some general stuff about the endpoint, such as identifier and a user-friendly name. The attributes for the endpoint-tag are:

Attribute name	Value
id	Contains a unique identifier for this endpoint. The identifier is not required to be unique on the whole network, but should be usable to identify a particular hardware device (i.e. use the serial number of a hardware device if it is available as the ID)
namespace	The namespace is an optional attribute that specifies the type of identifier. This is commonly used to find all devices of a certain type; i.e. if the namespace is 'bluetooth', this could indicate that the identifier can be interpreted as bluetooth address, or something like that.
friendly-name	The name of this device as it is shown to the end-user
version	The version of this endpoint definition; optional.
mediation-level	Indicates the mediation level

Method specifications

The specifications of all methods are contained in a <methods> block. There can be only one <methods> block in an endpoint. Each method is identified with a <method> tag, that has the following attributes:

Attribute name	Value
id	internal identifier of the method; has to be unique
friendly-name	Name of the method as shown to the end-user
bind-enabled	The name of the (boolean) state variable that indicates whether this method is enabled

A method tag can contain a <description> tag that contains an optional description to be shown to the end-user. Also, a method is required to contain at least one <path> tag, containing a supported message path for this method. Each method definition can contain an arbitrary number of <parameter> tags, defining the parameters that have to be sent with messages having one of the specified paths. A parameter can have the following attributes:

Attribute name	Value
friendly-name	The name of the parameter, as shown to the end-user
type	The data type of the identifier; currently supported values are int32, bool, double, string
min	The minimum value that is accepted for this parameter (optional)
max	The maximum value that is accepted for this parameter (optional)
default	The default (or current) value of this parameter
nature	Specifies the nature of the parameter (either 'discrete' or 'default'); used for choosing an appropriate user interface control for this parameter
bind-value	The state variable name to which the (current) value of this parameter is to be bound

Transport specifications

Each endpoint definition contains a single <transports> block that lists all possible connection types, or transports that the endpoint supports to accept messages. Each transport is described by a <transport> tag, which can have the following attributes:

Attribute name	Value
type	The type of the underlying connection. Currently supported are 'udp' and 'tcp' (both over IPv6 or IPv4, depending on the specified address)
format	The format of the message; currently the only supported value is 'osc' (OpenSoundControl); the message can either be an OSC message or an OSC bundle
address	The address to connect to; the format of the value depends on the connection type (for 'tcp' and 'udp', it is an IP address. If empty, client should connect to the address that was used to request the definition file
framing	The framing used (if the connection is a stream-based connection, i.e. 'tcp'). Currently, only 'slip' is supported as framing type (SLIP-framing) and is the default for 'tcp' connections. Datagram-based connections, such as 'udp' do not need framing.
port	The port number to which the connection should be made