tep113.txt

tinyos-2.x.rar

After sending an entire frame and receiving the last putDone() event
from below, SerialP signals sendCompleted() to indicate the success or
failure of a requested transmission.

Packet reception is also managed by SerialP and the interface
provided to the upper layer is ReceiveBytePacket:

::

  interface ReceiveBytePacket {
    async event error_t startPacket();
    async event void byteReceived(uint8_t b);
    async event void endPacket(error_t result);
  }

Upon receiving an interframe delimiter and a new frame's header,
SerialP signals the upper layer indicating that a packet is
arriving. For each byte received, SerialP signals byteReceived().
Once SerialP receives the complete frame it signals endPacket with a
value of SUCCESS. If instead it loses sync during reception it signals
endPacket with FAIL.

SerialP acknowledges frames it receives. Acknowledgements have a
higher priority than data transmissions and consequently, data frames
may be slightly delayed. However, acknowledgement information is
stored in a queue separate from the data buffer, so a data packet to
be transmitted may begin spooling into SerialP while SerialP is
actively sending an acknowledgement.

Only the PC-to-mote communication path supports acknowledgements.
SerialP does not request acknowledgements from the PC for two reasons.
First, acks are not perfect reliable: they are used on the
PC-to-mote path to raise reliability to a usable level. In the case of
the PC-to-mote path, the UART receive buffer is typically a single
byte, so a high interrupt load can easily lose (and sometimes does) a
byte. This is in contrast to the PC receive buffer, which is much
larger and does not have to deal with overflow. Second, adding support
for acks would increase the code size and complexity of the serial
stack. As code space is often at a premium, this would add little
needed functionality at significant cost. Of course, any application
that requires perfect reliability may layer its own scheme on top of
the serial protocol.

The acknowledgement protocol is stop-and-wait to minimize buffering on
the mote side. This is considered more important on memory constrained
devices than increased throughput in the PC-to-mote direction, which
most applications only use for occasional control transmissions.


3.4 Dispatcher: SerialDispatcherC
--------------------------------------------------------------------

SerialDispatcherC handles the data packets that the Protocol component
receives. It uses the SendBytePacket and ReceiveBytePacket interfaces,
and provides parameterized Send and Receive interfaces. The parameter
in the Send and Receive interfaces (``uart_id_t``) determines the
packet format contained in the message_t.

SerialDispatcherC places a one-byte header, the packet format
identifier, on the packets sent and received through SerialP.
SerialDispatcherC uses a parameterized SerialPacketInfo interface to
be able to handle various packet formats:

::

  interface SerialPacketInfo {
    async command uint8_t offset();
    async command uint8_t dataLinkLength(message_t* msg, uint8_t upperLen);
    async command uint8_t upperLength(message_t* msg, uint8_t dataLinkLen);
  }

When SerialDispatcherC receives the first data byte of a packet from
SerialP, it stores it as the packet type and calls
offset() to determine where in a message_t that
packet format begins. It then spools data bytes in, filling them into
its message_t buffer. Similarly, on the send side, it first sends the
type byte and spools out data bytes starting from the index denoted by
the call to offset(). SerialDispatcherC uses the two length commands,
dataLinkLength() and upperLength(), to translate between the two notions
of packet length: above, length refers to the payload excluding
header, while below it refers to the payload plus header.

A component that provides communication over the serial port with
uart_id_t *U* MUST wire a component implementing SerialPacketInfo to
SerialDispatcherC with uart_id_t *U*. The file ``Serial.h`` contains
reserved uart_id_t's for supported packet formats. Currently, only
platform independent active messages
(``TOS_SERIAL_ACTIVE_MESSAGE_ID``, described in Section 3.5), 802.15.4
active messages (``TOS_SERIAL_802_15_4_ID``), mica2 CC1000 packets
(``TOS_SERIAL_CC1000_ID``) and the error code
``TOS_SERIAL_UNKNOWN_ID`` are reserved. New packet formats MUST NOT
reuse any reserved identifiers.

3.5 SerialActiveMessageC
--------------------------------------------------------------------

SerialActiveMessageC is a platform-independent active message layer
that operates on top of the serial communication
stack. SerialActiveMessageC is a configuration that wires
SerialActiveMessageP to SerialDispatcherC with uart_id_t
TOS_SERIAL_ACTIVE_MESSAGE_ID and wires SerialPacketInfoActiveMessageP
to SerialDispatcherC with uart_id_t TOS_SERIAL_ACTIVE_MESSAGE_ID:

::

  includes Serial;``
  configuration SerialActiveMessageC {
    provides {
      interface Init;
      interface AMSend[am_id_t id];
      interface Receive[am_id_t id];
      interface Packet;
      interface AMPacket;
    }
    uses interface Leds;
  }
  implementation {
    components new SerialActiveMessageP() as AM, SerialDispatcherC;
    components SerialPacketInfoActiveMessageP as Info;
   
    Init = SerialDispatcherC;
    Leds = SerialDispatcherC;
   
    AMSend = AM;
    Receive = AM;
    Packet = AM;
    AMPacket = AM;
    
    AM.SubSend -> SerialDispatcherC.Send[TOS_SERIAL_ACTIVE_MESSAGE_ID];
    AM.SubReceive -> SerialDispatcherC.Receive[TOS_SERIAL_ACTIVE_MESSAGE_ID];
    
    SerialDispatcherC.SerialPacketInfo[TOS_SERIAL_ACTIVE_MESSAGE_ID] -> Info;
  }


SerialActiveMessageP is a generic component so that it can be used to
sit on top of any packet-level communication layer. It does not filter
packets based on destination address or group. It assumes that if the
packet was received over the serial port, it was destined to the
node. This saves PC-side tools from having to discover or consider the
ID and group of a mote.

Platform-independent active messages do not have a CRC (they assumes
the serial stack CRC is sufficient), and have the following header:

::

  typedef nx_struct SerialAMHeader {
    nx_am_addr_t addr;
    nx_uint8_t length;
    nx_am_group_t group;
    nx_am_id_t type;
  } SerialAMHeader;



3.6 Packet Format
--------------------------------------------------------------------

A data packet in the TinyOS 2.x serial stack has the following format
over the wire. Each protocol field is associated with a specific component:

::

     ____________________________________________
    | | | | |                               |  | |
    | | | | |                               |  | | 
    |_|_|_|_|_______________________________|__|_|
     F P S D         Payload                 CR F
   
  F       = Framing byte, denoting start of packet: HdlcTranslateC
  P       = Protocol byte: SerialP
  S       = Sequence number byte: SerialP
  D       = Packet format dispatch byte: SerialDispatcherC
  Payload = Data payload (stored in SerialDispatcherC): SerialDispatcherC
  CR      = Two-byte CRC over S to end of Payload: SerialP
  F       = Framing byte denoting end of packet: HdlcTranslateC

Payload is a contiguous packet that SerialDispatcherC reads in.  Note
that any data bytes (P - CR) equal to 0x7e or 0x7d will be escaped to
0x7d 0x5e or 0x7d 0x5d accordingly. For example, a platform
independent AM packet of type 6, group 0x7d, and length 5 to
destination 0xbeef with a payload of 1 2 3 4 5 would look like this:

``7e 40 09 00 be ef 05 7d 5d 06 01 02 03 04 05 7e``

Note that the group 0x7d is escaped to 0x7d 0x5d. The protocol field
(P) is 0x40 (64), corresponding to ``SERIAL_PROTO_ACK`` (in Serial.h).


4. Access Abstractions
====================================================================

Two generic components: SerialAMSenderC and SerialAMReceiverC connect
to SerialActiveMessageC to provide virtualized access to the serial
stack. Each instantiation of SerialAMSenderC has its own queue of
depth one. Therefore, it does not have to contend with other
SerialAMSender instantiations for queue space. The underlying
implementation schedulers the packets in these queues using some form
of fair-share queueing. SerialAMReceiverC provides the virtualized
abstraction for reception. These abstractions are very similar to
TinyOS's radio abstractions, namely, AMSenderC and AMReceiverC. See
Section 4 of TEP 116[TEP116_] for more information. Unlike the
services in the TEP 116, the serial component virtualizations provide
no snooping capabilities.


5. Author's Address
====================================================================

| Philip Levis
| 358 Gates
| Computer Science Laboratory
| Stanford University
| Stanford, CA 94305
|
| phone - [phone]
| email - [e-mail]
|
|
| Ben Greenstein
| Intel Research Seattle
| 1100 NE 45th Street, 6th Floor
| Seattle, WA 98105
|
| phone -  [phone]
| email - [e-mail]

6. Citations
====================================================================

.. [TEP2] TEP 2: Hardware Abstraction Architecture. tinyos-2.x/doc/txt/tep2.txt

.. [TEP111] TEP 111: message_t. tinyos-2.x/doc/txt/tep111.txt

.. [TEP116] TEP 116: Packet Protocols. tinyos-2.x/doc/txt/tep116.txt
 
.. [TEP117] TEP 117: Low-Level I/O. tinyos-2.x/doc/txt/tep117.txt

.. [HDLC] International Organization For Standardization, ISO Standard 3309-1979, "Data communication - High-level data link control procedures - Frame structure", 1979.

.. [RFC1662] PPP in HDLC-like Framing, Internet Engineering Task Force (IETF), 1994