Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:otlib:mpipe

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
opentag:otlib:mpipe [2012/03/24 16:40]
jpnorair [NDEF Header]
opentag:otlib:mpipe [2013/11/15 02:16] (current)
jpnorair MPipe 2
Line 1: Line 1:
 ====== MPipe (Message Pipe) ====== ====== MPipe (Message Pipe) ======
-"​MPipe"​ is a message pipe interface that is used for [[opentag:​system_arch|client-server]] communication in [[opentag:​main|OpenTag]]. ​ In most cases, MPipe is a wireline link, such as SPI, UART, USB, etc.  It could potentially be a wireless link, however. ​ In any case, MPipe is designed to be a point-to-point link between two known devices. ​ The protocol is extremely light, and it performs no addressing.+"​MPipe"​ is a message pipe interface that is used for [[opentag:​system_arch|client-server]] communication in [[opentag:​main|OpenTag]]. ​ In most cases, MPipe is a wireline link, such as SPI, UART, USB, etc.  It could potentially be a wireless link, however. ​ In any case, MPipe is designed to be a point-to-point link between two implicitly addressed ​devices. ​ The protocol is extremely light, and it performs no addressing
 + 
 +=== MPipe 1, MPipe 2 === 
 +There are two versions of MPipe: 1 and 2.  Version 1 is the original, NDEF-based protocol that came with all versions of OpenTag BEFORE v0.5.  MPipe 2 is included in OpenTag v0.5.  Likewise, [[opentag:​tools:​otcom|OTcom]] versions BEFORE 3.x use MPipe 1, and starting with v3.x MPipe 2 is used. 
 + 
 +===== MPipe Feature Overview ===== 
 +=== Versions 1 & 2 === 
 +  * No explicit addressing 
 +  * Uses a single [[opentag:​otlib:​alp|ALP/​NDEF]] record per packet 
 +  * Max packet length = ALP/NDEF Overhead + MPipe Overhead + 255 byte payload = ~268 bytes 
 +  * Contains CRC16 for data integrity 
 +  * Contains a sequence ID for keeping data in order 
 +  * Optional ability for ACK and NACK 
 + 
 +=== Version 1 Only === 
 +  * Designed with fully in-place memory access in mind. 
 +    * Header is shared with 6-byte NDEF "​Type=Unknown"​ header 
 +    * Additional control data is placed in a 4 byte footer 
 +  * No extensibility beyond what is available in the applied subset of NDEF 
 + 
 +=== Version 2 Only === 
 +  * Designed with energy optimization and client implementation in mind 
 +    * Includes a wake-up and sync component to the header 
 +    * New header is 8 bytes fixed length, and orthogonal to the ALP interior 
 +    * No more footer 
 +  * Requires translation for compatibility with formal NDEF specification,​ but full compatibility and interchange with DASH7 ALP. 
 +  * Some extensibility available in header, for example to support crypto in the future.
  
-===== MPipe Basic Features ===== 
-  * Typically a serial-style communication link 
-  * Lightweight data integrity checks 
-  * Uses an NDEF header 
-  * Contains CRC16 for data integrity (footer) 
-  * Contains a 16 bit sequence ID for keeping data in order (footer) 
  
 ==== Link Types ==== ==== Link Types ====
-At present, MPipe has been implemented over an RS-232 style UART (i.e. TTY or COM port) as well as a USB CDC virtual COM port.  When using USB, often USB will do some packet data integrity management of its own.  In these implementations, ​it is possible ​to remove ​(or bypass) MPipe's data integrity management with no penalty.+At present, MPipe has been implemented over an RS-232 style UART (i.e. TTY or COM port) as well as a USB CDC ACM "virtual COM" ​port.  When using USB, often USB will do some packet data integrity management of its own.  In these implementations, ​you may consider removing the MPipe CRC if you are confident there is not possibility of malicious client that might try to send corrupted data by virtue of a USB overflow hack (vulnerability actually depends a lot on the USB implementation of the MCU).  ​MPipe 2 has some design features that are intended to make it a lot less vulnerable to these sorts of hacks (or bugs!).
  
 ==== Data Integrity ==== ==== Data Integrity ====
-MPipe uses a CRC16 footer ​and sequence ​ID footer ​to allow receiving devices to determine if the incoming packet is erroneous.  ​Mpipe also includes ​an ACK/NACK method ​for notifying the sender.+MPipe 1 and 2 both use CRC16 and sequence ​IDs to allow receiving devices to determine if the incoming packet is erroneous.  ​Data retransmissions can be actuated by an ACK/NACK method ​of notifying the sender.
  
-  * **Sequence Number** is a 16 bit unsigned integer that counts-up whenever a new packet is generated. ​ It does not count-up during ACK/NACKs or retransmissions.+  * **Sequence Number** is a 16 bit (v1) or 8 bit (v2) unsigned integer that counts-up whenever a new packet is generated. ​ It does not count-up during ACK/NACKs or retransmissions.
   * **CRC16** is a 16 bit CRC field. ​ The actual CRC16 method is unspecified,​ but by convention the same [[opentag:​otlib:​crc|CRC16 method used by DASH7]] is used by MPipe.   * **CRC16** is a 16 bit CRC field. ​ The actual CRC16 method is unspecified,​ but by convention the same [[opentag:​otlib:​crc|CRC16 method used by DASH7]] is used by MPipe.
-  * An **ACK** is an MPipe packet with 0 payload, the same sequence number as the last-received packet, and 0x0000 for the ID. +  * An **ACK** is an MPipe packet with 0 payload, the same sequence number as the last-received packet, and ID (v1) or CONTROL (v2) set to 0
-  * A **NACK** is an MPipe packet with 0 payload, the same sequence number as the last-received packet, and 0x00xx for the ID, where "​xx"​ is non-zero. +  * A **NACK** is an MPipe packet with 0 payload, the same sequence number as the last-received packet, and ID set to non-zero ​(v1) or CONTROL set to 1 (v2)
-  * ACKing/​NACKing is not mandatory.+  * ACKing/​NACKing is not mandatory!  For USB CDC ACM links, it is not helpful because USB already does its own ACKing at low level.
  
-==== NDEF Header ====+==== Version 1 Header ​(NDEF) ​====
 The [[http://​www.nfc-forum.org/​specs/​spec_list/​|NDEF]] header is implemented via the [[opentag:​otlib:​ndef|OTlib NDEF library]], and thus it follows the normal requirements of OpenTag'​s stripped-down version of NDEF.  In summary, OpenTag NDEF headers are always 6 bytes in length, and structured as below. The [[http://​www.nfc-forum.org/​specs/​spec_list/​|NDEF]] header is implemented via the [[opentag:​otlib:​ndef|OTlib NDEF library]], and thus it follows the normal requirements of OpenTag'​s stripped-down version of NDEF.  In summary, OpenTag NDEF headers are always 6 bytes in length, and structured as below.
  
Line 30: Line 50:
   * The "ALP Ctrl" data corresponds to a Protocol ID (1 Byte) and a Command Descriptor (1 Byte). ​ For more information on this, check the [[opentag:​otlib:​alp|ALP Module]].   * The "ALP Ctrl" data corresponds to a Protocol ID (1 Byte) and a Command Descriptor (1 Byte). ​ For more information on this, check the [[opentag:​otlib:​alp|ALP Module]].
   * The short record length is always used.  Therefore, the maximum size of an MPipe frame payload is 255 bytes. ​ Also, 4 bytes must be included for the MPipe footer, making 265 bytes (6+255+4) the maximum size of a total MPipe frame. ​ Therefore, a good minimum allocation for an MPipe Queue is 265 bytes, although custom implementations can be smaller as long as the client is aware.   * The short record length is always used.  Therefore, the maximum size of an MPipe frame payload is 255 bytes. ​ Also, 4 bytes must be included for the MPipe footer, making 265 bytes (6+255+4) the maximum size of a total MPipe frame. ​ Therefore, a good minimum allocation for an MPipe Queue is 265 bytes, although custom implementations can be smaller as long as the client is aware.
 +
 +==== Version 2 Header ====
 +Version 2 uses an orthogonal header, and the NDEF header from v1 is replaced with an interior ALP Header. ​ The footer from v1 is now in the v2 header, leading to a somewhat unusual-looking implementation of CRC (the implementation is actually no less elegant).
 +
 +^  Sync Word  ^  CRC16    ^  Payload Length ​ ^  Sequence ​ ^  Control ​ ^  Payload ​       ^
 +|  2 Bytes    |  2 Bytes  |  2 Bytes         ​| ​ 1 Byte    |  1 Byte   ​^ ​ N Bytes        ^
 +|  0xFF55 ​    ​| ​          ​| ​ N               ​| ​           |           ​^ ​ 1 ALP Record ​  ^
 +
 +== Low Power Wakeup ==
 +The first byte of the sync word, FF, is designed so that a serial link can be completely shut-down, and a line interrupt can be used to wakeup the system from deep sleep in time to turn on the serial subsystems and receive the rest of the packet.
 +
 +== Client-Friendly ==
 +Client implementations that search through unbounded sets of data can search for the FF55 sync word.  This is especially helpful on Windows, which doesn'​t have any method for generating a new-received-data signal. ​ POSIX can do that easily, but in any case it doesn'​t //need// to anymore.
 +
 +== CRC in Header ==
 +The CRC16 value is computed on the Payload Length, Sequence, Control, and Payload. ​ Then it is deposited onto the header. ​ To check the CRC of a received packet, simply do a block computation over the same data field and subtract it from the received CRC (It should yield 0).
 +
 +== Control ==
 +The control bytes is used by ACK and NACK, but in the near future it may also have some of its bits used to specify that cryptography is being used on the payload.
  
  
opentag/otlib/mpipe.txt · Last modified: 2013/11/15 02:16 by jpnorair