FSP v4.0.0 FreeRTOS Stack Migration Guide

Note

This guide only applies to users converting e² studio projects created with FSP v3.8.0 or earlier

Migration is only possible for network stacks using CoreMQTT and CoreHTTP modules. Stacks using deprecated MQTT Client and HTTP Client modules will not be able to be migrated over to FSP v4.0.0 and up. See the following guide for migrating code from the deprecated Client libraries: https://aws.github.io/aws-iot-device-sdk-embedded-C/202103.00/docs/doxygen/output/html/mqtt_migration.html

Overview

This migration guide is for moving to the new FreeRTOS Network stacks introduced in FSP v4.0.0. It will describe steps for moving over stacks as well as changes to make code compile correctly.

Stack Migration Steps

Note

Perform all of the following steps before attempting to save the project. Failure to do so may cause unexpected errors in the configuration.xml.

1. Open project to be migrated in e² studio using FSP v4.0.0 or greater. The existing CoreMQTT/HTTP stack should still exist. Many of the stack components will have No Longer Supported in the display and have permanent constraint error messages on them:

   

   Old MQTT Stack

2. Add a new network stack (New Stack->Networking->AWS CoreHTTP or AWS CoreMQTT):

   

   Add a New MQTT Stack

3. Choose a sockets wrapper for the new stack (Add Sockets Wrapper).

   

   Add a Sockets Wrapper

4. The submodule for AWS PKCS11 to MbedTLS will likely be missing. Click Add FreeRTOS MbedTLS Port and use the existing instance:

   

   FreeRTOS MbedTLS Port

5. Got to the components tab and see if AWS MbedTLS FreeRTOS Port (AWS|Abstractions|FreeRTOS_Plus|utilities|mbedtls) is checked. If this component is not checked then check it so that appears like so:

   

   FreeRTOS MbedTLS Port Component
6. Check that settings/properties are correct on the new stack. Common stack elements between the old and new stacks should already have previous settings.
7. Remove the old stack.
8. Save project and generate project content. See the next section for things to change in the code for successful compilation.

List of Code Change Highlights

This is a list of important changes from pre-4.0 code. For more detailed examples see CoreMQTT/HTTP examples and devassist.

• Any calls to SYSTEM_Init() should be removed. mbedtls_platform_setup() now does initialization that this IoT library function originally did.
• xLoggingTaskInitialize should no longer be called. Logging libraries which create a logging task no longer exist. Logging by default uses printf when enabled. The user can redefine vLoggingPrintf(const char * pcFormat, ...) and vLoggingPrint(const char * pcFormat) to change this behavior.
• The transport interface for CoreMQTT/HTTP will now need to be setup directly by creating a transport interface and setting the send and receive pointers to TLS_FreeRTOS_recv and TLS_FreeRTOS_send. See the examples and devassist for more info.
• The user will need to call TLS_FreeRTOS_Connect to connect to a server/endpoint before using CoreMQTT/HTTP APIs to communicate. TLS_FreeRTOS_Disconnect can be used to disconnect from a server/endpoint.