M2MXML TM Specification Version 1.1

Table of Contents

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:
DateDescriptionAuthor Version
December 21 , 2004 Initial Release Byron K. Appelt  
March 10, 2005 First Major Release Byron K. Appelt 1.0
March 21, 2005

Made corrections to examples 4.5 and 4.6

Added description of version numbering scheme.

Byron K. Appelt 1.0.1
June 2, 2006 Second major release Byron K. Appelt 1.1

2. M2MXML TM Protocol Overview

The M2MXML TM protocol is an XML based messaging protocol designed for Machine-To-Machine (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 identifer 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.

Element Name Description Attribute Name Description Required see section
M2MXML Root Element ver M2MXML protocol version YES 3.1
td unique ID of telemetry device NO 3.1
Percept Data Point from a transducer address transducer address YES, unless nested in a PerceptBundle w/address specified  
perceptType data type, defaults to simple NO 3.4
timestamp when sampled timestamp NO 3.7
entryType     type of data entry NO 3.5
value string representation of value

YES, except complex Percept

seq sequence number NO 3.9
note textual annotation NO  
PerceptBundle Group of percepts address transducer address NO  
perceptType data type, defaults to simple NO 3.4
timestamp when sampled timestamp NO 3.7
entryType     type of data entry NO 3.5
Command command address transducer address, device level
command if not present
name type of command YES 3.3
seq sequence number YES 3.9
timestamp when issued timestamp NO 3.9
TTL time to live in minutes NO  
Response command result resultCode general result type YES 3.2
message additional message NO  
seq sequence number matching command YES 3.9
timestamp timestamp when result state reached NO 3.7
Exception event report exception code general exception type YES 3.8
message additional message NO  
Property property name property name YES  
value property value YES  

3. Element Details

3.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 for major.minor, "1.0" for example.


3.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.
0Command Successfully Executed
1Message Received by device
2Message Submitted to carrier for delivery
3Delivery Failed
4Execution Failed
5Unrecognized Command
6Bad Argument(s)
7Executed with warning

3.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 Description


name description required
requestPercept A request for data from a transducer


turnOn change digital output to active state duration pulse duration in milliseconds, permanent state change if not present NO
turnOff change digital output to inactive state duration pulse duration in milliseconds, permanent state change if not present NO
setStringOutput set the output of a string actuator data string value to be sent to actuator YES
setAnalogOutput set the output value of an analog actuator setPoint desired value YES
reboot reboot the device


queryConfiguration request configuration data Device specific names of the properties being requested are sent as properties w/o values
setConfiguration set configuration parameter(s) Device specific parameter names are sent with their desired values
reportConfig unsolicited report of config parameters Device specific parameter names are sent with their current values

3.4 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 combersome to endcode inside of XML.

Percept TypeDescriptionFormat
analog(default) single floating point valuedecimal number or IEEE754
as ASCII hex with prepended '%f' e.g. '%f1C34ABC4'
digital single Boolean value1 or 0
locationlatitude, longitude, altitudecomma delimited decimal numbers in degrees, altitude optional
stringCharacter String unspecified, can be sent as element value rather than attribute
complex unpecified, possibly XML unspecified as element value, CDATA tags encouraged

3.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.
0scheduled report (default)
1requested report
2report by exception
3manually entered data
4 actuator value report (not sensed)
5 Other

3.6 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.

3.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.

3.8 Exception Codes

Exceptions reference an exception code that is defined according to the following table.
0Hardware Failure
1Software Error / Failure
2Bad or missing sequence number
3Corrupt message

3.9 Sequence Number format

Sequence numbers are positive decimal integers ranging from 0 to 65,535.

4. Examples

4.1 Percepts

4.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" />


4.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>


4.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"/>


4.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. ]]>


4.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>


4.3 Percept Request

<M2MXML ver="1.1">
<Command name="requestPercept" address="A1" seq="123"/>

<M2MXML ver="1.1">
<Percept address="AI1" value="102.5" timestamp="1234556789" seq="123" entryType="1" />


4.4 Configuration Request and Response

<M2MXML ver="1.1">
<Command name="setConfiguration" address="AI1" seq ="321">
<Property name="reportTime" value="123456789"/>


<M2MXML ver="1.1">
<Response seq="321" resultCode="0" message="OK"/>

4.5 Configuration Request and Response, multiple parameters

<M2MXML ver="1.1">
<Command name="setConfiguration" seq="123" address="AI1">
<property name="reportTime" value="12244"/>
<property name="high" value="4095"/>


<M2MXML ver="1.1">
<Response seq="123" resultCode="6" message="unknown property 'high' "/>

4.6 Actuator turn on command

<M2MXML ver="1.1">
<Command name="turnOn" address="DO1" seq ="123"/>

<M2MXML ver="1.1">
<Response address="DO1" seq ="123" resultCode="0"/>
<Percept address="DO1" type="digital" value="1" entryType="4"/>

4.7 Actuator pulse on command

<M2MXML ver="1.1">
<Command name="turnOn" address="DO1" seq ="123"> <Property name="duration" value="1000"/> </Command>

<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"/>

4.8 Device Reboot command

<M2MXML ver="1.1">
<Command name="reboot" seq ="123"/>

<M2MXML ver="1.1">
<Response seq ="123" resultCode="0"/>

4.9 Configuration Query for actuator properties

<M2MXML ver="1.1">
<Command name="queryConfiguration" address="A1" seq="123">
<Property name="H"/>
<Property name="HH"/>


<M2MXML ver="1.1">
<Response address="A1" seq="123">
<Property name="H" value="110"/>
<Property name="HH" value="125"/>