radio_link.h File Reference

#include <cc2511_types.h>
#include <radio_mac.h>

Go to the source code of this file.

Macros
#define	RADIO_LINK_PAYLOAD_SIZE   18
#define	RADIO_LINK_MAX_PAYLOAD_TYPE   15

Functions
void	radioLinkInit (void)
uint8	radioLinkTxAvailable (void)
uint8	radioLinkTxQueued (void)
uint8 XDATA *	radioLinkTxCurrentPacket (void)
void	radioLinkTxSendPacket (uint8 payloadType)
uint8 XDATA *	radioLinkRxCurrentPacket (void)
uint8	radioLinkRxCurrentPayloadType (void)
void	radioLinkRxDoneWithPacket (void)
BIT	radioLinkConnected (void)

Variables
int32 CODE	param_radio_channel
volatile BIT	radioLinkResetPacketReceived
volatile BIT	radioLinkActivityOccurred

Detailed Description

The radio_link.lib library provides reliable, ordered delivery and reception of a series of data packets between two Wixels on the same frequency. This is the library that takes care of Ping/ACK/NAK packets and handles the details of timing. This library defines radio packet memory buffers and controls access to those buffers.

This library does not work if there are more than two Wixels broadcasting on the same channel. For wireless communication between more than two Wixels, you can use radio_queue.lib (see radio_queue.h).

Similarly, this library also restricts the Wixels to only having one logical data pipe. If you want to send some extra data that doesn't get NAKed, or gets NAKed at different times then the regular data, you would need to replace this library with something more complicated that keeps track of different streams and schedules them.

This library depends on radio_mac.lib, which uses an interrupt. For this library to work, you must write include <radio_link.h> in the source file that contains your main() function.

Definition in file radio_link.h.

Macro Definition Documentation

#define RADIO_LINK_MAX_PAYLOAD_TYPE   15

Each packet has a "Payload Type" attached to it, which is a number between 0 and RADIO_LINK_MAX_PAYLOAD_TYPE. The meanings of the different payload types can be defined by higher-level code.

Definition at line 40 of file radio_link.h.

#define RADIO_LINK_PAYLOAD_SIZE   18

Each packet can contain at most 18 bytes of payload. This limit is imposed by the radio_link.lib library, not the CC2511.

Definition at line 34 of file radio_link.h.

Function Documentation

BIT radioLinkConnected

(

void

)

Returns

1 if a connection to another Wixel has been established.

Currently the radio_link library does not detect disconnection, so this value will never change from 1 to 0.

Definition at line 138 of file radio_link.c.

void radioLinkInit

(

void

)

Initializes the radio_link.lib library and the lower-level libraries that it depends on. This must be called before any other functions in the library.

Definition at line 105 of file radio_link.c.

uint8 XDATA* radioLinkRxCurrentPacket

(

void

)

Returns

A pointer to the current RX packet. This is the earliest packet received from the other Wixel which has not yet been processed yet by higher-level code. Returns 0 if there is no RX packet available.

The RX packet has the same format as the TX packet: the length of the payload is at offset 0 and the data starts at offset 1.

When you are done reading the packet you should call radioLinkRxDoneWithPacket() to advance to the next packet.

Definition at line 191 of file radio_link.c.

uint8 radioLinkRxCurrentPayloadType

(

void

)

Returns

The payload type of the current RX packet. This number was the argument to radioLinkTxSendPacket() on the other Wixel.

This should only be called if radioLinkRxCurrentPacket() recently returned a non-zero pointer.

Definition at line 201 of file radio_link.c.

void radioLinkRxDoneWithPacket

(

void

)

Frees the current RX packet so that you can advance to processing the next one. See the radioLinkRxCurrentPacket() documentation for details.

Definition at line 206 of file radio_link.c.

uint8 radioLinkTxAvailable

(

void

)

Returns

The number of radio TX packet buffers that are currently free (available to hold data).

Definition at line 145 of file radio_link.c.

uint8 XDATA* radioLinkTxCurrentPacket

(

void

)

Returns

A pointer to the current TX packet, or 0 if no packet is available.

To populate this packet, you should write the length of the payload data (which must not exceed RADIO_LINK_PAYLOAD_SIZE) to offset 0, and write the data starting at offset 1. After you have put this data in the packet, call radioLinkTxSendPacket() to actually queue the packet up to be sent on the radio. Example usage:

uint8 XDATA * packet = radioLinkTxCurrentPacket();
if (packet != 0)
{
    packet[0] = 3;   // payload length.  Must not exceed RADIO_LINK_PAYLOAD_SIZE.
    packet[1] = 'a';
    packet[2] = 'b';
    packet[3] = 'c';
    radioLinkTxSendPacket(0);
}

This function has no side effects.

Definition at line 156 of file radio_link.c.

uint8 radioLinkTxQueued

(

void

)

Returns

The number of radio TX packet buffers that are currently busy (holding a data packet that has not been successfully sent yet).

Definition at line 151 of file radio_link.c.

void radioLinkTxSendPacket

(

uint8

payloadType

)

Sends the current TX packet. See the documentation of radioLinkTxCurrentPacket() for details.

Parameters

payloadType

A number between 0 and RADIO_LINK_MAX_PACKET_TYPE that will be attached to the packet. This can be used to specify what type of data the packet contains.

Definition at line 166 of file radio_link.c.

Variable Documentation

int32 CODE param_radio_channel

Defines the frequency to use. Valid values are from 0 to 255. To avoid interference, the channel numbers of different Wixel pairs operating in the should be at least 2 apart. (This is a Wixel App parameter; the user can set it using the Wixel Configuration Utility.)

Definition at line 20 of file radio_link.c.

volatile BIT radioLinkActivityOccurred

The library will set this bit to 1 whenever it receives a packet that has payload data in it or sends a packet. Higher-level code may check this bit and clear it.

Definition at line 101 of file radio_link.c.

volatile BIT radioLinkResetPacketReceived

This bit allows the higher-level code to detect when a reset packet is received. It is set to 1 in an interrupt by the radio_link.lib library whenever a reset packet is received. The higher-level code should set it to zero when it uses this information.

A reset packet will be received whenever the other Wixel is reset for any reason. Multiple reset packets can also be received in quick succession if the other device does not receive the acknowledgment packet sent by this device (every radio packet has a chance of being lost). This situation is indistinguishable from the situation where the other party is actually getting reset several times in quick succession.

If the higher-level code responds to this bit by sending an initialization packet to the other device, then it should clear radioLinkResetPacketReceived BEFORE queueing the packet to be sent. Otherwise, the following sequence of events could occur:

1. Main Loop: This device detects a reset packet (radioLinkResetPacketReceived==1).
2. Main Loop: This device queues initialization packet to be sent.
3. ISR: This device sends an initialization packet.
4. ISR: This device receives a reset packet because other device got reset.
5. This device clears the radioLinkResetPacketReceived.

By clearing the bit first, you guarantee that an initialization packet will be sent AFTER the final reset packet is received.

Example use:

if (radioLinkResetPacketReceived && radioLinkTxAvailable())
{
    uint8 XDATA * packet;

    // A reset packet from the other party was received, so send
    // a packet to initialize the connection.

    // Clear the flag.  This must be done BEFORE queueing the packet
    // to be sent, as discussed in radio_link.h
    radioLinkResetPacketReceived = 0;

    packet = radioLinkTxAvailable();
    packet[0] = INIT_PACKET_LENGTH;  // defined by higher-level code
    packet[1] = INIT_PACKET_PAYLOAD; // defined by higher-level code
    radioLinkTxSendPacket(INIT_PACKET_PAYLOAD_TYPE);
}

Definition at line 81 of file radio_link.c.