fap.h

这是nrf24lu1的无线鼠标源代码,应用平台是keil c

or transmitting it may automatically return to IDLE mode after 
a specified timeout period, or in TRANSMIT mode also after transmission
success. 

In addition, this function can be ysed to immediately 
force the FAP to IDLE mode.
*/
void fap_goto_idle_mode(void);

/**
Function for observing the current FAP mode.

@return 
Returns the current the FAP mode.
@retval FAP_IDLE
@retval FAP_TRANSMITTING 
@retval FAP_RECEIVING

@sa fap_rx_data(), fap_tx_data(), fap_goto_idle_mode()
*/
fap_modes_t fap_get_mode(void);  

//@}

/** @name Transmit related functions */
//@{

/**
Function for transmitting data. This function transmits the data provided in
the @b pl field of the input data structure *datainput to the destination given by 
the @b pipe field. The actual TX address to be used is setup using the function 
fap_set_address().

When the data is successfully transmitted the FAP will automatically return to IDLE mode. 
In addition it may be specified a maximum timeout period the FAP shall try to transmit 
data before returning to IDLE mode. 

It is not required for the FAP to be in IDLE mode before issuing this function. It is possible to upload new data to the TX FIFO during an ongoing transmission. The data uploaded to the TX FIFO will immediately be transmitted when the ongoing transmission is completed, thus enabling a streaming type of operation. However, in order to upload TX data during an ongoing transmission, the following criteria must be fulfilled:

-	Channel synchronization must be disabled by fap_ch_sync_enable().
-	The destination for the uploaded data must be the same as for the ongoing transmission.
-	The TX FIFO cannot be full. The TX FIFO can hold up to 3 payloads.
-	The transmit timeout specified must be the same as for the ongoing transmission.  
 
If the FAP is in RECEIVE mode when issuing this function, the FAP will automatically enter 
TRANSMIT mode. After completion the FAP will always go to IDLE mode. 

@param *datainput [in] is a pointer to a structure containing the payload to be transmitted, 
the payload length and the transmit destination. 

@param tx_timeout specifies the maximum period the FAP shall attempt to
transmit before returning to IDLE mode. The maximum timeout period will 
equal transmit_timeout*FAP_MAX_TX_PERIOD [us]. An infinite transmit 
period may be specified by setting this parameter to 0. 

@return
Returns whether the data was successfully handed to the FAP for transmission.    
@retval true if data successfully handed to FAP. The data will be attempted transmitted by the FAP.
@retval false if data were not successfully handed to the FAP due to one or more of the 
required criteria not fulfilled. Any ongoing FAP operation is not affected and the FAP
mode remains the same as before the function was called.    
     
@sa fap_get_mode(), fap_set_address(), fap_tx_success(), fap_goto_idle_mode(void), fap_ch_sync_disable().
*/
bool fap_tx_data(fap_tx_rx_struct_t *datainput, uint16_t tx_timeout);

/**
Function for flushing the hardware transmit FIFO. This yields any pending data in the TX FIFO,
both normal device to host data, and host to device preloaded acknowledge data.

It is recommended that the FAP is in IDLE mode whenever this function is called.

*/
void fap_flush_tx_fifo(void);

/**
Function for writing data to be piggybacked on the next acknowledge packet sent from the host to a device. This function will not initiate a transmission, but only prepare the data to be returned on the next package received from the selected device.  

@param *ackdata [in] is a pointer to the input data structure containing the payload to be transmitted, the payload length and the transmit destination. 
*/
bool fap_write_ack_pload(fap_tx_rx_struct_t* ackdata);

/**
Function returning @b false if TX FIFO full, else @ true.
*/
bool fap_tx_fifo_full(void);

/**
Function for setting the radio output power.

@param power selects the output power.    
Possible arguments are: 
@arg @c HAL_NRF_0DBM for 0 dBm output power
@arg @c HAL_NRF_6DBM for -6 dBm output power
@arg @c HAL_NRF_12DBM for -12 dBm output power
@arg @c HAL_NRF_18DBM for -18 dBm output power
*/
void fap_set_output_power(hal_nrf_output_power_t power);

/**
Function for enabling a new transmission to be started synchronously to the
receiver channel rotation.   

When synchronization is disabled, any new transmission will be started
synchronously with an internal "frequency guess counter". This synchronization must 
be enabled whenever using the function fap_ch_sync_enable().

@sa fap_get_ch_offset(), fap_ch_sync_disable()
*/
void fap_ch_sync_enable(void);

/**
Function for getting the offset by the "guessed" receive channel and the 
previous successful transmit channel.

The basic concept for the FAP is that the receiver continuously monitors 
a subset of channels in a rotating fashion. After a successful transmission the 
transmitting always adjusts an internal "guess counter" to equal this
receive channel rotation. A new transmission is always started using the 
previous successful channel. When awaiting to send new data until this 
function equals 0, the data will be transmitted using the same 
frequency as the receiver most likely monitors, thus minimizing 
the number of retransmits.

Note, when using this functionality, the channel synchronization must be enabled by 
fap_ch_sync_enable().

@sa fap_get_ch_offset(), fap_ch_sync_disable()
*/
uint8_t fap_get_ch_offset(void);

/**
Function for disabling synchronization of transmission frequency to receive 
frequency.

When synchronization is disabled, any new transmission will start
immediately after calling fap_tx_data(). 

@sa fap_get_ch_offset(), fap_ch_sync_enable()
*/
void fap_ch_sync_disable(void);

/**
Function for getting the result of the previous transmit operation.
The return value from this function is only credible when the FAP is 
in IDLE mode 

@return
Result of the previous transmit operation. 

@retval true if previous data were successfully transmitted, or 
if transmission in progress. (FAP mode TRANSMITTING). 
@retval false if previous were not successfully transmitted   
@sa fap_tx_data(), fap_get_mode(), fap_goto_idle_mode(void)
*/
bool fap_tx_success(void); 

/**
Function for providing the number of transmission
attempts needed during the previous transmit operation. 
This function may be used as an indication on
the current radio transmit conditions. In a noisy 
environment one will experience an increase in the 
number of transmission attempts needed for a 
successful packet delivery to the receiver. Note that 
even in an environment without any interfering radio
sources one will experience that the FAP sometimes
uses several transmission attempts. This due to the
frequency altering scheme used at the receiver.      

The returned value from this function is only reliable 
when the FAP is in IDLE mode, and will only yield the
previous transmitted package.

@sa fap_get_ch_switches(), fap_get_ch_offset(), 
fap_ch_sync_disable(), fap_ch_sync_disable()  
*/
uint16_t fap_get_tries(void);

/**
Function for providing the number of 
frequency channel changes needed during the previous 
transmit operation. In an environment without any 
interfering radio sources one will not normally 
experience that the FAP needs to switch transmission 
frequency. A large number of channel switches
will be an indication on extensive radio 
interference.

The returbe value from this function is only reliable 
when the FAP is in IDLE mode.  

@sa fap_get_tries()
*/
uint16_t fap_get_ch_switches(void);

//@}

/** @name Receive related functions */
//@{
/**
Function for setting the FAP in receive mode and start monitoring the air for data. 
Received data will be stored in a FIFO which can be read out by the function
fap_read_rx_fifo(). It may be specified a timeout period after which 
the FAP shall automatically stop receiving and return to IDLE mode.

The FAP offers two different receive modes; one low power mode and one low latency mode.
In low power mode the FAP is monitoring the air for data in only short
slots of time and the receiver is switched off most of the time. 
This leads to a low power consumption at the receive side but a higher latency
experienced at the transmit side as the transmitter has to "struggle"
more to hit the the time slots the receiver is listening. In low
latency mode the receiver is continuously monitoring the air for data, 
which gives a higher power consumption at the receive side but a lower 
experienced latency at the transmit side.
The FAP do not have to be in IDLE mode before using this function. If 
the FAP is in receive mode when this function is used the new 
receive settings will apply immediately.     

@param rx_setup selects receive power mode and pipe(s)/address(es) to 
monitor for incoming data. Bit 0-5 enables/disables receive
pipes/addresses 0-5; 1 enables reception and 0 disables 
reception. Bit 6 selects the receive power mode; 1 sets receiver 
in low power mode and 0 sets the receiver in low latency mode.    

@param receive_timeout specifies the receive timeout period. The timeout period
will be equivalent to receive_timeout*FAP_RX_PERIOD [us]. By setting this 
parameter to 0 the receiver will remain in receive mode until it
is forced to IDLE mode by fap_goto_idle_mode(). If a finite timeout
is specified, it is recommended that the timeout value is set equal or 
grater than FAP_RX_FULL_CH_REV when operating in low latency mode or
 FAP_RX_SINGLE_CH_REV when operating in low power mode.

@sa fap_set_address(), fap_get_mode(), fap_get_rx_fifo_status(), fap_read_rx_fifo(), fap_select_rx_power_mode, 
fap_goto_idle_mode()
*/
void fap_rx_data(uint8_t rx_setup, uint16_t receive_timeout); 

/**
Function for flushing the hardware receive FIFO. 

It is recommended that the FAP is in IDLE mode whenever this function is called.

*/
void fap_flush_rx_fifo(void);

/**
Function for reading received data from receive FIFO.
When the FAP is in receive mode all incoming data will
be stored in a FIFO which can be read using this function.

@param return_struct specifies the destination to where FIFO 
read data shall be copied. This is a structure type fap_tx_rx_struct_t
which contains the field pl for the actual payload data, pl_length
for the received payload length and pipe which tells the pipe
in which the data were received.  

@return 
Information on whether FIFO contained data or not.  
@retval true if unread FIFO data were copied to destination.
@retval false if FIFO was empty and no data were copied.  
@sa fap_rx_data(), fap_get_rx_fifo_status(), 
*/
bool fap_read_rx_fifo(fap_tx_rx_struct_t* return_struct);

//@}

/** @name Interrupt service routine functions */
//@{
/**
Function to be called by the nRF radio interrupt service routine.  
*/
void fap_nrf_isr_function(void);

/**
Function to be called by the FAP timer interrupt service routine.
The FAP requires one dedicated auto reload timer. This function must
be called by the FAP timer interrupt service routine. 
*/
void fap_timer_isr_function(void);
//@}
#endif // FAP_H__
/** @} */