831 lines
27 KiB
C
831 lines
27 KiB
C
/*
|
|
* 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
|