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