Skip to content

Commit

Permalink
v1.3 release.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Ludovic-Lesur
Ludovic-Lesur committed Nov 9, 2023
1 parent 3a267c4 commit 0b83c01
Show file tree
Hide file tree
Showing 7 changed files with 342 additions and 152 deletions.
23 changes: 23 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [v1.3](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases/tag/v1.3) - 09 Nov 2023

### Added

* Implement `RF_API_start_continuous_wave()` function for **type approval addon**.
* Add **RF frequency parameter check** in `RF_API_init()` function since it is not performed by ST driver.

### Fixed

* Fix **TX output power formula** in ST driver (patch file update).
* Do not close radio driver in `RF_API_error()` function.
* Add **missing pointer symbol** on HW API callback syntax.

### Removed

* Remove `doc` folder since images are now hosted on the GitHub wiki.

### Known limitations

* **LBT** not implemented.
* **External radio front-end** not supported.
* **Modulated CW** not supported for type approval addon.

## [v1.2](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases/tag/v1.2) - 10 Aug 2023

### Changed
Expand Down
229 changes: 155 additions & 74 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,127 +4,208 @@

This **S2LP RF API** is a low level implementation example of the [Sigfox EP library](https://github.com/sigfox-tech-radio/sigfox-ep-lib), showing the `manuf/rf_api.c` file implementation for the [S2LP](https://www.st.com/en/wireless-connectivity/s2-lp.html) transceiver from ST-Microelectronics.

The table below shows the version compatibility with the SIGFOX_EP_LIB version.
> [!WARNING]
> The resulting radio performances of your device strongly depends on your **hardware design** (schematic, PCB routing, crystal oscillator placement, good RF practices, etc...). **Sigfox certification remains mandatory** whatever the software embedded in your device (including the Sigfox End-Point library and its implementation examples).
| **S2LP_RF_API** | **SIGFOX_EP_LIB** |
|:---------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------:|
| [v1.2](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases/tag/v1.2) | >= [v3.2](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.2) |
| [v1.1](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases/tag/v1.1) | >= [v3.2](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.2) |
| [v1.0](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases/tag/v1.0) | >= [v3.2](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.2) |
The table below shows the versions compatibility between this radio example and the Sigfox End-Point library.

**Note:** the resulting radio performances of your device strongly depends on your hardware design (schematic, PCB routing, crystal oscillator placement, good RF practices, etc...). **Sigfox certification remains mandatory** whatever the software embedded in your device (including the Sigfox End-Point library and its implementation examples).
| **S2LP_RF_API** | **EP_LIB** |
|:---:|:---:|
| [v1.3](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases/tag/v1.3) | >= [v3.4](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.4) |
| [v1.2](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases/tag/v1.2) | [v3.2](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.2) to [v3.3](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.3) |
| [v1.1](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases/tag/v1.1) | [v3.2](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.2) to [v3.3](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.3) |
| [v1.0](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases/tag/v1.0) | [v3.2](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.2) to [v3.3](https://github.com/sigfox-tech-radio/sigfox-ep-lib/releases/tag/v3.3) |

## Architecture

<p align="center">
<img src="docs/images/sigfox_ep_example_st_s2lp_architecture.png" width="600"/>
<img src="https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/wiki/images/sigfox_ep_rf_api_st_s2lp_architecture.drawio.png" width="600"/>
</p>

## External S2LP library
## Compilation flags for optimization

The **S2LP RF API** is based on the official [S2LP library](https://github.com/STMicroelectronics/x-cube-sfxs2lp1/tree/main/Drivers/BSP/Components/S2LP/S2LP_Library) from ST-Microelectronics. This library exposes a functional interface to configure the chip registers, which is used to perform the Sigfox uplink modulation and optional downlink reception.
This radio example inherits all the [Sigfox End-Point library flags](https://github.com/sigfox-tech-radio/sigfox-ep-lib/wiki/compilation-flags-for-optimization) and can be optimized accordingly.

## Hardware
The `LOW_LEVEL_OPEN_CLOSE` flag must be enabled to use this example.

The driver relies on **low level functions** (called board drivers) which need to be implemented to run on your specific hardware. There are divided in 2 groups:
## How to add S2LP RF API example to your project

* **MCU_Interface_template** : low level functions of the S2LP library from ST (registers access through SPI and shutdown pin management).
* **S2LP_HW_API** : additional hardware-dependent functions required to get a generic RF API implementation of the S2LP.
### Dependencies

These drivers are located in the `src/board` folder.
The **S2LP RF API** is based on the [official S2LP driver](https://github.com/STMicroelectronics/x-cube-sfxs2lp1/tree/main/Drivers/BSP/Components/S2LP/S2LP_Library) from ST-Microelectronics. This driver exposes a functional interface to configure the chip registers, which is used to perform the Sigfox uplink modulation and optional downlink reception. It relies on **low level functions** (called board drivers) which need to be implemented to run on your specific hardware. There are divided in 2 groups:

## Code optimization
* **MCU_Interface_template** : low level functions of the S2LP driver from ST (registers access through SPI and shutdown pin management).
* **S2LP_HW_API** : additional hardware dependent functions required to get a generic RF API implementation of the S2LP.

The driver inherits all the [Sigfox EP library](https://github.com/sigfox-tech-radio/sigfox-ep-lib) flags and can be optimized accordingly.
The templates are located in the `src/board` folder.

## Getting Started
### Submodule

### Cloning the repository
The best way to embed the S2LP RF API example into your project is to use a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules), in a similar way to the library. The radio driver will be seen as a sub-repository with independant history. It will be much easier to **upgrade the radio driver** or to **switch between versions** when necessary, by using the common `git pull` and `git checkout` commands within the `sigfox-ep-rf-api-st-s2lp` folder.

In order to keep the repository clean, you will need to **exclude** the `src/board` folder from build (where the board templates are defined) and implement the functions in another location of your project.

To add the S2LP RF API submodule, go to your project location and run the following commands:

```bash
$ git clone https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp.git
mkdir lib
cd lib/
git submodule add https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp.git
```

### Usage
This will clone the S2LP RF API repository. At project level, you can commit the submodule creation with the following commands:

```bash
git commit --message "Add Sigfox S2LP RF API submodule."
git push
```

This code can be used in 3 different ways:
* 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 generate a compiled library.
With the submodule, you can easily:

### Original source code
* Update the radio driver to the **latest version**:

Sources files are available in the `inc` and `src` folders and must be copied directly in your embedded project.
```bash
cd lib/sigfox-ep-rf-api-st-s2lp/
git pull
git checkout master
```

### Precompiled source code
* Use a **specific release**:

#### Dependency
```bash
cd lib/sigfox-ep-rf-api-st-s2lp/
git pull
git checkout <tag>
```

### Raw source code

You can [download](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases) or clone any release of the S2LP RF API example and copy all files into your project.

```bash
git clone https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp.git
```

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

#### Building process
You can [download](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases) or clone any release of the S2LP RF API example and copy all files into your project. If you do not plan to change your compilation flags in the future, you can perform a **precompilation step** before copying the file in your project. The precompilation will **remove all preprocessor directives** according to your flags selection, in order to produce a more **readable code**. Then you can copy the new files into your project.

If you want to **precompile** the sources files for a given flags selection, you need to use the **cmake** commands:
```bash
git clone https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp.git
```

Create a build folder:
To perform the precompilation, you have to install `cmake` and `unifdef` tools, and run the following commands:

```bash
$ cd sigfox-ep-rf-api-st-s2lp
$ mkdir build
$ cd build
cd sigfox-ep-rf-api-st-s2lp/
mkdir build
cd build/
```

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

```bash
$ cmake -DSIGFOX_EP_LIB_DIR=<Sigfox EP library path> \
-DUSE_SIGFOX_EP_FLAGS_H=ON ..
$ make precompil
cmake -DSIGFOX_EP_LIB_DIR=<sigfox-ep-lib path> \
-DUSE_SIGFOX_EP_FLAGS_H=ON ..
make precompil_s2lp_rf_api
```

* Precompiling by entering the flags selection on command line:

```bash
$ cmake -DSIGFOX_EP_LIB_DIR=<Sigfox EP library path> \
-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 \
-DLATENCY_COMPENSATION=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
cmake -DSIGFOX_EP_LIB_DIR=<sigfox-ep-lib path> \
-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 \
-DLATENCY_COMPENSATION=ON \
-DSINGLE_FRAME=ON \
-DUL_BIT_RATE_BPS=OFF \
-DTX_POWER_DBM_EIRP=OFF \
-DT_IFU_MS=OFF \
-DT_CONF_MS=OFF \
-DUL_PAYLOAD_SIZE=OFF \
-DCRC_HW=OFF \
-DMESSAGE_COUNTER_ROLLOVER=OFF \
-DPARAMETERS_CHECK=ON \
-DCERTIFICATION=ON \
-DPUBLIC_KEY_CAPABLE=ON \
-DVERBOSE=ON \
-DERROR_CODES=ON \
-DERROR_STACK=12 ..
make precompil_s2lp_rf_api
```

The precompiled files will be generated in the `build/precompil` folder.
The new 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:
You can also [download](https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp/releases) or clone any release of the S2LP RF API example and build a **static library**.
```bash
git clone https://github.com/sigfox-tech-radio/sigfox-ep-rf-api-st-s2lp.git
```

To build a static library, you have to install `cmake` tool and run the following commands:

```bash
cd sigfox-ep-rf-api-st-s2lp/
mkdir build
cd build/
```

* Building by reading the `sigfox_ep_flags.h` file:

```bash
cmake -DSIGFOX_EP_LIB_DIR=<sigfox-ep-lib path> \
-DUSE_SIGFOX_EP_FLAGS_H=ON ..
make s2lp_rf_api
```

* Building by entering the flags selection on command line:

```bash
$ make s2lp_rf_api
cmake -DSIGFOX_EP_LIB_DIR=<sigfox-ep-lib path> \
-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 \
-DLATENCY_COMPENSATION=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 s2lp_rf_api
```

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

0 comments on commit 0b83c01

Please sign in to comment.