STMicroelectronics X-CUBE-SUBG2 User Manual
UM2669
User manual
Getting started with X-CUBE-SUBG2, Sub-1 GHz RF software expansion for STM32Cube
Introduction
X-CUBE-SUBG2 is an expansion software package for STM32Cube. The software runs on the STM32 and includes drivers that recognize the Sub-1 GHz RF communication for S2-LP.
The expansion is built on STM32Cube software technology to ease portability across different STM32 microcontrollers.
The software comes with sample applications of P2P and 6LoWPAN communication protocols, running on an X-NUCLEO- S2868A2 or X-NUCLEO-S2915A1 expansion board when connected to a compatible STM32 Nucleo development board.
RELATED LINKS
Visit the STM32Cube ecosystem web page on www.st.com for further information
UM2669 - Rev 3 - December 2020 |
www.st.com |
For further information contact your local STMicroelectronics sales office. |
|
|
|
UM2669
Acronyms and abbreviations
1Acronyms and abbreviations
|
Table 1. List of acronyms |
|
|
Acronym |
Description |
|
|
GHz |
Giga Hertz |
|
|
AMR |
Automatic Meter Reading |
|
|
EEPROM |
Electrically erasable programmable read-only memory |
|
|
GUI |
Graphical User Interface |
|
|
P2P |
Point-to-Point communication |
|
|
RF |
Radio frequency |
|
|
MCU |
Microcontroller unit |
|
|
P2P |
Point-to-Point communication |
|
|
HAL |
Hardware Abstraction Layer |
|
|
SPI |
Serial peripheral interface |
|
|
USB |
Universal Serial Bus |
|
|
NVIC |
Nested Vectored Interrupt Controller |
|
|
WSN |
Wireless sensors network |
|
|
BSP |
Board support package |
|
|
LED |
Light emitting diode |
|
|
IPv6 |
Internet Protocol vers. 6 |
|
|
UDP |
User Datagram Protocol |
|
|
TCP |
Transmission Control Protocol |
|
|
6LoWPAN |
IPv6 over Low -Power Wireless Personal Area Networks |
|
|
RPL |
Routing Protocol for Low-Power and Lossy Networks |
|
|
MAC |
Medium Access Control |
|
|
CSMA |
Carrier-sense multiple access |
|
|
DMA |
Direct Memory Access |
|
|
USART |
Universal Synchronous Asynchronous Receiver Transmitter |
|
|
wM-Bus |
Wireless metering bus |
|
|
UM2669 - Rev 3 |
page 2/39 |
|
|
UM2669
X-CUBE-SUBG2 software expansion for STM32Cube
2X-CUBE-SUBG2 software expansion for STM32Cube
2.1Overview
X-CUBE-SUBG2 software package expands STM32Cube functionality .
The key features of the package are:
•Firmware package to start developing using S2-LP expansion boards
•Point-to-point communication sample application for simple buffer transmission and acknowledgement implementation
•Contiki-NG based applications for 6LoWPAN connectivity
•Low-power optimizations for the STM32 MCU family
•Easy portability across different MCU families thanks to STM32Cube
•Package compatible with STM32CubeMX, can be downloaded from and installed directly into STM32CubeMX
•Free user-friendly license terms
•Sample implementation available on X-NUCLEO-S2868A1, X-NUCLEO-S2868A2 or X-NUCLEO-S2915A1 expansion boards when connected to NUCLEO-F401RE, NUCLEO-L053R8 or NUCLEO-L152RE development boards
Starting from this software, it is possible to develop other applications, such as:
•automatic meter reading
•home and building automation
•industrial monitoring and control
•wireless fire and security alarm systems
The firmware partitioning among the STM32 microcontroller on the STM32 Nucleo development boards and the S2-LP is:
•STM32 MCU
–P2P and 6LowPAN applications implementation
–low power mode handling
–interrupt services
•S2-LP role
–basic/stack modes
–header, sync and trailer fields
–encoding/decoding
–sync detection
–RX and TX 128 bytes FIFO buffers
–IEEE 802.15.4g hardware packet support with whitening, FEC, CRC and dual sync word detection.
2.2Architecture
This software is fully compliant with and expands STM32Cube to enable development of applications using X- NUCLEO-S2868A1, X-NUCLEO-S2868A2 or X-NUCLEO-S2915A1 expansion board hosting the S2-LP devices.
The software is based on the STM32CubeHAL hardware abstraction layer for the STM32 microcontroller. The package extends STM32Cube by providing a board support package (BSP) for the S2-LP expansion board and firmware examples for P2P communication.
UM2669 - Rev 3 |
page 3/39 |
|
|
UM2669
Architecture
The software layers used by the application software to access and use the S2-LP expansion board are:
•STM32Cube HAL layer: provides a generic, multi-instance set of APIs to interact with the upper layers (the application, libraries and stacks). It consists of generic and extension APIs based on a common architecture which allows other layers like the middleware layer to function without specific Microcontroller Unit (MCU) hardware configurations. This structure improves library code reusability and guarantees easy device portability.
•Board support package (BSP) Layer: includes the software to support the peripherals on the STM32 Nucleo board (apart from the MCU). It is a set of APIs which provides a programming interface for certain board-specific peripherals (LED, user button etc.). The X-NUCLEO-S2868A1, X-NUCLEO-S2868A2 or X- NUCLEO-S2915A1 expansion board BSP firmware layer contains APIs for the hardware components and consists of:
–Component driver: related to the on-board device (not related to the STM32). The S2-LP BSP driver is known as the firmware component. The S2-LP component driver provides specific APIs and can be ported to and used on any board.
–BSP driver: enables the component driver to be linked to a specific board and provides a set of user-friendly APIs.
•Application layer: provides a Point-to-Point communication example for sending a buffer from one node to another and acknowledgments using the S2-LP link layer features.
•Application layer for Contiki-NG based applications: provides 6LoWPAN communication for mesh-network as well as featured examples for UDP Client/Server, Serial Sniffer and Border Router.
Figure 1. X-CUBE-SUBG2 software architecture
Application |
Examples |
|
|
|
|
Middleware |
6LoWPAN |
Hardware |
STM32Cube Hardware Abstraction Layer (HAL) |
Abstraction |
|
|
|
|
|
|
STM32 Nucleo expansion boards |
Hardware |
X-NUCLEO-S2868A2/X-NUCLEO-S2915A1 (Connect) |
|
|
|
STM32 Nucleo development board |
|
|
UM2669 - Rev 3 |
page 4/39 |
|
|
UM2669
Folder structure
2.3Folder structure
Figure 2. X-CUBE-SUBG2 package folder structure
The software package includes the following folders:
•‘CubeMX’: contains the meta data files for the package support in the STM32CubeMX tool.
•‘Documentation’: contains a compiled HTML file generated from the source code and detailed documentation of the software components and APIs
•‘Drivers’: contains the HAL drivers and the board-specific drivers for supported board and hardware platforms, including those for the on-board components and the CMSIS vendor-independent hardware abstraction layer for the Cortex-M processor series
•‘Middlewares’: contains Contiki-NG source code for 6LoWPAN communication over S2-LP radio
•‘Projects’: contains a sample application used for P2P firmware examples and 6LoWPAN communication for the NUCLEO-L053R8 (P2P only), NUCLEO-F401RE or NUCLEO-L152RE platforms with three development environments (IAR Embedded Workbench for ARM (IAR-EWARM), RealView Microcontroller Development Kit (MDK-ARM-STR) and STM32CubeIDE)
•‘Utilities’: contains tools to be used on a host PC to interact with Serial Sniffer and Border Router firmware applications (6LoWPAN)
2.4APIs
Detailed descriptions of all the functions and parameters of the user APIs user can be found in a compiled HTML file located inside the ‘Documentation’ folder.
UM2669 - Rev 3 |
page 5/39 |
|
|
UM2669
Point-to-Point (P2P) demo firmware description
3Point-to-Point (P2P) demo firmware description
3.1P2P application details
The P2P application operates using two nodes (STM32 Nucleo development board plus S2-LP expansion board) as follows:
1.by pressing the STM32 Nucleo board user button (shown in the picture below), each node can transmit a buffer to the other node
2.on receiving the signal, the receiver node LED lights up and an acknowledgment (ACK) signal is returned to the transmitter node
3.on reception of the ACK signal, the transmitter node LED flashes four times and switches off after a delay period
|
|
Figure 3. X-NUCLEO-S2868A1 plus STM32 Nucleo used as a node (transmitter/receiver) in P2P |
|
|
communication |
|
1. |
STM32 Nucleo user button |
|
2. |
X-NUCLEO-S2868A1 expansion board LED |
Note: |
The LED on the expansion board is mounted but not connected: only the STM32 Nucleo LED blinks during P2P |
|
|
communication. |
|
2 
1
3.2Application state diagram
When running the demo sample with the STM32 Nucleo boards, S2-LP remains by default in receive mode but changes to transmit mode when the user button is pressed.
Once transmission stops, the transceiver returns to its default receive mode. On successful completion of the two-way communication (Command/ Ack), the MCU enters low-power mode.
To limit low-power mode current consumption, the LED is switched off by default.
P2P nodes have the same functionality; the address of each node is set in the firmware by the user.
UM2669 - Rev 3 |
page 6/39 |
|
|
UM2669
Application state diagram
Figure 4. Application state diagram when Node 1 user button is pressed
Press SW on Nucleo
Prepared the Command
Change S2-LP mode to Transmit and transmit the Command Packet
Switch the S2-LP back to Receiver mode
ACK Received
Toggle LED and Switch OFF
Command Received
Switch ON the LED
Prepared the ACK for
Command
Change S2-LP mode to Transmit and send ACK Packet
Switch the S2-LP back to Receiver mode
Node 1 |
Node 2 |
If the user presses the other node user button, the functionality is the same: Node 2 wakes up from low-power mode, prepares the command for transmission, sends the data packet and waits for acknowledgment.
Figure 5. Application state diagram when Node 2 user button is pressed
Command Received
Switch ON the LED
Prepared the ACK for
Command
Change S2-LP mode to Transmit and send ACK Packet
Switch the S2-LP back to Receiver mode
Press SW on Nucleo
Prepared the Command
Change S2-LP mode to Transmit and transmit the Command Packet
Switch the S2-LP back to Receiver mode
ACK Received
Toggle LED and Switch OFF
Node 1 |
Node 2 |
The following diagram shows data communication in low-power mode.
UM2669 - Rev 3 |
page 7/39 |
|
|
UM2669
SPIRIT1 packet handler overview
Figure 6. Application state diagram (low-power mode): data communication transmit and receive states
Idle mode
Power |
|
Saving |
ACK |
Mode |
Received |
(if enabled) |
|
S2-LP RX |
Data |
Process |
|
mode |
|||
Received |
|||
(Prepare to |
received |
||
data |
|||
Receive) |
|
||
|
|
Wait for |
Button |
Command |
|
Command |
Press |
||
Received |
|||
Send |
Event |
||
|
If Command,
send ACK
S2-LP TX |
|
Prepare to |
mode |
|
send ACK |
3.3S2-LP packet handler overview
Before on-air transmission, raw data is arranged in a packet structure. S2-LP offers a highly flexible and fully programmable packet which lets you configure the structure of the packet, the number, the type, and the dimension of the fields inside the packet.
Through a register, the user can choose from one of the formats shown in the tables below.
Table 2. Stack
Preamble |
Sync |
Length |
Destination address |
Source address |
Control |
Seq. no. |
No ACK |
Payload |
CRC |
|
|
|
|
|
|
|
|
|
|
Table 3. wM-Bus
Preamble |
Sync |
Payload |
Postamble |
|
|
|
|
UM2669 - Rev 3 |
page 8/39 |
|
|
UM2669
Transmit and receive (command and response) packet structure
Table 4. Basic
Preamble |
Sync |
Length |
Destination address |
Control |
Payload |
CRC |
|
|
|
|
|
|
|
See S2-LP datasheet for further details on the embedded packet handler.
Since P2P communication requires the receiving node destination address, the P2P demo is based on stack and basic packet handlers.
Note: |
The wM-Bus packet format is not used in this sample demonstration. |
|
|
|
|
Table 5. Packet handler feature comparison |
|
|
|
|
|
|
|
|
|
Features |
Stack |
wM-Bus |
Basic |
|
|
|
|
|
|
Destination address filtering |
Yes |
No |
Yes |
|
|
|
|
|
|
Broadcast and multicast addressing |
Yes |
No |
Yes |
|
|
|
|
|
|
Source address filtering |
Yes |
No |
No |
|
|
|
|
|
|
Custom filtering |
Yes |
No |
Yes |
|
|
|
|
|
|
CRC filtering |
Yes |
No |
Yes |
|
|
|
|
|
|
LLP: automatic acknowledgment(1) |
Yes |
No |
No |
|
LLP: automatic acknowledgment with piggybacking(1) |
Yes |
No |
No |
|
LLP: automatic retransmission(1) |
Yes |
No |
No |
1. Link layer protocol
3.4Transmit and receive (command and response) packet structure
Command packet features:
•command with data sent at the same time
•S2-LP can handle 65535 bytes of data
•customizable command structure
•customizable data packet maximum size
Figure 7. Command data packet structure
Response packet features:
•data buffer is replied from the node
•tag contains the number associated with the command so the receiver can associate the response with the specific command
UM2669 - Rev 3 |
page 9/39 |
|
|
UM2669
User configuration
Figure 8. Response packet structure
3.4.1Packet field description
•Cmd Length: the basic command is 1 byte long, but you can set multiple command bytes
•Cmd Tag: a unique tag number is linked to each command issued from the node and the response must replicate the same number
•Cmd Type: flag to identify application level or network command
•Commands: the actual command set sent from the source to destination (it may include parameters)
•Data Length: the data packet length
•Data buffer: the actual data associated with the command
3.5User configuration
You can modify the configuration file s2868A1_conf.h (or s2868a2_conf.h, s2915a1_conf.h depending on the expansion board) according to the application used.
3.5.1Selecting packet handler
The user can select the desired features by setting the relevant macros:
#define USE_BASIC_PROTOCOL
#define USE_BASIC_PROTOCOL_ADDRESS /* to activate Basic protocol with Address field, to be activated with USE_BASIC_PROTOCOL */
#define USE_RADIO_868MHz
/*...*/ |
|
#define EN_AUTOACK |
S_DISABLE |
#define EN_PIGGYBACKING |
S_DISABLE |
#define MAX_RETRANSMISSIONS |
PKT_DISABLE_RETX |
#if defined(USE_STack_PROTOCOL)
//#define USE_STack_LLP /*Uncomment if LLP featured need to be used*/ #endif
#ifdef USE_BASIC_PROTOCOL
#define CSMA_ENABLE /* Comment this line to disable the CSMA */ #endif
By default, S2-LP works with the basic packet handler.
S2-LP uses the STack packet handler only if the link layer features (such as auto-ack, piggybacking and autoretransmission) are defined.
UM2669 - Rev 3 |
page 10/39 |
|
|
UM2669
User configuration
3.5.2Setting low-power mode
The P2P application supports low-power mode (disabled by default). It allows the MCU to either enter stop or sleep mode (check app_x-cube-subg2.c file for these settings).
Optional Low Power modes for the S2-LP can also be activated (RF_* macros).
#if defined (USE_LOW_POWER_MODE) //#define MCU_SLEEP_MODE
#define MCU_STOP_MODE #endif
/*Possible Low Power modes for the S2-LP: */ //#define RF_STANDBY
//#define RF_SHUTDOWN //#define RF_SLEEP
3.5.3Setting radio configuration parameters
You can set the radio parameters in the configuration file, even though it is not recommended to change them.
/* Radio configuration parameters */ |
0 |
|
#define |
XTAL_OFFSET_PPM |
|
#define |
INFINITE_TIMEOUT |
0.0 |
#ifdef USE_RADIO_868MHz #define BASE_FREQUENCY #endif
#define CHANNEL_SPACE #define CHANNEL_NUMBER #define DATARATE #define FREQ_DEVIATION #define BANDWIDTH #define POWER_INDEX #define RECEIVE_TIMEOUT period*/
#define RSSI_THRESHOLD
#define CSMA_RSSI_THRESHOLD
868.0e6
100e3
0
38400
20e3
100E3
7
2000.0 /*change the value for required timeout
-120 /* Default RSSI at reception, more than noise floor */
-90 /* Higher RSSI to Transmit.
If it's lower, the Channel will be seen as busy */
/* Packet configuration parameters |
*/ |
|
#define |
MODULATION_SELECT |
MOD_2FSK |
#define |
POWER_DBM |
12.0 |
3.5.4Setting packet configuration parameters
You can set the packet configuration, even though it is not recommended to change default settings.
*/ Packet configuration parameters */
#define SYNC_WORD |
0x88888888 |
#define LENGTH_WIDTH |
7 |
#define CRC_MODE |
PKT_CRC_MODE_8BITS |
#define EN_FEC |
S_DISABLE |
#define EN_WHITENING |
S_ENABLE |
#define PREAMBLE_LENGTH |
PREAMBLE_BYTE(4) |
#define SYNC_LENGTH |
SYNC_BYTE(4) |
#define CONTROL_LENGTH |
0x00 |
#define VARIABLE_LENGTH |
S_ENABLE |
#define EXTENDED_LENGTH_FIELD |
S_DISABLE |
#define PREAMBLE_BYTE(v) |
(4*v) |
#define SYNC_BYTE(v) |
(8*v) |
UM2669 - Rev 3 |
page 11/39 |
|
|
UM2669
User configuration
3.5.5Setting node address
Node adresses parameters can be set in following section of the system setup guide.
*/ Addresses configuration parameters */
#define EN_ADDRESS |
S_DISABLE |
#define EN_FILT_MY_ADDRESS |
S_DISABLE |
#define EN_FILT_MULTICAST_ADDRESS |
S_DISABLE |
#define EN_FILT_BROADCAST_ADDRESS |
S_DISABLE |
#define EN_FILT_SOURCE_ADDRESS |
S_DISABLE |
#define SOURCE_ADDR_MASK |
0xf0 |
#define SOURCE_ADDR_REF |
0x37 |
#define MULTICAST_ADDRESS |
0xEE |
#define BROADCAST_ADDRESS |
0xFF |
3.5.6User defined commands and macros
/* User Command */ |
0x11 |
#define APPLI_CMD |
|
#define NWK_CMD |
0x22 |
#define LED_TOGGLE |
0xff |
#define ACK_OK |
0x01 |
#define MAX_BUFFER_LEN |
96 |
#define TIME_TO_EXIT_RX |
3000 |
#define DELAY_RX_LED_TOGGLE |
100 |
#define DELAY_TX_LED_GLOW |
100 |
#define LPM_WAKEUP_TIME |
100 |
UM2669 - Rev 3 |
page 12/39 |
|
|
Loading...