/* Copyright (c) 2007 Nordic Semiconductor. All Rights Reserved.
 *
 * The information contained herein is property of Nordic Semiconductor ASA.
 * Terms and conditions of usage are described in detail in NORDIC
 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT. 
 *
 * Licensees are granted free, non-transferable use of the information. NO
 * WARRENTY of ANY KIND is provided. This heading must NOT be removed from
 * the file.
 *
 * $LastChangedRevision: 2290 $
 */ 

/** @file
 * Interface functions for the Frequency Agility Protocol.
 *
 * @author Lasse Olsen
 *
 * @defgroup nordic_protocol_fap Frequency Agility Protocol
 * @{ 
 * Implementation of frequency agility protocol for better robustness against
 * interference from co-existing radio frequency sources.  
 */
#ifndef FAP_H__
#define FAP_H__

#include <stdint.h>
#include <stdbool.h>
#include "fap_setup.h"
#include "fap_macros.h"
#include "hal_nrf.h"

//***************************************************************************** 
// FAP static parameters
//*****************************************************************************

#define FAP_DATARATE HAL_NRF_2MBPS    // 2Mbps datarate 

#define FAP_OUTPUT_POWER HAL_NRF_0DBM // 0 dBm output power 
#define FAP_CRC HAL_NRF_CRC_16BIT     // 16 bit CRC (maximum)
#define FAP_ADDRESS_WIDTH 5           // 5 byte address
#define FAP_LP_RX_LISTEN_PERIODS 1    // Low power RX on time                                       

#if(FAP_MAX_FW_PL_LENGTH > FAP_MAX_ACK_PL_LENGTH)
  #define FAP_MAX_PL_LENGTH FAP_MAX_FW_PL_LENGTH 
#else
  #define FAP_MAX_PL_LENGTH FAP_MAX_ACK_PL_LENGTH 
#endif
         
#if(FAP_MAX_ACK_PL_LENGTH > 15)
  #define FAP_AUTO_RETR_DELAY 500       
#else
  #define FAP_AUTO_RETR_DELAY 250       
#endif  

#define FAP_MAX_TX_PERIOD (130+37+(FAP_MAX_FW_PL_LENGTH*4)+FAP_AUTO_RETR_DELAY)    

//***************************************************************************** 
// Misc. macros
//*****************************************************************************

#define FAP_GET_BIT(a, b) ((a >> b) & 0x01)
#define FAP_CLEAR_BIT(a, b) (a &= ~(1 << b))
#define FAP_SET_BIT(a, b) (a |= (1 << b)) 

//***************************************************************************** 
// Derived parameters
//*****************************************************************************

/**
Specifies the radio wakeup from power down time. This constant is specifies in
number of FAP_RX_PERIODs. 
*/
#define FAP_RADIO_PWR_UP_DELAY ((2000/FAP_RX_PERIOD)+1)   // ~ 2 ms radio startup

/**
Equals the number of transmit periods the transmitter resides at one channel before
channel switch. This period equals the duration between the start of each 
retransmit, and is derived form the retransmit delay and "on air" packet length.
The maximum length of one transmit period in [us] is specified by #FAP_MAX_TX_PERIOD.
*/
#define FAP_TX_SINGLE_CH_REV ((FAP_NRF_AUTO_RETRIES+1)*FAP_AUTO_RETRIES_EXTEND)//[#]  

/*
Equals the maximum time in [us] the transmitter resides on a single channel before 
channel switch. This parameter is derived from the device maximum payload length.
*/  
#define FAP_TX_SINGLE_CH_REV_TIME (FAP_TX_SINGLE_CH_REV*FAP_TX_PERIOD_MAX)//[us]

/*
Equals the number of transmit periods necessary  for a full revolution
through all channels. It is recommended that the transmit timeout period 
specified when using fap_tx_data() is equal or greater than this value.
The maximum length of one transmit period in [us] is specified by #FAP_MAX_TX_PERIOD.
*/
#define FAP_TX_FULL_CH_REV (FAP_TX_SINGLE_CH_REV*FAP_CH_TAB_SIZE)//[#]

/*
Equals the time in [us] necessary for the transmitter to revolve through 
all channels.
*/
#define FAP_TX_FULL_CH_REV_TIME (FAP_TX_FULL_CH_REV*FAP_TX_PERIOD_MAX)//[us]

/**
Equals the number of receive periods the transmitter
resides on a single channel before channel switch. 
The length of one transmit period in [us] is specified by FAP_RX_PERIOD.
*/
#define FAP_RX_SINGLE_CH_REV ((uint16_t)(((FAP_TX_SINGLE_CH_REV*FAP_MAX_TX_PERIOD)/FAP_RX_PERIOD)+1))//[#]

/**
Function used internally by the FAP for a device to synchronize to the host receive channel rotation. 
This function must be customized for the actual MCU implementation. It is required from this 
function that when issued, the FAP protocol timer shall be adjusted to generate an interrupt 
FAP_TIMER_MODIFY_PERIOD microseconds after the point issued. Subsequently this interrupt the 
protocol timer shall retain the original setup (timeout every FAP_RX_PERIOD us).
*/
void fap_modify_timer_period(void);
          
/**
Specifies the time in [us] that equals the time the transmitter
resides on a single channel before channel switch.
Thus, FAP_RX_SINGLE_CH_REV_TIME=FAP_TX_SINGLE_CH_REV_TIME.      
*/
#define FAP_RX_SINGLE_CH_REV_TIME (FAP_RX_SINGLE_CH_REV*FAP_RX_PERIOD) //[us]

/**
Equals the number of receive periods the transmitter
uses on a full revolution through all channels. The length of one transmit 
period in [us] is specified by FAP_RX_PERIOD.     
*/
#define FAP_RX_FULL_CH_REV (FAP_RX_SINGLE_CH_REV*FAP_CH_TAB_SIZE) // [#]

/**
Equals the time in [us] that the transmitter uses on 
a full revolution through all channels. Thus
FAP_RX_FULL_CH_REV=FAP_TX_FULL_CH_REV.    
*/
#define FAP_RX_FULL_CH_REV_TIME (FAP_RX_FULL_CH_REV*FAP_RX_PERIOD) // [us]

//***************************************************************************** 
// Typedefs
//*****************************************************************************

/**
Type used for storing payload, payload length and pipe number    
*/
typedef struct
{
  uint8_t pl[FAP_MAX_PL_LENGTH];  
  uint8_t pl_length;
  uint8_t pipe;
} fap_tx_rx_struct_t;

/**
Possible FAP modes. Return values for function fap_get_mode().    
*/
typedef enum
{
  FAP_IDLE,
  FAP_TRANSMITTING,
  FAP_RECEIVING
}fap_modes_t;

/**
Possible RX fifo states. Return values for function fap_get_rx_fifo_status().    
*/
typedef enum
{
  FAP_RX_FIFO_EMPTY,
  FAP_RX_DATA_IN_FIFO,
  FAP_RX_FIFO_FULL,
}fap_rx_status_t;

/**
Possible radio modes during FAP IDLE mode. Input parameters for 
function fap_select_radio_idle_mode().    
*/
typedef enum
{
  FAP_PDOWN_IDLE,
  FAP_STANDBY_IDLE 
}fap_radio_idle_modes_t;

#define FAP_DEVICE0 HAL_NRF_PIPE0
#define FAP_DEVICE1 HAL_NRF_PIPE1
#define FAP_DEVICE2 HAL_NRF_PIPE2
#define FAP_DEVICE3 HAL_NRF_PIPE3
#define FAP_DEVICE4 HAL_NRF_PIPE4
#define FAP_DEVICE5 HAL_NRF_PIPE5
#define FAP_LP_RX_BIT (FAP_DEVICE5+1)

//***************************************************************************** 
// Function prototypes and function parameter defines
//*****************************************************************************

/** @name General functions */
//@{
/**
Initialization function for the frequency agility protocol (FAP). This function
must be called at least once before any of the remaining FAP functions may be used. 
It is recommended that the FAP timer interrupt service routine is not 
enabled until after the FAP is initialized.
*/
void fap_init(void);

/**
Function for setting the explicit receive address for a given pipe.

The radio can monitor up to 6 addresses (pipes) simultaneously. The addresses
for pipe 0 and 1 are specified using 5 bytes, while the address for pipe 2-5 
are specified using a 1 byte address. This 1 byte address specifies 
the LSByte address whilst the remaining address bytes for these 
pipes will equal those for pipe 1.

Note that the FAP must be in IDLE mode in order for this function to 
have any effect.

@param dev specifies the pipe number (0-5) for which to set the address.    

@param adr is a pointer to the address to be used for the given pipe. 
This address is copied and stored in the radio hardware, 
thus the address does not need to reside on this location during receive.   

@return
@retval false if failure due to the FAP not beeing in IDLE prior to function call.
@retval success.
     
@sa fap_rx_data(), fap_tx_data(), fap_goto_idle_mode()
*/
bool fap_set_address(uint8_t dev, uint8_t* adr); 

/**
Function for reading the address set for a given pipe. 

@param dev specifies the pipe number(0-5) for which to get the address.    

@param adr is a pointer to where the address shall be written. For pipe 1-2 5 bytes 
are returned, whilst for the remaining pipes a single byte is returned.
  
@sa  fap_set_address()
*/
void fap_get_address(uint8_t dev, uint8_t* adr);  

/**
Function for setting up the subset of channels to be used by the FAP.

Note that the receiver and the transmitter must be set up using the same subset of channels. 
The number of channels to be used is specified by the constant 
FAP_CH_TAB_SIZE in fap_setup.h. 

It is recommended that the selected channels are distributed over a 
wide frequency range. The possible channel range 
for nRF24L01 is 0 to 123. 

@param channels is a pointer to an array holding the FAP_CH_TAB_SIZE number of
channels to be used.  
*/
void fap_set_channels(uint8_t *channels);
      
/**
Function for selecting in which mode the radio shall reside when
the FAP is in IDLE mode. The nRF radio may reside in two different modes 
when not transmitting or receiving (FAP IDLE), 
which are STANDBY or POWER DOWN, respectively.
In STANDBY the radio consumes more power than in POWER DOWN, but 
the radio start-up time is shorter, which will result in a lower transmit 
latency when starting a new transmit operation. When the radio resides
in power down one must account for an increased latency of typically 1.5 ms. 

The FAP must be in IDLE mode in order for this function to have any effect.

@param mode selects the radio mode.    
Possible arguments are: 
@arg @c FAP_PDOWN_IDLE   
@arg @c FAP_STANDBY_IDLE 

@return 

@retval false if failure due to the FAP not being in IDLE prior to function call. 
@retval true if function executed successfully. 

*/
bool fap_select_radio_idle_mode(fap_radio_idle_modes_t mode); // Power down / standby

/**
Function for forcing the FAP to IDLE mode.