M2MXML Protocol 1.1
M2MXML Protocol
Specification
Version 1.1
Page 1
2/6/2009
M2MXML Protocol 1.1
About This Document ......................................................................................................3
Revision History........................................................................................................3
1. M2MXML™ Protocol Overview.............................................................................3
2. Elements...............................................................................................................5
2.1. Root Element.....................................................................................................5
2.2. Responses ........................................................................................................5
2.3. Commands ........................................................................................................6
2.4. Percept Types ...................................................................................................6
2.5. Percept Entry Types..........................................................................................7
2.6. PerceptBundle...................................................................................................7
2.7. TimeStamp Format............................................................................................7
2.8. Exception Codes ...............................................................................................7
2.9. Sequence Number Format ................................................................................7
3. Examples ..............................................................................................................8
3.1. Percepts ............................................................................................................8
3.2. Percept Bundle..................................................................................................9
3.3. Percept Request................................................................................................9
3.4. Configuration Request and Response...............................................................9
3.5. Configuration Request and Response, Multiple Parameters...........................10
3.6. Actuator Turn On Command ...........................................................................10
3.7. Actuator Pulse On Command..........................................................................10
3.8. Device Reboot Command ...............................................................................11
3.9. Configuration Query For Actuator Properties ..................................................11
Page 2
2/6/2009
M2MXML Protocol 1.1
About This Document
Revision History
Releases of this document will be versioned using the following scheme:
major.minor.revision with the following definitions:
major: A large change to the protocol, possibly breaking backwards compatibility.
minor: A small change to the protocol, preserving backward compatibility.
revision: Changes made to the document only, no changes to the actual protocol.
This document has the following release history:
Date
December 21, 2004
March 10, 2005
March 21, 2005
June 2, 2006
Description
Initial Release
First Major Release
Made corrections to
examples 4.5 and 4.6
Added description of
version numbering
scheme.
Second major release
Author
Byron K. Appelt
Byron K. Appelt
Byron K. Appelt
Version
1.0
1.0.1
Byron K. Appelt
1.1
1. M2MXML™ Protocol Overview
The M2MXML protocol is an XML based messaging protocol designed for Machine-ToMachine (M2M) communications. Messages are represented as small XML documents using
the UTF-8 encoding of the unicode character set. This is a strict superset of ASCII, and in
general, M2MXML messages are pure ASCII.
For the purposes of this protocol, the world is modeled as containing telemetry devices and
transducers. Devices themselves are uniquely identified by a unique alphanumeric identifier,
the suggested form for this identifier is a 128-bit UUID represented by 32 hexadecimal
characters.
A device may have one or more transducers (sensors or actuators) that are identified with
an alphanumeric address that is unique within the device. Transducer addresses are
arbitrary strings with a maximum length of 128 characters and may contain any valid
unicode characters. However, single quotes, double quotes, and less than symbols nees to
be escaped as "'" , """ and "<" respectively. Messages may contain an
optional address attribute. If specified; this indicates that the message is intended to apply
to a transducer. If not specified, the message applies to the telemetry device. Messages
may also contain a sequence number attribute that can be used to match queries to
responses. These sequence numbers should be reasonably unique and are required in a
response if they are present in the request or query. The following table lists the valid XML
elements and associated attributes.
Page 3
2/6/2009
M2MXML Protocol 1.1
Element
Name
M2MXML
Description
Root Element
Attribute
Name
ver
td
address
perceptType
Percept
Data Point
from a
transducer
timestamp
entryType
value
seq
note
address
PerceptBundle
Group of
percepts
perceptType
timestamp
entryType
address
Command
command
name
seq
timestamp
TTL
resultCode
message
Response
command
result
seq
timestamp
Exception
Property
event report
property
exception
code
message
name
value
Description
Required
M2MXML
protocol
version
unique
ID
of
telemetry device
transducer address
YES
See
Section
3.1
NO
3.1
YES, unless
nested in a
PerceptBundle
w/address
specified
NO
3.4
NO
3.7
NO
YES, except
complex
Percept
NO
NO
NO
3.5
NO
3.4
NO
3.7
NO
3.5
data type, defaults
to simple
when sampled
timestamp
type of data entry
string representation
of value
sequence number
textual annotation
transducer address
data type, defaults
to simple
when sampled
timestamp
type of data entry
transducer address,
device level
command if not
present
type of command
sequence number
when issued
timestamp
time to live in
minutes
general result type
additional message
sequence number
matching command
timestamp when
result state reached
general exception
type
additional message
property name
property value
Page 4
3.4
3.9
NO
YES
YES
3.3
3.9
NO
3.9
NO
YES
NO
3.2
YES
3.9
NO
3.7
YES
3.8
NO
YES
YES
2/6/2009
M2MXML Protocol 1.1
2. Elements
2.1.
Root Element
The root element is the <M2MXML> element. This message contains a 'td' attribute,
which is the unique identifier of the telemetry device sending the message. The 'td'
attribute is frequently optional for messages being sent to the server from a device. This
is the case when the communications medium already uniquely identifies the sender of
data. For example, If an SMS message is sent by a device, the MIN of the device is
included in the SMS overhead and will uniquely identify the device to the server,
allowing it to add the 'td' attribute to the message upon arrival. Also, this attribute will
frequently not be present in a message sent to a device since point-to-point modes of
communication are generally used and a device only receives messages intended for it.
This element also contains a version attribute. This is the version of M2MXML in use or
the major.minor, "1.0" for example.
2.2.
Responses
Commands normally result in one or more responses from the destination entity and/or
routing entities. The responses must each contain a response code from the table below,
and may optionally contain a text message that may be very specific to the device and
condition.
Code
0
1
2
3
4
5
6
7
Description
Command Successfully Executed
Message Received by device
Message Submitted to carrier for delivery
Delivery Failed
Execution Failed
Unrecognized Command
Bad Argument(s)
Executed with warning
Page 5
2/6/2009
M2MXML Protocol 1.1
2.3.
Commands
The following table is a list of predefined command names. Devices can implement
additional commands, but may not overload these names. Commands may have any
number of arguments, which are sent as nested Property elements.
Command Name
requestPercept
turnOn
turnOff
setStringOutput
setAnalogOutput
reboot
queryConfiguration
setConfiguration
reportConfig
2.4.
Description
A request for data
from a transducer
change digital output
to active state
change digital output
to inactive state
set the output of a
string actuator
set the output value
of an analog actuator
reboot the device
request configuration
data
set configuration
parameter(s)
unsolicited report of
config parameters
Name
duration
duration
data
setPoint
Arguments
Description
none
Required
pulse duration in milliseconds,
permanent state change
if not present
pulse duration in milliseconds,
permanent state change
if not present
string value to be sent to actuator
NO
desired value
YES
NO
YES
none
Device specific names of the properties being
requested are sent as properties w/o values
Device specific parameter names are sent with their
desired values
Device specific parameter names are sent with their
current values
Percept Types
Data from a sensor or related to an actuator are reported as percepts. Data from a
percept can have one of the data types described in the table below. The format of the
value attribute depends on the percept type and is also described in the table. In the
case of a complex percept, the data is represented in the elements value, rather than in
an attribute. This allows the use of CDATA tags for either data that is itself XML, or other
data that would be cumbersome to encode inside of XML.
Percept Type
analog(default)
Description
single floating point value
digital
location
single Boolean value
latitude, longitude, altitude
string
Character String
complex
unspecified, possibly XML
Format
decimal number or IEEE754
as ASCII hex with pre-pended '%f' e.g.
'%f1C34ABC4'
digital
1 or 0
comma delimited decimal numbers in degrees,
altitude optional
unspecified, can be sent as element value rather
than attribute
unspecified as element value, CDATA tags
encouraged
Page 6
2/6/2009
M2MXML Protocol 1.1
2.5.
Percept Entry Types
Percepts also specify an attribute related to the type of entry, generally what triggered
the percept to be reported. Entry types are specified in the following table.
0
1
2
3
4
5
2.6.
scheduled report (default)
requested report
report by exception
manually entered data
actuator value report (not sensed)
other
PerceptBundle
The percept bundle is included as a convenience for reporting a group of percepts with
some common properties. One example is a group of percepts from a single address but
with different timestamps. Another example would be a set of percepts from different
addresses, but the same timestamp. Any attribute not specified on a percept inside a
bundle will be inherited from the bundle if it is specified there.
2.7.
TimeStamp Format
The format for timestamps is YYYYMMDDhhmmss where seconds are optional. The time
zone should always be UTC and expressed in 24-hour format.
2.8.
Exception Codes
Exceptions reference an exception code that is defined according to the following table.
Code
0
1
2
3
2.9.
Description
Hardware Failure
Software Error/ Failure
Bad or missing sequence number
Corrupt message
Sequence Number Format
Sequence numbers are positive decimal integers ranging from 0 to 65,535.
Page 7
2/6/2009
M2MXML Protocol 1.1
3. Examples
3.1.
Percepts
3.1.1. Basic percept, scheduled report, originating telemetry device specified explicitly
by UUID
<M2MXML ver="1.1" td="A3EAB3000C4F4323BED38BD659878DAB">
<Percept address="AI1" value="102.5" timestamp="1234556789" seq="123" />
</M2MXML>
3.1.2. String Percept, originating telemetry device specified explicitly by alternate unique ID
<M2MXML ver="1.1" td="2145551212">
<Percept perceptType="string" address="S01" timestamp="1234556789" seq="123">
Here is the value</Percept>
</M2MXML>
3.1.3. Location Percept, originating telemetry device not explicitly specified
<M2MXML ver="1.1">
<Percept perceptType="location" address="DI1" value="1.0,2.0,3.0"
timestamp="20040415120125" entryType="0" seq="123"/>
</M2MXML>
3.1.4. Complex Percept
<M2MXML ver="1.1">
<Percept perceptType="complex" address="DI1" timestamp="20040415120125"
entryType="0" seq="123">
<![CDATA[
<NONM2MXML:Element>This is data in another XML format and will not be
parsed by the M2MXML parser</NONM2MXML:Element>
This could also be UUEncoded binary data with minor
restrictions.
]]>
</M2MXML>
Page 8
2/6/2009
M2MXML Protocol 1.1
3.2.
Percept Bundle
<M2MXML ver="1.1">
<PerceptBundle address="A1">
<Percept value="102.5" timestamp="20040415080000" />
<Percept value="103.0" timestamp="20040415090000" />
<Percept value="104.5" timestamp="20040415100000" />
</PerceptBundle>
</M2MXML>
<M2MXML ver="1.1">
<PerceptBundle timestamp="20040415080000">
<Percept address="A1" value="102.5" />
<Percept address="A2" value="103.0" />
<Percept address="A3" value="104.5" />
</PerceptBundle>
</M2MXML>
3.3.
Percept Request
Request
<M2MXML ver="1.1">
<Command name="requestPercept" address="A1" seq="123"/>
</M2MXML>
Response
<M2MXML ver="1.1">
<Percept address="AI1" value="102.5" timestamp="1234556789" seq="123"
entryType="1" />
</M2MXML>
3.4.
Configuration Request and Response
Request
<M2MXML ver="1.1">
<Command name="setConfiguration" address="AI1" seq ="321">
<Property name="reportTime" value="123456789"/>
</Command>
</M2MXML>
Response
<M2MXML ver="1.1">
<Response seq="321" resultCode="0" message="OK"/>
</M2MXML>
Page 9
2/6/2009
M2MXML Protocol 1.1
3.5.
Configuration Request and Response, Multiple Parameters
Request
<M2MXML ver="1.1">
<Command name="setConfiguration" seq="123" address="AI1">
<property name="reportTime" value="12244"/>
<property name="high" value="4095"/>
</Command>
</M2MXML>
Response
<M2MXML ver="1.1">
<Response seq="123" resultCode="6" message="unknown property 'high' "/>
</M2MXML>
3.6.
Actuator Turn On Command
Request
<M2MXML ver="1.1">
<Command name="turnOn" address="DO1" seq ="123"/>
</M2MXML>
Response
<M2MXML ver="1.1">
<Response address="DO1" seq ="123" resultCode="0"/>
<Percept address="DO1" type="digital" value="1" entryType="4"/>
</M2MXML>
3.7.
Actuator Pulse On Command
Request
<M2MXML ver="1.1">
<Command name="turnOn" address="DO1" seq ="123">
<Property name="duration" value="1000"/>
</Command>
</M2MXML>
Response
<M2MXML ver="1.1">
<Response address="DO1" seq ="123" resultCode="0"/>
<Percept address="DO1" type="digital" value="1" timestamp="20040415120125"
entryType="4"/>
<Percept address="DO1" type="digital" value="0" timestamp="20040415120126"
entryType="4"/>
</M2MXML>
Page 10
2/6/2009
M2MXML Protocol 1.1
3.8.
Device Reboot Command
Request
<M2MXML ver="1.1">
<Command name="reboot" seq ="123"/>
</M2MXML>
Response
<M2MXML ver="1.1">
<Response seq ="123" resultCode="0"/>
</M2MXML>
3.9.
Configuration Query For Actuator Properties
Request
<M2MXML ver="1.1">
<Command name="queryConfiguration" address="A1" seq="123">
<Property name="H"/>
<Property name="HH"/>
</Command>
</M2MXML>
Response
<M2MXML ver="1.1">
<Response address="A1" seq="123">
<Property name="H" value="110"/>
<Property name="HH" value="125"/>
</Response>
</M2MXML>
Page 11
2/6/2009