idnits 2.17.1 draft-jennings-senml-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 20, 2012) is 4479 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE.754.1985' ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) == Outdated reference: A later version (-05) exists of draft-arkko-core-dev-urn-01 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-08 == Outdated reference: A later version (-14) exists of draft-ietf-core-link-format-09 -- Obsolete informational reference (is this intentional?): RFC 2141 (Obsoleted by RFC 8141) Summary: 4 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Jennings 3 Internet-Draft Cisco 4 Intended status: Standards Track Z. Shelby 5 Expires: July 23, 2012 Sensinode 6 J. Arkko 7 Ericsson 8 January 20, 2012 10 Media Types for Sensor Markup Language (SENML) 11 draft-jennings-senml-08 13 Abstract 15 This specification defines media types for representing simple sensor 16 measurements and device parameters in the Sensor Markup Language 17 (SenML). Representations are defined in JavaScript Object Notation 18 (JSON), eXtensible Markup Language (XML) and Efficient XML 19 Interchange (EXI), which share the common SenML data model. A simple 20 sensor, such as a temperature sensor, could use this media type in 21 protocols such as HTTP or CoAP to transport the measurements of the 22 sensor or to be configured. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on July 23, 2012. 41 Copyright Notice 43 Copyright (c) 2012 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Requirements and Design Goals . . . . . . . . . . . . . . . . 3 60 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 4. Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 5. Associating Meta-data . . . . . . . . . . . . . . . . . . . . 7 63 6. JSON Representation (application/senml+json) . . . . . . . . . 7 64 6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 6.1.1. Single Datapoint . . . . . . . . . . . . . . . . . . . 9 66 6.1.2. Multiple Datapoints . . . . . . . . . . . . . . . . . 9 67 6.1.3. Multiple Measurements . . . . . . . . . . . . . . . . 10 68 6.1.4. Collection of Resources . . . . . . . . . . . . . . . 10 69 7. XML Representation (application/senml+xml) . . . . . . . . . . 11 70 8. EXI Representation (application/senml+exi) . . . . . . . . . . 12 71 9. Usage Considerations . . . . . . . . . . . . . . . . . . . . . 14 72 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 73 10.1. Units Registry . . . . . . . . . . . . . . . . . . . . . . 15 74 10.2. Media Type Registration . . . . . . . . . . . . . . . . . 18 75 10.2.1. senml+json Media Type Registration . . . . . . . . . . 18 76 10.2.2. senml+xml Media Type Registration . . . . . . . . . . 19 77 10.2.3. senml+exi Media Type Registration . . . . . . . . . . 20 78 10.3. XML Namespace Registration . . . . . . . . . . . . . . . . 21 79 11. Security Considerations . . . . . . . . . . . . . . . . . . . 21 80 12. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 21 81 13. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 21 82 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 83 14.1. Normative References . . . . . . . . . . . . . . . . . . . 22 84 14.2. Informative References . . . . . . . . . . . . . . . . . . 22 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 87 1. Overview 89 Connecting sensors to the internet is not new, and there have been 90 many protocols designed to facilitate it. This specification defines 91 new media types for carrying simple sensor information in a protocol 92 such as HTTP or CoAP[I-D.ietf-core-coap] called the Sensor Markup 93 Language (SenML). This format was designed so that processors with 94 very limited capabilities could easily encode a sensor measurement 95 into the media type, while at the same time a server parsing the data 96 could relatively efficiently collect a large number of sensor 97 measurements. There are many types of more complex measurements and 98 measurements that this media type would not be suitable for. A 99 decision was made not to carry most of the meta data about the sensor 100 in this media type to help reduce the size of the data and improve 101 efficiency in decoding. Instead meta-data about a sensor resource 102 can be described out-of-band using the CoRE Link Format 103 [I-D.ietf-core-link-format]. The markup language can be used for a 104 variety of data flow models, most notably data feeds pushed from a 105 sensor to a collector, and the web resource model where the sensor is 106 requested as a resource representation (GET /sensor/temperature). 108 SenML is defined by a data model for measurements and simple meta- 109 data about measurements and devices. The data is structured as a 110 single object (with attributes) that contains an array of entries. 111 Each entry is an object that has attributes such as a unique 112 identifier for the sensor, the time the measurement was made, and the 113 current value. Serializations for this data model are defined for 114 JSON [RFC4627], XML and Efficient XML Interchange (EXI) 115 [W3C.REC-exi-20110310]. 117 For example, the following shows a measurement from a temperature 118 gauge encoded in the JSON syntax. 119 {"e":[{ "n": "urn:dev:ow:10e2073a01080063", "v":23.5, "u":"degC" }]} 121 In the example above, the array in the object has a single 122 measurement for a sensor named "urn:dev:ow:10e2073a01080063" with a 123 temperature of 23.5 degrees Celsius. 125 2. Requirements and Design Goals 127 The design goal is to be able to send simple sensor measurements in 128 small packets on mesh networks from large numbers of constrained 129 devices. Keeping the total size under 80 bytes makes this easy to 130 use on a wireless mesh network. It is always difficult to define 131 what small code is, but there is a desire to be able to implement 132 this in roughly 1 KB of flash on a 8 bit microprocessor. Experience 133 with Google power meter and large scale deployments has indicated 134 that the solution needs to support allowing multiple measurements to 135 be batched into a single HTTP or CoAP request. This "batch" upload 136 capability allows the server side to efficiently support a large 137 number of devices. It also conveniently supports batch transfers 138 from proxies and storage devices, even in situations where the sensor 139 itself sends just a single data item at a time. The multiple 140 measurements could be from multiple related sensors or from the same 141 sensor but at different times. 143 3. Terminology 145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 147 document are to be interpreted as described in RFC 2119 [RFC2119]. 149 4. Semantics 151 Each representation caries a single SenML object that represents a 152 set of measurements and/or parameters. This object contains several 153 optional attributes described below and a mandatory array of one or 154 more entries. 156 Base Name 158 This is a string that is prepended to the names found in the 159 entries. This attribute is optional. 161 Base Time 163 A base time that is added to the time found in an entry. This 164 attribute is optional. 166 Base Units 168 A base unit that is assumed for all entries, unless otherwise 169 indicated. This attribute is optional. Acceptable values are 170 specified in Section 10.1. 172 Version 174 Version number of media type format. This attribute is optional 175 positive integer and defaults to 1 if not present. 177 Measurement or Parameter Entries 179 Array of values for sensor measurements or other generic 180 parameters (such as configuration parameters). If present there 181 must be at least one entry in the array. 183 Each array entry contains several attributes, some of which are 184 optional and some of which are mandatory. 186 Name 188 Name of the sensor or parameter. When appended to the Base Name 189 attribute, this must result in a globally unique identifier for 190 the resource. The name is optional, if the Base Name is present. 191 If the name is missing Base Name must uniquely identify the 192 resource. This can be used to represent a large array of 193 measurements from the same sensor without having to repeat its 194 identifier on every measurement. 196 Units 198 Units for a measurement value. Optional, if Base Unit is present 199 or if not required for a parameter. Acceptable values are 200 specified in Section 10.1. 202 Value 204 Value of the entry. Optional if a Sum value is present, otherwise 205 required. Values are represented using three basic data types, 206 Floating point numbers ("v" field for "Value"), Booleans ("bv" for 207 "Boolean Value") and Strings ("sv" for "String Value"). Exactly 208 one of these three fields MUST appear. 210 Sum 212 Integrated sum of the values over time. Optional. This attribute 213 is in the units specified in the Unit value multiplied by seconds. 215 Time 217 Time when value was recorded. Optional. 219 Update Time 221 Update time. A time in seconds that represents the maximum time 222 before this sensor will provide an updated reading for a 223 measurement. This can be used to detect the failure of sensors or 224 communications path from the sensor. Optional. 226 The SenML format can be extended with further custom attributes 227 placed in the base object, or in an entry. Extensions in the base 228 object pertain to all entries, whereas extensions in an entry object 229 only pertain to that. 231 Systems reading one of the objects MUST check for the Version 232 attribute. If this value is a version number larger than the version 233 which the system understands, the system SHOULD NOT use this object. 234 This allows the version number to indicate that the object contains 235 mandatory to understand attributes. New version numbers can only be 236 defined in RFC which updates this specification or it successors. 238 The Name value is concatenated to the Base Name value to get the name 239 of the sensor. The resulting name needs to uniquely identify and 240 differentiate the sensor from all others. If the object is a 241 representation resulting from the request of a URI [RFC3986], then in 242 the absence of the Base Name attribute, this URI is used as the 243 default value of Base Name. Thus in this case the Name field needs 244 to be unique for that URI, for example an index or subresource name 245 of sensors handled by the URI. 247 Alternatively, for objects not related to a URI, a unique name is 248 required. In any case, it is RECOMMENDED that the full names are 249 represented as URIs or URNs [RFC2141]. One way to create a unique 250 name is to include a EUI-48 or EUI-64 identifier (A MAC address) or 251 some other bit string that is guaranteed uniqueness (such as a 1-wire 252 address) that is assigned to the device. Some of the examples in 253 this draft use the device URN type as specified in 254 [I-D.arkko-core-dev-urn]. UUIDs [RFC4122] are another way to 255 generate a unique name. 257 The resulting concatenated name MUST consist only of characters out 258 of the set "A" to "Z", "a" to "z", "0" to "9", "-", ":", ".", or "_" 259 and it MUST start with a character out of the set "A" to "Z", "a" to 260 "z", or "0" to "9". This restricted character set was chosen so that 261 these names can be directly used as in other types of URI including 262 segments of an HTTP path with no special encoding. [RFC5952] 263 contains advice on encoding an IPv6 address in a name. 265 If either the Base Time or Time value is missing, the missing 266 attribute is considered to have a value of zero. The Base Time and 267 Time values are added together to get the time of measurement. A 268 time of zero indicates that the sensor does not know the absolute 269 time and the measurement was made roughly "now". A negative value is 270 used to indicate seconds in the past from roughly "now". A positive 271 value is used to indicate the number of seconds, excluding leap 272 seconds, since the start of the year 1970 in UTC . 274 Representing the statistical characteristics of measurements can be 275 very complex. Future specification may add new attributes to provide 276 better information about the statistical properties of the 277 measurement. 279 5. Associating Meta-data 281 SenML is designed to carry the minimum dynamic information about 282 measurements, and for efficiency reasons does not carry more static 283 meta-data about the device, object or sensors. Instead, it is 284 assumed that this meta-data is carried out of band. For web 285 resources using SenML representations, this meta-data can be made 286 available using the CoRE Link Format [I-D.ietf-core-link-format]. 288 The CoRE Link Format provides a simple way to describe Web Links, and 289 in particular allows a web server to describe resources it is 290 hosting. The list of links that a web server has available, can be 291 discovered by retrieving the /.well-known/core resource, which 292 returns the list of links in the CoRE Link Format. Each link may 293 contain attributes, for example title, resource type, interface 294 description and content-type. 296 The most obvious use of this link format is to describe that a 297 resource is available in a SenML format in the first place. The 298 relevant media type indicator is included in the Content-Type (ct=) 299 attribute. 301 Further semantics about a resource can be included in the Resource 302 Type and Interface Description attributes. The Resource Type (rt=) 303 attribute is meant to give a semantic meaning to that resource. For 304 example rt="OutdoorTemperature" would indicate static semantic 305 meaning in addition to the unit information included in SenML. The 306 Interface Description (if=) attribute is used to describe the REST 307 interface of a resource, and may include e.g. a reference to a WADL 308 description [WADL]. 310 6. JSON Representation (application/senml+json) 312 Root variables: 314 +---------------------------+------+--------+ 315 | SenML | JSON | Type | 316 +---------------------------+------+--------+ 317 | Base Name | bn | String | 318 | Base Time | bt | Number | 319 | Base Units | bu | Number | 320 | Version | ver | Number | 321 | Measurement or Parameters | e | Array | 322 +---------------------------+------+--------+ 324 Measurement or Parameter Entries: 326 +---------------+------+----------------+ 327 | SenML | JSON | Notes | 328 +---------------+------+----------------+ 329 | Name | n | String | 330 | Units | u | String | 331 | Value | v | Floating point | 332 | String Value | sv | String | 333 | Boolean Value | bv | Boolean | 334 | Value Sum | s | Floating point | 335 | Time | t | Number | 336 | Update Time | ut | Number | 337 +---------------+------+----------------+ 339 All of the data is UTF-8, but since this is for machine to machine 340 communications on constrained systems, only characters with code 341 points between U+0001 and U+007F are allowed which corresponds to the 342 ASCII[RFC0020] subset of UTF-8. 344 The root contents MUST consist of exactly one JSON object as 345 specified by [RFC4627]. This object MAY contain a "bn" attribute 346 with a value of type string. This object MAY contain a "bt" 347 attribute with a value of type number. The object MAY contain a "bu" 348 attribute with a value of type string. The object MAY contain a 349 "ver" attribute with a value of type number. The object MAY contain 350 other attribute value pairs, and the object MUST contain exactly one 351 "e" attribute with a value of type array. The array MUST have one or 352 more measurement or parameter objects. 354 Inside each measurement or parameter object the "n", "u", and "sv" 355 attributes are of type string, the "t" and "ut" attributes are of 356 type number, the "bv" attribute is of type boolean, and the "v" and 357 "s" attributes are of type floating point. All the attributes are 358 optional, but as specified in Section 4, one of the "v", "sv", or 359 "bv" attributes MUST appear unless the "s" attribute is also present. 360 The "v", and "sv", and "bv" attributes MUST NOT appear together. 362 Systems receiving measurements MUST be able to process the range of 363 floating point numbers that are representable as an IEEE double- 364 precision floating-point numbers [IEEE.754.1985]. The number of 365 significant digits in any measurement is not relevant, so a reading 366 of 1.1 has exactly the same semantic meaning as 1.10. If the value 367 has an exponent, the "e" MUST be in lower case. The mantissa SHOULD 368 be less than 19 characters long and the exponent SHOULD be less than 369 5 characters long. This allows time values to have better than micro 370 second precision over the next 100 years. 372 6.1. Examples 374 6.1.1. Single Datapoint 376 The following shows a temperature reading taken approximately "now" 377 by a 1-wire sensor device that was assigned the unique 1-wire address 378 of 10e2073a01080063: 380 {"e":[{ "n": "urn:dev:ow:10e2073a01080063", "v":23.5 }]} 382 6.1.2. Multiple Datapoints 384 The following example shows voltage and current now, i.e., at an 385 unspecified time. The device has an EUI-64 MAC address of 386 0024befffe804ff1. 388 {"e":[ 389 { "n": "voltage", "t": 0, "u": "V", "v": 120.1 }, 390 { "n": "current", "t": 0, "u": "A", "v": 1.2 }], 391 "bn": "urn:dev:mac:0024befffe804ff1/" 392 } 394 The next example is similar to the above one, but shows current at 395 Tue Jun 8 18:01:16 UTC 2010 and at each second for the previous 5 396 seconds. 398 {"e":[ 399 { "n": "voltage", "u": "V", "v": 120.1 }, 400 { "n": "current", "t": -5, "v": 1.2 }, 401 { "n": "current", "t": -4, "v": 1.30 }, 402 { "n": "current", "t": -3, "v": 0.14e1 }, 403 { "n": "current", "t": -2, "v": 1.5 }, 404 { "n": "current", "t": -1, "v": 1.6 }, 405 { "n": "current", "t": 0, "v": 1.7 }], 406 "bn": "urn:dev:mac:0024befffe804ff1/", 407 "bt": 1276020076, 408 "ver": 1, 409 "bu": "A" 411 } 413 6.1.3. Multiple Measurements 415 The following example shows humidity measurements from a mobile 416 device with an IPv6 address 2001:db8::1, starting at Mon Oct 31 13: 417 24:24 UTC 2011. The device also provide position data, which is 418 provided in the same measurement or parameter array as separate 419 entries. Note time is used to for correlating data that belongs 420 together, e.g., a measurement and a parameter associated with it. 421 Finally, the device also reports extra data about its battery status 422 at a separate time. 424 {"e":[ 425 { "v": 20.0, "t": 0 }, 426 { "sv": "E 24' 30.621", "u": "lon", "t": 0 }, 427 { "sv": "N 60' 7.965", "u": "lat", "t": 0 }, 428 { "v": 20.3, "t": 60 }, 429 { "sv": "E 24' 30.622", "u": "lon", "t": 60 }, 430 { "sv": "N 60' 7.965", "u": "lat", "t": 60 }, 431 { "v": 20.7, "t": 120 }, 432 { "sv": "E 24' 30.623", "u": "lon", "t": 120 }, 433 { "sv": "N 60' 7.966", "u": "lat", "t": 120 }, 434 { "v": 98.0, "u": "%EL", "t": 150 }, 435 { "v": 21.2, "t": 180 }, 436 { "sv": "E 24' 30.628", "u": "lon", "t": 180 }, 437 { "sv": "N 60' 7.967", "u": "lat", "t": 180 }], 438 "bn": "http://[2001:db8::1]", 439 "bt": 1320067464, 440 "bu": "%RH" 441 } 443 6.1.4. Collection of Resources 445 The following example shows how to query one device that can provide 446 multiple measurements. The example assumes that a client has fetched 447 information from a device at 2001:db8::2 by performing a GET 448 operation on http://[2001:db8::2] at Mon Oct 31 16:27:09 UTC 2011, 449 and has gotten two separate values as a result, a temperature and 450 humidity measurement. 452 {"e":[ 453 { "n": "temperature", "v": 27.2, "u": "degC" }, 454 { "n": "humidity", "v": 80, "u": "%RH" }], 455 "bn": "http://[2001:db8::2]/", 456 "bt": 1320078429, 457 "ver": 1 458 } 460 7. XML Representation (application/senml+xml) 462 A SenML object can also be represented in XML format as defined in 463 this section. The following example shows an XML example for the 464 same sensor measurement as in Section 6.1.2. 466 467 472 474 476 478 480 482 484 486 488 The RelaxNG schema for the XML is: 490 default namespace = "urn:ietf:params:xml:ns:senml" 491 namespace rng = "http://relaxng.org/ns/structure/1.0" 493 e = element e { 494 attribute n { xsd:string }?, 495 attribute u { xsd:string }?, 496 attribute v { xsd:float }?, 497 attribute sv { xsd:string }?, 498 attribute bv { xsd:boolean }?, 499 attribute s { xsd:decimal }?, 500 attribute t { xsd:integer }?, 501 attribute ut { xsd:integer }?, 502 p* 503 } 505 senml = 506 element senml { 507 attribute bn { xsd:string }?, 508 attribute bt { xsd:integer }?, 509 attribute bu { xsd:string }?, 510 attribute ver { xsd:integer }?, 511 e* 512 } 514 start = senml 516 8. EXI Representation (application/senml+exi) 518 For efficient transmission of SenML over e.g. a constrained network, 519 Efficient XML Interchange (EXI) can be used. This encodes the XML 520 Schema structure of SenML into binary tags and values rather than 521 ASCII text. An EXI representation of SenML SHOULD be made using the 522 strict schema-mode of EXI. This mode however does not allow tag 523 extensions to the schema, and therefore any extensions will be lost 524 in the encoding. For uses where extensions need to be preserved in 525 EXI, the non-strict schema mode of EXI MAY be used. 527 The EXI header option MUST be included. An EXI schemaID options MUST 528 be set to value of "a" indicating the scheme provided in this 529 specification. Future revisions to the schema can change this 530 schemaID to allow for backwards compatibility. When the data will be 531 transported over COAP or HTTP, an EXI Cookie SHOULD NOT be used as it 532 simply makes things larger as is redundant to information provided in 533 the Content-Type header. 535 The following XSD Schema is generated from the RelaxNG and used for 536 strict schema guided EXI processing. 538 539 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 569 The following shows a hexdump of the EXI produced from encoding the 570 following XML example. Note that while this example is similar to 571 the first example in Section 6.1.2 in JSON format. 573 574 576 577 578 580 Which compresses to the following displayed in hexdump: 582 00000000 a0 30 0d 85 01 d7 57 26 e3 a6 46 57 63 a6 f7 73 583 00000010 a3 13 06 53 23 03 73 36 13 03 13 03 83 03 03 63 584 00000020 36 21 2e cd ed 8e 8c 2c ec a8 00 00 d5 95 88 4c 585 00000030 02 08 4b 1b ab 93 93 2b 73 a2 00 00 34 14 19 00 586 00000040 c0 588 The above example used the bit packed form of EXI but it is also 589 possible to use a byte packed form of EXI which can makes it easier 590 for a simple sensor to produce valid EXI without really implementing 591 EXI. Consider the example of a temperature sensor that produces a 592 value in tenths of degrees Celsius over a range of 0.0 to 55.0. = It 593 would produce XML SenML file such as: 595 596 598 599 601 The compressed form, using the byte alignment option of EXI, for the 602 above XML is the following: 604 00000000 a00048806c200200 1d75726e3a646576 |..H.l ...urn:dev| 605 00000010 3a6f773a31306532 3037336130313038 |:ow:10e2073a0108| 606 00000020 3030363303010674 656d700306646567 |0063...temp..deg| 607 00000030 430100e701010001 02 |C........| 609 A small temperature sensor devices that only generates this one EXI 610 file does not really need an full EXI implementation. It can simple 611 hard code the output replacing the one wire device ID starting at 612 byte 0x14 and going to byte 0x23 with it's device ID , and replacing 613 the value "0xe7 0x01" at location 0x33 to 0x34 with the current 614 temperature. The EXI Specification[W3C.REC-exi-20110310] contains 615 the full information on how floating point numbers are represented, 616 but for the purpose of this sensor, the temperature can be converted 617 to an integer in tenths of degrees ( 231 in this example ). EXI 618 stores 7 bits of the integer in each byte with the top bit set to one 619 if there are further bytes. So the first bytes at location 0x33 is 620 set to low 7 bits of the integer temperature in tenths of degrees 621 plus 0x80. In this example 231 & 0x7F + 0x80 = 0xE7. The second 622 byte at location 0x34 is set to the integer temperature in tenths of 623 degrees right shifted 7 bits. In this example 231 >> 7 = 0x01. 625 9. Usage Considerations 627 The measurements support sending both the current value of a sensor 628 as well as the an integrated sum. For many types of measurements, 629 the sum is more useful than the current value. For example, an 630 electrical meter that measures the energy a given computer uses will 631 typically want to measure the cumulative amount of energy used. This 632 is less prone to error than reporting the power each second and 633 trying to have something on the server side sum together all the 634 power measurements. If the network between the sensor and the meter 635 goes down over some period of time, when it comes back up, the 636 cumulative sum helps reflect what happened while the network was 637 down. A meter like this would typically report a measurement with 638 the units set to watts, but it would put the sum of energy used in 639 the "s" attribute of the measurement. It might optionally include 640 the current power in the "v" attribute. 642 While the benefit of using the integrated sum is fairly clear for 643 measurements like power and energy, it is less obvious for something 644 like temperature. Reporting the sum of the temperature makes it easy 645 to compute averages even when the individual temperature values are 646 not reported frequently enough to compute accurate averages. 647 Implementors are encouraged to report the cumulative sum as well as 648 the raw value of a given sensor. 650 Applications that use the cumulative sum values need to understand 651 they are very loosely defined by this specification, and depending on 652 the particular sensor implementation may behave in unexpected ways. 653 Applications should be able to deal with the following issues: 655 1. Many sensors will allow the cumulative sums to "wrap" back to 656 zero after the value gets sufficiently large. 657 2. Some sensors will reset the cumulative sum back to zero when the 658 device is reset, loses power, or is replaced with a different 659 sensor. 660 3. Applications cannot make assumptions about when the device 661 started accumulating values into the sum. 663 Typically applications can make some assumptions about specific 664 sensors that will allow them to deal with these problems. A common 665 assumption is that for sensors whose measurement values are always 666 positive, the sum should never get smaller; so if the sum does get 667 smaller, the application will know that one of the situations listed 668 above has happened. 670 10. IANA Considerations 672 Note to RFC Editor: Please replace all occurrences of "RFC-AAAA" 673 with the RFC number of this specification. 675 10.1. Units Registry 677 IANA will create a registry of unit symbols. The primary purpose of 678 this registry is to make sure that symbols uniquely map to give type 679 of measurement. Definitions for many of these units can be found in 681 [NIST822] and [BIPM]. 683 +--------+----------------------------------------------+-----------+ 684 | Symbol | Description | Reference | 685 +--------+----------------------------------------------+-----------+ 686 | m | meter | RFC-AAAA | 687 | kg | kilogram | RFC-AAAA | 688 | s | second | RFC-AAAA | 689 | A | ampere | RFC-AAAA | 690 | K | kelvin | RFC-AAAA | 691 | cd | candela | RFC-AAAA | 692 | mol | mole | RFC-AAAA | 693 | Hz | hertz | RFC-AAAA | 694 | rad | radian | RFC-AAAA | 695 | sr | steradian | RFC-AAAA | 696 | N | newton | RFC-AAAA | 697 | Pa | pascal | RFC-AAAA | 698 | J | joule | RFC-AAAA | 699 | W | watt | RFC-AAAA | 700 | C | coulomb | RFC-AAAA | 701 | V | volt | RFC-AAAA | 702 | F | farad | RFC-AAAA | 703 | Ohm | ohm | RFC-AAAA | 704 | S | siemens | RFC-AAAA | 705 | Wb | weber | RFC-AAAA | 706 | T | tesla | RFC-AAAA | 707 | H | henry | RFC-AAAA | 708 | degC | degrees Celsius | RFC-AAAA | 709 | lm | lumen | RFC-AAAA | 710 | lx | lux | RFC-AAAA | 711 | Bq | becquerel | RFC-AAAA | 712 | Gy | gray | RFC-AAAA | 713 | Sv | sievert | RFC-AAAA | 714 | kat | katal | RFC-AAAA | 715 | pH | pH acidity | RFC-AAAA | 716 | % | Value of a switch. A value of 0.0 indicates | RFC-AAAA | 717 | | the switch is off while 100.0 indicates on. | | 718 | count | counter value | RFC-AAAA | 719 | %RH | Relative Humidity | RFC-AAAA | 720 | m2 | area | RFC-AAAA | 721 | l | volume in liters | RFC-AAAA | 722 | m/s | velocity | RFC-AAAA | 723 | m/s2 | acceleration | RFC-AAAA | 724 | l/s | flow rate in liters per second | RFC-AAAA | 725 | W/m2 | irradiance | RFC-AAAA | 726 | cd/m2 | luminance | RFC-AAAA | 727 | Bspl | bel sound pressure level | RFC-AAAA | 728 | bit/s | bits per second | RFC-AAAA | 729 | lat | degrees latitude. Assumed to be in WGS84 | RFC-AAAA | 730 | | unless another reference frame is known for | | 731 | | the sensor. | | 732 | lon | degrees longitude. Assumed to be in WGS84 | RFC-AAAA | 733 | | unless another reference frame is known for | | 734 | | the sensor. | | 735 | %EL | remaining battery energy level in percents | RFC-AAAA | 736 | EL | remaining battery energy level in seconds | RFC-AAAA | 737 | beet/m | Heart rate in beets per minute | RFC-AAAA | 738 | beets | Cumulative number of heart beats | RFC-AAAA | 739 +--------+----------------------------------------------+-----------+ 741 New entries can be added to the registration by either Expert Review 742 or IESG Approval as defined in [RFC5226]. Experts should exercise 743 their own good judgment but need to consider the following 744 guidelines: 746 1. There needs to be a real and compelling use for any new unit to 747 be added. 748 2. Units should define the semantic information and be chosen 749 carefully. Implementors need to remember that the same word may 750 be used in different real-life contexts. For example, degrees 751 when measuring latitude have no semantic relation to degrees 752 when measuring temperature; thus two different units are needed. 753 3. These measurements are produced by computers for consumption by 754 computers. The principle is that conversion has to be easily be 755 done when both reading and writing the media type. The value of 756 a single canonical representation outweighs the convenience of 757 easy human representations or loss of precision in a conversion. 758 4. Use of SI prefixes such as "k" before the unit is not allowed. 759 Instead one can represent the value using scientific notation 760 such a 1.2e3. 761 5. For a given type of measurement, there will only be one unit 762 type defined. So for length, meters are defined and other 763 lengths such as mile, foot, light year are not allowed. For 764 most cases, the SI unit is preferred. 765 6. Symbol names that could be easily confused with existing common 766 units or units combined with prefixes should be avoided. For 767 example, selecting a unit name of "mph" to indicate something 768 that had nothing to do with velocity would be a bad choice, as 769 "mph" is commonly used to mean miles per hour. 770 7. The following should not be used because the are common SI 771 prefixes: Y, Z, E, P, T, G, M, k, h, da, d, c, n, u, p, f, a, 772 z, y, Ki, Mi, Gi, Ti, Pi, Ei, Zi, Yi. 773 8. The following units should not be used as they are commonly used 774 to represent other measurements Ky, Gal, dyn, etg, P, St, Mx, G, 775 Oe, Gb, sb, Lmb, ph, Ci, R, RAD, REM, gal, bbl, qt, degF, Cal, 776 BTU, HP, pH, B/s, psi, Torr, atm, at, bar, kWh. 778 9. The unit names are case sensitive and the correct case needs to 779 be used, but symbols that differ only in case should not be 780 allocated. 781 10. A number after a unit typically indicates the previous unit 782 raised to that power, and the / indicates that the units that 783 follow are the reciprocal. A unit should have only one / in the 784 name. 786 10.2. Media Type Registration 788 The following registrations are done following the procedure 789 specified in [RFC4288] and [RFC3023]. 791 Note to RFC Editor: Please replace all occurrences of "RFC-AAAA" 792 with the RFC number of this specification. 794 10.2.1. senml+json Media Type Registration 796 Type name: application 798 Subtype name: senml+json 800 Required parameters: none 802 Optional parameters: none 804 Encoding considerations: Must be encoded as using a subset of the 805 encoding allowed in [RFC4627]. Specifically, only the ASCII[RFC0020] 806 subset of the UTF-8 characters are allowed. This simplifies 807 implementation of very simple system and does not impose any 808 significant limitations as all this data is meant for machine to 809 machine communications and is not meant to be human readable. 811 Security considerations: Sensor data can contain a wide range of 812 information ranging from information that is very public, such the 813 outside temperature in a given city, to very private information that 814 requires integrity and confidentiality protection, such as patient 815 health information. This format does not provide any security and 816 instead relies on the transport protocol that carries it to provide 817 security. Given applications need to look at the overall context of 818 how this media type will be used to decide if the security is 819 adequate. 821 Interoperability considerations: Applications should ignore any JSON 822 key value pairs that they do not understand. This allows backwards 823 compatibility extensions to this specification. The "ver" field can 824 be used to ensure the receiver supports a minimal level of 825 functionality needed by the creator of the JSON object. 827 Published specification: RFC-AAAA 829 Applications that use this media type: The type is used by systems 830 that report electrical power usage and environmental information such 831 as temperature and humidity. It can be used for a wide range of 832 sensor reporting systems. 834 Additional information: 836 Magic number(s): none 838 File extension(s): senml 840 Macintosh file type code(s): none 842 Person & email address to contact for further information: Cullen 843 Jennings 845 Intended usage: COMMON 847 Restrictions on usage: None 849 Author: Cullen Jennings 851 Change controller: IESG 853 10.2.2. senml+xml Media Type Registration 855 Type name: application 857 Subtype name: senml+xml 859 Required parameters: none 861 Optional parameters: none 863 Encoding considerations: TBD 865 Security considerations: TBD 867 Interoperability considerations: TBD 869 Published specification: RFC-AAAA 871 Applications that use this media type: TBD 873 Additional information: 875 Magic number(s): none 877 File extension(s): senml 879 Macintosh file type code(s): none 881 Person & email address to contact for further information: Cullen 882 Jennings 884 Intended usage: COMMON 886 Restrictions on usage: None 888 Author: Cullen Jennings 890 Change controller: IESG 892 10.2.3. senml+exi Media Type Registration 894 Type name: application 896 Subtype name: senml+exi 898 Required parameters: none 900 Optional parameters: none 902 Encoding considerations: TBD 904 Security considerations: TBD 906 Interoperability considerations: TBD 908 Published specification: RFC-AAAA 910 Applications that use this media type: TBD 912 Additional information: 914 Magic number(s): none 916 File extension(s): senml 918 Macintosh file type code(s): none 920 Person & email address to contact for further information: Cullen 921 Jennings 922 Intended usage: COMMON 924 Restrictions on usage: None 926 Author: Cullen Jennings 928 Change controller: IESG 930 10.3. XML Namespace Registration 932 This document registers the following XML name paces in the IETF XML 933 registry defined in [RFC3688]. 935 URI: urn:ietf:params:xml:ns:senml 937 Registrant Contact: The IESG. 939 XML: N/A, the requested URIs are XML namespaces 941 11. Security Considerations 943 See Section 12.Further discussion of security proprieties can be 944 found in Section 10.2. 946 12. Privacy Considerations 948 Sensor data can range from information with almost no security 949 considerations, such as the current temperature in a given city, to 950 highly sensitive medical or location data. This specification 951 provides no security protection for the data but is meant to be used 952 inside another container or transport protocol such as S/MIME or HTTP 953 with TLS that can provide integrity, confidentiality, and 954 authentication information about the source of the data. 956 13. Acknowledgement 958 We would like to thank Lisa Dusseault, Joe Hildebrand, Lyndsay 959 Campbell, Martin Thomson, John Klensin, Bjoern Hoehrmann, and Carsten 960 Bormann for their review comments. 962 14. References 963 14.1. Normative References 965 [IEEE.754.1985] 966 Institute of Electrical and Electronics Engineers, 967 "Standard for Binary Floating-Point Arithmetic", 968 IEEE Standard 754, August 1985. 970 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 971 Requirement Levels", BCP 14, RFC 2119, March 1997. 973 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 974 Types", RFC 3023, January 2001. 976 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 977 January 2004. 979 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 980 Registration Procedures", BCP 13, RFC 4288, December 2005. 982 [RFC4627] Crockford, D., "The application/json Media Type for 983 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 985 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 986 IANA Considerations Section in RFCs", BCP 26, May 2008. 988 [W3C.REC-exi-20110310] 989 Kamiya, T. and J. Schneider, "Efficient XML Interchange 990 (EXI) Format 1.0", World Wide Web Consortium 991 Recommendation REC-exi-20110310, March 2011, 992 . 994 14.2. Informative References 996 [BIPM] Bureau International des Poids et Mesures, "The 997 International System of Units (SI)", 8th edition, 2006 . 999 [I-D.arkko-core-dev-urn] 1000 Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource 1001 Names for Device Identifiers", draft-arkko-core-dev-urn-01 1002 (work in progress), October 2011. 1004 [I-D.ietf-core-coap] 1005 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 1006 "Constrained Application Protocol (CoAP)", 1007 draft-ietf-core-coap-08 (work in progress), October 2011. 1009 [I-D.ietf-core-link-format] 1010 Shelby, Z., "CoRE Link Format", 1011 draft-ietf-core-link-format-09 (work in progress), 1012 November 2011. 1014 [NIST822] Thompson, A. and B. Taylor, "Guide for the Use of the 1015 International System of Units (SI)", NIST Special 1016 Publication 811, 2008 Edition . 1018 [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, 1019 October 1969. 1021 [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. 1023 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1024 Resource Identifier (URI): Generic Syntax", STD 66, 1025 RFC 3986, January 2005. 1027 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1028 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1029 July 2005. 1031 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1032 Address Text Representation", RFC 5952, August 2010. 1034 [WADL] Hadley, M., "Web Application Description Language (WADL)", 1035 2009, . 1038 Authors' Addresses 1040 Cullen Jennings 1041 Cisco 1042 170 West Tasman Drive 1043 San Jose, CA 95134 1044 USA 1046 Phone: +1 408 421-9990 1047 Email: fluffy@cisco.com 1048 Zach Shelby 1049 Sensinode 1050 Kidekuja 2 1051 Vuokatti 88600 1052 FINLAND 1054 Phone: +358407796297 1055 Email: zach@sensinode.com 1057 Jari Arkko 1058 Ericsson 1059 Jorvas 02420 1060 Finland 1062 Email: jari.arkko@piuha.net