idnits 2.17.1 draft-jennings-core-senml-04.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 13, 2016) is 3025 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. 'NIST811' ** 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) == 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 (==), 5 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 16, 2016 ARM 6 J. Arkko 7 A. Keranen 8 Ericsson 9 January 13, 2016 11 Media Types for Sensor Markup Language (SENML) 12 draft-jennings-core-senml-04 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 July 16, 2016. 43 Copyright Notice 45 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Requirements and Design Goals . . . . . . . . . . . . . . . . 3 62 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 4. Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 5. Associating Meta-data . . . . . . . . . . . . . . . . . . . . 7 65 6. JSON Representation (application/senml+json) . . . . . . . . 8 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) . . . . . . . . . 14 74 10. Usage Considerations . . . . . . . . . . . . . . . . . . . . 16 75 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 76 11.1. Units Registry . . . . . . . . . . . . . . . . . . . . . 18 77 11.2. Media Type Registration . . . . . . . . . . . . . . . . 20 78 11.2.1. senml+json Media Type Registration . . . . . . . . . 20 79 11.2.2. senml+cbor Media Type Registration . . . . . . . . . 22 80 11.2.3. senml+xml Media Type Registration . . . . . . . . . 22 81 11.2.4. senml-exi Media Type Registration . . . . . . . . . 23 82 11.3. XML Namespace Registration . . . . . . . . . . . . . . . 24 83 11.4. CoAP Content-Format Registration . . . . . . . . . . . . 24 84 12. Security Considerations . . . . . . . . . . . . . . . . . . . 25 85 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 25 86 14. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 25 87 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 88 15.1. Normative References . . . . . . . . . . . . . . . . . . 25 89 15.2. Informative References . . . . . . . . . . . . . . . . . 27 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 92 1. Overview 94 Connecting sensors to the internet is not new, and there have been 95 many protocols designed to facilitate it. This specification defines 96 new media types for carrying simple sensor information in a protocol 97 such as HTTP or CoAP called the Sensor Markup Language (SenML). This 98 format was designed so that processors with very limited capabilities 99 could easily encode a sensor measurement into the media type, while 100 at the same time a server parsing the data could relatively 101 efficiently collect a large number of sensor measurements. The 102 markup language can be used for a variety of data flow models, most 103 notably data feeds pushed from a sensor to a collector, and the web 104 resource model where the sensor is requested as a resource 105 representation (e.g., "GET /sensor/temperature"). 107 There are many types of more complex measurements and measurements 108 that this media type would not be suitable for. SenML strikes a 109 balance between having some information about the sensor carried with 110 the sensor data so that the data is self describing but it also tries 111 to make that a fairly minimal set of auxiliary information for 112 efficiency reason. Other information abot the sensor can be 113 discovered by other methods suc as using the CoRE Link Format 114 [RFC6690]. 116 SenML is defined by a data model for measurements and simple meta- 117 data about measurements and devices. The data is structured as a 118 single array that contains a series of SenML Records which can each 119 contain attributes such as an unique identifier for the sensor, the 120 time the measurement was made, the unit the measurement is in, and 121 the current value of the sensor. Serializations for this data model 122 are defined for JSON [RFC7159], CBOR [RFC7049], XML, and Efficient 123 XML Interchange (EXI) [W3C.REC-exi-20110310]. 125 For example, the following shows a measurement from a temperature 126 gauge encoded in the JSON syntax. 128 [{ "n": "urn:dev:ow:10e2073a01080063", "v":23.1, "u":"Cel" }] 130 In the example above, the array has a single SenML record with a 131 measurement for a sensor named "urn:dev:ow:10e2073a01080063" with a 132 current value of 23.5 degrees Celsius. 134 2. Requirements and Design Goals 136 The design goal is to be able to send simple sensor measurements in 137 small packets on mesh networks from large numbers of constrained 138 devices. Keeping the total size of payload under 80 bytes makes this 139 easy to use on a wireless mesh network. It is always difficult to 140 define what small code is, but there is a desire to be able to 141 implement this in roughly 1 KB of flash on a 8 bit microprocessor. 142 Experience with Google power meter and large scale deployments has 143 indicated that the solution needs to support allowing multiple 144 measurements to be batched into a single HTTP or CoAP request. This 145 "batch" upload capability allows the server side to efficiently 146 support a large number of devices. It also conveniently supports 147 batch transfers from proxies and storage devices, even in situations 148 where the sensor itself sends just a single data item at a time. The 149 multiple measurements could be from multiple related sensors or from 150 the same sensor but at different times. 152 The basic design is an array with a series of measurements. The 153 following example shows two meassuremets made at different times. 154 The value of the measurements are in the "v" tag, the time of the 155 measurement is in the "t" while the "n" has the unique sensor name 156 and unit is carried in the "u". 158 [ 159 { "n": "urn:dev:ow:10e2073a01080063", 160 "t": 1276020076, "v":23.5, "u":"Cel" }, 161 { "n": "urn:dev:ow:10e2073a01080063", 162 "t": 1276020091, "v":23.6, "u":"Cel" } 163 ] 165 To keep the messages small, it does not make sense to repeat the n in 166 each SenML Record so there is a concept of a Base Name which is 167 simply a strong that is prepended to the Name field of any elements 168 that record or any records that follow it and don't contain a Base 169 Name. So a more compact form of the example above is the following. 171 [ 172 { "bn": "urn:dev:ow:10e2073a01080063", 173 "t": 1276020076, "v":23.5, "u":"Cel" }, 174 { "t": 1276020091, "v":23.6, "u":"Cel" } 175 ] 177 In the above example the Base Name is in the "bn" tag and the "n" 178 tags in each Record are the empty string so they are omitted. The 179 Base Name also could be put in a separate Record such as the 180 following example. 182 [ 183 { "bn": "urn:dev:ow:10e2073a01080063" }, 184 { "t": 1276020076, "v":23.5, "u":"Cel" }, 185 { "t": 1276020091, "v":23.6, "u":"Cel" } 186 ] 187 Some devices have accurate time while others do not so SenML supports 188 absolute and relative times. Time is represented in floating point 189 as second and values greater than zero represent an absolute time 190 relative to the unix epoch while values of 0 or less represent a 191 relative time in the past from the current time. A simple sensor 192 with no absolute wall clock time might take a measurement every 193 second and batch up 60 of them then send it to a server. It would 194 include the relative time the measurement was made to the time the 195 batch was send in the SenML. The server might have accurate NTP time 196 and use the time it received the data, and the relative offset, to 197 replace the times in the SenML with absolute times before saving the 198 SenML in a document database. 200 3. Terminology 202 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 203 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 204 "OPTIONAL" in this document are to be interpreted as described in 205 [RFC2119]. 207 4. Semantics 209 Each SenML representation carries a single array that represents a 210 set of measurements and/or parameters. This array contains a serious 211 of object with several optional attributes described below: 213 Base Name: This is a string that is prepended to the names found in 214 the entries. This attribute is optional. This applies to the 215 entries in the Record containing the Base Name and all entries 216 that come in Records after it until there is a Record with a new 217 Base Name that replaces this one. 219 Base Time: A base time that is added to the time found in an entry. 220 This attribute is optional. This applies to the entries in the 221 Record containing the Base Time and all entries that come in 222 Records after it until there is a Record with a new Base Time that 223 replaces this one. 225 Base Unit: A base unit that is assumed for all entries, unless 226 otherwise indicated. This attribute is optional. If a record 227 does not a unit value, then the base unit is used otherwise the 228 value of found in the Unit is used. Note the Base Unit is not 229 prepended to the Unit. This applies to the entries in the Record 230 containing the Base Unit and all entries that come in Records 231 after it until there is a Record with a new Base Unit that 232 replaces this one. 234 Version: Version number of media type format. This attribute is 235 optional positive integer and defaults to 3 if not present. If 236 this value is present at all, it SHOULD only be used in the first 237 Record in the SenML Stream array. 239 Name: Name of the sensor or parameter. When appended to the Base 240 Name attribute, this must result in a globally unique identifier 241 for the resource. The name is optional, if the Base Name is 242 present. If the name is missing, Base Name must uniquely identify 243 the resource. This can be used to represent a large array of 244 measurements from the same sensor without having to repeat its 245 identifier on every measurement. 247 Unit: Units for a measurement value. Optional. If the Record has 248 not Unit, the Base Unit is used as the Unit. 250 Value Value of the entry. Optional if a Sum value is present, 251 otherwise required. Values are represented using three basic data 252 types, Floating point numbers ("v" field for "Value"), Booleans 253 ("vb" for "Boolean Value") and Strings ("vs" for "String Value"). 254 Exactly one of these three fields MUST appear. 256 Sum: Integrated sum of the values over time. Optional. This 257 attribute is in the units specified in the Unit value multiplied 258 by seconds. 260 Time: Time when value was recorded. Optional. 262 Update Time: A time in seconds that represents the maximum time 263 before this sensor will provide an updated reading for a 264 measurement. This can be used to detect the failure of sensors or 265 communications path from the sensor. Optional. 267 The SenML format can be extended with further custom attributes. 268 TODO - describe what extensions are possible and how to do them. 270 Systems reading one of the objects MUST check for the Version 271 attribute. If this value is a version number larger than the version 272 which the system understands, the system SHOULD NOT use this object. 273 This allows the version number to indicate that the object contains 274 mandatory to understand attributes. New version numbers can only be 275 defined in an RFC that updates this specification or it successors. 277 The Name value is concatenated to the Base Name value to get the name 278 of the sensor. The resulting name needs to uniquely identify and 279 differentiate the sensor from all others. If the object is a 280 representation resulting from the request of a URI [RFC3986], then in 281 the absence of the Base Name attribute, this URI is used as the 282 default value of Base Name. Thus in this case the Name field needs 283 to be unique for that URI, for example an index or subresource name 284 of sensors handled by the URI. 286 Alternatively, for objects not related to a URI, a unique name is 287 required. In any case, it is RECOMMENDED that the full names are 288 represented as URIs or URNs [RFC2141]. One way to create a unique 289 name is to include a EUI-48 or EUI-64 identifier (a MAC address) or 290 some other bit string that has guaranteed uniqueness (such as a 291 1-wire address) that is assigned to the device. Some of the examples 292 in this draft use the device URN type as specified in 293 [I-D.arkko-core-dev-urn]. UUIDs [RFC4122] are another way to 294 generate a unique name. 296 The resulting concatenated name MUST consist only of characters out 297 of the set "A" to "Z", "a" to "z", "0" to "9", "-", ":", ".", or "_" 298 and it MUST start with a character out of the set "A" to "Z", "a" to 299 "z", or "0" to "9". This restricted character set was chosen so that 300 these names can be directly used as in other types of URI including 301 segments of an HTTP path with no special encoding and can be directly 302 used in many databases and analytic systems.. [RFC5952] contains 303 advice on encoding an IPv6 address in a name. 305 If either the Base Time or Time value is missing, the missing 306 attribute is considered to have a value of zero. The Base Time and 307 Time values are added together to get the time of measurement. A 308 time of zero indicates that the sensor does not know the absolute 309 time and the measurement was made roughly "now". A negative value is 310 used to indicate seconds in the past from roughly "now". A positive 311 value is used to indicate the number of seconds, excluding leap 312 seconds, since the start of the year 1970 in UTC. 314 Representing the statistical characteristics of measurements, such as 315 accuracy, can be very complex. Future specification may add new 316 attributes to provide better information about the statistical 317 properties of the measurement. 319 5. Associating Meta-data 321 SenML is designed to carry the minimum dynamic information about 322 measurements, and for efficiency reasons does not carry significant 323 static meta-data about the device, object or sensors. Instead, it is 324 assumed that this meta-data is carried out of band. For web 325 resources using SenML representations, this meta-data can be made 326 available using the CoRE Link Format [RFC6690]. The most obvious use 327 of this link format is to describe that a resource is available in a 328 SenML format in the first place. The relevant media type indicator 329 is included in the Content-Type (ct=) attribute. 331 6. JSON Representation (application/senml+json) 333 Record atributes: 335 +---------------+------+----------------+ 336 | SenML | JSON | Type | 337 +---------------+------+----------------+ 338 | Base Name | bn | String | 339 | Base Time | bt | Number | 340 | Base Unit | bu | Number | 341 | Version | ver | Number | 342 | Name | n | String | 343 | Unit | u | String | 344 | Value | v | Floating point | 345 | String Value | vs | String | 346 | Boolean Value | vb | Boolean | 347 | Value Sum | s | Floating point | 348 | Time | t | Number | 349 | Update Time | ut | Number | 350 +---------------+------+----------------+ 352 All of the data is UTF-8, but since this is for machine to machine 353 communications on constrained systems, only characters with code 354 points between U+0001 and U+007F are allowed which corresponds to the 355 ASCII [RFC0020] subset of UTF-8 with the exception of characters 356 found in the String Value. 358 Characters in the String Value are encoded TODO. Open Issue How. 360 The root content consists of an array with and JSON object for each 361 SenML Record. 363 The objects MAY contain a "bn" attribute with a value of type string. 364 The object MAY contain a "bt" attribute with a value of type number. 365 The object MAY contain a "bu" attribute with a value of type string. 366 The object MAY contain a "ver" attribute with a value of type number. 367 The object MAY contain other attribute value pairs. 369 The objects MAY include the "n", "u", and "vs" attributes are of type 370 string, the "t" and "ut" attributes are of type number, the "vb" 371 attribute is of type boolean, and the "v" and "s" attributes are of 372 type floating point for the SenML atributes defined in the table 373 above. All the attributes are optional, but as specified in 374 Section 4, one of the "v", "vs", or "vb" attributes MUST appear 375 unless the "s" attribute is also present in Records that represent a 376 measurement. The "v", and "vs", and "vb" attributes MUST NOT appear 377 together in the same object. 379 Systems receiving measurements MUST be able to process the range of 380 floating point numbers that are representable as an IEEE double- 381 precision floating-point numbers [IEEE.754.1985]. The number of 382 significant digits in any measurement is not relevant, so a reading 383 of 1.1 has exactly the same semantic meaning as 1.10. If the value 384 has an exponent, the "e" MUST be in lower case. The mantissa SHOULD 385 be less than 19 characters long and the exponent SHOULD be less than 386 5 characters long. This allows time values to have better than micro 387 second precision over the next 100 years. 389 6.1. Examples 391 6.1.1. Single Datapoint 393 The following shows a temperature reading taken approximately "now" 394 by a 1-wire sensor device that was assigned the unique 1-wire address 395 of 10e2073a01080063: 397 [{ "n": "urn:dev:ow:10e2073a01080063", "v":23.1, "u":"Cel" }] 399 6.1.2. Multiple Datapoints 401 The following example shows voltage and current now, i.e., at an 402 unspecified time. The device has an EUI-64 MAC address of 403 0024befffe804ff1. 405 [{"bn": "urn:dev:mac:0024befffe804ff1/"}, 406 { "n": "voltage", "t": 0, "u": "V", "v": 120.1 }, 407 { "n": "current", "t": 0, "u": "A", "v": 1.2 } 408 ] 410 The next example is similar to the above one, but shows current at 411 Tue Jun 8 18:01:16 UTC 2010 and at each second for the previous 5 412 seconds. 414 [{"bn": "urn:dev:mac:0024befffe804ff1/", 415 "bt": 1276020076, 416 "bu": "A", 417 "ver": 3}, 418 { "n": "voltage", "u": "V", "v": 120.1 }, 419 { "n": "current", "t": -5, "v": 1.2 }, 420 { "n": "current", "t": -4, "v": 1.30 }, 421 { "n": "current", "t": -3, "v": 0.14e1 }, 422 { "n": "current", "t": -2, "v": 1.5 }, 423 { "n": "current", "t": -1, "v": 1.6 }, 424 { "n": "current", "t": 0, "v": 1.7 } 425 ] 426 Note that in some usage scenarios of SenML the implementations MAY 427 store or transmit SenML in a stream-like fashion, where data is 428 collected over time and continuously added to the object. This mode 429 of operation is optional, but systems or protocols using SenML in 430 this fashion MUST specify that they are doing this. SenML defines a 431 separate mine type (TODO) to indicate Senor Streaming Markup Langage 432 (SensML) for this usage. In this situation the SensML stream can be 433 sent and received in a partial fashion, i.e., a measurement entry can 434 be read as soon as the SenML Record is received and not have to wait 435 for the full SenML Stream to be complete. 437 For instance, the following stream of measurements may be sent via a 438 long lived HTTP POST from the producer of a SensML to the consumer of 439 that, and each measurement object may be reported at the time it 440 measured: 442 [ {"bn": "http://[2001:db8::1]", 443 "bt": 1320067464, 444 "bu": "%RH"}, 445 { "v": 21.2, "t": 0 }, 446 { "v": 21.3, "t": 10 }, 447 { "v": 21.4, "t": 20 }, 448 { "v": 21.4, "t": 30 }, 449 { "v": 21.5, "t": 40 }, 450 { "v": 21.5, "t": 50 }, 451 { "v": 21.5, "t": 60 }, 452 { "v": 21.6, "t": 70 }, 453 { "v": 21.7, "t": 80 }, 454 { "v": 21.5, "t": 90 }, 455 ... 457 6.1.3. Multiple Measurements 459 The following example shows humidity measurements from a mobile 460 device with an IPv6 address 2001:db8::1, starting at Mon Oct 31 461 13:24:24 UTC 2011. The device also provides position data, which is 462 provided in the same measurement or parameter array as separate 463 entries. Note time is used to for correlating data that belongs 464 together, e.g., a measurement and a parameter associated with it. 465 Finally, the device also reports extra data about its battery status 466 at a separate time. 468 [{"bn": "http://[2001:db8::1]", 469 "bt": 1320067464, 470 "bu": "%RH"}, 471 { "v": 20.0, "t": 0 }, 472 { "v": 24.30621, "u": "lon", "t": 0 }, 473 { "v": 60.07965, "u": "lat", "t": 0 }, 474 { "v": 20.3, "t": 60 }, 475 { "v": 24.30622, "u": "lon", "t": 60 }, 476 { "v": 60.07965, "u": "lat", "t": 60 }, 477 { "v": 20.7, "t": 120 }, 478 { "v": 24.30623, "u": "lon", "t": 120 }, 479 { "v": 60.07966, "u": "lat", "t": 120 }, 480 { "v": 98.0, "u": "%EL", "t": 150 }, 481 { "v": 21.2, "t": 180 }, 482 { "v": 24.30628, "u": "lon", "t": 180 }, 483 { "v": 60.07967, "u": "lat", "t": 180 } 484 ] 486 6.1.4. Collection of Resources 488 The following example shows how to query one device that can provide 489 multiple measurements. The example assumes that a client has fetched 490 information from a device at 2001:db8::2 by performing a GET 491 operation on http://[2001:db8::2] at Mon Oct 31 16:27:09 UTC 2011, 492 and has gotten two separate values as a result, a temperature and 493 humidity measurement. 495 [{"bn": "http://[2001:db8::2]/", 496 "bt": 1320078429, 497 "ver": 3}, 498 { "n": "temperature", "v": 27.2, "u": "Cel" }, 499 { "n": "humidity", "v": 80, "u": "%RH" } 500 ] 502 7. CBOR Representation (application/senml+cbor) 504 The CBOR [RFC7049] representation is equivalent to the JSON 505 representation, with the following changes: 507 o For compactness, the CBOR representation uses integers for the map 508 keys defined in Table 1. This table is conclusive, i.e., there is 509 no intention to define any additional integer map keys; any 510 extensions will use string map keys. 512 o For JSON Numbers, the CBOR representation can use integers, 513 floating point numbers, or decimal fractions (CBOR Tag 4); the 514 common limitations of JSON implementations are not relevant for 515 these. For the version number, however, only an unsigned integer 516 is allowed. 518 +---------------+------------+------------+ 519 | Name | JSON label | CBOR label | 520 +---------------+------------+------------+ 521 | Version | ver | -1 | 522 | Base Name | bn | -2 | 523 | Base Time | bt | -3 | 524 | Base Units | bu | -4 | 525 | Name | n | 0 | 526 | Units | u | 1 | 527 | Value | v | 2 | 528 | String Value | vs | 3 | 529 | Boolean Value | vb | 4 | 530 | Value Sum | s | 5 | 531 | Time | t | 6 | 532 | Update Time | ut | 7 | 533 +---------------+------------+------------+ 535 Table 1: CBOR representation: integers for map keys 537 8. XML Representation (application/senml+xml) 539 A SenML Stream can also be represented in XML format as defined in 540 this section. The following example shows an XML example for the 541 same sensor measurement as in Section 6.1.2. 543 544 546 547 548 549 550 551 552 553 555 TODO - tag names in examples are wrong 557 The SenML Stream is represented as a sensml tag that contains a 558 series of senml tags for each SenML Record. The SenML Fields are 559 represents as XML attributes. The following table shows the mapping 560 the SenML Field names to the atribute used on the XML senml tag. 562 +---------------+-----+---------+ 563 | SenML Field | XML | Type | 564 +---------------+-----+---------+ 565 | Base Name | bn | string | 566 | Base Time | bt | int | 567 | Base Unit | bu | int | 568 | Version | ver | int | 569 | Name | n | string | 570 | Unit | u | string | 571 | Value | v | float | 572 | String Value | vs | string | 573 | Boolean Value | vb | boolean | 574 | Value Sum | s | float | 575 | Time | t | int | 576 | Update Time | ut | int | 577 +---------------+-----+---------+ 579 The RelaxNG schema for the XML is: 581 default namespace = "urn:ietf:params:xml:ns:senml" 582 namespace rng = "http://relaxng.org/ns/structure/1.0" 584 senml = element senml { 585 attribute bn { xsd:string }?, 586 attribute bt { xsd:int }?, 587 attribute bu { xsd:string }?, 588 attribute n { xsd:string }?, 589 attribute s { xsd:float }?, 590 attribute t { xsd:int }?, 591 attribute u { xsd:string }?, 592 attribute ut { xsd:int }?, 593 attribute v { xsd:float }?, 594 attribute vb { xsd:boolean }?, 595 attribute ver { xsd:int }?, 596 attribute vs { xsd:string }? 597 } 599 senmls = 600 element senmls { 601 senml+ 602 } 604 start = senmls 606 9. EXI Representation (application/senml-exi) 608 For efficient transmission of SenML over e.g. a constrained network, 609 Efficient XML Interchange (EXI) can be used. This encodes the XML 610 Schema structure of SenML into binary tags and values rather than 611 ASCII text. An EXI representation of SenML SHOULD be made using the 612 strict schema-mode of EXI. This mode however does not allow tag 613 extensions to the schema, and therefore any extensions will be lost 614 in the encoding. For uses where extensions need to be preserved in 615 EXI, the non-strict schema mode of EXI MAY be used. 617 The EXI header option MUST be included. An EXI schemaID options MUST 618 be set to the value of "a" indicating the scheme provided in this 619 specification. Future revisions to the schema can change this 620 schemaID to allow for backwards compatibility. When the data will be 621 transported over CoAP or HTTP, an EXI Cookie SHOULD NOT be used as it 622 simply makes things larger and is redundant to information provided 623 in the Content-Type header. 625 TODO - examples are probably have the wrong setting the schemaID 627 The following is the XSD Schema to be used for strict schema guided 628 EXI processing. It is generated from the RelaxNG. 630 631 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 660 The following shows a hexdump of the EXI produced from encoding the 661 following XML example. Note this example is the same information as 662 the first example in Section 6.1.2 in JSON format. 664 665 666 667 668 670 TODO - replace ex8 with ex2 as they are the same. Replace ex9 with 671 ex1. Simplify rest of examples. 673 Which compresses to the following displayed in hexdump: 675 0000000 a0 30 41 cd 95 b9 b5 b0 cc b9 9d 95 b8 b9 e1 cd 676 0000010 90 80 fb ab 93 71 d3 23 2b b1 d3 6b 0b 19 d1 81 677 0000020 81 91 a3 13 2b 33 33 33 29 c1 81 a3 33 31 89 7d 678 0000030 8c 25 d9 bd b1 d1 85 9d 94 80 d5 8a c4 26 01 8c 679 0000040 25 8d d5 c9 c9 95 b9 d0 80 d0 48 32 01 c0 680 000004e 682 The above example used the bit packed form of EXI but it is also 683 possible to use a byte packed form of EXI which can makes it easier 684 for a simple sensor to produce valid EXI without really implementing 685 EXI. Consider the example of a temperature sensor that produces a 686 value in tenths of degrees Celsius over a range of 0.0 to 55.0. It 687 would produce an XML SenML file such as: 689 690 691 693 The compressed form, using the byte alignment option of EXI, for the 694 above XML is the following: 696 00 a0 00 48 82 0e 6c ad cd ad 86 65 cc ec ad c5 cf |..H..l....e.....| 697 10 0e 6c 80 01 03 1d 75 72 6e 3a 64 65 76 3a 6f 77 |.l....urn:dev:ow| 698 20 3a 31 30 65 32 30 37 33 61 30 31 30 38 30 30 36 |:10e2073a0108006| 699 30 33 02 05 43 65 6c 01 00 e7 01 01 00 03 01 |3..Cel........| 700 3e 702 A small temperature sensor devices that only generates this one EXI 703 file does not really need an full EXI implementation. It can simple 704 hard code the output replacing the one wire device ID starting at 705 byte 0x16 and going to byte 0x31 with it's device ID, and replacing 706 the value "0xe7 0x01" at location 0x38 to 0x39 with the current 707 temperature. The EXI Specification [W3C.REC-exi-20110310] contains 708 the full information 'on how floating point numbers are represented, 709 but for the purpose of this sensor, the temperature can be converted 710 to an integer in tenths of degrees (231 in this example). EXI stores 711 7 bits of the integer in each byte with the top bit set to one if 712 there are further bytes. So the first bytes at is set to low 7 bits 713 of the integer temperature in tenths of degrees plus 0x80. In this 714 example 231 & 0x7F + 0x80 = 0xE7. The second byte is set to the 715 integer temperature in tenths of degrees right shifted 7 bits. In 716 this example 231 >> 7 = 0x01. 718 10. Usage Considerations 720 The measurements support sending both the current value of a sensor 721 as well as the an integrated sum. For many types of measurements, 722 the sum is more useful than the current value. For example, an 723 electrical meter that measures the energy a given computer uses will 724 typically want to measure the cumulative amount of energy used. This 725 is less prone to error than reporting the power each second and 726 trying to have something on the server side sum together all the 727 power measurements. If the network between the sensor and the meter 728 goes down over some period of time, when it comes back up, the 729 cumulative sum helps reflect what happened while the network was 730 down. A meter like this would typically report a measurement with 731 the units set to watts, but it would put the sum of energy used in 732 the "s" attribute of the measurement. It might optionally include 733 the current power in the "v" attribute. 735 While the benefit of using the integrated sum is fairly clear for 736 measurements like power and energy, it is less obvious for something 737 like temperature. Reporting the sum of the temperature makes it easy 738 to compute averages even when the individual temperature values are 739 not reported frequently enough to compute accurate averages. 740 Implementors are encouraged to report the cumulative sum as well as 741 the raw value of a given sensor. 743 Applications that use the cumulative sum values need to understand 744 they are very loosely defined by this specification, and depending on 745 the particular sensor implementation may behave in unexpected ways. 746 Applications should be able to deal with the following issues: 748 1. Many sensors will allow the cumulative sums to "wrap" back to 749 zero after the value gets sufficiently large. 751 2. Some sensors will reset the cumulative sum back to zero when the 752 device is reset, loses power, or is replaced with a different 753 sensor. 755 3. Applications cannot make assumptions about when the device 756 started accumulating values into the sum. 758 Typically applications can make some assumptions about specific 759 sensors that will allow them to deal with these problems. A common 760 assumption is that for sensors whose measurement values are always 761 positive, the sum should never get smaller; so if the sum does get 762 smaller, the application will know that one of the situations listed 763 above has happened. 765 11. IANA Considerations 767 Note to RFC Editor: Please replace all occurrences of "RFC-AAAA" with 768 the RFC number of this specification. 770 11.1. Units Registry 772 IANA will create a registry of unit symbols. The primary purpose of 773 this registry is to make sure that symbols uniquely map to give type 774 of measurement. Definitions for many of these units can be found in 775 location such as [NIST811] and [BIPM]. 777 +--------+--------------------------------------+-------+-----------+ 778 | Symbol | Description | Type | Reference | 779 +--------+--------------------------------------+-------+-----------+ 780 | m | meter | float | RFC-AAAA | 781 | kg | kilogram | float | RFC-AAAA | 782 | s | second | float | RFC-AAAA | 783 | A | ampere | float | RFC-AAAA | 784 | K | kelvin | float | RFC-AAAA | 785 | cd | candela | float | RFC-AAAA | 786 | mol | mole | float | RFC-AAAA | 787 | Hz | hertz | float | RFC-AAAA | 788 | rad | radian | float | RFC-AAAA | 789 | sr | steradian | float | RFC-AAAA | 790 | N | newton | float | RFC-AAAA | 791 | Pa | pascal | float | RFC-AAAA | 792 | J | joule | float | RFC-AAAA | 793 | W | watt | float | RFC-AAAA | 794 | C | coulomb | float | RFC-AAAA | 795 | V | volt | float | RFC-AAAA | 796 | F | farad | float | RFC-AAAA | 797 | Ohm | ohm | float | RFC-AAAA | 798 | S | siemens | float | RFC-AAAA | 799 | Wb | weber | float | RFC-AAAA | 800 | T | tesla | float | RFC-AAAA | 801 | H | henry | float | RFC-AAAA | 802 | Cel | degrees Celsius | float | RFC-AAAA | 803 | lm | lumen | float | RFC-AAAA | 804 | lx | lux | float | RFC-AAAA | 805 | Bq | becquerel | float | RFC-AAAA | 806 | Gy | gray | float | RFC-AAAA | 807 | Sv | sievert | float | RFC-AAAA | 808 | kat | katal | float | RFC-AAAA | 809 | pH | pH acidity | float | RFC-AAAA | 810 | % | Value of a switch (note 1) | float | RFC-AAAA | 811 | count | counter value | float | RFC-AAAA | 812 | %RH | Relative Humidity | float | RFC-AAAA | 813 | m2 | area | float | RFC-AAAA | 814 | l | volume in liters | float | RFC-AAAA | 815 | m/s | velocity | float | RFC-AAAA | 816 | m/s2 | acceleration | float | RFC-AAAA | 817 | l/s | flow rate in liters per second | float | RFC-AAAA | 818 | W/m2 | irradiance | float | RFC-AAAA | 819 | cd/m2 | luminance | float | RFC-AAAA | 820 | Bspl | bel sound pressure level | float | RFC-AAAA | 821 | bit/s | bits per second | float | RFC-AAAA | 822 | lat | degrees latitude (note 2) | float | RFC-AAAA | 823 | lon | degrees longitude (note 2) | float | RFC-AAAA | 824 | %EL | remaining battery energy level in | float | RFC-AAAA | 825 | | percents | | | 826 | EL | remaining battery energy level in | float | RFC-AAAA | 827 | | seconds | | | 828 | beat/m | Heart rate in beats per minute | float | RFC-AAAA | 829 | beats | Cumulative number of heart beats | float | RFC-AAAA | 830 +--------+--------------------------------------+-------+-----------+ 832 Table 2 834 o Note 1: A value of 0.0 indicates the switch is off while 1.0 835 indicates on and 0.5 would be half on. 837 o Note 2: Assumed to be in WGS84 unless another reference frame is 838 known for the sensor. 840 New entries can be added to the registration by either Expert Review 841 or IESG Approval as defined in [RFC5226]. Experts should exercise 842 their own good judgment but need to consider the following 843 guidelines: 845 1. There needs to be a real and compelling use for any new unit to 846 be added. 848 2. Units should define the semantic information and be chosen 849 carefully. Implementors need to remember that the same word may 850 be used in different real-life contexts. For example, degrees 851 when measuring latitude have no semantic relation to degrees 852 when measuring temperature; thus two different units are needed. 854 3. These measurements are produced by computers for consumption by 855 computers. The principle is that conversion has to be easily be 856 done when both reading and writing the media type. The value of 857 a single canonical representation outweighs the convenience of 858 easy human representations or loss of precision in a conversion. 860 4. Use of SI prefixes such as "k" before the unit is not allowed. 861 Instead one can represent the value using scientific notation 862 such a 1.2e3. 864 5. For a given type of measurement, there will only be one unit 865 type defined. So for length, meters are defined and other 866 lengths such as mile, foot, light year are not allowed. For 867 most cases, the SI unit is preferred. 869 6. Symbol names that could be easily confused with existing common 870 units or units combined with prefixes should be avoided. For 871 example, selecting a unit name of "mph" to indicate something 872 that had nothing to do with velocity would be a bad choice, as 873 "mph" is commonly used to mean miles per hour. 875 7. The following should not be used because the are common SI 876 prefixes: Y, Z, E, P, T, G, M, k, h, da, d, c, n, u, p, f, a, z, 877 y, Ki, Mi, Gi, Ti, Pi, Ei, Zi, Yi. 879 8. The following units should not be used as they are commonly used 880 to represent other measurements Ky, Gal, dyn, etg, P, St, Mx, G, 881 Oe, Gb, sb, Lmb, ph, Ci, R, RAD, REM, gal, bbl, qt, degF, Cal, 882 BTU, HP, pH, B/s, psi, Torr, atm, at, bar, kWh. 884 9. The unit names are case sensitive and the correct case needs to 885 be used, but symbols that differ only in case should not be 886 allocated. 888 10. A number after a unit typically indicates the previous unit 889 raised to that power, and the / indicates that the units that 890 follow are the reciprocal. A unit should have only one / in the 891 name. 893 11. A good list of common units can be found in the Unified Code for 894 Units of Measure [UCUM]. 896 11.2. Media Type Registration 898 The following registrations are done following the procedure 899 specified in [RFC6838] and [RFC7303]. 901 11.2.1. senml+json Media Type Registration 903 Type name: application 905 Subtype name: senml+json and sensml+json 907 Required parameters: none 909 Optional parameters: none 911 Encoding considerations: Must be encoded as using a subset of the 912 encoding allowed in [RFC7159]. See RFC-AAAA for details. This 913 simplifies implementation of very simple system and does not impose 914 any significant limitations as all this data is meant for machine to 915 machine communications and is not meant to be human readable. 917 Security considerations: Sensor data can contain a wide range of 918 information ranging from information that is very public, such the 919 outside temperature in a given city, to very private information that 920 requires integrity and confidentiality protection, such as patient 921 health information. This format does not provide any security and 922 instead relies on the transport protocol that carries it to provide 923 security. Given applications need to look at the overall context of 924 how this media type will be used to decide if the security is 925 adequate. 927 Interoperability considerations: Applications should ignore any JSON 928 key value pairs that they do not understand. This allows backwards 929 compatibility extensions to this specification. The "ver" field can 930 be used to ensure the receiver supports a minimal level of 931 functionality needed by the creator of the JSON object. 933 Published specification: RFC-AAAA 935 Applications that use this media type: The type is used by systems 936 that report electrical power usage and environmental information such 937 as temperature and humidity. It can be used for a wide range of 938 sensor reporting systems. 940 Additional information: 942 Magic number(s): none 944 File extension(s): senml 946 Macintosh file type code(s): none 948 Person & email address to contact for further information: Cullen 949 Jennings 951 Intended usage: COMMON 953 Restrictions on usage: None 955 Author: Cullen Jennings 957 Change controller: IESG 959 11.2.2. senml+cbor Media Type Registration 961 Type name: application 963 Subtype name: senml+cbor 965 Required parameters: none 967 Optional parameters: none 969 Encoding considerations: TBD 971 Security considerations: TBD 973 Interoperability considerations: TBD 975 Published specification: RFC-AAAA 977 Applications that use this media type: The type is used by systems 978 that report electrical power usage and environmental information such 979 as temperature and humidity. It can be used for a wide range of 980 sensor reporting systems. 982 Additional information: 984 Magic number(s): none 986 File extension(s): senml 988 Macintosh file type code(s): none 990 Person & email address to contact for further information: Cullen 991 Jennings 993 Intended usage: COMMON 995 Restrictions on usage: None 997 Author: Cullen Jennings 999 Change controller: IESG 1001 11.2.3. senml+xml Media Type Registration 1003 Type name: application 1005 Subtype name: senml+xml and sensml+xml 1006 Required parameters: none 1008 Optional parameters: none 1010 Encoding considerations: TBD 1012 Security considerations: TBD 1014 Interoperability considerations: TBD 1016 Published specification: RFC-AAAA 1018 Applications that use this media type: TBD 1020 Additional information: 1022 Magic number(s): none 1024 File extension(s): senml 1026 Macintosh file type code(s): none 1028 Person & email address to contact for further information: Cullen 1029 Jennings 1031 Intended usage: COMMON 1033 Restrictions on usage: None 1035 Author: Cullen Jennings 1037 Change controller: IESG 1039 11.2.4. senml-exi Media Type Registration 1041 Type name: application 1043 Subtype name: senml-exi 1045 Required parameters: none 1047 Optional parameters: none 1049 Encoding considerations: TBD 1051 Security considerations: TBD 1053 Interoperability considerations: TBD 1054 Published specification: RFC-AAAA 1056 Applications that use this media type: TBD 1058 Additional information: 1060 Magic number(s): none 1062 File extension(s): senml 1064 Macintosh file type code(s): none 1066 Person & email address to contact for further information: Cullen 1067 Jennings 1069 Intended usage: COMMON 1071 Restrictions on usage: None 1073 Author: Cullen Jennings 1075 Change controller: IESG 1077 11.3. XML Namespace Registration 1079 This document registers the following XML namespaces in the IETF XML 1080 registry defined in [RFC3688]. 1082 URI: urn:ietf:params:xml:ns:senml 1084 Registrant Contact: The IESG. 1086 XML: N/A, the requested URIs are XML namespaces 1088 11.4. CoAP Content-Format Registration 1090 IANA is requested to assign CoAP Content-Format IDs for the SenML 1091 media types in the "CoAP Content-Formats" sub-registry, within the 1092 "CoRE Parameters" registry [RFC7252]. All IDs are assigned from the 1093 "Expert Review" (0-255) range. The assigned IDs are show in Table 3. 1095 +-------------------------+-----+ 1096 | Media type | ID | 1097 +-------------------------+-----+ 1098 | application/senml+json | TBD | 1099 | application/sensml+json | TBD | 1100 | application/senml+cbor | TBD | 1101 | application/senml+xml | TBD | 1102 | application/sensml+xml | TBD | 1103 | application/senml-exi | TBD | 1104 +-------------------------+-----+ 1106 Table 3: CoAP Content-Format IDs 1108 12. Security Considerations 1110 See Section 13. Further discussion of security properties can be 1111 found in Section 11.2. 1113 13. Privacy Considerations 1115 Sensor data can range from information with almost no security 1116 considerations, such as the current temperature in a given city, to 1117 highly sensitive medical or location data. This specification 1118 provides no security protection for the data but is meant to be used 1119 inside another container or transport protocol such as S/MIME or HTTP 1120 with TLS that can provide integrity, confidentiality, and 1121 authentication information about the source of the data. 1123 14. Acknowledgement 1125 We would like to thank Lisa Dusseault, Joe Hildebrand, Lyndsay 1126 Campbell, Martin Thomson, John Klensin, Bjoern Hoehrmann, Carsten 1127 Bormann, and Christian Amsuess for their review comments. 1129 The CBOR Representation text was contributed by Carsten Bormann. 1131 15. References 1133 15.1. Normative References 1135 [BIPM] Bureau International des Poids et Mesures, "The 1136 International System of Units (SI)", 8th edition, 2006. 1138 [IEEE.754.1985] 1139 Institute of Electrical and Electronics Engineers, 1140 "Standard for Binary Floating-Point Arithmetic", IEEE 1141 Standard 754, August 1985. 1143 [NIST811] Thompson, A. and B. Taylor, "Guide for the Use of the 1144 International System of Units (SI)", NIST Special 1145 Publication 811, 2008. 1147 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1148 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1149 RFC2119, March 1997, 1150 . 1152 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1153 DOI 10.17487/RFC3688, January 2004, 1154 . 1156 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1157 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1158 DOI 10.17487/RFC5226, May 2008, 1159 . 1161 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1162 Specifications and Registration Procedures", BCP 13, RFC 1163 6838, DOI 10.17487/RFC6838, January 2013, 1164 . 1166 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1167 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1168 October 2013, . 1170 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1171 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1172 2014, . 1174 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1175 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ 1176 RFC7252, June 2014, 1177 . 1179 [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303, 1180 DOI 10.17487/RFC7303, July 2014, 1181 . 1183 [W3C.REC-exi-20110310] 1184 Schneider, J. and T. Kamiya, "Efficient XML Interchange 1185 (EXI) Format 1.0", World Wide Web Consortium 1186 Recommendation REC-exi-20110310, March 2011, 1187 . 1189 15.2. Informative References 1191 [I-D.arkko-core-dev-urn] 1192 Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource 1193 Names for Device Identifiers", draft-arkko-core-dev-urn-03 1194 (work in progress), July 2012. 1196 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 1197 RFC 20, DOI 10.17487/RFC0020, October 1969, 1198 . 1200 [RFC2141] Moats, R., "URN Syntax", RFC 2141, DOI 10.17487/RFC2141, 1201 May 1997, . 1203 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1204 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1205 3986, DOI 10.17487/RFC3986, January 2005, 1206 . 1208 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1209 Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 1210 10.17487/RFC4122, July 2005, 1211 . 1213 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1214 Address Text Representation", RFC 5952, DOI 10.17487/ 1215 RFC5952, August 2010, 1216 . 1218 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1219 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1220 . 1222 [UCUM] Schadow, G. and C. McDonald, "The Unified Code for Units 1223 of Measure (UCUM)", Regenstrief Institute and Indiana 1224 University School of Informatics, 2013, 1225 . 1227 Authors' Addresses 1229 Cullen Jennings 1230 Cisco 1231 400 3rd Avenue SW 1232 Calgary, AB T2P 4H2 1233 Canada 1235 Phone: +1 408 421-9990 1236 Email: fluffy@cisco.com 1237 Zach Shelby 1238 ARM 1239 150 Rose Orchard 1240 San Jose 95134 1241 USA 1243 Phone: +1-408-203-9434 1244 Email: zach.shelby@arm.com 1246 Jari Arkko 1247 Ericsson 1248 Jorvas 02420 1249 Finland 1251 Email: jari.arkko@piuha.net 1253 Ari Keranen 1254 Ericsson 1255 Jorvas 02420 1256 Finland 1258 Email: ari.keranen@ericsson.com