idnits 2.17.1 draft-jennings-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 9, 2010) is 5033 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). 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: Experimental July 9, 2010 5 Expires: January 10, 2011 7 Media Type for Sensor Markup Language (SENML) 8 draft-jennings-senml-01 10 Abstract 12 This specification defines media types for representing simple sensor 13 measurements in JSON. A simple sensor, such as a temperature sensor, 14 could use this media type in protocols such as HTTP to transport the 15 values of a sensor. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 10, 2011. 34 Copyright Notice 36 Copyright (c) 2010 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. Requirements and Design Goals . . . . . . . . . . . . . . . . 3 53 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 4. Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 5. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 56 5.1. Simple Example . . . . . . . . . . . . . . . . . . . . . . 6 57 5.2. Complex Example . . . . . . . . . . . . . . . . . . . . . 6 58 6. Usage Considerations . . . . . . . . . . . . . . . . . . . . . 7 59 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 60 7.1. Units Registry . . . . . . . . . . . . . . . . . . . . . . 8 61 7.2. Media Type Registration . . . . . . . . . . . . . . . . . 11 62 7.2.1. senml+json Media Type Registration . . . . . . . . . . 11 63 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 64 9. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 12 65 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 66 10.1. Normative References . . . . . . . . . . . . . . . . . . . 12 67 10.2. Informative References . . . . . . . . . . . . . . . . . . 13 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 70 1. Overview 72 Connecting sensors to the internet is not new, and there have been 73 many protocols designed to facilitate it. This specification defines 74 new media types for carrying simple sensor information in a protocol 75 such as HTTP or CoAP[I-D.shelby-core-coap]. This format was designed 76 so that processors with very limited capabilities could easily encode 77 a sensor reading into the media type, while at the same time a server 78 parsing the data could relatively efficiently collect a large number 79 of sensor readings. There are many types of more complex 80 measurements and readings that this media type would not be suitable 81 for. A decision was made not to carry most of the meta data about 82 the sensor in this media type to help reduce the size of the data and 83 improve efficiency in decoding. 85 JSON[RFC4627] was selected as a basis for the encoding as it 86 represents a widely understood way of encoding data that is popular 87 in current web based APIs and represents reasonable trade-offs 88 between extensibility, simplicity, and efficiency. 90 The data is structured as a single JSON object (with attributes) that 91 contains an array of measurements. Each measurement is a JSON object 92 that has attributes such as a unique identifier for the sensor, the 93 time the measurement was made, and the current value. For example, 94 the following shows a measurement from a temperature gauge in JSON 95 syntax. 97 {"m":[{ "n": "0017f202a5c5-Temp", "v":23.5, "u":"degC" }]} 99 In the example above, the array in the object has a single 100 measurement for a sensor named "0017f202a5c5-Temp" with a temperature 101 of 23.5 degrees Celsius. 103 2. Requirements and Design Goals 105 The design goal is to be able to send simple sensor measurements in 106 small packets on mesh networks from large numbers of constrained 107 devices. Keeping the total size under 80 bytes makes this easy to 108 use on a wireless mesh network. It is always difficult to define 109 what small code is, but there is a desire to be able to implement 110 this in roughly 1 KB of flash on a 8 bit microprocessor. Experience 111 with Google power meter and other large scale deployments has 112 indicated strongly that the solution needs to support allowing 113 multiple measurements to be batched into a single HTTP request. This 114 "batch" upload capability allows the server side to efficiently 115 support a large number of devices. The multiple measurements could 116 be from multiple related sensors or from the same sensor but at 117 different times. 119 3. Terminology 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 123 document are to be interpreted as described in RFC 2119 [RFC2119]. 125 4. Semantics 127 Each media type caries a single JSON object that represents a set of 128 measurements. This object contains several optional attributes 129 described below, followed by an mandatory array of one or more 130 measurements. 132 bn: This is a base name string that is perpended to the names found 133 in the measurements. This attribute is optional. 134 bt: A base time that is added to the time found in a measurement. 135 This attribute is optional. 136 ver: Version number of media type format. This attribute is 137 optional positive integer and defaults to 1 if not present. 138 m: Array of measurements. Required, and there must be at least one 139 measurement in the array. 141 Each measurement contains several attributes, some of which are 142 optional and some of which are mandatory. 144 n: Name of sensor. When appended to the "bn" attribute, this must 145 result in a globally unique identifier for the sensor. 146 u: Units for the sensor value. Optional. Acceptable values are 147 specified in Section 7.1 148 v: Value of sensor. Optional if an s value is present, otherwise 149 required. 150 s: Integrated sum of the sensor values over time. Optional. This 151 attribute is in the units specified in the u value multiplied by 152 seconds. 153 t: Time when measurement was made. Optional. 155 Open Issue: Ongoing conversations around Privacy, Accuracy/ 156 Confidence, Valid time, and tags. 158 The bt, v, s, and t attributes are floating point numbers. Systems 159 receiving measurements MUST be able to process the range of numbers 160 that are representable as an IEEE double-precision floating-point 161 numbers [IEEE.754.1985]. The number of significant digits in any 162 measurement is not relevant, so a reading of 1.1 has exactly the same 163 semantic meaning as 1.10. If the value has an exponent, the "e" MUST 164 be in lower case. The mantissa SHOULD be less than 19 characters 165 long and the exponent SHOULD be less than 5 characters long. 167 Systems reading one of the JSON objects MUST check for the ver 168 attribute. If this value is a version number larger than the version 169 which system understands, the system SHOULD NOT use this JSON object. 170 This allows the version number to indicate that the object contains 171 mandatory to understand attributes. New version numbers can only be 172 defined in RFC which update this specification or it successors. 174 The n value is concatenated to the bn value to get the name of the 175 sensor. The resulting name needs to uniquely identity and 176 differentiate the sensor from all others. If the name contains 48 177 bits of random material, or 48 bits of material that is procedurally 178 assigned in a unique way, it is considered to be good enough 179 uniqueness. One way to achieve this uniqueness is to include a 180 EUI-48 identifier (A MAC address) or some other 48 bit identifier 181 that is guaranteed uniqueness (such as a 1-wire address) that is 182 assigned to the device. UUIDs [RFC4122] are another way to generate 183 a unique name. 185 The resulting concatenated name MUST consist only of characters out 186 of the set "A" to "Z", "a" to "z", "0" to "9", "-", ":", ".", or "_" 187 and it MUST start with a character out of the set "A" to "Z", "a" to 188 "z", or "0" to "9". This restricted character set was chosen so that 189 these names can be directly used as in other types of URI including 190 segments of an HTTP path with no special encoding. 191 [I-D.ietf-6man-text-addr-representation] contains advice on encoding 192 an IPv6 address in a name. 194 If either the bt or t value is missing, the missing attribute is 195 considered to have a value of zero. The bt and t values are added 196 together to get the time of measurement. A time of zero is 197 considered to mean that the sensor does not know the time and the 198 measurement was made roughly "now". A negative value is used to 199 indicate seconds in the past from roughly "now". A positive value is 200 used to indicate the number of seconds since the start of the year 201 1970 in UTC excluding leap seconds. 203 Open Issue: Should this be atomic seconds instead of "Unix" style 204 time? 206 Open Issue: What about NaN and Infinity in the floating point 207 numbers? 209 Open Issue: If bt & t where floating point, this would allow sub 210 second precision. What time precision is needed? 211 Open Issue: What to do about Y2K38 problem that comes form 212 representing time in this way? This is coming up very soon and will 213 no doubt impact devices using this. Would it be better to use an 214 epoch of 2010 instead of 1970? There does not seem to be any need to 215 represent values before 2010. Would using a floating point double 216 work better? 218 5. Syntax 220 All of the data is UTF-8, but since this is for machine to machine 221 communications on constrained systems, only characters with code 222 points between U+0001 and U+007F are allowed. 224 The contents MUST consist of exactly one JSON object as specified by 225 [RFC4627]. This object MAY contain a "bn" attribute with a value of 226 type string. This object MAY contain a "bt" attribute with a value 227 of type number. The object MAY contain other attribute value pairs. 228 The object MUST contain exactly one "m" attribute with a value of 229 type array. The array MUST have one or more measurement objects. 231 Inside each measurement object the "n" and "u" attribute are of type 232 string and the "t", "v", and "s" attributes are of type number. 234 5.1. Simple Example 236 The following shows a temperature reading taken approximately "now": 237 {"m":[{ "n": "0017f202a5c5-Temp", "v":23.5 }]} 239 5.2. Complex Example 241 The following example show the voltage at Tue Jun 8 18:01:16 UTC 2010 242 along with the current at that time and at each second for the 243 previous 5 seconds. 244 {"m":[ 245 { "n": "voltage", "u": "V", 246 "v": 120.1, "anExtension": 0.0 }, 247 { "n": "current", "t": -5, "v": 1.2 }, 248 { "n": "current", "t": -4, "v": 1.30 }, 249 { "n": "current", "t": -3, "v": 0.14e1 }, 250 { "n": "current", "t": -2, "v": 1.5 }, 251 { "n": "current", "t": -1, "v": 1.6 }, 252 { "n": "current", "t": 0 "v": 1.7 }, 253 ] 254 "bn": "0017f202a5c5", 255 "bt": 1276020076, 256 "someExtensions": "a value", 257 } 259 6. Usage Considerations 261 The measurements support sending both the current value of a sensor 262 as well as the an integrated sum. For many types of measurements, 263 the sum is more useful than the current value. For example, an 264 electrical meter that measures the energy a given computer uses will 265 typically want to measure the cumulative amount of energy used. This 266 is less prone to error than reporting the power each second and 267 trying to have something on the server side sum together all the 268 power measurements. If the network between the sensor and the meter 269 goes down over some period of time, when it comes back up, the 270 cumulative sum helps reflect what happened while the network was 271 down. A meter like this would typically report a measurement with 272 the units set to watts, but it would put the sum of energy used in 273 the "s" attribute of the measurement. It might optionally include 274 the current power in the "v" attribute. 276 While the benefit of using the integrated sum is fairly clear for 277 measurements like power and energy, it is less obvious for something 278 like voltage. Reporting the sum of the temperatures makes it easy to 279 compute averages even when the individual temperature values are not 280 reported frequently enough to compute accurate averages. 281 Implementors are encouraged to report the cumulative sum as well as 282 the raw value of a given sensor. 284 Applications that use the cumulative sum values need to understand 285 they are very loosely defined by this specification, and depending on 286 the particular sensor implementation may behave in unexpected ways. 287 Applications should be able to deal with the following issues: 289 1. Many sensors will allow the cumulative sums to "wrap" back to 290 zero after the value gets sufficiently large. 291 2. Some sensors will reset the cumulative sum back to zero when the 292 device is reset, loses power, or is replaced with a different 293 sensor. 294 3. Applications cannot make assumptions about when the device 295 started accumulating values into the sum. 297 Typically applications can make some assumptions about specific 298 sensors that will allow them to deal with these problems. A common 299 assumption is that for sensors whose measurement values are always 300 positive, the sum should never get smaller; so if the sum does get 301 smaller, the application will know that one of the situations listed 302 above has happened. 304 7. IANA Considerations 306 Note to RFC Editor: Please replace all occurrences of "RFC-AAAA" 307 with the RFC number of this specification. 309 7.1. Units Registry 311 IANA will create a registry of unit symbols. The primary purpose of 312 this registry is to make sure that symbols uniquely map to give type 313 of measurement. Definitions for many of these units can be found in 314 [NIST822] and [BIPM]. 316 +--------+----------------------------------------------+-----------+ 317 | Symbol | Description | Reference | 318 +--------+----------------------------------------------+-----------+ 319 | m | meter | RFC-AAAA | 320 | kg | kilogram | RFC-AAAA | 321 | s | second | RFC-AAAA | 322 | A | ampere | RFC-AAAA | 323 | K | kelvin | RFC-AAAA | 324 | cd | candela | RFC-AAAA | 325 | mol | mole | RFC-AAAA | 326 | Hz | hertz | RFC-AAAA | 327 | rad | radian | RFC-AAAA | 328 | sr | steradian | RFC-AAAA | 329 | N | newton | RFC-AAAA | 330 | Pa | pascal | RFC-AAAA | 331 | J | joule | RFC-AAAA | 332 | W | watt | RFC-AAAA | 333 | C | coulomb | RFC-AAAA | 334 | V | volt | RFC-AAAA | 335 | F | farad | RFC-AAAA | 336 | Ohm | ohm | RFC-AAAA | 337 | S | siemens | RFC-AAAA | 338 | Wb | weber | RFC-AAAA | 339 | T | tesla | RFC-AAAA | 340 | H | henry | RFC-AAAA | 341 | degC | degrees Celsius | RFC-AAAA | 342 | lm | lumen | RFC-AAAA | 343 | lx | lux | RFC-AAAA | 344 | Bq | becquerel | RFC-AAAA | 345 | Gy | gray | RFC-AAAA | 346 | Sv | sievert | RFC-AAAA | 347 | kat | katal | RFC-AAAA | 348 | pH | pH acidity | RFC-AAAA | 349 | % | Value of a switch. A value of 0.0 indicates | RFC-AAAA | 350 | | the switch is off while 100.0 indicates on. | | 351 | count | counter value | RFC-AAAA | 352 | %RH | Relative Humidity | RFC-AAAA | 353 | m2 | area | RFC-AAAA | 354 | l | volume in liters | RFC-AAAA | 355 | m/s | velocity | RFC-AAAA | 356 | m/s2 | acceleration | RFC-AAAA | 357 | l/s | flow rate in liters per second | RFC-AAAA | 358 | W/m2 | irradiance | RFC-AAAA | 359 | cd/m2 | luminance | RFC-AAAA | 360 | Bspl | bel sound pressure level | RFC-AAAA | 361 | b/s | bits per second | RFC-AAAA | 362 | lat | degrees latitude. Assumed to be in WGS84 | RFC-AAAA | 363 | | unless another reference frame is known for | | 364 | | the sensor. | | 365 | lon | degrees longitude. Assumed to be in WGS84 | RFC-AAAA | 366 | | unless another reference frame is known for | | 367 | | the sensor. | | 368 +--------+----------------------------------------------+-----------+ 370 New entries can be added to the registration by either Expert Review 371 or IESG Approval as defined in [RFC5226]. Experts should exercise 372 their own good judgement but need to consider the following 373 guidelines: 375 1. There needs to be a real and compelling use for any new unit to 376 be added. 377 2. Units should define the semantic information and be chosen 378 carefully. Implementors need to remember that the same word may 379 be used in different real-life contexts. For example, degrees 380 when measuring latitude have no semantic relation to degrees 381 when measuring temperature; thus two different units are needed. 382 3. These measurements are produced by computers for consumption by 383 computers. The principle is that conversion has to be easily be 384 done when both reading and writing the media type. The value of 385 a single canonical representation outweighs the convenience of 386 easy human representations or loss of precision in a conversion. 387 4. Use of SI prefixes such as "k" before the unit is not allowed. 388 Instead one can represent the value using scientific notation 389 such a 1.2e3. 390 5. For a given type of measurement, there will only be one unit 391 type defined. So for length, meters are defined and other 392 lengths such as mile, foot, light year are not allowed. For 393 most cases, the SI unit is preferred. 394 6. Symbol names that could be easily confused with existing common 395 units or units combined with prefixes should be avoided. For 396 example, selecting a unit name of "mph" to indicate something 397 that had nothing to do with velocity would be a bad choice, as 398 "mph" is commonly used to mean mile per hour. 399 7. The following should not be used because the are common SI 400 prefixes: Y, Z, E, P, T, G, M, k, h, da, d, c, n, u, n, p, f, 401 a, z, y, Ki, Mi, Gi, Ti, Pi, Ei, Zi, Yi. 402 8. The following units should not be used as they are commonly used 403 to represent other measurements Ky, Gal, dyn, etg, P, St, Mx, G, 404 Oe, Gb, sb, Lmb, ph, Ci, R, RAD, REM, gal, bbl, qt, degF, Cal, 405 BTU, HP, pH, B/s, psi, Torr, atm, at, bar, kWh. 406 9. The unit names are case sensitive and the correct case needs to 407 be used, but symbols that differ only in case should not be 408 allocated. 410 10. A number after a unit typically indicates the previous unit 411 raised to that power, and the / indicates that the units that 412 follow are the reciprocal. A unit should have only one / in the 413 name. 415 7.2. Media Type Registration 417 The following registrations are done following the procedure 418 specified in [RFC4288] and [RFC3023]. 420 Note to RFC Editor: Please replace all occurrences of "RFC-AAAA" 421 with the RFC number of this specification. 423 7.2.1. senml+json Media Type Registration 425 To: ietf-types@iana.org 427 Subject: Registration of media type application/senml+json 429 Type name: application 431 Subtype name: senml+json 433 Required parameters: none 435 Optional parameters: none 437 Encoding considerations: Must be encoded as binary. See additional 438 constraints in [RFC4627]. 440 Security considerations: Sensor data can contain a wide range of 441 information ranging from information that is very public, such the 442 outside temperature in a given city, to very private information that 443 requires integrity and confidentiality protection, such as patient 444 health information. This format does not provide any security and 445 instead relies on the transport protocol that carries it to provide 446 security. Given applications need to look at the overall context of 447 how this media type will be used to decide if the security is 448 adequate. 450 Interoperability considerations: JSON allows new fields to be 451 defined and applications should be able to ignore fields they do not 452 understand to ensure forward compatibility with extensions to this 453 specification. 455 Published specification: RFC-AAAA 457 Applications that use this media type: N/A 458 Additional information: 460 Magic number(s): none 462 File extension(s): senml 464 Macintosh file type code(s): none 466 Person & email address to contact for further information: Cullen 467 Jennings 469 Intended usage: COMMON 471 Restrictions on usage: None 473 Author: Cullen Jennings 475 Change controller: Cullen Jennings 477 8. Security Considerations 479 Sensor data can range from information with almost no security 480 considerations, such as the current temperature in a given city, to 481 highly sensitive medical or location data. This specification 482 provides no security protection for the data but is meant to be used 483 inside another container or transport protocol such as S/MIME or HTTP 484 with TLS that can provide integrity, confidentiality, and 485 authentication information about the source of the data. 487 Further discussion of security proprieties can be found in 488 Section 7.2. 490 9. Acknowledgement 492 I would like to thank Lisa Dusseault, Joe Hildebrand, Lyndsay 493 Campbell and Carsten Bormann for their review comments. 495 10. References 497 10.1. Normative References 499 [RFC4627] Crockford, D., "The application/json Media Type for 500 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 502 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 503 Types", RFC 3023, January 2001. 505 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 506 Registration Procedures", BCP 13, RFC 4288, December 2005. 508 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 509 Requirement Levels", BCP 14, RFC 2119, March 1997. 511 [IEEE.754.1985] 512 Institute of Electrical and Electronics Engineers, 513 "Standard for Binary Floating-Point Arithmetic", 514 IEEE Standard 754, August 1985. 516 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 517 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 518 May 2008. 520 [NIST822] Thompson, A. and B. Taylor, "Guide for the Use of the 521 International System of Units (SI)", NIST Special 522 Publication 811, 2008 Edition . 524 [BIPM] Bureau International des Poids et Mesures, "The 525 International System of Units (SI)", 8th edition, 2006 . 527 10.2. Informative References 529 [I-D.shelby-core-coap] 530 Shelby, Z., Frank, B., and D. Sturek, "Constrained 531 Application Protocol (CoAP)", draft-shelby-core-coap-01 532 (work in progress), May 2010. 534 [I-D.ietf-6man-text-addr-representation] 535 Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 536 Address Text Representation", 537 draft-ietf-6man-text-addr-representation-07 (work in 538 progress), February 2010. 540 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 541 Unique IDentifier (UUID) URN Namespace", RFC 4122, 542 July 2005. 544 Author's Address 546 Cullen Jennings 547 Cisco 548 170 West Tasman Drive 549 San Jose, CA 95134 550 USA 552 Phone: +1 408 421-9990 553 Email: fluffy@cisco.com