idnits 2.17.1 draft-bormann-t2trg-slipmux-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 05, 2019) is 1634 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Informational T. Kaupat 5 Expires: May 8, 2020 Lobaro UG 6 November 05, 2019 8 Slipmux: Using an UART interface for diagnostics, configuration, and 9 packet transfer 10 draft-bormann-t2trg-slipmux-03 12 Abstract 14 Many research and maker platforms for Internet of Things 15 experimentation offer a serial interface. This is often used for 16 programming, diagnostic output, as well as a crude command interface 17 ("AT interface"). Alternatively, it is often used with SLIP 18 (RFC1055) to transfer IP packets only. 20 The present report describes how to use a single serial interface for 21 diagnostics, configuration commands and state readback, as well as 22 packet transfer. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on May 8, 2020. 41 Copyright Notice 43 Copyright (c) 2019 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Using a UART interface . . . . . . . . . . . . . . . . . . . 3 61 3. Packet Transfer . . . . . . . . . . . . . . . . . . . . . . . 3 62 4. Diagnostics Transfer . . . . . . . . . . . . . . . . . . . . 4 63 5. Configuration . . . . . . . . . . . . . . . . . . . . . . . . 4 64 6. Framing considerations . . . . . . . . . . . . . . . . . . . 5 65 7. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 7.1. Why no shell? . . . . . . . . . . . . . . . . . . . . . . 5 67 7.2. Frame aborts . . . . . . . . . . . . . . . . . . . . . . 6 68 7.3. Unknown initial bytes . . . . . . . . . . . . . . . . . . 6 69 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 9. Security Considerations . . . . . . . . . . . . . . . . . . . 7 71 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 10.1. Normative References . . . . . . . . . . . . . . . . . . 8 73 10.2. Informative References . . . . . . . . . . . . . . . . . 8 74 Appendix A. Implementation . . . . . . . . . . . . . . . . . . . 8 75 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 78 1. Introduction 80 Many research and maker hardware modules for Internet of Things 81 experimentation ("platforms") offer a serial ("UART") interface. 82 This is often used for programming, diagnostic output, as well as a 83 crude command interface ("AT interface"). Alternatively, it is used 84 with SLIP (RFC1055) to transfer IP packets only; this may require the 85 use of another serial interface for diagnostics and configuration. 87 The present report describes how to use a single serial interface for 88 diagnostics, configuration commands and state readback, as well as 89 packet transfer. 91 1.1. Terminology 93 The term "byte" is used in its now customary sense as a synonym for 94 "octet". Where bit arithmetic is explained, this document uses the 95 notation familiar from the programming language C (including C++14's 96 0bnnn binary literals), except that the operator "**" stands for 97 exponentiation. 99 2. Using a UART interface 101 The serial interfaces provided by today's platforms often do not 102 actually use EIA-232 ("RS-232") levels, but some form of logic levels 103 (TTL or more likely 3.3 V CMOS). The present report does not discuss 104 physical interfacing, but assumes that a TXD (transmit data) pin, a 105 RXD (receive data) pin, and a GND (common ground) pin are all that is 106 available. To interface laptops and similar devices to these serial 107 interfaces, inexpensive ($2) USB to UART adapters based on chips such 108 as PL2303, CP2102 or CH340 are easily obtainable. (The usual care 109 needs to be taken when mixing 3.3 V and 5 V platforms; this is well 110 understood but beyond the scope of the present report.) 112 The general assumption is that a serial port configuration of 8N1 (8 113 bits per character, no parity, 1 stop bit) and a bit rate of 115200 114 bit/s is used. As with the logic levels, alternative arrangements 115 are possible, but a 3.3 V CMOS, 115200 bit/s interface is most likely 116 to provide the best interoperability. 118 While it would be possible to run relatively complex and versatile 119 protocols such as PPP [RFC1661] on such serial interfaces, this goes 120 against a need for simplicity and ease of setup. In today's systems, 121 either weird ad-hoc protocols based on "AT commands" are used that 122 are not interoperable at all, or a simple encapsulation such as SLIP 123 [RFC1055] is used for packet transfer only. 125 For the purposes of the present report, on top of the serial UART 126 protocol, the frame format defined by [RFC1055] is indeed employed. 127 The detailed descriptions below generally describe the frame data 128 before applying SLIP escaping in the transmitter or after removing it 129 in the receiver. 131 The approach described here is informally referred to as "slipmux". 133 3. Packet Transfer 135 Packet transfer uses the definitions of [RFC1055]. However, contrary 136 to the statement in section DEFICIENCIES of [RFC1055], multiplexing 137 is very well possible. A frame used for packet transfer is detected 138 by an initial byte of one of the two forms: 140 o 0x45 to 0x4f: IPv4 packet 142 o 0x60 to 0x6f: IPv6 packet 143 This initial byte forms part of the packet; it is not removed from 144 the payload as with the other formats defined below. 146 There are no changes to the formats defined by [RFC1055], so there 147 should be immediate interoperability with tools such as tunslip. 149 4. Diagnostics Transfer 151 While not transferring a frame bearing a packet, the platform can 152 alternatively transmit a diagnostic frame. These are encoded (and 153 escaped) using SLIP framing exactly like packet frames, but start 154 with the byte 0x0a (ASCII newline) and contain UTF-8 encoded 155 characters after that byte. There is no semantics attached to the 156 diagnostics message, except that it is intended as a human-readable 157 debug or diagnostic message from the platform code. It is generally 158 preferable to end the payload of a diagnostics message in another 159 newline (0x0a, which on the wire is then followed by 0xc0 due to the 160 SLIP framing). Note that, as long as only ASCII characters are used, 161 there is no need to actually perform escaping on the diagnostic 162 message. 164 Since diagnostic messages are intended for humans, they are only 165 defined for the direction from platform to host (e.g., laptop); for 166 robustness when connecting two platform modules, they should be 167 ignored by platform modules. 169 5. Configuration 171 Configuration is performed by sending CoAP messages [RFC7252] in SLIP 172 framing. The encapsulation of a CoAP message starts with an 173 additional byte 0xA9, with the bytes of the CoAP message following 174 (which, as for all data in frames, are escaped as necessary as per 175 [RFC1055]). 177 In contrast to the packet and diagnostics frames defined above, CoAP 178 frames benefit from a frame check mechanism. After the CoAP message, 179 the last two bytes of a CoAP frame therefore contain a 16-bit CRC FCS 180 computed over the byte 0xA9 followed by the (unescaped) bytes of the 181 CoAP message, computed as specified in [RFC1662]. (Note that the two 182 bytes of the CRC are escaped, as necessary, by the SLIP framing, as 183 are all other bytes of the CoAP message.) 185 CoAP messages with incorrect CRCs are silently discarded. 187 Where a local URI needs to be formed for the configuration messages, 188 the URI scheme "coap+uart" is used; the authority part of that URI 189 might be used to refer to local interface names as needed, as in: 191 coap+uart://ttyUSB0/APlist 193 The client could also be using a local mapping table to provide some 194 indirection in translating the authority part to a local identifier 195 of the serial port(e.g., COM0 to ttyUSB0). 197 Using an empty URI authority allows the client to use a default port, 198 as in: 200 coap+uart:///APlist 202 A later version of this report might define some common CoAP 203 resources that research or maker platforms might want to provide, 204 e.g. to cover the configuration and status checking often done by "AT 205 commands" today. 207 6. Framing considerations 209 To make SLIP framing robust, it is important to send SLIP frame 210 delimiters (0xc0) before and after each SLIP frame (maybe unless 211 frames follow each other back to back). This means that empty frames 212 need to be silently ignored by a receiver. 214 If a platform starts to send a packet or message, but then decides it 215 should not complete the message before having sent the rest of the 216 frame, it can send the SLIP ESC (0xdb) followed by SLIP END (0xc0) to 217 abort the frame. Note that this goes beyond the error handling 218 suggested by the section "SLIP DRIVERS" in [RFC1055] and might 219 therefore be of limited interoperability at first. 221 Messages in slipmux are strictly sequential; there is no [RFC2687] 222 style suspension. In particular, this means that diagnostic messages 223 that are generated while another message is in progress may have to 224 be buffered (unless they are important enough to abort the frame as 225 described above). 227 7. Discussion 229 7.1. Why no shell? 231 The present report is somewhat radical in that it does not provide a 232 common staple of interactive computer access: A command line 233 interface (CLI), or "shell". 235 This would be easy to add, but distracts from the use of the platform 236 as a "thing" - it should not have to carry an (even primitive) user 237 interface; instead it should provide what would have been "shell 238 commands" as CoAP resources. 240 As a transition aid, existing shell commands can first be converted 241 to just accept their parameters via CoAP but continue to provide 242 their output as ASCII text over the diagnostic channel. 244 However, in order to aid script-driven use of the platform, the next 245 step should then be to also provide the response to the command in a 246 CoAP response, possibly structured for better use by the script. 247 Often code that was designed to format the data for human consumption 248 can be simplified to just ship the raw data, e.g. in a CBOR data item 249 [RFC7049]. 251 7.2. Frame aborts 253 Implementing frame aborts as described in Section 6 requires a 254 receiver to receive the entire frame before acting on it. For 255 diagnostic information, this is somewhat moot - the information is 256 there independent of whether its frame was aborted or not. For 257 packets, it is usually necessary to check a UDP or TCP header 258 checksum before acting on it, anyway. For CoAP requests, similarly, 259 the CRC needs to be checked. So implementing frame aborts should not 260 be an undue burden. 262 7.3. Unknown initial bytes 264 Frames with unknown initial bytes should be silently ignored. 266 The same is true for frames with initial bytes that are 267 unimplemented. However, there is an expectation that true slipmux 268 implementations do implement CoAP framing. If this is unexpectedly 269 not the case, as a courtesy to a peer CoAP client, a slipmux 270 implementation could at least send CoAP Reset messages: a CoAP frame 271 (initial byte 0xA9) with a message that starts with 0x40 to 0x5f 272 could be replied to with a CoAP frame with a CoAP RST message, 273 containing just these four bytes (as always, escaped as needed, and 274 framed with an initial 0xA9 and a CRC): 276 o 0x70 278 o 0x00 280 o The third (unescaped) byte of the message being replied to 282 o The fourth (unescaped) byte of the message being replied to 284 (Generating proper CoAP framing in response does, require 285 implementing the PPP CRC.) In conjunction with the CoAP ping 286 response of a normal CoAP implementation, this also can be used for 287 liveness testing. 289 (The check for the first byte of the CoAP message is needed to avoid 290 endless back and forth of reset messages in certain error 291 situations.) 293 8. IANA Considerations 295 The present report does not foresee adding additional frame types, 296 but as a matter of precaution, this section might define a registry 297 for initial bytes in a frame. At this point, this would contain: 299 o 0x0a: Diagnostics 301 o 0x45 to 0x4f: IPv4 packet 303 o 0x60 to 0x6f: IPv6 packet 305 o 0xA9: CoAP message with 16-bit FCS 307 If such a registry is desired, the following values for initial bytes 308 should probably be reserved (while all these values could be used if 309 required, implementation is easier if they are not): 311 o 0x00 313 o 0xc0: [RFC1055] END 315 o 0xdb: [RFC1055] ESC 317 There might also be a need to formally register the URI scheme 318 "coap+uart". 320 9. Security Considerations 322 The usual security considerations apply to the IP packets transferred 323 in packet frames. 325 When displaying information from diagnostic frames, care should be 326 taken that features of a terminal triggered e.g. by escape sequences 327 cannot be used for nefarious purposes. 329 The CoAP configuration interface does not itself provide any 330 security. This may be appropriate for the local configuration needs 331 of an experimentation platform that is not expected to be physically 332 connected to any system that is not allowed full control over it 333 (e.g., by using the same physical interface for reflashing new 334 firmware). Where the platform might connect to other systems over 335 serial, object security for CoAP [RFC8613] might be employed, or the 336 configuration interface might be restricted to a read-only mode only 337 providing information that does not need confidentiality protection. 338 (It would be possible to provide a DTLS encapsulation, but this might 339 go beyond the objective of extreme simplicity.) 341 10. References 343 10.1. Normative References 345 [RFC1055] Romkey, J., "Nonstandard for transmission of IP datagrams 346 over serial lines: SLIP", STD 47, RFC 1055, 347 DOI 10.17487/RFC1055, June 1988, 348 . 350 [RFC1662] Simpson, W., Ed., "PPP in HDLC-like Framing", STD 51, 351 RFC 1662, DOI 10.17487/RFC1662, July 1994, 352 . 354 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 355 Application Protocol (CoAP)", RFC 7252, 356 DOI 10.17487/RFC7252, June 2014, 357 . 359 10.2. Informative References 361 [RFC1661] Simpson, W., Ed., "The Point-to-Point Protocol (PPP)", 362 STD 51, RFC 1661, DOI 10.17487/RFC1661, July 1994, 363 . 365 [RFC2687] Bormann, C., "PPP in a Real-time Oriented HDLC-like 366 Framing", RFC 2687, DOI 10.17487/RFC2687, September 1999, 367 . 369 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 370 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 371 October 2013, . 373 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 374 "Object Security for Constrained RESTful Environments 375 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 376 . 378 Appendix A. Implementation 380 A work in progress implementation of slipmux is available as part of 381 Lobaro's SLIP implementation: 383 https://github.com/Lobaro/slip 384 https://github.com/Lobaro/util-slip 386 Acknowledgements 388 TBD 390 Authors' Addresses 392 Carsten Bormann 393 Universitaet Bremen TZI 394 Postfach 330440 395 Bremen D-28359 396 Germany 398 Phone: +49-421-218-63921 399 Email: cabo@tzi.org 401 Tobias Kaupat 402 Lobaro UG 403 Tempowerkring 21d 404 Hamburg D-21079 405 Germany 407 Phone: +49-40-22816531-0 408 Email: tobias.kaupat@lobaro.de