Skip to content

Commit

Permalink
v3.0 release.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Ludovic-Lesur
Ludovic-Lesur committed Dec 20, 2022
1 parent a678755 commit 0992be0
Show file tree
Hide file tree
Showing 27 changed files with 9,014 additions and 0 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
build/
159 changes: 159 additions & 0 deletions CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
cmake_minimum_required(VERSION 3.15)
project(sigfox_ep_lib)

# Define macro to manage the options
macro(opt TYPE FLAG DEFAULT DESC)
if(${TYPE} STREQUAL TYPE_BOOL)
option(${FLAG} ${DESC} ${DEFAULT})
elseif(${TYPE} STREQUAL TYPE_VALUE)
set(${FLAG} ${DEFAULT} CACHE STRING ${DESC})
else()
message(FATAL_ERROR "Only TYPE_BOOL and TYPE_VALUE are supported")
endif()
list(APPEND COMPILE_FLAG_LIST ${FLAG})
endmacro()

set(LIB_SOURCES
src/sigfox_ep_api.c
src/sigfox_error.c
src/core/sigfox_crc.c
src/core/sigfox_ep_bitstream.c
src/core/sigfox_ep_frequency.c
src/core/sigfox_tx_control.c
)

set(LIB_HEADERS
inc/sigfox_ep_version.h
inc/sigfox_ep_api.h
inc/sigfox_ep_api_test.h
inc/sigfox_error.h
inc/sigfox_rc.h
inc/sigfox_types.h
inc/core/sigfox_ep_bitstream.h
inc/core/sigfox_ep_frequency.h
inc/core/sigfox_tx_control.h
inc/core/sigfox_crc.h
inc/manuf/mcu_api.h
inc/manuf/rf_api.h
)

set(LIB_PUBLIC_HEADERS
inc/core/sigfox_ep_bitstream.h
inc/core/sigfox_ep_frequency.h
inc/core/sigfox_tx_control.h
inc/core/sigfox_crc.h
inc/manuf/rf_api.h
inc/manuf/mcu_api.h
inc/sigfox_ep_api.h
inc/sigfox_ep_api_test.h
inc/sigfox_error.h
inc/sigfox_rc.h
inc/sigfox_types.h
inc/sigfox_ep_version.h
)

set(MANUF_SOURCES
src/manuf/mcu_api.c
src/manuf/rf_api.c
)

# Set the path for the static library
set(LIB_LOCATION ${CMAKE_BINARY_DIR}/lib/ CACHE STRING "")

# Set the path for the public header of the library
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")

#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")
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)")
opt(TYPE_BOOL RC3C ON "Support RC3C with LBT (Japan)")
opt(TYPE_BOOL RC3D ON "Support RC3D with DC (Japan)")
opt(TYPE_BOOL RC4 ON "Support RC4 (Latin America and Asia Pacific)")
opt(TYPE_BOOL RC5 ON "Support RC5 (South-Corea)")
opt(TYPE_BOOL RC6 ON "Support RC6 (India)")
opt(TYPE_BOOL RC7 ON "Support RC7 (Russia)")
opt(TYPE_BOOL APPLICATION_MESSAGES ON "Support uplink application messages")
opt(TYPE_BOOL CONTROL_KEEP_ALIVE_MESSAGE ON "Support uplink control keep alive message")
opt(TYPE_BOOL BIDIRECTIONAL ON "Support downlink communication")
opt(TYPE_BOOL ASYNCHRONOUS ON "Support Asynchronous mode")
opt(TYPE_BOOL LOW_LEVEL_OPEN_CLOSE ON "Enable MCU and RF open/close functions")
opt(TYPE_BOOL REGULATORY ON "Enable Regulatory before transmission (DC, FH or LBT)")
opt(TYPE_BOOL SINGLE_FRAME OFF "Send only 1 frame per message (N=1)")
opt(TYPE_BOOL PARAMETERS_CHECK ON "Enable parameters check")
opt(TYPE_BOOL CERTIFICATION ON "Enable certification functions")
opt(TYPE_BOOL PUBLIC_KEY_CAPABLE ON "Enable public key switch feature")
opt(TYPE_BOOL VERBOSE ON "Enable versionning functions")
opt(TYPE_BOOL CRC_HW OFF "Support hardware CRC")
opt(TYPE_BOOL ERROR_CODES ON "Enable error codes on all functions")
opt(TYPE_VALUE UL_BIT_RATE_BPS OFF "Fixed uplink bit rate in bps (100/600)")
opt(TYPE_VALUE T_IFU_MS OFF "Fixed inter-frame delay in ms (10 to 2000)")
opt(TYPE_VALUE T_CONF_MS OFF "Fixed DL confirmation delay in ms (1400 to 4000)")
opt(TYPE_VALUE UL_PAYLOAD_SIZE OFF "Fixed UL payload size in bytes (0 to 12)")
opt(TYPE_VALUE TX_POWER_DBM_EIRP OFF "Fixed the TX power supported by the radio")
opt(TYPE_VALUE MESSAGE_COUNTER_ROLLOVER OFF "Fixed message counter rollover (128, 256, 512, 1024, 2048 or 4096)")
opt(TYPE_VALUE ERROR_STACK 32 "Enable error stack and defined the depth")

foreach( COMPILE_FLAG ${COMPILE_FLAG_LIST} )
if((NOT ${COMPILE_FLAG} STREQUAL OFF))
if(${${COMPILE_FLAG}} STREQUAL ON)
list(APPEND DEF_FLAG_LIST "-D${COMPILE_FLAG}")
else()
list(APPEND DEF_FLAG_LIST "-D${COMPILE_FLAG}=${${COMPILE_FLAG}} ")
list(APPEND DEF_FLAG_WITH_VALUE_LIST "${COMPILE_FLAG}")
endif()
endif()
endforeach()
if(${CRC_HW} STREQUAL ON)
list(REMOVE_ITEM LIB_SOURCES "src/core/sigfox_crc.c")
list(REMOVE_ITEM LIB_HEADERS "inc/core/sigfox_crc.h")
list(REMOVE_ITEM LIB_PUBLIC_HEADERS "inc/core/sigfox_crc.h")
endif()
if(${REGULATORY} STREQUAL OFF)
list(REMOVE_ITEM LIB_SOURCES "src/core/sigfox_tx_control.c")
list(REMOVE_ITEM LIB_HEADERS "inc/core/sigfox_tx_control.h")
list(REMOVE_ITEM LIB_PUBLIC_HEADERS "inc/core/sigfox_tx_control.h")
endif()
if(${CERTIFICATION} STREQUAL OFF)
list(REMOVE_ITEM LIB_HEADERS "inc/sigfox_ep_api_test.h")
list(REMOVE_ITEM LIB_PUBLIC_HEADERS "inc/sigfox_ep_api_test.h")
endif()
endif()
#add DEF_FLAG_LIST to parent scope to be used by a child
if(NOT (${CMAKE_PROJECT_NAME} STREQUAL ${PROJECT_NAME}))
set(DEF_FLAG_LIST ${DEF_FLAG_LIST} PARENT_SCOPE)
endif()

#Add Cmake module path
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)
include(addon_rfp)
endif()

add_library(${PROJECT_NAME} STATIC ${PRECOMPIL_LIB_SOURCES})
target_include_directories(${PROJECT_NAME} PUBLIC ${PRECOMPIL_DIR}/inc)
target_compile_definitions(${PROJECT_NAME} PUBLIC ${DEF_FLAG_LIST})
target_compile_options(${PROJECT_NAME} PRIVATE -Wall)
set_target_properties(${PROJECT_NAME} PROPERTIES PUBLIC_HEADER "${PRECOMPIL_LIB_PUBLIC_HEADERS}")
set_target_properties(${PROJECT_NAME}
PROPERTIES
ARCHIVE_OUTPUT_DIRECTORY ${LIB_LOCATION}
LIBRARY_OUTPUT_DIRECTORY ${LIB_LOCATION}
)
install(TARGETS ${PROJECT_NAME}
ARCHIVE DESTINATION ${LIB_LOCATION}
PUBLIC_HEADER DESTINATION ${API_LOCATION}
)
156 changes: 156 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
# Sigfox End-Point library (EP_LIB)

## Description

The **Sigfox End-Point library** is an example of the [Sigfox radio protocol](https://build.sigfox.com/sigfox-device-radio-specifications) implementation. The stack is designed to operate either in **blocking** or **asynchronous** mode, and supports most of **MCUs** and **radio chipsets**.

The user API is provided in the `inc/sigfox_ep_api.h` file, to send **application messages** and **control messages** over the Sigfox network.

## Stack architecture

<p align="center">
<img src="docs/images/sigfox_ep_lib_architecture.png" width="600"/>
</p>

## Hardware

The stack relies on **low level drivers** (called manufacturer drivers) which need to be implemented to run on your specific hardware. There are divided in 2 groups:

* **MCU_API** : MCU related functions such as timers, non-volatile memory and encryption.
* **RF_API** : radio related functions such as uplink transmission and downlink reception.

These drivers are located in the `src/manuf` folder.

## Code optimization

Most of Sigfox radio parameters and features are conditionned to a **dedicated flag**, so that the stack can be configured to perfectly match your application, **without dead code** and thus with a **minimum memory footprint**. The flags are located in the `inc/sigfox_ep_flags.h` file, but can also be set through the **cmake** command when building the project.

To have such a flexibilty, the stack use a lot of preprocessor directives, which makes the source code less readable. If you plan to look or modify the source files, we advise you to **run the cmake pre-compilation command**, that will remove all preprocessor directives according to your flags selection.

Below is the list of available flags.

| **Flag name** | **Value** | **Description** |
|:----------------------------:|:--------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| `RCx` | `undefined` / `defined` | Support the RCx radio configuration if defined |
| `APPLICATION_MESSAGES` | `undefined` / `defined` | Support uplink application messages if defined |
| `CONTROL_KEEP_ALIVE_MESSAGE` | `undefined` / `defined` | Support uplink control keep alive message if defined |
| `BIDIRECTIONAL` | `undefined` / `defined` | Support bidirectional procedure (downlink) if defined. Only applicable to application messages. Otherwise all messages will be uplink only. |
| `ASYNCHRONOUS` | `undefined` / `defined` | Asynchronous mode if defined, blocking mode otherwise. |
| `LOW_LEVEL_OPEN_CLOSE` | `undefined` / `defined` | Enable MCU and RF open/close functions if defined. |
| `REGULATORY` | `undefined` / `defined` | Enable radio regulatory control (DC, FH or LBT check) if defined. |
| `SINGLE_FRAME` | `undefined` / `defined` | Send 1 frame per message (N=1) if defined. Otherwise number of frames per message is dynamically given when sending a message (N=1, N=2 or N=3). |
| `UL_BIT_RATE_BPS` | `undefined` / `100` / `600` | If defined, give the only uplink bit rate supported (100 or 600 depending on the RC). Otherwise, value is dynamically given when sending a message. |
| `TX_POWER_DBM_EIRP` | `undefined` / `<tx_power_dbm_eirp>` | If defined, give the only TX power supported by the radio. Otherwise the value is dynamically given when sending a message. |
| `T_IFU_MS` | `undefined` / `<t_ifu_ms>` | If defined, give the fixed inter-frame delay used between uplink frames of a same message (0 to 2000ms). Value 0 disables the delay and associated timers to optimize memory space. Otherwise value is dynamically given when sending a message. |
| `T_CONF_MS` | `undefined` / `<t_conf_ms>` | If defined, give the fixed delay between downlink frame reception and uplink confirmation message (1400 to 4000ms). Otherwise value is dynamically given when sending a message. |
| `UL_PAYLOAD_SIZE` | `undefined` / `<ul_payload_size>` | If defined, give the only uplink payload length supported (0 to 12). Value 0 enables the bit 0, bit 1 and empty messages. Otherwise, all uplink payload lengths are dynamically supported. |
| `CRC_HW` | `undefined` / `defined` | If defined, enable hardware CRC through MCU API functions. Otherwise the embedded driver is used. |
| `MESSAGE_COUNTER_ROLLOVER` | `undefined` / `128` / `256` / `512` / `1024` / `2048` / `4096` | If defined, give the only message counter rollover value supported. Otherwise, value is dynamically given when opening the library. |
| `PARAMETERS_CHECK` | `undefined` / `defined` | Enable parameters check if defined. |
| `CERTIFICATION` | `undefined` / `defined` | Enable certification features if defined. |
| `PUBLIC_KEY_CAPABLE` | `undefined` / `defined` | Enable public key switch feature if defined. |
| `VERBOSE` | `undefined` / `defined` | Enable credentials (ID / PAC) API access and version control functions if defined. |
| `ERROR_CODES` | `undefined` / `defined` | Use return codes if defined, otherwise all functions return void. |
| `ERROR_STACK` | `undefined` / `<error_stack_depth>` | If defined, store low level errors in a stack (the macro gives the depth). Errors can be read with the `SIGFOX_EP_API_unstack_error()` function. |

## Getting Started

### Cloning the repository

```bash
$ 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 [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.

### Original source code

Sources files are available in the `inc` and `src` folders and must be copied directly in your embedded project. Then you can customize the `inc/sigfox_ep_flags.h` according to your flags selection.

### Precompiled source code

#### Dependency

Before building process install **unifdef** and **cmake**. The unifdef tool is used to remove dead code and cmake to build.

#### Building process

If you want to **precompile** the sources files for a given flags selection, you need to use the **cmake** commands:

Create a build folder:

```bash
$ cd sigfox-ep-lib
$ mkdir build
$ cd build
```

* Precompiling by reading the `inc/sigfox_ep_flags.h` file:

```bash
$ cmake -DUSE_SIGFOX_EP_FLAGS_H=ON ..
$ make precompil
```
* Precompiling by entering the flags selection on command line:

```bash
$ cmake -DUSE_SIGFOX_EP_FLAGS_H=OFF \
-DRC1=ON \
-DRC2=ON \
-DRC3C=ON \
-DRC3D=ON \
-DRC4=ON \
-DRC5=ON \
-DRC6=ON \
-DRC7=ON \
-DAPPLICATION_MESSAGES=ON \
-DCONTROL_KEEP_ALIVE_MESSAGE=ON \
-DBIDIRECTIONAL=ON \
-DASYNCHRONOUS=ON \
-DLOW_LEVEL_OPEN_CLOSE=ON \
-DREGULATORY=ON \
-DSINGLE_FRAME=ON \
-DPARAMETERS_CHECK=ON \
-DCERTIFICATION=ON \
-DPUBLIC_KEY_CAPABLE=ON \
-DVERBOSE=ON \
-DCRC_HW=OFF \
-DERROR_CODES=ON \
-DUL_BIT_RATE_BPS=OFF \
-DT_IFU_MS=OFF \
-DT_CONF_MS=OFF \
-DUL_PAYLOAD_SIZE=OFF \
-DMESSAGE_COUNTER_ROLLOVER=OFF \
-DERROR_STACK=12 ..
$ make precompil
```

The precompiled files will be generated in the `build/precompil` folder.

### Static library

If you want to build a **static library**, you need to run this additionnal **cmake** command:

```bash
$ make sigfox_ep_lib
```

The archive will be generated in the `build/lib` folder.


## Addons

### RF & Protocol

In order to **test your implementation** against Sigfox specifications, you can use the [Sigfox End-Point RF & Protocol addon](https://github.com/sigfox-tech-radio/sigfox-ep-addon-rfp) which will drive the library to perform some test modes.

The addon can be directly generated from the Sigfox End-Point library **cmake** by using the `ADDON_RFP` option:

```bash
$ cmake <all previous flags> -DADDON_RFP=ON ..
```
20 changes: 20 additions & 0 deletions cmake/addon_rfp.cmake
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
include(ExternalProject)
include(FetchContent)
Set(FETCHCONTENT_QUIET FALSE)
FetchContent_Declare(
addon_rfp
GIT_REPOSITORY "https://github.com/sigfox-tech-radio/sigfox-ep-addon-rfp"
GIT_TAG "master"
GIT_PROGRESS TRUE
GIT_SHALLOW 1
#SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/addons/rfp
UPDATE_DISCONNECTED TRUE
STEP_TARGETS update
)
FetchContent_GetProperties(addon_rfp)
if (NOT platform_POPULATED)
FetchContent_Populate(addon_rfp)
add_subdirectory(${addon_rfp_SOURCE_DIR} ${addon_rfp_BINARY_DIR})
endif()
#FetchContent_MakeAvailable(addon_rfp)

Loading

0 comments on commit 0992be0

Please sign in to comment.