idnits 2.17.1 draft-jennings-core-senml-01.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 (July 6, 2015) is 3217 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. 'BIPM' -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE.754.1985' -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST822' ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'UCUM' == Outdated reference: A later version (-05) exists of draft-arkko-core-dev-urn-03 -- Obsolete informational reference (is this intentional?): RFC 2141 (Obsoleted by RFC 8141) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 6 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: January 7, 2016 ARM 6 J. Arkko 7 A. Keranen 8 Ericsson 9 July 6, 2015 11 Media Types for Sensor Markup Language (SENML) 12 draft-jennings-core-senml-01 14 Abstract 16 This specification defines media types for representing simple sensor 17 measurements and device parameters in the Sensor Markup Language 18 (SenML). Representations are defined in JavaScript Object Notation 19 (JSON), Concise Binary Object Representation (CBOR), eXtensible 20 Markup Language (XML), and Efficient XML Interchange (EXI), which 21 share the common SenML data model. A simple sensor, such as a 22 temperature sensor, could use this media type in protocols such as 23 HTTP or CoAP to transport the measurements of the sensor or to be 24 configured. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 7, 2016. 43 Copyright Notice 45 Copyright (c) 2015 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Requirements and Design Goals . . . . . . . . . . . . . . . . 3 62 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 4. Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 5. Associating Meta-data . . . . . . . . . . . . . . . . . . . . 7 65 6. JSON Representation (application/senml+json) . . . . . . . . 7 66 6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 9 67 6.1.1. Single Datapoint . . . . . . . . . . . . . . . . . . 9 68 6.1.2. Multiple Datapoints . . . . . . . . . . . . . . . . . 9 69 6.1.3. Multiple Measurements . . . . . . . . . . . . . . . . 10 70 6.1.4. Collection of Resources . . . . . . . . . . . . . . . 11 71 7. CBOR Representation (application/senml+cbor) . . . . . . . . 11 72 8. XML Representation (application/senml+xml) . . . . . . . . . 12 73 9. EXI Representation (application/senml-exi) . . . . . . . . . 13 74 10. Usage Considerations . . . . . . . . . . . . . . . . . . . . 16 75 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 76 11.1. Units Registry . . . . . . . . . . . . . . . . . . . . . 17 77 11.2. Media Type Registration . . . . . . . . . . . . . . . . 19 78 11.2.1. senml+json Media Type Registration . . . . . . . . . 20 79 11.2.2. senml+cbor Media Type Registration . . . . . . . . . 21 80 11.2.3. senml+xml Media Type Registration . . . . . . . . . 22 81 11.2.4. senml-exi Media Type Registration . . . . . . . . . 22 82 11.3. XML Namespace Registration . . . . . . . . . . . . . . . 23 83 12. Security Considerations . . . . . . . . . . . . . . . . . . . 24 84 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 24 85 14. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 24 86 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 87 15.1. Normative References . . . . . . . . . . . . . . . . . . 24 88 15.2. Informative References . . . . . . . . . . . . . . . . . 25 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 91 1. Overview 93 Connecting sensors to the internet is not new, and there have been 94 many protocols designed to facilitate it. This specification defines 95 new media types for carrying simple sensor information in a protocol 96 such as HTTP or CoAP [RFC7252] called the Sensor Markup Language 97 (SenML). This format was designed so that processors with very 98 limited capabilities could easily encode a sensor measurement into 99 the media type, while at the same time a server parsing the data 100 could relatively efficiently collect a large number of sensor 101 measurements. There are many types of more complex measurements and 102 measurements that this media type would not be suitable for. A 103 decision was made not to carry most of the meta data about the sensor 104 in this media type to help reduce the size of the data and improve 105 efficiency in decoding. Instead meta-data about a sensor resource 106 can be described out-of-band using the CoRE Link Format [RFC6690]. 107 The markup language can be used for a variety of data flow models, 108 most notably data feeds pushed from a sensor to a collector, and the 109 web resource model where the sensor is requested as a resource 110 representation (GET /sensor/temperature). 112 SenML is defined by a data model for measurements and simple meta- 113 data about measurements and devices. The data is structured as a 114 single object (with attributes) that contains an array of entries. 115 Each entry is an object that has attributes such as a unique 116 identifier for the sensor, the time the measurement was made, and the 117 current value. Serializations for this data model are defined for 118 JSON [RFC7159], CBOR [RFC7049], XML, and Efficient XML Interchange 119 (EXI) [W3C.REC-exi-20110310]. 121 For example, the following shows a measurement from a temperature 122 gauge encoded in the JSON syntax. 124 {"e":[{ "n": "urn:dev:ow:10e2073a01080063", "v":23.5, "u":"Cel" }]} 126 In the example above, the array in the object has a single 127 measurement for a sensor named "urn:dev:ow:10e2073a01080063" with a 128 temperature of 23.5 degrees Celsius. 130 2. Requirements and Design Goals 132 The design goal is to be able to send simple sensor measurements in 133 small packets on mesh networks from large numbers of constrained 134 devices. Keeping the total size of payload under 80 bytes makes this 135 easy to use on a wireless mesh network. It is always difficult to 136 define what small code is, but there is a desire to be able to 137 implement this in roughly 1 KB of flash on a 8 bit microprocessor. 138 Experience with Google power meter and large scale deployments has 139 indicated that the solution needs to support allowing multiple 140 measurements to be batched into a single HTTP or CoAP request. This 141 "batch" upload capability allows the server side to efficiently 142 support a large number of devices. It also conveniently supports 143 batch transfers from proxies and storage devices, even in situations 144 where the sensor itself sends just a single data item at a time. The 145 multiple measurements could be from multiple related sensors or from 146 the same sensor but at different times. 148 3. Terminology 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 152 document are to be interpreted as described in RFC 2119 [RFC2119]. 154 4. Semantics 156 Each representation carries a single SenML object that represents a 157 set of measurements and/or parameters. This object contains several 158 optional attributes described below and a mandatory array of one or 159 more entries. 161 Base Name 163 This is a string that is prepended to the names found in the 164 entries. This attribute is optional. 166 Base Time 168 A base time that is added to the time found in an entry. This 169 attribute is optional. 171 Base Units 173 A base unit that is assumed for all entries, unless otherwise 174 indicated. This attribute is optional. 176 Version 178 Version number of media type format. This attribute is optional 179 positive integer and defaults to 1 if not present. 181 Measurement or Parameter Entries 183 Array of values for sensor measurements or other generic 184 parameters (such as configuration parameters). If present there 185 must be at least one entry in the array. 187 Each array entry contains several attributes, some of which are 188 optional and some of which are mandatory. 190 Name 192 Name of the sensor or parameter. When appended to the Base Name 193 attribute, this must result in a globally unique identifier for 194 the resource. The name is optional, if the Base Name is present. 195 If the name is missing, Base Name must uniquely identify the 196 resource. This can be used to represent a large array of 197 measurements from the same sensor without having to repeat its 198 identifier on every measurement. 200 Units 202 Units for a measurement value. 204 Value 206 Value of the entry. Optional if a Sum value is present, otherwise 207 required. Values are represented using three basic data types, 208 Floating point numbers ("v" field for "Value"), Booleans ("bv" for 209 "Boolean Value") and Strings ("sv" for "String Value"). Exactly 210 one of these three fields MUST appear. 212 Sum 214 Integrated sum of the values over time. Optional. This attribute 215 is in the units specified in the Unit value multiplied by seconds. 217 Time 219 Time when value was recorded. Optional. 221 Update Time 223 A time in seconds that represents the maximum time before this 224 sensor will provide an updated reading for a measurement. This 225 can be used to detect the failure of sensors or communications 226 path from the sensor. Optional. 228 The SenML format can be extended with further custom attributes 229 placed in the base object, or in an entry. Extensions in the base 230 object pertain to all entries, whereas extensions in an entry object 231 only pertain to that. 233 Systems reading one of the objects MUST check for the Version 234 attribute. If this value is a version number larger than the version 235 which the system understands, the system SHOULD NOT use this object. 236 This allows the version number to indicate that the object contains 237 mandatory to understand attributes. New version numbers can only be 238 defined in an RFC that updates this specification or it successors. 240 The Name value is concatenated to the Base Name value to get the name 241 of the sensor. The resulting name needs to uniquely identify and 242 differentiate the sensor from all others. If the object is a 243 representation resulting from the request of a URI [RFC3986], then in 244 the absence of the Base Name attribute, this URI is used as the 245 default value of Base Name. Thus in this case the Name field needs 246 to be unique for that URI, for example an index or subresource name 247 of sensors handled by the URI. 249 Alternatively, for objects not related to a URI, a unique name is 250 required. In any case, it is RECOMMENDED that the full names are 251 represented as URIs or URNs [RFC2141]. One way to create a unique 252 name is to include a EUI-48 or EUI-64 identifier (A MAC address) or 253 some other bit string that is guaranteed uniqueness (such as a 1-wire 254 address) that is assigned to the device. Some of the examples in 255 this draft use the device URN type as specified in 256 [I-D.arkko-core-dev-urn]. UUIDs [RFC4122] are another way to 257 generate a unique name. 259 The resulting concatenated name MUST consist only of characters out 260 of the set "A" to "Z", "a" to "z", "0" to "9", "-", ":", ".", or "_" 261 and it MUST start with a character out of the set "A" to "Z", "a" to 262 "z", or "0" to "9". This restricted character set was chosen so that 263 these names can be directly used as in other types of URI including 264 segments of an HTTP path with no special encoding. [RFC5952] 265 contains advice on encoding an IPv6 address in a name. 267 If either the Base Time or Time value is missing, the missing 268 attribute is considered to have a value of zero. The Base Time and 269 Time values are added together to get the time of measurement. A 270 time of zero indicates that the sensor does not know the absolute 271 time and the measurement was made roughly "now". A negative value is 272 used to indicate seconds in the past from roughly "now". A positive 273 value is used to indicate the number of seconds, excluding leap 274 seconds, since the start of the year 1970 in UTC. 276 Representing the statistical characteristics of measurements can be 277 very complex. Future specification may add new attributes to provide 278 better information about the statistical properties of the 279 measurement. 281 5. Associating Meta-data 283 SenML is designed to carry the minimum dynamic information about 284 measurements, and for efficiency reasons does not carry more static 285 meta-data about the device, object or sensors. Instead, it is 286 assumed that this meta-data is carried out of band. For web 287 resources using SenML representations, this meta-data can be made 288 available using the CoRE Link Format [RFC6690]. 290 The CoRE Link Format provides a simple way to describe Web Links, and 291 in particular allows a web server to describe resources it is 292 hosting. The list of links that a web server has available, can be 293 discovered by retrieving the /.well-known/core resource, which 294 returns the list of links in the CoRE Link Format. Each link may 295 contain attributes, for example title, resource type, interface 296 description and content-type. 298 The most obvious use of this link format is to describe that a 299 resource is available in a SenML format in the first place. The 300 relevant media type indicator is included in the Content-Type (ct=) 301 attribute. 303 Further semantics about a resource can be included in the Resource 304 Type and Interface Description attributes. The Resource Type (rt=) 305 attribute is meant to give a semantic meaning to that resource. For 306 example rt="outdoor-temperature" would indicate static semantic 307 meaning in addition to the unit information included in SenML. The 308 Interface Description (if=) attribute is used to describe the REST 309 interface of a resource, and may include e.g. a reference to a WADL 310 description [WADL]. 312 6. JSON Representation (application/senml+json) 314 Root variables: 316 +---------------------------+------+--------+ 317 | SenML | JSON | Type | 318 +---------------------------+------+--------+ 319 | Base Name | bn | String | 320 | Base Time | bt | Number | 321 | Base Units | bu | Number | 322 | Version | ver | Number | 323 | Measurement or Parameters | e | Array | 324 +---------------------------+------+--------+ 326 Measurement or Parameter Entries: 328 +---------------+------+----------------+ 329 | SenML | JSON | Notes | 330 +---------------+------+----------------+ 331 | Name | n | String | 332 | Units | u | String | 333 | Value | v | Floating point | 334 | String Value | sv | String | 335 | Boolean Value | bv | Boolean | 336 | Value Sum | s | Floating point | 337 | Time | t | Number | 338 | Update Time | ut | Number | 339 +---------------+------+----------------+ 341 It is RECOMMENDED that in textual JSON format, when present, the 342 attributes appear in the above order. However, implementations MUST 343 be able to process them in any order. 345 All of the data is UTF-8, but since this is for machine to machine 346 communications on constrained systems, only characters with code 347 points between U+0001 and U+007F are allowed which corresponds to the 348 ASCII[RFC0020] subset of UTF-8. 350 The root contents MUST consist of exactly one JSON object as 351 specified by [RFC7159]. This object MAY contain a "bn" attribute 352 with a value of type string. This object MAY contain a "bt" 353 attribute with a value of type number. The object MAY contain a "bu" 354 attribute with a value of type string. The object MAY contain a 355 "ver" attribute with a value of type number. The object MAY contain 356 other attribute value pairs, and the object MUST contain exactly one 357 "e" attribute with a value of type array. The array MUST have one or 358 more measurement or parameter objects. 360 Inside each measurement or parameter object the "n", "u", and "sv" 361 attributes are of type string, the "t" and "ut" attributes are of 362 type number, the "bv" attribute is of type boolean, and the "v" and 363 "s" attributes are of type floating point. All the attributes are 364 optional, but as specified in Section 4, one of the "v", "sv", or 365 "bv" attributes MUST appear unless the "s" attribute is also present. 366 The "v", and "sv", and "bv" attributes MUST NOT appear together. 368 Systems receiving measurements MUST be able to process the range of 369 floating point numbers that are representable as an IEEE double- 370 precision floating-point numbers [IEEE.754.1985]. The number of 371 significant digits in any measurement is not relevant, so a reading 372 of 1.1 has exactly the same semantic meaning as 1.10. If the value 373 has an exponent, the "e" MUST be in lower case. The mantissa SHOULD 374 be less than 19 characters long and the exponent SHOULD be less than 375 5 characters long. This allows time values to have better than micro 376 second precision over the next 100 years. 378 6.1. Examples 380 6.1.1. Single Datapoint 382 The following shows a temperature reading taken approximately "now" 383 by a 1-wire sensor device that was assigned the unique 1-wire address 384 of 10e2073a01080063: 386 {"e":[{ "n": "urn:dev:ow:10e2073a01080063", "v":23.5 }]} 388 6.1.2. Multiple Datapoints 390 The following example shows voltage and current now, i.e., at an 391 unspecified time. The device has an EUI-64 MAC address of 392 0024befffe804ff1. 394 {"bn": "urn:dev:mac:0024befffe804ff1/", 395 "e":[ 396 { "n": "voltage", "t": 0, "u": "V", "v": 120.1 }, 397 { "n": "current", "t": 0, "u": "A", "v": 1.2 }] 398 } 400 The next example is similar to the above one, but shows current at 401 Tue Jun 8 18:01:16 UTC 2010 and at each second for the previous 5 402 seconds. 404 {"bn": "urn:dev:mac:0024befffe804ff1/", 405 "bt": 1276020076, 406 "bu": "A", 407 "ver": 1, 408 "e":[ 409 { "n": "voltage", "u": "V", "v": 120.1 }, 410 { "n": "current", "t": -5, "v": 1.2 }, 411 { "n": "current", "t": -4, "v": 1.30 }, 412 { "n": "current", "t": -3, "v": 0.14e1 }, 413 { "n": "current", "t": -2, "v": 1.5 }, 414 { "n": "current", "t": -1, "v": 1.6 }, 415 { "n": "current", "t": 0, "v": 1.7 }] 416 } 418 Note that in some usage scenarios of SenML the implementations MAY 419 store or transmit SenML in a stream-like fashion, where data is 420 collected over time and continuously added to the object. This mode 421 of operation is optional, but systems or protocols using SenML in 422 this fashion MUST specify that they are doing this. In this 423 situation the SenML stream can be sent and received in a partial 424 fashion, i.e., a measurement entry can be read as soon as it is 425 received and only not when the entire SenML object is complete. 427 For instance, the following stream of measurements may be sent from 428 the producer of a SenML object to the consumer of that SenML object, 429 and each measurement object may be reported at the time it arrives: 431 {"bn": "http://[2001:db8::1]", 432 "bt": 1320067464, 433 "bu": "%RH", 434 "e":[ 435 { "v": 21.2, "t": 0 }, 436 { "v": 21.3, "t": 10 }, 437 { "v": 21.4, "t": 20 }, 438 { "v": 21.4, "t": 30 }, 439 { "v": 21.5, "t": 40 }, 440 { "v": 21.5, "t": 50 }, 441 { "v": 21.5, "t": 60 }, 442 { "v": 21.6, "t": 70 }, 443 { "v": 21.7, "t": 80 }, 444 { "v": 21.5, "t": 90 }, 445 ... 447 6.1.3. Multiple Measurements 449 The following example shows humidity measurements from a mobile 450 device with an IPv6 address 2001:db8::1, starting at Mon Oct 31 451 13:24:24 UTC 2011. The device also provides position data, which is 452 provided in the same measurement or parameter array as separate 453 entries. Note time is used to for correlating data that belongs 454 together, e.g., a measurement and a parameter associated with it. 455 Finally, the device also reports extra data about its battery status 456 at a separate time. 458 {"bn": "http://[2001:db8::1]", 459 "bt": 1320067464, 460 "bu": "%RH", 461 "e":[ 462 { "v": 20.0, "t": 0 }, 463 { "sv": "E 24' 30.621", "u": "lon", "t": 0 }, 464 { "sv": "N 60' 7.965", "u": "lat", "t": 0 }, 465 { "v": 20.3, "t": 60 }, 466 { "sv": "E 24' 30.622", "u": "lon", "t": 60 }, 467 { "sv": "N 60' 7.965", "u": "lat", "t": 60 }, 468 { "v": 20.7, "t": 120 }, 469 { "sv": "E 24' 30.623", "u": "lon", "t": 120 }, 470 { "sv": "N 60' 7.966", "u": "lat", "t": 120 }, 471 { "v": 98.0, "u": "%EL", "t": 150 }, 472 { "v": 21.2, "t": 180 }, 473 { "sv": "E 24' 30.628", "u": "lon", "t": 180 }, 474 { "sv": "N 60' 7.967", "u": "lat", "t": 180 }] 475 } 477 6.1.4. Collection of Resources 479 The following example shows how to query one device that can provide 480 multiple measurements. The example assumes that a client has fetched 481 information from a device at 2001:db8::2 by performing a GET 482 operation on http://[2001:db8::2] at Mon Oct 31 16:27:09 UTC 2011, 483 and has gotten two separate values as a result, a temperature and 484 humidity measurement. 486 {"bn": "http://[2001:db8::2]/", 487 "bt": 1320078429, 488 "ver": 1, 489 "e":[ 490 { "n": "temperature", "v": 27.2, "u": "Cel" }, 491 { "n": "humidity", "v": 80, "u": "%RH" }] 492 } 494 7. CBOR Representation (application/senml+cbor) 496 The CBOR [RFC7049] representation is equivalent to the JSON 497 representation, with the following changes: 499 o For compactness, the CBOR representation uses integers for the map 500 keys defined in Figure 1. This table is conclusive, i.e., there 501 is no intention to define any additional integer map keys; any 502 extensions will use string map keys. 504 o For JSON Numbers, the CBOR representation can use integers, 505 floating point numbers, or decimal fractions (CBOR Tag 4); the 506 common limitations of JSON implementations are not relevant for 507 these. For the version number, however, only an unsigned integer 508 is allowed. 510 +---------------------------+------------+------------+ 511 | Name | JSON label | CBOR label | 512 +---------------------------+------------+------------+ 513 | Version | ver | -1 | 514 | Measurement or Parameters | e | -2 | 515 | Base Name | bn | -3 | 516 | Base Time | bt | -4 | 517 | Base Units | bu | -5 | 518 | Name | n | 0 | 519 | Units | u | 1 | 520 | Value | v | 2 | 521 | String Value | sv | 3 | 522 | Boolean Value | bv | 4 | 523 | Value Sum | s | 5 | 524 | Time | t | 6 | 525 | Update Time | ut | 7 | 526 +---------------------------+------------+------------+ 528 Figure 1: CBOR representation: integers for map keys 530 8. XML Representation (application/senml+xml) 532 A SenML object can also be represented in XML format as defined in 533 this section. The following example shows an XML example for the 534 same sensor measurement as in Section 6.1.2. 536 537 541 542 543 544 545 546 547 548 550 The RelaxNG schema for the XML is: 552 default namespace = "urn:ietf:params:xml:ns:senml" 553 namespace rng = "http://relaxng.org/ns/structure/1.0" 555 e = element e { 556 attribute n { xsd:string }?, 557 attribute u { xsd:string }?, 558 attribute v { xsd:float }?, 559 attribute sv { xsd:string }?, 560 attribute bv { xsd:boolean }?, 561 attribute s { xsd:decimal }?, 562 attribute t { xsd:int }?, 563 attribute ut { xsd:int }?, 564 p* 565 } 567 senml = 568 element senml { 569 attribute bn { xsd:string }?, 570 attribute bt { xsd:int }?, 571 attribute bu { xsd:string }?, 572 attribute ver { xsd:int }?, 573 e* 574 } 576 start = senml 578 9. EXI Representation (application/senml-exi) 580 For efficient transmission of SenML over e.g. a constrained network, 581 Efficient XML Interchange (EXI) can be used. This encodes the XML 582 Schema structure of SenML into binary tags and values rather than 583 ASCII text. An EXI representation of SenML SHOULD be made using the 584 strict schema-mode of EXI. This mode however does not allow tag 585 extensions to the schema, and therefore any extensions will be lost 586 in the encoding. For uses where extensions need to be preserved in 587 EXI, the non-strict schema mode of EXI MAY be used. 589 The EXI header option MUST be included. An EXI schemaID options MUST 590 be set to the value of "a" indicating the scheme provided in this 591 specification. Future revisions to the schema can change this 592 schemaID to allow for backwards compatibility. When the data will be 593 transported over CoAP or HTTP, an EXI Cookie SHOULD NOT be used as it 594 simply makes things larger and is redundant to information provided 595 in the Content-Type header. 597 The following XSD Schema is generated from the RelaxNG and used for 598 strict schema guided EXI processing. 600 601 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 The following shows a hexdump of the EXI produced from encoding the 631 following XML example. Note that while this example is similar to 632 the first example in Section 6.1.2 in JSON format. 634 635 637 638 639 641 Which compresses to the following displayed in hexdump: 643 00000000 a0 30 0d 85 01 d7 57 26 e3 a6 46 57 63 a6 f7 73 644 00000010 a3 13 06 53 23 03 73 36 13 03 13 03 83 03 03 63 645 00000020 36 21 2e cd ed 8e 8c 2c ec a8 00 00 d5 95 88 4c 646 00000030 02 08 4b 1b ab 93 93 2b 73 a2 00 00 34 14 19 00 647 00000040 c0 649 The above example used the bit packed form of EXI but it is also 650 possible to use a byte packed form of EXI which can makes it easier 651 for a simple sensor to produce valid EXI without really implementing 652 EXI. Consider the example of a temperature sensor that produces a 653 value in tenths of degrees Celsius over a range of 0.0 to 55.0. It 654 would produce XML SenML file such as: 656 657 659 660 662 The compressed form, using the byte alignment option of EXI, for the 663 above XML is the following: 665 00000000 a00048806c200200 1d75726e3a646576 |..H.l ...urn:dev| 666 00000010 3a6f773a31306532 3037336130313038 |:ow:10e2073a0108| 667 00000020 3030363303010674 656d700306646567 |0063...temp..deg| 668 00000030 430100e701010001 02 |C........| 670 A small temperature sensor devices that only generates this one EXI 671 file does not really need an full EXI implementation. It can simple 672 hard code the output replacing the one wire device ID starting at 673 byte 0x14 and going to byte 0x23 with it's device ID, and replacing 674 the value "0xe7 0x01" at location 0x33 to 0x34 with the current 675 temperature. The EXI Specification [W3C.REC-exi-20110310] contains 676 the full information on how floating point numbers are represented, 677 but for the purpose of this sensor, the temperature can be converted 678 to an integer in tenths of degrees (231 in this example ). EXI 679 stores 7 bits of the integer in each byte with the top bit set to one 680 if there are further bytes. So the first bytes at location 0x33 is 681 set to low 7 bits of the integer temperature in tenths of degrees 682 plus 0x80. In this example 231 & 0x7F + 0x80 = 0xE7. The second 683 byte at location 0x34 is set to the integer temperature in tenths of 684 degrees right shifted 7 bits. In this example 231 >> 7 = 0x01. 686 10. Usage Considerations 688 The measurements support sending both the current value of a sensor 689 as well as the an integrated sum. For many types of measurements, 690 the sum is more useful than the current value. For example, an 691 electrical meter that measures the energy a given computer uses will 692 typically want to measure the cumulative amount of energy used. This 693 is less prone to error than reporting the power each second and 694 trying to have something on the server side sum together all the 695 power measurements. If the network between the sensor and the meter 696 goes down over some period of time, when it comes back up, the 697 cumulative sum helps reflect what happened while the network was 698 down. A meter like this would typically report a measurement with 699 the units set to watts, but it would put the sum of energy used in 700 the "s" attribute of the measurement. It might optionally include 701 the current power in the "v" attribute. 703 While the benefit of using the integrated sum is fairly clear for 704 measurements like power and energy, it is less obvious for something 705 like temperature. Reporting the sum of the temperature makes it easy 706 to compute averages even when the individual temperature values are 707 not reported frequently enough to compute accurate averages. 708 Implementors are encouraged to report the cumulative sum as well as 709 the raw value of a given sensor. 711 Applications that use the cumulative sum values need to understand 712 they are very loosely defined by this specification, and depending on 713 the particular sensor implementation may behave in unexpected ways. 714 Applications should be able to deal with the following issues: 716 1. Many sensors will allow the cumulative sums to "wrap" back to 717 zero after the value gets sufficiently large. 719 2. Some sensors will reset the cumulative sum back to zero when the 720 device is reset, loses power, or is replaced with a different 721 sensor. 723 3. Applications cannot make assumptions about when the device 724 started accumulating values into the sum. 726 Typically applications can make some assumptions about specific 727 sensors that will allow them to deal with these problems. A common 728 assumption is that for sensors whose measurement values are always 729 positive, the sum should never get smaller; so if the sum does get 730 smaller, the application will know that one of the situations listed 731 above has happened. 733 11. IANA Considerations 735 Note to RFC Editor: Please replace all occurrences of "RFC-AAAA" with 736 the RFC number of this specification. 738 11.1. Units Registry 740 IANA will create a registry of unit symbols. The primary purpose of 741 this registry is to make sure that symbols uniquely map to give type 742 of measurement. Definitions for many of these units can be found in 743 [NIST822] and [BIPM]. 745 In addition to the units in this table, any of the Unified Code for 746 Units of Measure [UCUM] in case sensitive form (c/s column) can be 747 prepended by the string "UCUM:" and used in SenML. 749 +--------+----------------------------------------------+-----------+ 750 | Symbol | Description | Reference | 751 +--------+----------------------------------------------+-----------+ 752 | m | meter | RFC-AAAA | 753 | kg | kilogram | RFC-AAAA | 754 | s | second | RFC-AAAA | 755 | A | ampere | RFC-AAAA | 756 | K | kelvin | RFC-AAAA | 757 | cd | candela | RFC-AAAA | 758 | mol | mole | RFC-AAAA | 759 | Hz | hertz | RFC-AAAA | 760 | rad | radian | RFC-AAAA | 761 | sr | steradian | RFC-AAAA | 762 | N | newton | RFC-AAAA | 763 | Pa | pascal | RFC-AAAA | 764 | J | joule | RFC-AAAA | 765 | W | watt | RFC-AAAA | 766 | C | coulomb | RFC-AAAA | 767 | V | volt | RFC-AAAA | 768 | F | farad | RFC-AAAA | 769 | Ohm | ohm | RFC-AAAA | 770 | S | siemens | RFC-AAAA | 771 | Wb | weber | RFC-AAAA | 772 | T | tesla | RFC-AAAA | 773 | H | henry | RFC-AAAA | 774 | Cel | degrees Celsius | RFC-AAAA | 775 | lm | lumen | RFC-AAAA | 776 | lx | lux | RFC-AAAA | 777 | Bq | becquerel | RFC-AAAA | 778 | Gy | gray | RFC-AAAA | 779 | Sv | sievert | RFC-AAAA | 780 | kat | katal | RFC-AAAA | 781 | pH | pH acidity | RFC-AAAA | 782 | % | Value of a switch. A value of 0.0 indicates | RFC-AAAA | 783 | | the switch is off while 100.0 indicates on. | | 784 | count | counter value | RFC-AAAA | 785 | %RH | Relative Humidity | RFC-AAAA | 786 | m2 | area | RFC-AAAA | 787 | l | volume in liters | RFC-AAAA | 788 | m/s | velocity | RFC-AAAA | 789 | m/s2 | acceleration | RFC-AAAA | 790 | l/s | flow rate in liters per second | RFC-AAAA | 791 | W/m2 | irradiance | RFC-AAAA | 792 | cd/m2 | luminance | RFC-AAAA | 793 | Bspl | bel sound pressure level | RFC-AAAA | 794 | bit/s | bits per second | RFC-AAAA | 795 | lat | degrees latitude. Assumed to be in WGS84 | RFC-AAAA | 796 | | unless another reference frame is known for | | 797 | | the sensor. | | 798 | lon | degrees longitude. Assumed to be in WGS84 | RFC-AAAA | 799 | | unless another reference frame is known for | | 800 | | the sensor. | | 801 | %EL | remaining battery energy level in percents | RFC-AAAA | 802 | EL | remaining battery energy level in seconds | RFC-AAAA | 803 | beat/m | Heart rate in beats per minute | RFC-AAAA | 804 | beats | Cumulative number of heart beats | RFC-AAAA | 805 +--------+----------------------------------------------+-----------+ 807 New entries can be added to the registration by either Expert Review 808 or IESG Approval as defined in [RFC5226]. Experts should exercise 809 their own good judgment but need to consider the following 810 guidelines: 812 1. There needs to be a real and compelling use for any new unit to 813 be added. 815 2. Units should define the semantic information and be chosen 816 carefully. Implementors need to remember that the same word may 817 be used in different real-life contexts. For example, degrees 818 when measuring latitude have no semantic relation to degrees 819 when measuring temperature; thus two different units are needed. 821 3. These measurements are produced by computers for consumption by 822 computers. The principle is that conversion has to be easily be 823 done when both reading and writing the media type. The value of 824 a single canonical representation outweighs the convenience of 825 easy human representations or loss of precision in a conversion. 827 4. Use of SI prefixes such as "k" before the unit is not allowed. 828 Instead one can represent the value using scientific notation 829 such a 1.2e3. 831 5. For a given type of measurement, there will only be one unit 832 type defined. So for length, meters are defined and other 833 lengths such as mile, foot, light year are not allowed. For 834 most cases, the SI unit is preferred. 836 6. Symbol names that could be easily confused with existing common 837 units or units combined with prefixes should be avoided. For 838 example, selecting a unit name of "mph" to indicate something 839 that had nothing to do with velocity would be a bad choice, as 840 "mph" is commonly used to mean miles per hour. 842 7. The following should not be used because the are common SI 843 prefixes: Y, Z, E, P, T, G, M, k, h, da, d, c, n, u, p, f, a, z, 844 y, Ki, Mi, Gi, Ti, Pi, Ei, Zi, Yi. 846 8. The following units should not be used as they are commonly used 847 to represent other measurements Ky, Gal, dyn, etg, P, St, Mx, G, 848 Oe, Gb, sb, Lmb, ph, Ci, R, RAD, REM, gal, bbl, qt, degF, Cal, 849 BTU, HP, pH, B/s, psi, Torr, atm, at, bar, kWh. 851 9. The unit names are case sensitive and the correct case needs to 852 be used, but symbols that differ only in case should not be 853 allocated. 855 10. A number after a unit typically indicates the previous unit 856 raised to that power, and the / indicates that the units that 857 follow are the reciprocal. A unit should have only one / in the 858 name. 860 11.2. Media Type Registration 862 The following registrations are done following the procedure 863 specified in [RFC6838] and [RFC7303]. 865 Note to RFC Editor: Please replace all occurrences of "RFC-AAAA" with 866 the RFC number of this specification. 868 11.2.1. senml+json Media Type Registration 870 Type name: application 872 Subtype name: senml+json 874 Required parameters: none 876 Optional parameters: none 878 Encoding considerations: Must be encoded as using a subset of the 879 encoding allowed in [RFC7159]. Specifically, only the ASCII 880 [RFC0020] subset of the UTF-8 characters are allowed. This 881 simplifies implementation of very simple system and does not impose 882 any significant limitations as all this data is meant for machine to 883 machine communications and is not meant to be human readable. 885 Security considerations: Sensor data can contain a wide range of 886 information ranging from information that is very public, such the 887 outside temperature in a given city, to very private information that 888 requires integrity and confidentiality protection, such as patient 889 health information. This format does not provide any security and 890 instead relies on the transport protocol that carries it to provide 891 security. Given applications need to look at the overall context of 892 how this media type will be used to decide if the security is 893 adequate. 895 Interoperability considerations: Applications should ignore any JSON 896 key value pairs that they do not understand. This allows backwards 897 compatibility extensions to this specification. The "ver" field can 898 be used to ensure the receiver supports a minimal level of 899 functionality needed by the creator of the JSON object. 901 Published specification: RFC-AAAA 903 Applications that use this media type: The type is used by systems 904 that report electrical power usage and environmental information such 905 as temperature and humidity. It can be used for a wide range of 906 sensor reporting systems. 908 Additional information: 910 Magic number(s): none 912 File extension(s): senml 914 Macintosh file type code(s): none 915 Person & email address to contact for further information: Cullen 916 Jennings 918 Intended usage: COMMON 920 Restrictions on usage: None 922 Author: Cullen Jennings 924 Change controller: IESG 926 11.2.2. senml+cbor Media Type Registration 928 Type name: application 930 Subtype name: senml+cbor 932 Required parameters: none 934 Optional parameters: none 936 Encoding considerations: TBD 938 Security considerations: TBD 940 Interoperability considerations: TBD 942 Published specification: RFC-AAAA 944 Applications that use this media type: The type is used by systems 945 that report electrical power usage and environmental information such 946 as temperature and humidity. It can be used for a wide range of 947 sensor reporting systems. 949 Additional information: 951 Magic number(s): none 953 File extension(s): senml 955 Macintosh file type code(s): none 957 Person & email address to contact for further information: Cullen 958 Jennings 960 Intended usage: COMMON 962 Restrictions on usage: None 963 Author: Cullen Jennings 965 Change controller: IESG 967 11.2.3. senml+xml Media Type Registration 969 Type name: application 971 Subtype name: senml+xml 973 Required parameters: none 975 Optional parameters: none 977 Encoding considerations: TBD 979 Security considerations: TBD 981 Interoperability considerations: TBD 983 Published specification: RFC-AAAA 985 Applications that use this media type: TBD 987 Additional information: 989 Magic number(s): none 991 File extension(s): senml 993 Macintosh file type code(s): none 995 Person & email address to contact for further information: Cullen 996 Jennings 998 Intended usage: COMMON 1000 Restrictions on usage: None 1002 Author: Cullen Jennings 1004 Change controller: IESG 1006 11.2.4. senml-exi Media Type Registration 1008 Type name: application 1010 Subtype name: senml-exi 1011 Required parameters: none 1013 Optional parameters: none 1015 Encoding considerations: TBD 1017 Security considerations: TBD 1019 Interoperability considerations: TBD 1021 Published specification: RFC-AAAA 1023 Applications that use this media type: TBD 1025 Additional information: 1027 Magic number(s): none 1029 File extension(s): senml 1031 Macintosh file type code(s): none 1033 Person & email address to contact for further information: Cullen 1034 Jennings 1036 Intended usage: COMMON 1038 Restrictions on usage: None 1040 Author: Cullen Jennings 1042 Change controller: IESG 1044 11.3. XML Namespace Registration 1046 This document registers the following XML namespaces in the IETF XML 1047 registry defined in [RFC3688]. 1049 URI: urn:ietf:params:xml:ns:senml 1051 Registrant Contact: The IESG. 1053 XML: N/A, the requested URIs are XML namespaces 1055 12. Security Considerations 1057 See Section 13.Further discussion of security proprieties can be 1058 found in Section 11.2. 1060 13. Privacy Considerations 1062 Sensor data can range from information with almost no security 1063 considerations, such as the current temperature in a given city, to 1064 highly sensitive medical or location data. This specification 1065 provides no security protection for the data but is meant to be used 1066 inside another container or transport protocol such as S/MIME or HTTP 1067 with TLS that can provide integrity, confidentiality, and 1068 authentication information about the source of the data. 1070 14. Acknowledgement 1072 We would like to thank Lisa Dusseault, Joe Hildebrand, Lyndsay 1073 Campbell, Martin Thomson, John Klensin, Bjoern Hoehrmann, and Carsten 1074 Bormann for their review comments. 1076 The CBOR Representation text was contributed by Carsten Bormann. 1078 15. References 1080 15.1. Normative References 1082 [BIPM] Bureau International des Poids et Mesures, "The 1083 International System of Units (SI)", 8th edition , 2006. 1085 [IEEE.754.1985] 1086 Institute of Electrical and Electronics Engineers, 1087 "Standard for Binary Floating-Point Arithmetic", IEEE 1088 Standard 754, August 1985. 1090 [NIST822] Thompson, A. and B. Taylor, "Guide for the Use of the 1091 International System of Units (SI)", NIST Special 1092 Publication 811, 2008 Edition , 2008. 1094 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1095 Requirement Levels", BCP 14, RFC 2119, March 1997. 1097 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1098 January 2004. 1100 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1101 IANA Considerations Section in RFCs", BCP 26, May 2008. 1103 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1104 Specifications and Registration Procedures", BCP 13, RFC 1105 6838, January 2013. 1107 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1108 Representation (CBOR)", RFC 7049, October 2013. 1110 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1111 Interchange Format", RFC 7159, March 2014. 1113 [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303, 1114 July 2014. 1116 [UCUM] Schadow, G. and C. McDonald, "The Unified Code for Units 1117 of Measure (UCUM)", Regenstrief Institute and Indiana 1118 University School of Informatics , 2013. 1120 [W3C.REC-exi-20110310] 1121 Kamiya, T. and J. Schneider, "Efficient XML Interchange 1122 (EXI) Format 1.0", World Wide Web Consortium 1123 Recommendation REC-exi-20110310, March 2011, 1124 . 1126 15.2. Informative References 1128 [I-D.arkko-core-dev-urn] 1129 Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource 1130 Names for Device Identifiers", draft-arkko-core-dev-urn-03 1131 (work in progress), July 2012. 1133 [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, 1134 October 1969. 1136 [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. 1138 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1139 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1140 3986, January 2005. 1142 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1143 Unique IDentifier (UUID) URN Namespace", RFC 4122, July 1144 2005. 1146 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1147 Address Text Representation", RFC 5952, August 2010. 1149 [RFC6690] Shelby, Z., "CoRE Link Format", RFC 6690, June 2012. 1151 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "Constrained 1152 Application Protocol (CoAP)", RFC 7252, June 2013. 1154 [WADL] Hadley, M., "Web Application Description Language (WADL)", 1155 2009, 1156 . 1159 Authors' Addresses 1161 Cullen Jennings 1162 Cisco 1163 170 West Tasman Drive 1164 San Jose, CA 95134 1165 USA 1167 Phone: +1 408 421-9990 1168 Email: fluffy@cisco.com 1170 Zach Shelby 1171 ARM 1172 150 Rose Orchard 1173 San Jose 95134 1174 FINLAND 1176 Phone: +1-408-203-9434 1177 Email: zach.shelby@arm.com 1179 Jari Arkko 1180 Ericsson 1181 Jorvas 02420 1182 Finland 1184 Email: jari.arkko@piuha.net 1186 Ari Keranen 1187 Ericsson 1188 Jorvas 02420 1189 Finland 1191 Email: ari.keranen@ericsson.com