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 dif

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.

1 Acronyms 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

Acronyms and abbreviations

UM2669 - Rev 3

page 2/39

X-CUBE-SUBG2 software expansion for STM32Cube

2 X-CUBE-SUBG2 software expansion for STM32Cube

2.1 Overview

X-CUBE-SUBG2 software package expands STM32Cube

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.

functionality .

UM2669

2.2 Architecture

This software is fully compliant with and expands STM32Cube

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

to enable development of applications using X-

page 3/39

STM32Cube Hardware Abstraction Layer (HAL)

STM32 Nucleo development board

6LoWPAN

Hardware

Middleware

Hardware Abstraction

Application

Examples

STM32 Nucleo expansion boards

X-NUCLEO-S2868A2/X-NUCLEO-S2915A1 (Connect)

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

UM2669 - Rev 3

page 4/39

2.3 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)

UM2669

Folder structure

Figure 2. X-CUBE-SUBG2 package folder structure

2.4 APIs

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

3 Point-to-Point (P2P) demo firmware description

3.1 P2P application details

The P2P application operates using two nodes (STM32 Nucleo development board plus S2-LP expansion board) as follows:

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.

3.2 Application 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.

o 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

Node 1

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 2

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

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 2

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

Application state diagram

Figure 4. Application state diagram when Node 1 user button is pressed

UM2669

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.

The following diagram shows data communication in low-power mode.

Figure 5. Application state diagram when Node 2 user button is pressed

UM2669 - Rev 3

page 7/39

Idle mode

Power

Saving

Mode

(if enabled)

S2-LP RX

mode

(Prepare to

Receive)

Wait for

Command

Send

S2-LP TX

mode

Prepare to

send ACK

Command

Received

Process

Received

data

ACK

Received

Button Press Event

Data received

If Command,

send ACK

UM2669

SPIRIT1 packet handler overview

Figure 6. Application state diagram (low-power mode): data communication transmit and receive states

3.3 S2-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.

Preamble Sync Length Destination address Source address Control Seq. no. No ACK Payload CRC

Table 2. Stack

Table 3. wM-Bus

UM2669 - Rev 3

Preamble Sync Payload Postamble

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

LLP: automatic acknowledgment with piggybacking

LLP: automatic retransmission

1. Link layer protocol

(1)

Yes No No

3.4 Transmit 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

3.4.1 Packet field description

• Cmd Length: the basic command is 1 byte long, but you can set multiple command bytes

• Cmd T

• 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

ag: a unique tag number is linked to each command issued from the node and the response must

replicate the same number

UM2669

User configuration

Figure 8. Response packet structure

3.5 User 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.1 Selecting 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

UM2669 - Rev 3

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 auto-

retransmission) are defined.

page 10/39

3.5.2 Setting 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

#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

can also be activated (RF_* macros).

3.5.3 Setting 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 */ #define XTAL_OFFSET_PPM 0 #define INFINITE_TIMEOUT 0.0

UM2669

User configuration

#ifdef USE_RADIO_868MHz #define BASE_FREQUENCY 868.0e6 #endif

#define CHANNEL_SPACE 100e3 #define CHANNEL_NUMBER 0 #define DATARATE 38400 #define FREQ_DEVIATION 20e3 #define BANDWIDTH 100E3 #define POWER_INDEX 7 #define RECEIVE_TIMEOUT 2000.0 /*change the value for required timeout period*/

#define RSSI_THRESHOLD -120 /* Default RSSI at reception, more than noise floor */ #define CSMA_RSSI_THRESHOLD -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.4 Setting 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

UM2669 - Rev 3

#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)

page 11/39

3.5.5 Setting 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.6 User defined commands and macros

/* User Command */ #define APPLI_CMD 0x11 #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

User configuration

UM2669 - Rev 3

page 12/39

+ 27 hidden pages