sigfox_monarch_api.h

Go to the documentation of this file.

 
#ifndef SIGFOX_MONARCH_API_H
#define SIGFOX_MONARCH_API_H
 
#include "sigfox_types.h"
 
/********************************
 * \enum sfx_timer_unit_enum_t
 * \brief value used to identify the unit of the timer
 *******************************/
typedef enum
{
    SFX_TIME_MS = 0, 
    SFX_TIME_S, 
    SFX_TIME_M, 
    SFX_TIME_H, 
}sfx_timer_unit_enum_t;
 
/********************************
 * \enum sfx_bitfield_rc_enum_t
 * \brief value used to identify the RC supported by the device
 *        or the RC found after the monarch scan.
 *******************************/
typedef enum
{
    SFX_BITFIELD_SHIFT_RC1 = 0, 
    SFX_BITFIELD_SHIFT_RC2 = 1, 
    SFX_BITFIELD_SHIFT_RC3 = 2, 
    SFX_BITFIELD_SHIFT_RC4 = 3, 
    SFX_BITFIELD_SHIFT_RC5 = 4, 
    SFX_BITFIELD_SHIFT_RC6 = 5, 
    SFX_BITFIELD_SHIFT_RC7 = 6, 
    /* Keep the below line still at the end */
    SFX_MAX_SIGFOX_RC, 
}sfx_bitfield_rc_enum_t;
 
/********************************
 * \enum sfx_pattern_enum_t
 * \brief This enum describes all the
 *        patterns that can be part of the
 *        Sigfox beacon, in first or second
 *        position of the beacon.
 *******************************/
typedef enum
{
    NO_MONARCH_PATTERN = 0, 
    MONARCH_DELTA_F1   = 1, 
    MONARCH_DELTA_F2   = 2, 
    MONARCH_DELTA_F3   = 3, 
    /* Keep this line at the end */
    LAST_MONARCH_PATTERN = MONARCH_DELTA_F3, 
}sfx_pattern_enum_t;
 
#define MAX_MONARCH_PATTERN_PER_FREQUENCY_SEARCH 2 /* On 1 frequency, we can at the maximum ask for the research of 2 different patterns */
 
/********************************
 * \struct sfx_monarch_pattern_search_t
 * \brief This structure describes
 *        for a single frequency, the patterns
 *        that need to be searched
 *******************************/
typedef struct
{
    sfx_u32 freq;
    sfx_pattern_enum_t patterns[MAX_MONARCH_PATTERN_PER_FREQUENCY_SEARCH];
}sfx_monarch_pattern_search_t;
 
/********************************
 * \enum sfx_monarch_listening_mode_t
 * \brief value used to define the monarch
 *        listening modes.
 *******************************/
typedef enum
{
    MONARCH_LISTENING_SWEEP, 
    MONARCH_LISTENING_WINDOW, 
}sfx_monarch_listening_mode_t;
 
/*!******************************************************************
 * \fn sfx_error_t sfx_error_t SIGFOX_MONARCH_API_execute_rc_scan (sfx_u8 rc_capabilities_bit_mask, sfx_u16 timer, sfx_timer_unit_enum_t unit, sfx_u8  (* app_callback_handler ) ( sfx_u8 rc_bit_mask, sfx_s16 rssi ) )
 * \brief This function executes a scan of the air to detect a Sigfox Beacon.
 *        It will return the RC enum value corresponding to the beacon found and its RSSI level.
 *        The scan is executed during the specific timer / unit time
 *
 *        NOTE : there is no need to open the sigfox Library to run this function.
 *
 * \param[in] sfx_u8 rc_capabilities_bit_mask   Bit Mask (format below ) of the RCx on which the scan has to be executed :
 *
 *                                              ---------------------------------------------------------
 *                                              | Bit7 | Bit6 | Bit5 | Bit4 | Bit3 | Bit2 | Bit1 | Bit0 |
 *                                              ---------------------------------------------------------
 *                                              |  -   |  RC7 | RC6  | RC5  | RC4  | RC3  | RC2  |  RC1 |
 *                                              ---------------------------------------------------------
 *
 * \param[in] sfx_u16 timer                     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] app_callback_handler              This is the function that will be called by the Sigfox Library when the scan is completed.
 *                                              ( either when RC Found or when Timeout )
 *                 parameter of this callback are :
 *                     \param[out] sfx_u8       rc  Value of the RC found. There could be only 1 RC or 0 ( not found )
 *                     \param[out] rssi         RSSI value of the RC found. if rc = 0, rssi is not valid ( is set to 0 too )
 *
 *    MSB_____________________________________________LSB
 *    15                      8|7                     0
 *     |                       |                      |
 *     |   MANUF_ERROR_CODE    |  SIGFOX_ERROR_CODE   |
 *     |_______________________|______________________|
 *
 *  SIGFOX_ERROR_CODE for this function : SFX_ERR_NONE or SFX_ERR_MONARCH_API_xx
 *
 *******************************************************************/
sfx_error_t SIGFOX_MONARCH_API_execute_rc_scan(sfx_u8 rc_capabilities_bit_mask, sfx_u16 timer, sfx_timer_unit_enum_t unit, sfx_u8 (* app_callback_handler)(sfx_u8 rc_bit_mask, sfx_s16 rssi));
 
/*!******************************************************************
 * \fn sfx_error_t SIGFOX_MONARCH_API_stop_rc_scan ( void )
 * \brief This function stops a RC scan which is on going
 *
 *        NOTE : there is no need to open the sigfox Library to run this function.
 *
 *    MSB_____________________________________________LSB
 *    15                      8|7                     0
 *     |                       |                      |
 *     |   MANUF_ERROR_CODE    |  SIGFOX_ERROR_CODE   |
 *     |_______________________|______________________|
 *
 *  SIGFOX_ERROR_CODE for this function : SFX_ERR_NONE or SFX_ERR_MONARCH_API_xx
 *
 *******************************************************************/
sfx_error_t SIGFOX_MONARCH_API_stop_rc_scan(void);
 
#endif