M2MXML TM Version 1.0.1 Specification

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

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 UUID of telemetry device NO 3.1
Percept Data Point from a transducer address transducer address YES  
perceptType data type, defaults to simple NO 3.4
timestamp when sampled timestamp NO 3.6
entryType     type of data entry NO 3.7
value string representation of value YES 3.4
seq sequence number NO 3.8
Command command address transducer address, device level
command if not present		 NO  
name type of command YES 3.3
seq sequence number YES 3.8
timestamp when issued timestamp NO 3.6
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.8
timestamp timestamp when result state reached NO 3.6
Exception event report exception code general exception type YES 3.7
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.
codedescription
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

Arguments
name description required
requestPercept A request for data from a transducer

none
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

none
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

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.

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

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 TimeStamp Format

The format for timestamps is YYYYMMDDhhmmss where seconds are optional. The time zone should always be UTC.

3.7 Exception Codes

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

3.8 Sequence Number format

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

4. Examples

4.1 Basic percept, scheduled report, originating telemetry device specified explicitly 

<M2MXML ver="1.0" td="A3EAB3000C4F4323BED38BD659878DAB">
   <Percept address="AI1" value="102.5" timestamp="1234556789" seq="123" />
</M2MXML>

4.2 Percept Request

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

Response: 
<M2MXML ver="1.0">
   <Percept address="AI1" value="102.5" timestamp="1234556789" seq="123" />
</M2MXML>

4.3 Location Percept

<M2MXML ver="1.0">
   <Percept perceptType="location" address="DI1" value="1.0,2.0,3.0" timestamp="20040415120125" entryType="0" seq="123"/>
</M2MXML>

4.4 Configuration Request and Response

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

Response: 

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

4.5 Configuration Request and Response, multiple parameters

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

Response: 

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

4.6 Actuator turn on command

Request: 
<M2MXML ver="1.0">
   <Command name="turnOn" address="DO1" seq ="123"/>
</M2MXML>

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

4.7 Actuator pulse on command

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

Response: 
<M2MXML ver="1.0">
   <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>

4.8 Device Reboot command

Request: 
<M2MXML ver="1.0">
   <Command name="reboot" seq ="123"/>
</M2MXML>

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

4.9 Configuration Query for actuator properties

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

Response: 

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