WUSB-NL Radio Driver API Guide Doc. No. 001-70689 Rev. *C Cypress Semiconductor 198 Champion Court San Jose, CA 95134-1709 Phone (USA): 800.858.1810 Phone (Intnl): 408.943.2600 http://www.cypress.com Copyrights Copyrights © Cypress Semiconductor Corporation, 2011-2012. The information contained herein is subject to change without notice. Cypress Semiconductor Corporation assumes no responsibility for the use of any circuitry other than circuitry embodied in a Cypress product. Nor does it convey or imply any license under patent or other rights. Cypress products are not warranted nor intended to be used for medical, life support, life saving, critical control or safety applications, unless pursuant to an express written agreement with Cypress. Furthermore, Cypress does not authorize its products for use as critical components in life-support systems where a malfunction or failure may reasonably be expected to result in significant injury to the user. The inclusion of Cypress products in life-support systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges. Trademarks PSoC Designer™ and Programmable System-on-Chip™ are trademarks and PSoC® is a registered trademark of Cypress Semiconductor Corp. All other trademarks or registered trademarks referenced herein are property of the respective corporations. Source Code Any Source Code (software and/or firmware) is owned by Cypress Semiconductor Corporation (Cypress) and is protected by and subject to worldwide patent protection (United States and foreign), United States copyright laws and international treaty provisions. Cypress hereby grants to licensee a personal, non-exclusive, non-transferable license to copy, use, modify, create derivative works of, and compile the Cypress Source Code and derivative works for the sole purpose of creating custom software and or firmware in support of licensee product to be used only in conjunction with a Cypress integrated circuit as specified in the applicable agreement. Any reproduction, modification, translation, compilation, or representation of this Source Code except as specified above is prohibited without the express written permission of Cypress. Disclaimer CYPRESS MAKES NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress reserves the right to make changes without further notice to the materials described herein. Cypress does not assume any liability arising out of the application or use of any product or circuit described herein. Cypress does not authorize its products for use as critical components in life-support systems where a malfunction or failure may reasonably be expected to result in significant injury to the user. The inclusion of Cypress’ product in a life-support systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges. Use may be limited by and subject to the applicable Cypress software license agreement. 2 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C Contents 1 Introduction.................................................................................................................................................................... 5 1.1 References ............................................................................................................................................................ 5 Document Revision History ............................................................................................................................................. 6 2 Description ..................................................................................................................................................................... 7 2.1 2.2 2.3 3 API Use ................................................................................................................................................................. 7 2.1.1 Initialization ............................................................................................................................................... 7 2.1.2 Transmitting .............................................................................................................................................. 7 2.1.3 Receiving .................................................................................................................................................. 7 Requirements ........................................................................................................................................................ 8 2.2.1 Header files .............................................................................................................................................. 8 2.2.2 HW interface ............................................................................................................................................. 8 2.2.3 Pins........................................................................................................................................................... 8 Type Declarations and Definitions ......................................................................................................................... 8 Radio High Level Functions ....................................................................................................................................... 13 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.13 3.14 3.15 3.16 3.17 3.18 3.19 3.20 RadioInit .............................................................................................................................................................. 13 RadioSetChannel ................................................................................................................................................ 13 RadioGetChannel ................................................................................................................................................ 14 RadioSetTxConfig ............................................................................................................................................... 14 RadioGetTxConfig ............................................................................................................................................... 15 RadioSetXactConfig ............................................................................................................................................ 15 RadioGetXactConfig ............................................................................................................................................ 16 RadioSetFrameConfig ......................................................................................................................................... 16 RadioGetFrameConfig ......................................................................................................................................... 17 RadioSetPreambleCount ..................................................................................................................................... 18 RadioGetPreambleCount .................................................................................................................................... 18 RadioSetCrcSeed ................................................................................................................................................ 19 RadioGetCrcSeed ............................................................................................................................................... 19 RadioSetPtr ......................................................................................................................................................... 19 RadioSetLength ................................................................................................................................................... 20 RadioBlockingTransmit ........................................................................................................................................ 20 RadioStartReceive............................................................................................................................................... 21 RadioGetReceiveState ........................................................................................................................................ 21 RadioEndReceive ................................................................................................................................................ 22 RadioForceState.................................................................................................................................................. 22 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 3 Contents 3.21 RadioGetRssi ...................................................................................................................................................... 23 3.22 RadioAbort........................................................................................................................................................... 23 3.23 RadioState ........................................................................................................................................................... 23 4 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 1 Introduction The WUSB-NL radio driver provides users with a consistent interface to the WUSB-NL radio. The driver is designed to interface with both C and M8C assembly written applications and consists of the following files: Nlradio.asm Nlradio.h Nlradio.inc Nlspi.asm This document describes the APIs exposed by the WUSB-NL driver. The WUSB-NL radio driver is used in wireless mouse, keyboard, and bridge application software stacks. The WUSB-NL radio driver is modular and can be used as a library. The API exported by this module is explained in this document. The following is a system level block diagram of a typical wireless mouse and keyboard application. Figure 1-1. System Level Block Diagram Figure 1.WirelessUSB 2-Way System 1.1 References 1. 001-13683 Rev. *B - SPI Master Data Sheet SPIM V 1.20 2. 001-13678 Rev. *F – SPI Master Data Sheet SPIM V 2.5 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 5 Introduction Document Revision History Revision Issue Date Origin of Change Description of Change ** 07/22/2011 DATT New spec. *A 08/19/2011 KPMD Changed posting to external web. *B 12/13/2011 KNTH Update to match driver v1.4. *C 11/28/2012 PRAM Update to match driver v2.0 Updated document title. 6 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 2 Description 2.1 API Use This section describes the high level use of APIs. It also describes the requirements to use this module and the type declarations used within this module. 2.1.1 Initialization RadioInit initializes the radio and should be called before any other function. Before calling this function the SPI Master connected to WUSB-NL radio must be initialized according to the configuration specified in the radio datasheet. Delay functions (TimerDelay10usec and TimerDelay100usec) are required by driver and should be initialized before initializing radio. Initialization example: RadioInit(); 2.1.2 Transmitting RadioBlockingTransmit is the transmit function provided by the driver. A call to RadioSetPtr and RadioSetLength is required before calling RadioBlockingTransmit This function loads the data into the FIFO and monitors the status of the radio. It will return RADIO_COMPLETE if the radio transmission is successful and RADIO_ERROR otherwise. Transmit example: unsigned char state,txbuf[4] = {0x5a,0x5a,0x5a,0x5a}; RadioSetPtr(txbuf); RadioSetLength(sizeof(txbuf)); state = RadioBlockingTransmit(1, sizeof(txbuf)); if (bState & RADIO_COMPLETE) { //Take some action; }; else if (bState & RADIO_ERROR) { //Take some action; }; 2.1.3 Receiving RadioStartReceive should be called in order to start a receive operation. A call to RadioSetPtr and RadioSetLength are required before calling RadioStartReceive. After calling RadioStartReceive, RadioGetReceiveState should be polled to get the status of the receive operation. RadioGetReceiveState will return RADIO_RX, RADIO_COMPLETE or RADIO_ERROR. A return value of RADIO_RX indicates that the receive operation is in progress. A return value of RADIO_COMPLETE indicates that the receive operation is complete and data is available in the buffer specified by the call to RadioSetPointer. A return value of RADIO_ERROR indicates that there was an error during the receive operation. RadioAbort or RadioEndReceive must be called to stop a receive operation. Note that after receive starts, no calls can be made to the configuration access routines until the receive operation is terminated. RX examples: BYTE arbRxData[7]; Description RadioSetLength(sizeof(arbRxData)); RadioSetPtr((unsigned char *)&arbRxData); RadioStartReceive(); do { // Other system tasks bState = RadioGetReceiveState(); } while((bState & (RADIO_ERROR | RADIO_COMPLETE)) == 0); RadioEndReceive(); if (bState & RADIO_COMPLETE) { //Take some action; }; if (bState & RADIO_ERROR) { //Action; }; 2.2 Requirements 2.2.1 Header files To use the radio driver you must include nlRadio.h or nlRadio.inc in any file that calls the radio driver functions. 2.2.2 HW interface The SPI Master block of the PSoC Designer UM (refer [1]) used to interface to the radio is named: SPIM_Radio. This block provides the firmware interface to the SPI pins, so their names have no requirements. 2.2.3 Pins In the PSoC Designer workspace, name the pins as mentioned in the following table. Sl. No Pin Description Pin Name 1 Pin connected to WUSB-NL Radio’sSlave select pin NL_nSS 2 Pin connected to WUSB-NL Radio’sreset pin NL_RST 4 SPI Pins to be prefixed with SPIM_Radio_ SPIM_Radio_MOSI SPIM_Radio_SCLK SPIM_Radio_MISO 2.3 Type Declarations and Definitions The type declarations are as follows. These declarations are kept the same as the LP radio driver to keep the changes in existing protocol and application to minimum. BYTE: Used for 8-bit register values. WORD: Used for 16-bit register values. RADIO_CONST_PTR: Used for ROM buffer pointers. RADIO_BUFFER_PTR: Used for RAM buffer pointers. RADIO_LENGTH: Used for radio field lengths. RADIO_REG_ADDR: 8 bit value used for Radio registers address. RADIO_STATE: Type unsigned char to store the radio state. Radio States are 8 RADIO_IDLE 0x00 RADIO_RX 0x80 RADIO_TX 0x20 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C Description RADIO_RX_STATUS: FUN_STATUS: RADIO_DATA 0x02 RADIO_COMPLETE 0x04 RADIO_ERROR 0x08 RADIO_SLEEP 0x40 END_STATE_SLEEP 0x00 END_STATE_IDLE 0x01 Type unsigned char. Radio receive status are RADIO_BAD_CRC 0x08 RADIO_BUF_NOT_SUF 0x30 RADIO_GFSK 0x00 Type unsigned char RADIO_SUCCESS RADIO_FAILURE RADIO_ABORT_SUCCESS XACT_CONFIG: 0x80 0x00 0xFF Type unsigned int ACK_EN 0x0800 ACK_TO_MSK 0xFF ACK_TO is of following value TX_CONFIG: ACK_TO_4X 0x6B ACK_TO_8X 0x9C ACK_TO_12X 0xCD ACK_TO_15X 0xFF Type unsigned int PA_VAL is of following value PA_N19_DBM 0x3FA0 PA_N12_DBM 0x1E20 PA_N8_DBM 0x1C20 PA_N3_DBM 0x1A20 PA_0_DBM 0x1920 PA_1_DBM 0x1820 PA_VAL can be masked by PA_VAL_MSK WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 0xFFFF 9 Description RADIO_FRAME_CONFIG: Type unsigned char RADIO_RSSI: RADIO_LENGTH: SOP_EN 0x00 // This is ignored for NL LEN_EN 0x20 SYNC_WRD_MSK 0x18 SYNC_WRD_64_BITS 0x18 SYNC_WRD_48_BITS 0x10 SYNC_WRD_32_BITS 0x08 SYNC_WRD_16_BITS 0x00 SOP_THRESH_MSK 0x1F Type unsigned char NOISE_RSSI 0x80 RSSI_LVL_MSK 0x3F Type unsigned char Preamble definitions are as follows PREAMBLE: Type unsigned char PREAMBLE_LEN_MSK 0xE0 PREAMBLE_LEN_1_BYTE 0x00 PREAMBLE_LEN_2_BYTE 0x20 PREAMBLE_LEN_3_BYTE 0x40 PREAMBLE_LEN_4_BYTE 0x60 PREAMBLE_LEN_5_BYTE 0x80 PREAMBLE_LEN_6_BYTE 0xA0 PREAMBLE_LEN_7_BYTE 0xC0 PREAMBLE_LEN_8_BYTE 0xE0 NL Register definitions are as follows 10 ANALOG_BLK_CONFIG1_ADR 0 ANALOG_BLK_CONFIG2_ADR 1 RX_CTRL_ADR 2 TX_RX_STS_ADR 3 BPF_CTRL1_ADR 4 BPF_CTRL2_ADR 5 RSSI_VAL_ADR 6 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C Description RF_SYNTH_TX_RX_CTRL_ADR 7 TX_DAC_CTRL_ADR 8 PA_CTRL_ADR 9 AMS_TST_CTRL1_ADR 10 AMS_TST_CTRL2_ADR 11 AMS_TST_CTRL3_ADR 12 RX_IF_CTRL_ADR 13 PM_CTRL_ADR 14 RSRVD_CTRL1_ADR 15 RSRVD_CTRL2_ADR 16 RSRVD_CTRL3_ADR 17 RSRVD_CTRL4_ADR 18 RSRVD_CTRL5_ADR 19 RSRVD_CTRL6_ADR 20 RSRVD_CTRL7_ADR 21 PWRMGMT_ADR 22 TX_RX_VCO_CAL_CTRL_ADR 23 FRACT_N_VCO_CAL_CTRL1_ADR 24 FRACT_N_VCO_CAL_CTRL2_ADR 25 VCO_SET_CTRL_ADR 26 VCO_N_CTYST_TRIM_ADR 27 FREQ_VAL_ADR 28 MAN_REV_CODE_ADR 29 MAN_ID_LSB_ADR 30 MAN_ID_MSB_ADR 31 CONFIG_ADR 32 DELAY_REG0_ADR 33 DELAY_REG1_ADR 34 MISC1_ADR 35 SYNC_WORD1_ADR 36 SYNC_WORD2_ADR 37 SYNC_WORD3_ADR 38 SYNC_WORD4_ADR 39 THRESHOLD_REG_ADR 40 MISC2_ADR 41 MISC3_ADR 42 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 11 Description 12 RSRVD_CTRL8_ADR 43 RSRVD_CTRL9_ADR 44 RSRVD_CTRL10_ADR 45 RSRVD_CTRL11_ADR 46 RSRVD_CTRL12_ADR 47 MAIN_STS_REG_ADR 48 RSRVD_CTRL13_ADR 49 TX_RX_FIFO_REG_ADR 50 RSRVD_CTRL14_ADR 51 FIFO_RD_PTR_REG_ADR 52 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 3 Radio High Level Functions 3.1 RadioInit void RadioInit(void); Parameters: None Return Value: None Description: This function initializes the radio module. Before calling this function, initialize SPI Master with the following configurations: enCoRe2 controller– BitOrder – MSB First, CPOL – Low, CPHA – High enCoRe5 controller – SPIM_Radio_SPIM_MODE_2, SPIM_Radio_SPIM_MSB_FIRST For the definition of SPIM configuration refer to [1] and [2]. 3.2 RadioSetChannel void RadioSetChannel(BYTE channel); Parameters: channel 8-bit value that is passed to the function. Return Value: None Description: This function sets the radio channel to a specified frequency. The frequency has the value of (2402 + channel) MHz. This function takes an 8-bit argument that is passed to it by ‘BYTE channel’. RadioSetChannel is limited to a maximum value of RADIO_MAX_CHAN, which is defined to 78. Example: RadioSetChannel(10); // Put carrier at 2412MHz Radio High Level Functions 3.3 RadioGetChannel BYTE RadioGetChannel(void); Parameters: None Return Value: This function returns the 8-bit value of the channel number. The frequency should be interpreted as (2402 + channel) MHz. Description: This function gets an 8-bit value from the channel. Example: RadioSetChannel(10); // Put carrier at 2412MHz c = RadioGetChannel(); // Returns 10. 3.4 RadioSetTxConfig void RadioSetTxConfig(TX_CONFIG config); Parameters: config: Radio power amplifier gain setting Possible values for config are: PA_N19_DBM : -19dBm PA_N12_DBM: -12dBm PA_N8_DBM: -8dBm PA_N3_DBM: -3dBm PA_0_DBM: 0dBm PA_1_DBM: 1dBm Return Value: None Description: This function sets the radio power amplifier gain. Example: RadioSetTxConfig(PA_N3_DBM); // Set PA gain to -3dBm 14 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C Radio High Level Functions 3.5 RadioGetTxConfig TX_CONFIG RadioGetTxConfig(void); Parameters: None Return Value: Radio power amplifier gain setting. Possible values are: PA_N19_DBM : -19dBm PA_N12_DBM: -12dBm PA_N8_DBM: -8dBm PA_N3_DBM: -3dBm PA_0_DBM: 0dBm PA_1_DBM: 1dBm Description: This function returns the radio power amplifier gain. Example: RadioSetTxConfig(PA_0_DBM); if (RadioGetTxConfig() != PA_0_DBM) { /* Not entered */ } 3.6 RadioSetXactConfig void RadioSetXactConfig(XACT_CONFIG config); Parameters: config: transaction configuration composed of two parts a) Enable auto-ack Possible value is ACK_EN b) Rx ack timeout Possible values are, ACK_TO_4X // Wait for 107 us ACK_TO_8X // Wait for 156 us ACK_TO_12X // Wait for 205 us ACK_TO_15X // Wait for 255 us Return Value: None WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 15 Radio High Level Functions Description: This function sets the transaction configuration composed of two parts, auto-ack enable and Rx ack timeout. Auto-ack is used to send ACK after receiving the data. Example: // Enable auto-ack and set maximum Rx ack timeout RadioSetXactConfig(ACK_EN | ACK_TO_15X); // Disable auto-ack and set maximum Rx ack timeout RadioSetXactConfig(ACK_TO_15X); 3.7 RadioGetXactConfig XACT_CONFIG RadioGetXactConfig(void); Parameters: None Return Value: Transaction configuration composed of two parts a) Enable auto-ack Possible value is ACK_EN b) Rx ack timeout Possible values are, ACK_TO_4X ACK_TO_8X ACK_TO_12X ACK_TO_15X Description: This function returns the transaction configuration composed of two parts, auto-ack enable and Rx ack timeout. Example: // Turn off the auto-ack function but keep the current ack timeout setting RadioSetXactConfig(RadioGetXactConfig() & ~ACK_EN); 3.8 RadioSetFrameConfig void RadioSetFrameConfig(RADIO_FRAME_CONFIG config); Parameters: config: frame configuration composed of a) 16 Syncword length. WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C Radio High Level Functions Possible values are, SYNC_WRD_64_BITS SYNC_WRD_48_BITS SYNC_WRD_32_BITS SYNC_WRD_16_BITS b) Packet length enable Possible value is LEN_EN Return Value: None Description: This function sets the frame configuration composed of two parts, packet length enable and syncword length. Syncword length can be 64, 48, 32 or 16 bits. After setting Syncword length actual sync words are to be set by upper layer. Enabling packet length causes the radio to treat the first byte of the payload as the length. Example: // Set syncword length to 48 bits and enable packet length. RadioSetFrameConfig(SYNC_WRD_48_BITS | LEN_EN); 3.9 RadioGetFrameConfig RADIO_FRAME_CONFIG RadioGetFrameConfig(void); Parameters: None Return Value: Frame configuration composed of a) Syncword length. Possible values are, SYNC_WRD_64_BITS SYNC_WRD_48_BITS SYNC_WRD_32_BITS SYNC_WRD_16_BITS b) Packet length enable Possible value is LEN_EN Description: This function sets the frame configuration composed of two parts, packet length enable and syncword length. Syncword length can be 64, 48, 32 or 16 bits. Enabling packet length causes the radio to treat the first byte of the payload as the length. Example: // Turn on packet length but keep the current syncword setting RadioSetFrameConfig(RadioGetFrameConfig() | LEN_EN); WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 17 Radio High Level Functions if (RadioGetFrameConfig() == SYNC_WRD_48_BITS) { /* Enters if above condition is satisfied */ } 3.10 RadioSetPreambleCount void RadioSetPreambleCount(BYTE count); Parameters: count: preamble length Possible values are, PREAMBLE_LEN_1_BYTE PREAMBLE_LEN_2_BYTE PREAMBLE_LEN_3_BYTE PREAMBLE_LEN_4_BYTE PREAMBLE_LEN_5_BYTE PREAMBLE_LEN_6_BYTE PREAMBLE_LEN_7_BYTE PREAMBLE_LEN_8_BYTE Return Value: None Description: This function sets the preamble length in bytes. The maximum length of the preamble is 8. Example, // Set the preamble length to 1 byte RadioSetPreambleCount(PREAMBLE_LEN_1_BYTE); 3.11 RadioGetPreambleCount BYTE RadioGetPreambleCount(void); Parameters: None Return Value: The preamble length Description: 18 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C Radio High Level Functions This function gets the preamble length in bytes. The maximum length of the preamble is 8. Example: if (RadioGetPreambleCount() == PREAMBLE_LEN_1_BYTE) { /* Enters if the above condition is satisfied */ } 3.12 RadioSetCrcSeed void RadioSetCrcSeed(BYTE crcSeed); Parameters: crcSeed The crcSeed value (0 to 255). Return Value: None Description: This function sets the value used as the CRC seed value for both transmit and receive. The WUSB-NL radio supports a 16-bit CRC with an 8 bit CRC seed. 3.13 RadioGetCrcSeed BYTE RadioGetCrcSeed(void); Parameters: None Return Value: CRC seed value for both transmit and receive. Description: Returns the current CRC seed value. The WUSB-NL radio supports a 16-bit CRC with an 8 bit CRC seed. 3.14 RadioSetPtr void RadioSetPtr(RADIO_BUFFER_PTR ramPtr); Parameters: ramPtr: Pointer to RAM buffer for future operations. Return Value: None Description: Set the buffer pointer address for future transmit and receive operations. Example: RADIO_BUFFER_PTR arbTxData = {1,2,3,4,5,6,7}; // Initialize the transmission buffer RadioSetPtr(arbTxData); WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 19 Radio High Level Functions 3.15 RadioSetLength void RadioSetPtr(RADIO_LENGTH length); Parameters: length: Length of buffer pointed to by most recent call to RadioSetPtr. Return Value: None Description: Set the buffer length pointed to by most recent call to RadioSetPtr. Example, RadioSetLength(sizeof(rx_packet)); RadioSetPtr((unsigned char *)&rx_packet); RadioStartReceive(); 3.16 RadioBlockingTransmit RADIO_STATE RadioBlockingTransmit(BYTE retryCount, RADIO_LENGTH length); Parameters: retryCount: Number of times the packet send should be retried if the transmit fails. length: Length, in bytes, of the packet. Return Value: Radio state. Description: This function transmits a packet. Blocks execution until it completes. The address of the packet buffer should have previously been set with a call to RadioSetPtr. Example: unsigned char bufferToTransmit[14] = “PacketPayload”; RADIO_STATE txState; RadioSetPtr(bufferToTransmit); txState = RadioBlockingTransmit(4, sizeof(bufferToTransmit)); if (txState == RADIO_COMPLETE) printf(“Transmit successful.\r\n”); if (txState == RADIO_ERROR) printf(“Transmit failed after 5 attempts.\r\n”); 20 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C Radio High Level Functions 3.17 RadioStartReceive void RadioStartReceive(void); Parameters: None Return Value: None Description: Start the reception of a packet. The location and length of the packet buffer to receive data must have previously been set with calls to RadioSetPtr and RadioSetLength. After starting the reception of a packet with this call, the state of the receive operation should be checked by calling RadioGetReceiveState. When RadioGetReceiveState indicates that the transmission has completed, a call should be made to RadioEndReceive. After calling RadioStartReceive, no calls can be made to the configuration access routines until the receive operation is terminated with a call to RadioEndReceive or RadioAbort. Until one of those calls is made to end the receive operation, the only other calls supported are RadioGetReceiveState and RadioGetRssi. 3.18 RadioGetReceiveState RADIO_STATE RadioGetReceiveState(void); Parameters: None Return Value: Returns the state of the current receive operation. Description: This call should be made after starting a receive operation with the RadioStartReceive function. This function checks for errors during reception or completion of reception and returns RADIO_ERROR, RADIO_COMPLETE or RADIO_RX. If reception was completed with no errors, received data would be available in the buffer pointed to by the most recent call to RadioSetPtr. Example: RadioSetLength(sizeof(rx_pkt)); RadioSetPtr((unsigned char *)&rx_pkt); RadioStartReceive(); while (1) { // Other system tasks status = RadioGetReceiveState(); if (status == RADIO_COMPLETE) { pkt_len = RadioEndReceive(); WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 21 Radio High Level Functions RadioSetLength(sizeof(rx_pkt)); RadioSetPtr((unsigned char *)&rx_pkt); RadioStartReceive(); } else if (status == RADIO_ERROR) { (void)RadioEndReceive(); RadioSetLength(sizeof(rx_pkt)); RadioSetPtr((unsigned char *)&rx_pkt); RadioStartReceive(); } } 3.19 RadioEndReceive RADIO_LENGTH RadioEndReceive(void); Parameters: None Return Value: This function returns the length of the received packet. In the case of packet payload truncation (due to inadequate buffer length), the return value is zero. Description: Completes a receive operation. 3.20 RadioForceState void RadioForceState(XACT_CONFIG endStateBitsOnly); Parameters: endStateBitsOnly: Immediate new state for the radio. Return Value: None Description: This function immediately changes the radio state. If the Radio is in receive mode, then RadioAbort or RadioEndReceive must be called before calling RadioForceState. Example: RadioForceState(END_STATE_SLEEP); 22 WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C Radio High Level Functions 3.21 RadioGetRssi RADIO_RSSI RadioGetRssi(void); Parameters: None Return Value: RADIO_RSSI – Received packet signal strength or carrier strength. Description: This function returns the Receive Signal Strength Indicator value. It is necessary that RadioGetRssi be called at least 100us after the radio has entered Receive mode. 3.22 RadioAbort void RadioAbort(void); Parameters: None Return Value: Zero. Description: Aborts a transmit or receive operation and transitions the radio to the idle state. 3.23 RadioState RADIO_STATE RadioState; Parameters: None Return Value: None Description: RadioState is a global variable that contains the state of the radio and the driver. The values for RadioState: RADIO_IDLE: The radio is neither in Receive mode nor in Transmit mode. RADIO_RX: The radio is in Receive mode. RADIO_TX: The radio is in Transmit mode. RADIO_COMPLETE: The radio has successfully completed a transmit or receive operation. RADIO_ERROR: The radio transmit or receive operation was unsuccessful. RADIO_SLEEP: The radio is in sleep mode. WUSB-NL Radio Driver API Guide, Doc. No. 001-70689 Rev. *C 23