Interface: moteiv.tos.lib.sp.SPSend

interface SPSend

The primary interface for sending a message using SP. SPSend submits messages (which are composed of packets) to the SP message pool for transmission. When each link is available, SP dispatches messages from the pool to the link. After transmission of the message, a sendDone() event is signalled with the appropriate error codes.

For multi-packet messages, the SPSendNext interface is used to acquire the next packet of data. Please see the documentation within the SPSendNext interface for more information about message futures.

Author:
Joe Polastre, Moteiv Corporation <info@moteiv.com>

Commands
command result_t cancel(sp_message_t *msg) Remove a message from the SP message pool.
command result_t send(sp_message_t *msg, TOS_Msg *tosmsg, sp_address_t addr, uint8_t length) Send a message using the SP abstraction.
command result_t sendAdv(sp_message_t *msg, TOS_Msg *tosmsg, sp_device_t dev, sp_address_t addr, uint8_t length, sp_message_flags_t flags, uint8_t quantity) Advanced SP Send command.
command result_t update(sp_message_t *msg, TOS_Msg *tosmsg, sp_device_t dev, sp_address_t addr, uint8_t length, sp_message_flags_t flags, uint8_t quantity) Update the contents of a message currently in the message pool.

Events
event void sendDone(sp_message_t *msg, sp_message_flags_t flags, sp_error_t error) Notification that the SP message has completed transmission.

Commands - Details

cancel

command result_t cancel(sp_message_t *msg)

Remove a message from the SP message pool.

Parameters:
msg - The SP message to remove from the pool
Returns:
SUCCESS if the message is removed or FAIL if the message is not in the pool or is currently busy.

send

command result_t send(sp_message_t *msg, TOS_Msg *tosmsg, sp_address_t addr, uint8_t length)

Send a message using the SP abstraction.

All sp_message_t fields other than msg->msg are *internal* to SP and should not be set by the user. Doing so may result in unpredictable results.

Each sp_message_t must define the first TOS_Msg to be sent over the radio.

Parameters:
msg - the SP message to send.
tosmsg - the first TOS_Msg packet in the SP message
addr - the destination address of the message
length - the length of the first TOS_Msg
Returns:
SUCCESS if the SP message pool has room to accept the message

sendAdv

command result_t sendAdv(sp_message_t *msg, TOS_Msg *tosmsg, sp_device_t dev, sp_address_t addr, uint8_t length, sp_message_flags_t flags, uint8_t quantity)

Advanced SP Send command.

sendAdv includes additional parameters for setting the message flags, destination interface, and message futures.

All sp_message_t fields other than msg->msg are *internal* to SP and should not be set by the user. Doing so may result in unpredictable results.

Each sp_message_t must define the first TOS_Msg to be sent over the radio.

Users of SP may set the control flags using the following options:

 - SP_FLAG_C_TIMESTAMP == adds a timestamp to all outgoing messages.  See the SPUtil interface for more information.
 - SP_FLAG_C_RELIABLE  == attempts to send the message with reliable transport
 - SP_FLAG_C_URGENT    == marks the message as urgent, a priority mechanism
 - SP_FLAG_C_NONE      == removes all flags
 - SP_FLAG_C_ALL       == sets all flags
 

For example, if you want timestamping and reliable transport,
flags = SP_FLAG_C_TIMESTAMP | SP_FLAG_C_RELIABLE;

Current SP device/interface options are:

 - SP_I_NOT_SPECIFIED == send over the default interface
 - SP_I_RADIO         == send over the primary radio link
 - SP_I_UART          == send over the primary uart link
 

Parameters:
msg - the SP message to send.
tosmsg - the first TOS_Msg packet in the SP message
dev - the destination interface for the message
addr - the destination address of the message
length - the length of the first TOS_Msg
flags - the flags for control information for this message
quantity - the number of packets in the message using SP message futures
Returns:
SUCCESS if the message is accepted into the SP message pool

update

command result_t update(sp_message_t *msg, TOS_Msg *tosmsg, sp_device_t dev, sp_address_t addr, uint8_t length, sp_message_flags_t flags, uint8_t quantity)

Update the contents of a message currently in the message pool.

Returns:
FAIL if the message is not in the pool or if it is busy

Events - Details

sendDone

event void sendDone(sp_message_t *msg, sp_message_flags_t flags, sp_error_t error)

Notification that the SP message has completed transmission.

Viable feedback options:

 - SP_FLAG_F_CONGESTION
 - SP_FLAG_F_PHASE
 - SP_FLAG_F_RELIABLE
 

Flags are accessible through the flags parameter

Parameters:
msg - the SP message removed from the message pool
flags - feedback from SP to network protocols
error - notification of any errors that the message incurred