v3.1 release.

CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [v3.1](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.1) - 01 Mar 2023
+
+### General
+
+* Add `CHANGELOG` file.
+
+### Added
+
+* Add `MCU_API_timer_status()` function to facilitate **timeout management in RF API** functions.
+* Add **logical names for timers** (`MCU_API_TIMER_INSTANCE_xxx` macros) in MCU API to define instances mapping.
+* Add `reason` field in timer structure.
+* Add `RF_API_get_latency()` function to compensate **radio delays** in MCU API timers duration.
+* Add new **bypass flags** in test API for RFP addon (`ul_enable`, `dl_enable`, `dl_decoding_enable`, `dl_conf_enable`, `ldc_check_enable` bits, `rx_frequency_hz`, `cs_max_duration_first_frame_ms`, and `dl_t_w_ms` / `dl_t_rx_ms` timing values).
+* Add **Low Duty Cycle (LDC) check** in TX control.
+* Add `MCU_API_print_dl_payload()` function to **print RFP addon downlink results**.
+
+### Changed
+
+* Rename fields of message status and split error flag into `execution_error` and `network_error` to **differentiate internal execution errors from external errors** such as TX control failure or downlink reception timeout.
+* Move `SIGFOX_UL_BITSTREAM_SIZE_BYTES` **macro** in `inc/sigfox_types.h` to avoid core files inclusion in manufacturer drivers.
+* Improve **manufacturer functions call sequence** (`Tw` timer and downlink ending).
+* **Random frequency generator**: optimize RAM footprint and increase allowed bandwidth of N=1 and N=2 modes.
+* Remove all **function pointers** in blocking mode for specific compilers compatibility.
+* Change default 32 bits type to `long`.
+* Rename `sigfox_ep_version.h` to `sigfox_ep_lib_version.h`.
+* Use `RETURN` macro in manufacturer functions **template**.
+
+### Fixed
+
+* **Buffer overflow** in downlink frame decoding functions (`src/core/sigfox_ep_bitstream.c`).
+* Wrong application message **pointer access** in blocking mode (`src/sigfox_ep_api.c`).
+* Wrong **LBT carrier sense timeout** computation for second and third frames (`src/core/sigfox_tx_control.c`).
+
+### Removed
+
+* Remove `dl_phy_content_size` field in **RX data structure**, as it is fixed to `SIGFOX_DL_PHY_CONTENT_SIZE_BYTES`.
+
+## [v3.0](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.0) - 12 Dec 2022
+
+### General
+
+* First version of the new Sigfox EP library.
+
+### Added
+
+* **Asynchronous** operation mode in addition to the legacy blocking mode.
+* **Memory footprint optimization** thanks to multiple **compilation flags** (`inc/sigfox_ep_flags.h`)
+* **Precompiled source** files and **library** generation with `cmake`.
+* Sigfox **empty frame** support.
+* **Message status** and **error stack**.
+* New **options in user API**: dynamic TX power, bit rate and inter-frame delay.
+* New **random frequency algorithm** with lower memory footprint and better distribution over device ID ranges.
+* Using **structures** as functions parameters to improve compatibility between compilation flags and versions.
+
+### Known limitations
+
+* **Payload encryption** not supported.
+* **Secure element** not supported.

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.15)
+cmake_minimum_required(VERSION 3.21)
 project(sigfox_ep_lib)
 
 # Define macro to manage the options 
@@ -23,7 +23,7 @@ set(LIB_SOURCES
 )
 
 set(LIB_HEADERS 
-    inc/sigfox_ep_version.h
+    inc/sigfox_ep_lib_version.h
     inc/sigfox_ep_api.h
     inc/sigfox_ep_api_test.h
     inc/sigfox_error.h
@@ -49,7 +49,7 @@ set(LIB_PUBLIC_HEADERS
     inc/sigfox_error.h
     inc/sigfox_rc.h
     inc/sigfox_types.h
-    inc/sigfox_ep_version.h    
+    inc/sigfox_ep_lib_version.h    
 )
 
 set(MANUF_SOURCES
@@ -66,12 +66,49 @@ set(API_LOCATION ${CMAKE_BINARY_DIR}/lib/api CACHE STRING 	"")
 #Options Use sigfox_ep_flag.h
 opt(TYPE_BOOL USE_SIGFOX_EP_FLAGS_H ON "library compilation options. ON:in sigfox_ep_flag.h file OFF:in command line")
 #Option addon RFP contents
-opt(TYPE_BOOL ADDON_RFP OFF "Add RFP addon contents to build it with library")
+if(NOT sigfox_ep_addon_rfp_IS_TOP_LEVEL)
+    opt(TYPE_BOOL ADDON_RFP OFF "Add RFP addon contents to build it with library")
+endif()
+#Option RF API contents
+if(NOT manuf_rf_api_IS_TOP_LEVEL)
+    opt(TYPE_BOOL MANUF_RF_API OFF "Add RF API contents to build it with library")
+else()
+    list(REMOVE_ITEM MANUF_SOURCES "src/manuf/rf_api.c")
+endif()
 
 #When sigfox_ep_flag.h is don't used
 if(${USE_SIGFOX_EP_FLAGS_H} STREQUAL "ON")
 	list(APPEND DEF_FLAG_LIST "-DUSE_SIGFOX_EP_FLAGS_H")
     list(APPEND LIB_HEADERS 	"inc/sigfox_ep_flags.h")
+    unset(RC1 CACHE)
+    unset(RC2 CACHE)
+    unset(RC3C CACHE)
+    unset(RC3D CACHE)
+    unset(RC4 CACHE)
+    unset(RC5 CACHE)
+    unset(RC6 CACHE)
+    unset(RC7 CACHE)
+    unset(APPLICATION_MESSAGES CACHE)
+    unset(CONTROL_KEEP_ALIVE_MESSAGE CACHE)
+    unset(BIDIRECTIONAL CACHE)
+    unset(ASYNCHRONOUS CACHE)
+    unset(LOW_LEVEL_OPEN_CLOSE CACHE)
+    unset(REGULATORY CACHE)
+    unset(SINGLE_FRAME CACHE)
+    unset(PARAMETERS_CHECK CACHE)
+    unset(CERTIFICATION CACHE)
+    unset(PUBLIC_KEY_CAPABLE CACHE)
+    unset(VERBOSE CACHE)
+    unset(CRC_HW CACHE)
+    unset(ERROR_CODES CACHE)
+    unset(UL_BIT_RATE_BPS CACHE)
+    unset(T_IFU_MS CACHE)
+    unset(T_CONF_MS CACHE)
+    unset(UL_PAYLOAD_SIZE CACHE)
+    unset(TX_POWER_DBM_EIRP CACHE)
+    unset(UL_PAYLOAD_SIZE CACHE)
+    unset(MESSAGE_COUNTER_ROLLOVER CACHE)
+    unset(ERROR_STACK CACHE)
 else()
 	opt(TYPE_BOOL   RC1                         ON  "Support RC1 (Europe, Middle-East and Africa)")
 	opt(TYPE_BOOL   RC2                         ON  "Support RC2 (Brazil, Canada, Mexico, Puerto Rico and USA)")
@@ -138,10 +175,15 @@ list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake")
 #Precompile module
 include(precompile)
 #Addon RFP module
-if(${ADDON_RFP} STREQUAL "ON")
-    unset(SFX_LIB_CORE_PROTOCOL_DIR CACHE)
+if(ADDON_RFP)
     include(addon_rfp)
 endif()
+#Addon RFP module
+if(MANUF_RF_API)
+    include(manuf_rf_api)
+endif()
+
+mark_as_advanced(CMAKE_BUILD_TYPE CMAKE_INSTALL_PREFIX LIB_LOCATION API_LOCATION)
 
 add_library(${PROJECT_NAME} STATIC ${PRECOMPIL_LIB_SOURCES})
 target_include_directories(${PROJECT_NAME} PUBLIC ${PRECOMPIL_DIR}/inc)

README.md

@@ -64,9 +64,9 @@ $ git clone https://github.com/sigfox-tech-radio/sigfox-ep-lib.git
 ### Usage
 
 This library can be used in 3 different ways:
- * The [original source code](#original-source-code) to used the raw sources files
+ * The [original source code](#original-source-code) to use the raw sources files
  * The [precompiled source code](#precompiled-source-code) to remove all unused source code and have more readability.
- * The [static-library](#static-library) to used a compiled library.
+ * The [static-library](#static-library) to generate a compiled library.
 
 ### Original source code
 

cmake/addon_rfp.cmake

@@ -4,7 +4,7 @@ Set(FETCHCONTENT_QUIET FALSE)
 FetchContent_Declare(
     addon_rfp
     GIT_REPOSITORY "https://github.com/sigfox-tech-radio/sigfox-ep-addon-rfp"
-    GIT_TAG "master"
+    GIT_TAG "v1.1"
     GIT_PROGRESS TRUE
     GIT_SHALLOW    1
     #SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/addons/rfp
@@ -16,5 +16,7 @@ if (NOT platform_POPULATED)
     FetchContent_Populate(addon_rfp)
     add_subdirectory(${addon_rfp_SOURCE_DIR} ${addon_rfp_BINARY_DIR})
 endif()
+mark_as_advanced(FETCHCONTENT_QUIET FETCHCONTENT_BASE_DIR FETCHCONTENT_FULLY_DISCONNECTED FETCHCONTENT_UPDATES_DISCONNECTED)
+mark_as_advanced(FETCHCONTENT_SOURCE_DIR_ADDON_RFP FETCHCONTENT_UPDATES_DISCONNECTED_ADDON_RFP)
 #FetchContent_MakeAvailable(addon_rfp)
 

cmake/manuf_rf_api.cmake

@@ -0,0 +1,22 @@
+include(ExternalProject)
+include(FetchContent)
+Set(FETCHCONTENT_QUIET FALSE)
+FetchContent_Declare(
+    manuf_rf_api
+    GIT_REPOSITORY "https://github.com/sigfox-tech-radio/manuf-rf-api"
+    GIT_TAG "v1.0"
+    GIT_PROGRESS TRUE
+    GIT_SHALLOW    1
+    #SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/addons/rfp
+    UPDATE_DISCONNECTED TRUE
+    STEP_TARGETS        update
+)
+FetchContent_GetProperties(manuf_rf_api)
+if (NOT platform_POPULATED)
+    FetchContent_Populate(manuf_rf_api)
+    add_subdirectory(${manuf_rf_api_SOURCE_DIR} ${manuf_rf_api_BINARY_DIR})
+endif()
+mark_as_advanced(FETCHCONTENT_QUIET FETCHCONTENT_BASE_DIR FETCHCONTENT_FULLY_DISCONNECTED FETCHCONTENT_UPDATES_DISCONNECTED)
+mark_as_advanced(FETCHCONTENT_SOURCE_DIR_MANUF_RF_API FETCHCONTENT_UPDATES_DISCONNECTED_MANUF_RF_API)
+#FetchContent_MakeAvailable(addon_rfp)
+

cmake/precompile.cmake

@@ -7,6 +7,7 @@ find_program(SPLINT splint REQUIRED)
 if(NOT SPLINT)
     message(FATAL_ERROR "splint not found!")
 endif()
+mark_as_advanced(SPLINT UNIFDEF PRECOMPIL_DIR)
 # specify the precompil files location
 set(PRECOMPIL_DIR ${CMAKE_BINARY_DIR}/precompil CACHE STRING 	"")
 

inc/core/sigfox_ep_bitstream.h

@@ -42,26 +42,6 @@
 #endif
 #include "sigfox_types.h"
 
-/*** SIGFOX EP BITSTREAM macros ***/
-
-#if (defined UL_PAYLOAD_SIZE)
-#if (UL_PAYLOAD_SIZE == 0)
-#define SIGFOX_EP_BITSTREAM_SIZE_BYTES	14
-#elif (UL_PAYLOAD_SIZE == 1)
-#define SIGFOX_EP_BITSTREAM_SIZE_BYTES	15
-#elif (UL_PAYLOAD_SIZE == 2) || (UL_PAYLOAD_SIZE == 3) || (UL_PAYLOAD_SIZE == 4)
-#define SIGFOX_EP_BITSTREAM_SIZE_BYTES	18
-#elif (UL_PAYLOAD_SIZE == 5) || (UL_PAYLOAD_SIZE == 6) || (UL_PAYLOAD_SIZE == 7) || (UL_PAYLOAD_SIZE == 8)
-#define SIGFOX_EP_BITSTREAM_SIZE_BYTES	22
-#elif (UL_PAYLOAD_SIZE == 9) || (UL_PAYLOAD_SIZE == 10) || (UL_PAYLOAD_SIZE == 11) || (UL_PAYLOAD_SIZE == 12)
-#define SIGFOX_EP_BITSTREAM_SIZE_BYTES	26
-#else
-#define SIGFOX_EP_BITSTREAM_SIZE_BYTES	26
-#endif
-#else
-#define SIGFOX_EP_BITSTREAM_SIZE_BYTES	26 // Maximum value used as default.
-#endif
-
 /*** SIGFOX EP BITSTREAM structures ***/
 
 #ifdef ERROR_CODES
@@ -152,6 +132,9 @@ typedef struct {
 #ifdef PUBLIC_KEY_CAPABLE
 	SIGFOX_ep_key_t ep_key_type;
 #endif
+#ifdef CERTIFICATION
+	sfx_bool dl_decoding_enable; // Enable or disable downlink frame decoding (dewhitening, BCH, CRC and AUTH).
+#endif
 } SIGFOX_EP_BITSTREAM_dl_frame_t;
 #endif
 

inc/core/sigfox_ep_frequency.h

@@ -53,6 +53,7 @@ typedef enum {
 	SIGFOX_EP_FREQUENCY_SUCCESS = 0,
 	SIGFOX_EP_FREQUENCY_ERROR_NULL_PARAMETER,
 	SIGFOX_EP_FREQUENCY_ERROR_FRAME_RANK,
+	SIGFOX_EP_FREQUENCY_ERROR_NUMBER_OF_FRAMES,
 	SIGFOX_EP_FREQUENCY_ERROR_SPECTRUM_ACCESS_TYPE,
 	SIGFOX_EP_FREQUENCY_ERROR_RANDOM_GENERATION,
 	SIGFOX_EP_FREQUENCY_ERROR_FRAME_1_FREQUENCY,
@@ -68,6 +69,7 @@ typedef void SIGFOX_EP_FREQUENCY_status_t;
  *******************************************************************/
 typedef struct {
 	SIGFOX_ul_frame_rank_t ul_frame_rank;
+	sfx_u8 number_of_frames;
 #ifdef BIDIRECTIONAL
 	sfx_bool bidirectional_flag;
 #endif

inc/core/sigfox_tx_control.h

@@ -95,7 +95,7 @@ typedef enum {
  *******************************************************************/
 typedef struct {
 	SIGFOX_TX_CONTROL_check_type type;
-	sfx_u8 bitstream_length_bytes;
+	sfx_u8 bitstream_size_bytes;
 	sfx_bool last_message_frame;
 #ifndef SINGLE_FRAME
 	SIGFOX_ul_frame_rank_t ul_frame_rank;
@@ -105,7 +105,7 @@ typedef struct {
 	sfx_u16 ul_bit_rate_bps;
 #endif
 #ifdef BIDIRECTIONAL
-	sfx_bool ack_message;
+	sfx_bool dl_conf_message;
 #endif
 #if !(defined SINGLE_FRAME) || (defined BIDIRECTIONAL)
 	sfx_u32 interframe_ms; // Tifu, Tifb or Tconf.
@@ -116,8 +116,12 @@ typedef struct {
 #endif
 #ifdef SPECTRUM_ACCESS_LBT
 	sfx_bool lbt_enable;
+	sfx_u32 lbt_cs_max_duration_first_frame_ms;
 #endif
+#ifdef SPECTRUM_ACCESS_LDC
+	sfx_bool ldc_check_enable;
 #endif
+#endif /* CERTIFICATION */
 #ifdef ASYNCHRONOUS
 	SIGFOX_TX_CONTROL_check_cplt_cb_t cplt_cb;
 #endif