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