monarch_api.h

Go to the documentation of this file.

 
/********************************************************
* External API dependencies to link with this library.
*
* Error codes of the MCU MONARCH API functions are described below.
* The Manufacturer can add more error code taking care of the limits defined.
*
********************************************************/
 
#include "sigfox_types.h"
#include "sigfox_monarch_api.h"
 
/*
 * ----------------------------------------------------------------
 * Bytes reserved for MCU API ERROR CODES : From 0x10 to 0x2F
 * ----------------------------------------------------------------
 */
 
/*
 * ----------------------------------------------------------------
 * Bytes reserved for RF API ERROR CODES : From 0x30 to 0x3F
 * ----------------------------------------------------------------
 */
 
/*
 * ----------------------------------------------------------------
 * Bytes reserved for SE API ERROR CODES : From 0x40 to 0x5F
 * ----------------------------------------------------------------
 */
 
/*
 * ----------------------------------------------------------------
 * Bytes reserved for REPEATER API ERROR CODES : From 0x60 to 0x7F
 * ----------------------------------------------------------------
 */
 
/*
 * ----------------------------------------------------------------
 * Bytes reserved for MONARCH API ERROR CODES : From 0x80 to 0x8F
 * ----------------------------------------------------------------
 */
#define MONARCH_ERR_API_MALLOC                   (sfx_u8)(0x80) 
#define MONARCH_ERR_API_FREE                     (sfx_u8)(0x81) 
#define MONARCH_ERR_API_TIMER_START              (sfx_u8)(0x82) 
#define MONARCH_ERR_API_TIMER_STOP               (sfx_u8)(0x83) 
#define MONARCH_ERR_API_CONFIGURE_SEARCH_PATTERN (sfx_u8)(0x84) 
#define MONARCH_ERR_API_STOP_SEARCH_PATTERN      (sfx_u8)(0x85) 
#define MONARCH_ERR_API_GET_VERSION              (sfx_u8)(0x86) 
/*!******************************************************************
 * \fn sfx_u8 MONARCH_API_malloc(sfx_u16 size, sfx_u8 **returned_pointer)
 * \brief Allocate memory for MONARCH library usage (Memory usage = size (Bytes))
 * This function is only called once at RC Scan.
 *
 * IMPORTANT NOTE:
 * --------------
 * The address reported need to be aligned with architecture of the microprocessor used.
 * For a Microprocessor of:
 *   - 8 bits  => any address is allowed
 *   - 16 bits => only address multiple of 2 are allowed
 *   - 32 bits => only address multiple of 4 are allowed
 *
 * \param[in] sfx_u16 size                  size of buffer to allocate in bytes
 * \param[out] sfx_u8 **returned_pointer    pointer to buffer (can be static)
 *
 * \retval SFX_ERR_NONE:                 No error
 * \retval MONARCH_ERR_API_MALLOC        Malloc error
 *******************************************************************/
sfx_u8 MONARCH_API_malloc(sfx_u16 size, sfx_u8** returned_pointer);
 
/*!******************************************************************
 * \fn sfx_u8 MONARCH_API_free(sfx_u8 *ptr)
 * \brief Free memory allocated to library with the MONARCH_API_malloc
 *
 * \param[in] sfx_u8 *ptr                        pointer to buffer
 * \param[out] none
 *
 * \retval SFX_ERR_NONE:                         No error
 * \retval MONARCH_ERR_API_FREE:                 Free error
 *******************************************************************/
sfx_u8 MONARCH_API_free(sfx_u8* ptr);
 
/*!******************************************************************
 * \fn sfx_u8 MONARCH_API_timer_start (sfx_u16 timer_value, sfx_timer_unit_enum_t unit, sfx_error_t  (* sigfox_callback_timeout_handler ) ( void ) )
 * \brief This function starts a timer based on timer_value and the units. When the timer expires
 *        the manufacturer has to call the timer callback function (sigfox_callback_timeout_handler)
 *
 * \param[in] sfx_u16 timer_value               Scan duration value ( with the unit parameter information )
 * \param[in] sfx_timer_unit_enum_t  unit       Unit to be considered for the scan time computation
 * \param[in] timeout_callback_handler          This is the function that needs to be called when the timer expires
 *                                              ( either when RC Found or when Timeout )
 *
 * \retval SFX_ERR_NONE:                             No error
 * \retval MONARCH_ERR_API_TIMER_START:              Timer Start error
 *******************************************************************/
sfx_u8 MONARCH_API_timer_start(sfx_u16 timer_value, sfx_timer_unit_enum_t unit, sfx_error_t (* timeout_callback_handler)(void));
 
/*!******************************************************************
 * \fn sfx_u8 MONARCH_API_timer_stop (void)
 * \brief This function stops the timer
 *
 * \retval SFX_ERR_NONE:                              No error
 * \retval MONARCH_ERR_API_TIMER_STOP:                Stop Timer error
 *******************************************************************/
sfx_u8 MONARCH_API_timer_stop(void);
 
/*!******************************************************************
 * \fn sfx_u8 MONARCH_API_configure_search_pattern ( sfx_monarch_pattern_search_t list_freq_pattern[], sfx_u8 size, sfx_monarch_listening_mode_t mode, sfx_error_t  (* monarch_pattern_freq_result_callback_handler ) (sfx_u32 freq, sfx_pattern_enum_t pattern, sfx_s16 rssi));
 *
 * \brief This function is used to configure a search pattern action from on the MCU/RF side.
 *        The list of frequencies to scan and associated pattern is given as parameter.
 *        When a pattern is found or the timeout ( set with MONARCH_API_timer_start ) occurs,
 *        the callback function has to be called.
 *
 *        There are 2 modes that can be used : LISTENING_SWEEP and LISTENING_WINDOW modes.
 *        They are detailed in the sfx_monarch_listening_mode_t description
 *
 * \param[in] sfx_monarch_pattern_search_t list_freq_pattern[]       Tab of the frequencies / patterns to check
 * \param[in] sfx_u8  size                                      Size of the list (list_freq_pattern)
 * \param[in] sfx_monarch_listening_mode_t  mode                Mode of the scan
 * \param[in] monarch_pattern_freq_result_callback_handler      Callback function when a pattern is found or when the timer expires
 *            with the following parameters :
 *                \param[in] sfx_u32 freq                       Report the Frequency on which the pattern has been found
 *                \param[in] sfx_pattern_enum_t pattern         Pattern which has been found
 *                \param[in] sfx_s16 rssi                       RSSI level of the found pattern
 *
 *
 * \retval SFX_ERR_NONE:                                  No error
 * \retval MONARCH_ERR_API_CONFIGURE_SEARCH_PATTERN:      Search pattern error
 *******************************************************************/
sfx_u8 MONARCH_API_configure_search_pattern(sfx_monarch_pattern_search_t list_freq_pattern[],
                                            sfx_u8 size,
                                            sfx_monarch_listening_mode_t mode,
                                            sfx_error_t (* monarch_pattern_freq_result_callback_handler)(sfx_u32 freq, sfx_pattern_enum_t pattern, sfx_s16 rssi));
 
/*!******************************************************************
 * \fn sfx_u8 MONARCH_API_stop_search_pattern (void)
 * \brief This function stops the scan
 *
 * \retval SFX_ERR_NONE:                              No error
 * \retval MONARCH_ERR_API_STOP_SEARCH_PATTERN:       Stop seach pattern error
 *******************************************************************/
sfx_u8 MONARCH_API_stop_search_pattern(void);
 
/*!******************************************************************
 * \fn sfx_u8 MONARCH_API_get_version(sfx_u8 **version, sfx_u8 *size)
 * \brief This function returns current MONARCH API version
 *
 * \param[out] sfx_u8 **version                  Pointer to Byte array (ASCII format) containing library version
 * \param[out] sfx_u8 *size                      Size of the byte array pointed by *version
 *
 * \retval SFX_ERR_NONE:                         No error
 * \retval MONARCH_ERR_API_GET_VERSION:          Get Version error
 *******************************************************************/
sfx_u8 MONARCH_API_get_version(sfx_u8** version, sfx_u8* size);