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