Interface: tos.lib.serial.ReceiveBytePacket

interface ReceiveBytePacket

This is the data interface that a serial protocol provides and a serial dispatcher uses. The dispatcher expects the following pattern of calls: ((startPacket)+ (byteReceived)* (endPacket)+)* It should ignore any signals that do not follow this pattern. The interface is used to separate the state machine of the wire protocol from the complexities of dispatch.

Author:: Philip Levis; Ben Greenstein
Date:: August 7 2005

Events

event void byteReceived(uint8_t data) Signals the upper layer that a byte of the encapsulated packet has been received.

event void endPacket(error_t result) Signalled to indicate that a packet encapsulated withing a serial frame has been received.

event error_t startPacket() Signals the upper layer to indicate that reception of a frame has begun.

Events - Details

byteReceived

event void byteReceived(uint8_t data)

Signals the upper layer that a byte of the encapsulated packet has been received. Passes this byte as a parameter to the function.

Parameters:: data - A byte of the encapsulated packet that has been received.

endPacket

event void endPacket(error_t result)

Signalled to indicate that a packet encapsulated withing a serial frame has been received. SUCCESS should be passed by the lower layer following verification that the packet has been received correctly. A value of error_t indicating an error should be passed when the lower layer's verification test fails or when the lower layer loses sync.

Parameters:: result - An error_t code indicating whether the framer has passed all bytes of an encapsulated packet it receives from serial to the dispatcher (SUCCESS) or not (FAIL).

startPacket

event error_t startPacket()

Signals the upper layer to indicate that reception of a frame has begun. Used by the upper layer to prepare for packet reception. If the upper layer does not want to receive a packet (or isn't ready) it may return a non-SUCCESS code such as EBUSY to the lower layer to discard the frame. The underlying layer may signal endPacket in response to such a discard request.

Returns:: Returns an error_t code indicating whether the dispatcher would like to receive a packet (SUCCESS), or not perhaps because it isn't ready (EBUSY).