phy-library.h

/*
 * File: stack/phy/phy-library.h
 * Description: Interface definition for library functionality.
 *
 * <!--(C) COPYRIGHT 2010 STMicroelectronics. All rights reserved.        -->
 */


//---------------------------------------------------------------------------
// Definitions
//------------

/**
 * @name SIMPLEMAC version defines
 *@{
 */


/**
 * @brief Version major number
 */
#define SIMPLEMAC_VERSION_MAJOR 1

/**
 * @brief Version minor number
 */
#define SIMPLEMAC_VERSION_MINOR 0

/**
 * @brief Version patch number
 */
#define SIMPLEMAC_VERSION_PATCH 2

/**
 * @brief Version qualifier
 */
#define SIMPLEMAC_VERSION_QUAL  ""

#define _SQUOTEME(a) #a
#define SQUOTEME(a) _SQUOTEME(a)

/**
 * @brief Version string
 */
#define SIMPLEMAC_VERSION_STRING SQUOTEME(SIMPLEMAC_VERSION_MAJOR) "." SQUOTEME(SIMPLEMAC_VERSION_MINOR) "." SQUOTEME(SIMPLEMAC_VERSION_PATCH) SIMPLEMAC_VERSION_QUAL

//@} \\END SIMPLEMAC version defines


#define SECURITY_BLOCK_SIZE  16 // bytes
#define MIN_RADIO_POWER     -43 // dBm
#define MAX_RADIO_POWER       3 // dBm

#ifndef  PHY_H_
enum {
  ST_RADIO_POWER_MODE_RX_ON,
  ST_RADIO_POWER_MODE_OFF
};
typedef u8 RadioPowerMode;

//---------------------------------------------------------------------------
// Transmit Configuration
//-----------------------
// The application must declare this structure and initialize each member
// variable.  radioTransmitConfig must be initialized prior to calling
// ST_RadioTransmit() and may be modified only while no transmit operation is
// in progress.

#define RADIO_CCA_ATTEMPT_MAX_DEFAULT      4
#define RADIO_BACKOFF_EXPONENT_MIN_DEFAULT 3
#define RADIO_BACKOFF_EXPONENT_MAX_DEFAULT 5

typedef struct {
  boolean waitForAck;       // Wait for ACK if ACK request set in FCF.
  boolean checkCca;         // backoff and check CCA before transmit.
  u8 ccaAttemptMax;      // The number of CCA attempts before failure;
  u8 backoffExponentMin; // Backoff exponent for the initial CCA attempt.
  u8 backoffExponentMax; // Backoff exponent for the final CCA attempt(s).
  boolean appendCrc;        // Append CRC to transmitted packets.
} RadioTransmitConfig;
#endif// PHY_H_

#ifndef ST_TYPES_H
/**
 * @name txPowerModes for stSetTxPowerMode and mfglibSetPower 
 */
//@{

/** @brief The application should call ::stSetTxPowerMode() with the
  * txPowerMode parameter set to this value to disable all power mode options,
  * resulting in normal power mode and bi-directional RF transmitter output.
  */
#define ST_TX_POWER_MODE_DEFAULT             0x0000
/** @brief The application should call ::stSetTxPowerMode() with the
  * txPowerMode parameter set to this value to enable boost power mode.
  */
#define ST_TX_POWER_MODE_BOOST               0x0001
/** @brief The application should call ::stSetTxPowerMode() with the
  * txPowerMode parameter set to this value to enable the alternate transmitter
  * output.
  */
#define ST_TX_POWER_MODE_ALTERNATE           0x0002
/** @brief The application should call ::stSetTxPowerMode() with the
  * txPowerMode parameter set to this value to enable both boost mode and the
  * alternate transmitter output.
  */
#define ST_TX_POWER_MODE_BOOST_AND_ALTERNATE (ST_TX_POWER_MODE_BOOST     \
                                                |ST_TX_POWER_MODE_ALTERNATE)
#ifndef DOXYGEN_SHOULD_SKIP_THIS
// The application does not ever need to call stSetTxPowerMode() with the
// txPowerMode parameter set to this value.  This value is used internally by
// the stack to indicate that the default token configuration has not been
// overidden by a prior call to stSetTxPowerMode().
#define ST_TX_POWER_MODE_USE_TOKEN           0x8000
#endif//DOXYGEN_SHOULD_SKIP_THIS
//@} \\END  Definitions

/**
 * @brief The maximum 802.15.4 channel number is 26.
 */
#define ST_MAX_802_15_4_CHANNEL_NUMBER 26

/**
 * @brief The minimum 802.15.4 channel number is 11.
 */
#define ST_MIN_802_15_4_CHANNEL_NUMBER 11

/**
 * @brief There are sixteen 802.15.4 channels.
 */
#define ST_NUM_802_15_4_CHANNELS \
  (ST_MAX_802_15_4_CHANNEL_NUMBER - ST_MIN_802_15_4_CHANNEL_NUMBER + 1)

#endif //ST_TYPES_H




//---------------------------------------------------------------------------
/** @name
 * Radio power state control APIs
 *
 * @brief
 * These APIs control the overall radio initialization and power state.
 */
//@{

/** @brief 
 * This function performs one-time radio initialization and calibration.
 * This function must be called once after chip reset or wake from deep sleep.
 * This function will power up the radio while it configures the radio channel.
 * After the radio is configured and the channel is set the radio will be left
 * in the state specified by the \c initialRadioPowerMode parameter.
 * This function calls ST_RadioSetPowerMode(),
 * ST_RadioEnableAddressFiltering(), ST_RadioEnableAutoAck(),
 * ST_RadioSetCoordinator(), ST_RadioSetPower(), ST_RadioSetChannel(),
 * ST_RadioEnablePacketTrace(), and ST_RadioEnableReceiveCrc()
 * providing the last used argument for each function.  If these functions have
 * not been called before ST_RadioInit() then the default for each is used.
 * Only the functions listed above can be called before ST_RadioInit().
 * All other library functions must not be called until after
 * ST_RadioInit() has been called once after each chip reset or wake from deep
 * sleep.
 *
 * @param
 * initialRadioPowerMode specifies the state that the function will leave the
 * radio in after it is configured.  This parameter can be either:
 * ST_RADIO_POWER_MODE_OFF - radio will be powered down.
 * ST_RADIO_POWER_MODE_RX_ON - radio will be left in the on (receive) state.
 *
 * @return ::ST_SUCCESS or a status code indicating the reason for failure.
 */
StStatus ST_RadioInit(RadioPowerMode initialRadioPowerMode);

/** @brief 
 * Turns on the radio.  The last radio configuration is used.
 */
void ST_RadioWake(void);

/** @brief 
 * This function turns off the radio.
 * Any transmit or receive packets in progress are aborted.
 * The library may or may not call ST_RadioTransmitCompleteIsrCallback() for an
 * aborted transmit packet.
 * ST_RadioWake() must not be called within 250us of having called
 * ST_RadioSleep().
 */
void ST_RadioSleep(void);

//@}//END Radio power state control APIs


//---------------------------------------------------------------------------
/** @name
 * Channel APIs
 *
 * @brief
 * These APIs control channel selection and calibration.
 */
//@{

/** @brief 
 * Configures the radio to communicate on a 802.15.4 channel.
 * If ST_RadioInit() has not been called yet, the channel number is recorded
 * but no calibration takes place.  The specified channel will be configured
 * when ST_RadioInit() is eventually called.
 * If the radio is asleep this function will wake it to perform channel
 * calibration and then return it to sleep before exiting.
 * The first time a channel is selected all radio parameters will be calibrated
 * for that channel.  This full calibration process can take up to 200ms to
 * complete.  The results of some of these calibrations are stored in flash
 * tokens for use the next time the same channel is selected.  Subsequent calls
 * to ST_RadioSetChannel() requesting the same channel will take less time
 * because the stored values will be retrieved from the flash tokens and reused.
 *
 * @param channel the 802.15.4 channel that the radio will communicate on.
 *
 * @return ::ST_SUCCESS or a status code indicating the reason for failure.
 */
StStatus ST_RadioSetChannel(u8 channel);

/** @brief
 * This function gets the 802.15.4 channel that the radio is configured to use.
 *
 * @return the 802.15.4 channel that the radio is configured to use.
 */
u8 ST_RadioGetChannel(void);

/** @brief
 * This function is identical to ST_RadioSetChannel() except that it
 * calibrates all radio parameters regardless of whether calibration is
 * required.
 *
 * NOTE: This function does not need to be called under normal operating
 * conditions.  The library will reuse available stored calibration values
 * and will perform necessary re-calibration automatically.  Calling this
 * function will cause the library to calibrate all radio parameters and
 * store the results in flash, overwriting previous stored values.  Use of
 * this function will cause unnecessary flash wear and will take longer to
 * complete than a call to ST_RadioSetChannel().  This function should only
 * be called to recover from hardware-related calibration problems, which
 * should only occur during hardware development.
 * 
 * @param channel the 802.15.4 channel that the radio will communicate on.
 *
 * @return ::ST_SUCCESS or a status code indicating the reason for failure.
 */
StStatus ST_RadioSetChannelAndForceCalibration(u8 channel);

/** @brief
 * This function checks to see if the radio needs calibrating to maintain
 * expected performance as environmental conditions change.
 * If this function indicates that the calibration is needed, the application
 * should call ST_RadioCalibrateCurrentChannel().
 *
 * NOTE: This function must not be called while a transmit is in progress.
 *
 * @return TRUE if calibration is needed to compensate for temperature changes,
 * FALSE otherwise.
 */
boolean ST_RadioCheckRadio(void);

/** @brief
 * This function performs necessary recalibration to counteract the effects of
 * temperature changes since the last calibration.  It should be called by the
 * application when ST_RadioCheckRadio() indicates that calibration is needed.
 */
void ST_RadioCalibrateCurrentChannel(void);

//@}//END Channel APIs


//---------------------------------------------------------------------------
/** @name
 * Transmit APIs
 *
 * @brief
 * These APIs control the transmission of packets.
 */
//@{

/** @brief
 * This function transmits a packet using the configuration specified in
 * \c radioTransmitConfig.
 *
 * @param *packet A pointer to the packet to be transmitted.  The first byte of
 * \c packet must be set to the number of payload bytes to be transmitted.
 * If \c radioTransmitConfig.appendCrc is TRUE the length byte must accommodate
 * the hardware-appended two-byte CRC.
 * e.g. A packet with a two-byte payload would be represented in memory as:
 * {0x04, 0x00, 0x01, 0xc0, 0xc1} where 0xc0 and 0xc1 are the CRC bytes.
 * If \c radioTransmitConfig.checkCca is TRUE this function performs CSMA-CA
 * backoff(s) and CCA check(s) before transmitting, else it starts the
 * transmit process immediately.
 * 
 * @return ::ST_SUCCESS if the transmission process is successfully started.
 * In this case ST_RadioTransmitCompleteIsrCallback() will eventually be
 * called to indicate the completion status.  If the radio is busy transmitting,
 * this function returns an error code and
 * ST_RadioTransmitCompleteIsrCallback() will not be called.
 */
StStatus ST_RadioTransmit(u8* packet);

/** @brief
 * This function is called by the library once after each ST_RadioTransmit()
 * call that returned successfully.  If the ST_RadioTransmit() call returned
 * an error ST_RadioTransmitCompleteIsrCallback() will not be called.
 * 
 * NOTE: ST_RadioTransmit() can be called again within the context of this
 * callback.
 * 
 * @param status parameter indicates one of the following conditions:
 * ::ST_SUCCESS - the last byte of the non-ACK-request packet has been
 * transmitted.
 * ::ST_PHY_ACK_RECEIVED - the requested ACK was received.
 * ::ST_MAC_NO_ACK_RECEIVED - the requested ACK was not received in time.
 * ::ST_PHY_TX_CCA_FAIL - unable to transmit due to lack of clear channel on
 * all attempts.
 * ::ST_PHY_TX_UNDERFLOW - DMA underflow occurred while transmitting.  Should
 * never happen.
 * ::ST_PHY_TX_INCOMPLETE - The PLL synthesizer failed to lock while
 * transmitting.  Should never happen.
 * 
 * @param sfdSentTime the value of the MAC timer captured when the SFD was sent.
 *
 * @param framePending TRUE if the received ACK indicates that data is
 * pending for this node, FALSE otherwise.
 */
extern void ST_RadioTransmitCompleteIsrCallback(StStatus status,
                                                  u32 sfdSentTime,
                                                  boolean framePending);

/** @brief
 * This function sets the Energy Detection Clear Channel Assessment threshold.
 *
 * @param threshold the energy level in dBm below which the channel will be
 * considered clear.
 */
void ST_RadioSetEdCcaThreshold(s8 threshold);

/** @brief
 * This function get the Energy Detection Clear Channel Assessment threshold.
 *
 * @return the Energy Detection Clear Channel Assessment threshold in units of
 * dBm.
 */
s8 ST_RadioGetEdCcaThreshold(void);

/** @brief This function enables or disables notification of the SFD sent event
 * via the ST_RadioSfdSentIsrCallback().
 *
 * @param enable TRUE if the notification is to be enabled, FALSE if the
 * notification is to be disabled.
 */
void ST_RadioEnableSfdSentNotification(boolean enable);

/** @brief
 * This function indicates whether the SFD sent notification via
 * \c ST_RadioSfdSentIsrCallback() is enabled or disabled.
 *
 * @return TRUE if the SFD sent notification is enabled, FALSE otherwise.
 */
boolean ST_RadioSfdSentNotificationEnabled(void);

/** @brief
 * This function is called by the library in response to an SFD sent event if
 * this notification has been enabled by a call to
 * \c ST_RadioEnableSfdSentNotification().
 *
 * NOTE: This callback is called for ACKs as well as normal packets.
 * 
 * NOTE: In cases of extreme interrupt latency it is possible that 
 * \c sfdSentTime may contain the SFD time of the last received packet instead
 * of the time of the last transmitted packet.
 *
 * @param sfdSentTime the value of the MAC timer when the SFD was sent in the
 * last transmitted packet.
 */
void ST_RadioSfdSentIsrCallback(u32 sfdSentTime);

/** @brief
 * This function sets the radio transmit power to a new level within the minimum
 * and maximum values specified in the datasheet for the specific device.
 *
 * NOTE: It is possible for this function to succeed and set the power level to
 * a value other than that specified in the \c power parameter.  The reason for
 * for this behavior is that not all integer power levels are available at lower
 * power levels.  When a specific power level is not available the next higher
 * power level is used.
 *
 * @return ::ST_SUCCESS if the power level has been changed, or an error
 * status code if not (e.g. if the requested value is out of range).
 *
 * @param power the desired power level in units of dBm.
 */
StStatus ST_RadioSetPower(s8 power);

/** @brief
 * This function gets the radio transmit power level.
 * 
 * @return the radio transmit power level in units of dBm.
 */
s8 ST_RadioGetPower(void);

//@}//END Transmit APIs


//---------------------------------------------------------------------------
/** @name
 * Receive APIs
 *
 * @brief
 * These APIs control the reception of packets.
 */
//@{

/** @brief
 * This function is called by the library when a packet has been received.
 *
 * @param *packet points to the packet data beginning with the length byte.
 * The CRC bytes will have been removed from the packet.
 *
 * @param ackFramePendingSet TRUE if the library set the Frame Pending bit in
 * the hardware-generated MAC ACK to this packet, FALSE otherwise.
 *
 * @param time The value of the MAC timer when the SFD was received for this
 * packet.
 *
 * @param errors The number of correlator errors in the packet.
 *
 * @param rssi The energy detected over the last 8 symbols of the packet in
 * units of dBm.
 */
extern void ST_RadioReceiveIsrCallback(u8 *packet,
                                         boolean ackFramePendingSet,
                                         u32 time,
                                         u16 errors,
                                         s8 rssi);

/** @brief
 * This function enables or disables address filtering on PAN ID, node ID, and
 * EUI 64.
 *
 * NOTE: Address filtering is enabled by default.
 *
 * @param enable TRUE to enable address filtering, FALSE otherwise.
 */
void ST_RadioEnableAddressFiltering(boolean enable);

/** @brief
 * This function gets the address filtering status of the device.
 *
 * @return TRUE if address filtering is enabled, FALSE otherwise.
 */ 
boolean ST_RadioAddressFilteringEnabled(void);

/** @brief
 * This function enables or disables automatic transmission of ACKs in response
 * to received packets which request ACKs.
 *
 * NOTE: Address filtering must be enabled for automatic transmission of ACKs to
 * occur.
 *
 * NOTE: Automatic acknowledgement is enabled by default.
 *
 * @param enable TRUE to enable automatic acknowledgement transmission, FALSE
 * otherwise.
 */
void ST_RadioEnableAutoAck(boolean enable);

/** @brief
 * This function gets the automatic acknowledgement status of the device.
 *
 * @return TRUE if automatic acknowledgement is enabled, FALSE otherwise.
 */
boolean ST_RadioAutoAckEnabled(void);

/** @brief
 * This function sets the short address of the node.
 *
 * @param nodeId the 16-bit address to use for filtering short-addressed
 * packets when address filtering is enabled.
 *
 */
void ST_RadioSetNodeId(u16 nodeId);

/** @brief
 * This function gets the short address of the node.
 *
 * @return nodeId the 16-bit address to use for filtering short-addressed
 * packets.
 */
u16 ST_RadioGetNodeId(void);

/** @brief
 * This function sets the PAN id of the node.
 *
 * @param panId the 16-bit PAN id to use for filtering packets when address
 * filtering is enabled.
 */
void ST_RadioSetPanId(u16 panId);

/** @brief
 * This function gets the PAN id of the node.
 *
 * @return 16-bit PAN id to use for filtering packets when address
 * filtering is enabled.
 */
u16 ST_RadioGetPanId(void);

/** @brief
 * This function get the EUI 64 of the node.
 *
 * NOTE: The EUI 64 is set via manufacturing tokens (See the Programming and
 * Serialization Specification for details).
 *
 * @return the memory address of the 64-bit EUI address to use for filtering
 * long-addressed packets when address filtering is enabled.
 */
u8* ST_RadioGetEui64(void);

/** @brief
 * This function is called by the library after the long address fields of a
 * packet have been received.  The library will set the frame pending bit in the
 * outgoing ACK only if the return value is TRUE.  The application must lookup
 * the \c eui64 in its own data structures and return TRUE if there is data
 * pending, FALSE otherwise.  It is critical that this function complete as
 * quickly as possible to ensure the frame pending bit can be set before the ACK
 * is transmitted.
 *
 * @return TRUE if the frame pending bit should be set in the outgoing ACK.
 */
boolean ST_RadioDataPendingLongIdIsrCallback(u8* longId);

/** @brief
 * This function is called by the library after the short address fields of a
 * packet have been received.  The library will set the frame pending bit in the
 * outgoing ACK only if the return value is TRUE.  The application must lookup
 * \c shortId in its own data structures and return TRUE if there is data
 * pending, FALSE otherwise.  It is critical that this function complete as
 * quickly as possible to ensure the frame pending bit can be set before the ACK
 * is transmitted.
 *
 * @return TRUE if the frame pending bit should be set in the outgoing ACK.
 */
boolean ST_RadioDataPendingShortIdIsrCallback(u16 shortId);

/** @brief
 * This function sets or clears coordinator mode for this node.  A
 * coordinator is able to receive 802.15.4. DATA frames that have no destination
 * address.  A node that is not a coordinator will not receive these packets.
 * 
 * NOTE: The source PAN id of the DATA frame with no destination address must
 * still match the node PAN id in order for it to be received by the
 * coordinator node.
 *
 * NOTE: A node is not a coordinator by default.
 *
 * @param coordinator TRUE to enable coordinator mode, FALSE to disable
 * coordinator mode.
 */
void ST_RadioSetCoordinator(boolean coordinator);

/** @brief
 * This function gets the coordinator status of the node.
 *
 * @return TRUE if the node is configured as a coordinator, FALSE otherwise.
 */
boolean ST_RadioDeviceIsCoordinator(void);

/** @brief
 * This function enables or disables notification of DMA receive buffer overflow
 * events via ST_RadioOverflowIsrCallback().
 *
 * @param enable TRUE to enable overflow notification, FALSE otherwise.
 */
void ST_RadioEnableOverflowNotification(boolean enable);

/** @brief
 * This function indicates whether the overflow notification via
 * ST_RadioOverflowIsrCallback() is enabled or disabled.
 *
 * @return TRUE if overflow notification is enabled, FALSE otherwise.
 */
boolean ST_RadioOverflowNotificationEnabled(void);

/** @brief
 * This function is called by the library in response to a receive overflow
 * event if this notification is enabled by a call to
 * ST_RadioEnableOverflowNotification().
 */
void ST_RadioOverflowIsrCallback(void);

/** @brief
 * This function enables or disables discarding received packets that fail the
 * Cyclic Redundancy Check.
 *
 * NOTE: When this option is enabled the library automatically strips the CRC
 * bytes off of packets that pass CRC check.
 *
 * NOTE: Discarding packets that fail CRC is enabled by default.
 *
 * @param enable TRUE to enable discarding packets that fail CRC, FALSE
 * otherwise.
 */
void ST_RadioEnableReceiveCrc(boolean enable);

/** @brief
 * This function gets the receive CRC configuration of the node.
 *
 * @return TRUE if received packets that fail CRC will be discarded, FALSE
 * otherwise.
 */
boolean ST_RadioReceiveCrcEnabled(void);

//@}//END Receive APIs


//---------------------------------------------------------------------------
/** @name
 * MAC Timer APIs
 *
 * @brief
 * These APIs expose an interface to the MAC Timer.
 * The MAC timer is 20-bits long with each LSB tick representing 1us.
 * The MAC timer rolls over to zero approximately once every second.
 * The MAC timer is free-running from the time that ST_RadioInit() is called.
 */
//@{

/** @brief
 * This function gets an instantaneous reading of the MAC timer.
 *
 * @return the current value of the MAC timer.
 */
u32 ST_RadioGetMacTimer(void);

/** @brief
 * This function enables or disables comparison of the MAC timer against an
 * application-supplied value and notification via
 * ST_RadioMacTimerCompareIsrCallback().
 *
 * @param enable TRUE to enable MAC timer comparison and notification via a
 * callback.
 */
void ST_RadioEnableMacTimerCompare(boolean enable);

/** @brief
 * This function indicates whether MAC timer comparison and callback
 * notification are enabled or disabled.
 *
 * @return TRUE if MAC timer comparison and notification are enabled, FALSE
 * otherwise.
 */
boolean ST_RadioMacTimerCompareEnabled(void);

/** @brief
 * This function sets the value to compare against the MAC timer.
 *
 * @param value the value to compare against the MAC timer.
 */
void ST_RadioSetMacTimerCompare(u32 value);

/** @brief
 * This function gets the value to compare against the MAC timer.
 *
 * @return the value to compare against the MAC timer.
 */
u32 ST_RadioGetMacTimerCompare(void);

/** @brief
 * This function is called by the library in response to MAC timer comparison
 * event.
 */
extern void ST_RadioMacTimerCompareIsrCallback(void);
//@}//END MAC Timer APIs


//---------------------------------------------------------------------------
/** @name
 * Cryptography APIs
 *
 * @brief
 * These APIs provide an interface to the hardware AES coprocessor.
 */
//@{

/** @brief
 * This function sets the key to use during AES encryption.
 *
 * @param *key pointer to 128 bits of key data.
 */
void ST_AesSetKey(u8* key);

/**
 * This function gets the key that is used during AES encryption.
 *
 * @param *key pointer to memory where 128 bits of key data will be written.
 */
void ST_AesGetKey(u8* key);

/** @brief
 * This function encrypts the 128 bits of plaintext data located at \c block
 * using the AES coprocessor previously configured by ST_AesSetKey().
 * The resulting 128 bits of cyphertext are stored at \c block, overwriting
 * the supplied plaintext.
 *
 * @param block pointer to memory containing the plaintext when this function is
 * called and containing the cyphertext after this function has returned.
 */
void ST_AesEncrypt(u8* block);

//@}//END Cryptography APIs


//---------------------------------------------------------------------------
/** @name
 * Miscellaneous APIs
 *
 * @brief
 * These APIs control diagnostic and configuration functionality.
 */
//@{

/** @brief
 * This function starts transmission of a carrier wave at the current channel
 * center frequency.  The carrier wave will be transmitted until
 * ST_RadioStopTransmitTone() is called.
 *
 * NOTE: The radio must be idle (not transmitting) before entering this mode.
 * 
 * NOTE: Other radio APIs must not be called while in this mode.
 */
void ST_RadioStartTransmitTone(void);

/** @brief
 * This function stops transmission of carrier wave started by
 * ST_RadioStartTransmitTone().
 */
void ST_RadioStopTransmitTone(void);

/** @brief
 * this function starts transmission of a continuous stream of modulated data.
 * No packet framing is present in this transmission.  Random symbols will be
 * transmitted until ST_RadioStopTransmitStream() is called.
 *
 * NOTE: The radio must be idle (not transmitting) before entering this mode.
 * 
 * NOTE: Other radio APIs must not be called while in this mode.
 */
void ST_RadioStartTransmitStream(void);

/** @brief
 * This function stops transmission of continuous stream of modulated data
 * started by ST_RadioStartTransmitStream().
 */
void ST_RadioStopTransmitStream(void);

/** @brief
 * This function gets a reading of the average energy detected over the previous
 * eight symbol periods (128us total).
 *
 * @return the energy level detected in units of dBm.
 */
s8 ST_RadioEnergyDetection(void);

/** @brief
 * This function accesses radio hardware to obtain true random numbers.
 *
 * @param *rn pointer to memory to hold \c count random numbers.
 * 
 * @param count the number of 16-bit random numbers to get.
 */
void ST_RadioGetRandomNumbers(u16 *rn, u8 count);

/** @brief
 * This function gets the clear or busy status of the channel.
 *
 * @return TRUE if channel is clear, FALSE if channel is busy.
 */
boolean ST_RadioChannelIsClear(void);

/** @brief
 * This function enables or disables Packet Trace output.
 * Before being enabled, the associated IO pins must be separately 
 * configured to allow for the packet trace peripheral to control the pins.
 *
 * NOTE: Packet Trace is on by default.
 *
 * @param enable TRUE to enable Packet Trace, FALSE otherwise.
 */
void ST_RadioEnablePacketTrace(boolean enable);

/** @brief
 * This function indicates whether Packet Trace is enabled or not.
 *
 * @return TRUE if Packet Trace is enabled, FALSE otherwise.
 */
boolean ST_RadioPacketTraceEnabled(void);

/** @brief
 * This function sets the radio power mode according to the bits
 * encoded in \c powerMode.
 *
 * NOTE: The default power mode is whatever is configured in the PHY_CONFIG
 * token (normal, bi-directional mode if not explicitly set otherwise.
 *
 * NOTE: It is preferable to set this configuration via the PHY_CONFIG token
 * rather than using this API.
 *
 * @param txPowerMode encodes the power mode as follows:
 * bit 0 set to 0: Normal mode.
 * bit 0 set to 1: Boost mode.
 * bit 1 set to 0: Use bi-directional transmit path.
 * bit 1 set to 1: Use alternate transmit path.
 *
 * @return ::ST_SUCCESS always.
 */
StStatus ST_RadioSetPowerMode(u16 txPowerMode);

/** @brief
 * This function gets the radio power mode.
 * 
 * @return the radio power mode (boost/normal, bi-directional/alternate transmit
 * path) encoded as bits in a 16-bit word (see ST_RadioSetPowerMode()
 * documentation for details).
 */
u16 ST_RadioGetPowerMode(void);

//@}//END Miscellaneous APIs