Migration Guide #

1. Introduction
2. General
3. How to Migrate
4. 130 to 152
   1. General Steps for Migration
   2. Common
      1. Application Startup
      2. Deprecations and Renaming
         1. New Platform Package List
         2. Renamed Removed Packages
         3. Removed Files
         4. Renamed Files
   3. Libraries
      1. FreeRTOS
         1. Timers
         2. Tasks
         3. Semaphores
   4. Platform
      1. Sensors
      2. SDC SD Card Driver
      3. FatFs
   5. Workbench Examples
5. 201 to 300
   1. Platform
      1. WLI NCI WiFi and Networking
6. 201 to 300
   1. Basic
   2. Common
      1. Essentials BSP HAL Config
   3. Libraries
      1. ServalStack
   4. Platform
      1. Module Organization
      2. FOTA
      3. SD Card Driver
      4. WLAN Driver
      5. BLE
      6. Utils
   5. Workbench Examples
      1. SendAccelerometerDataOverBle and SendAccelDataOverUdpAndBle
      2. SdCardExample

Introduction #

With every new version of the XDK-Workbench, major changes to the SDK and the Workbench itself are made. This document provides information on the most significant changes that were made from one Workbench version to another. The purpose is to allow for migration of projects from older to newer versions without much effort.

First, some important concepts on how versions are determined and what changes are generally made between versions are described in the chapter General.

In chapter How To Migrate, some basic ideas of how to migrate a project efficiently are introduced, that explain how to use this guide as a basis. Apart from that, there is one chapter for every version change that was determined to have significant changes that require detailed explanation and mention.

For every such chapter, there may be a sub-chapter called All that describes changes that affect all projects, regardless from the modules that will be eventually used. Other than that, there will be a sub-chapter for every noteworthy module or API library that has changed.

General #

In general, changes are distinguished between how much they affect project code that is based on the previous version of the SDK. In this context, project code refers to any piece of code written by XDK-Workbench users for applications that run on the XDK.

The three main types of changes are breaking changes, new features and bugfixes. Breaking changes are the focus of this document.

• Breaking Changes (C) break code that depends on APIs or modules, if a project from the previous version is using the new version’s SDK. Such a change requires either an adaption of the code using the respective API, or a complete rewrite. An example for this is BLE from 2.0.1 to 3.0.0, where the old API had been closed off, in favor of a platform specific API.

• New Features (F) are new endpoints and functions in an API. They do not change anything, and therefore do not cause breaks in the code. New features usually do not need to be added to an older project’s code. An example for a new feature is the possibility of adding custom headers using the HTTP API.

• Bugfixes (B) are changes to the source code that do not break existing project code. They do usually do not require an adaption in project code, but they may make a previously implemented workaround for a certain issue unnecessary.

The XDK-Workbench version is described as a combination of three numbers x.y.z, for example 3.0.0.

• The x number usually increments when major breaking changes are introduced, indicating that migration of older projects may be necessary. New features and bugfixes are also part of the version change.

• The y number usually increments on major changes and when new features are added. These changes do not break most projects. Bugfixes are also part of the version change.

• The z number usually increments on minor changes, such as minor features, and bugfixes in the SDK.

Each of the following chapters describes one major version change that requires extensive adaption of most/many older projects, if they were to be migrated from one specific version to the version that follows chronologically.

How to Migrate #

The SDK offers three main directories. They are Common, Libraries and Platform.

• The Common directory contains relevant makefiles, that can be freely edited (only recommended for advanced users). Additionally, the directory contains files for configuring certain parts of the SDK.

• The Libraries directory contains third party API, such as FreeRTOS, ServalStack, EMlib and FATfs. The implementation of most of these libraries stays unchanged, and if changes are made, they are usually major, such as new features. These libraries are independent from the XDK, and are mostly build to last. The only library actively receiving changes is the ServalStack.

• The Platform directory contains API provided by BCDS. These API are most commonly designed to offer a layer between third party libraries for hardware and the XDK’s system. For example, the sensors of the XDK have hardware-specific API in the 3rd-party library at Libraries/BSTLib. To use the sensors, the physical sensor itself must first be enabled and connected on a very low API level. The sensor values would have to be read from the sensor, converted and made available. The Platform-specific API handles all this, and only requires the user to call very few functions to enable the sensors and retrieve their data.

Generally, as implied by how likely the three directories are subject to change, the content of Platform is the most likely source of breaking changes between major updates of the XDK-Workbench.

Every sub-chapter of this guide covers one specific directory and package/module. When migrating a project from one version to another, first look at which sub-chapters are available. If any of the covered modules is used in the project code, check if the change is a breaking change, and modify the code accordingly.

For that, first consider the nature of the change. If it is a simple rename, then modification should be straightforward. If parameters changed, take a look at the header-file that contains the function and see the comment above the function’s declaration. Usually, the parameters and the effect of the function are described there. If one or more functions are removed, usually another one is added, that accounts for the removed function. This will usually be mentioned in the corresponding sub-chapter.

Unfortunately, documentation may not be available for every change currently.

If the project is based on one of the Workbench-Examples, please see the corresponding sub-chapter Workbench-Examples for general information. If an example is mentioned there, it may require changes.

130 to 152 #

1.3.0 to 1.5.2

In the following text, abbreviations are used for breaking changes, new features, and bugfixes as follows.

• (C) - Breaking Change
• (F) - New Feature
• (B) - Bugfixes

General Steps for Migration #

The following steps serve as a guideline for attempts in migrating a 1.3.0 project to 1.5.2.

1. Restructure the project directory and use the new correct Makefile, by:

   1. Either:

      • Creating a new project
      • Copying added code into new project from old project

   2. Or:

      • Delete the “make” folder containing the project application makefile. (Preferably, make a backup beforehand)
      • Copy the application makefile from any one of the example application into the application project directory
      • Copy the main.c file from any of example application into the application project directory
      • Replace your required application makefile changes in the copied example makefile.

   3. Apply API changes, when modules, that are mentioned within this chapter, are used.

   4. (Re-)compile and verify until the build gets successfully completed

Common #

Application Startup #

From 1.3.0 to 1.5.2, the way applications start has been changed

Deprecations and Renaming #

From 1.3.0 to 1.5.2, several files and modules have been renamed or removed. The following tables present most of the removals and renamings.

New Platform Package List #

Renamed Removed Packages #

Removed Files #

Renamed Files #

Libraries #

FreeRTOS #

In 1.3.0, the module OS, used to abstract some of the FreeRTOS functions, was part of the Platform modules. This is removed in 1.5.2. Therefore, instead of the abstraction functions, the FreeRTOS calls must be used.

The following tables show which functions from the OS module correspond to which FreeRTOS functions.

Timers #

When timer ticks need to be specified as input to FreeRTOS API, then it has to be explicitly converted as shown below.

uint32_t Ticks = 2;

if (Ticks != UINT32_MAX) /* Validated for portMAX_DELAY to assist the task to wait Infinitely (without timing out) */
{
    Ticks /= portTICK_RATE_MS;
}
if (UINT32_C(0) == Ticks) /* ticks cannot be 0 in FreeRTOS timer. So ticks is assigned to 1 */
{
    Ticks = UINT32_C(1);
}
xTimerStop(timerHandle, Ticks);

When using the FreeRTOS API to defer from ISR using pend timer, refer to the example below

   portBASE_TYPE xHigherPriorityTaskWoken = pdFALSE;
    if (xTimerPendFunctionCallFromISR(appDeferredISRCallback, NULL, UINT8_C(0), &xHigherPriorityTaskWoken) == pdPASS)
    {
        returnValue = INT32_C(0);
        portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
    }
    else
    {
        Retcode_raiseError(returnValue);
    }

Tasks #

Below is an example for Task Delay until.

#include "BCDS_PowerMgt.h"
#include <FreeRTOS.h>
#include <task.h>

static uint32_t timeToDelayTask = UINT32_C(0); /**< variable to delay OS task */

void Task_mainProcess(void *pvParameters)
{
    timeToDelayTask = xTaskGetTickCount();
    for (;;)
    {
     vTaskDelayUntil(&timeToDelayTask, PowerMgt_GetMsDelayTimeInSystemTicks(100));
    }
 }

Semaphores #

Platform #

Sensors #

All sensor API has been changed to unify return codes and the way functions are called. The new sensor API is presented in the current version of the Sensor Guide. Module names have been renamed as well. For an example, see the following table of changes for the Accelerometer.

SDC SD Card Driver #

• (C) The module SDC has been renamed to SDCardDriver
• (C) API function names have been changed to reflect the new module name
• (C) Return Types, Input Types and Enumerations have been changed for more uniformity
• (C) The interface is now provided by “BCDS_SDCardDriver.h” (previously “SDC_sdCardDriver_ih.h”)

See the complete list of changes for further information:

FatFs #

• (C) changed function signature FRESULT f_mount (BYTE, FATFS*) to FRESULT f_mount (FATFS* fs, const TCHAR* path, BYTE opt)

Workbench Examples #

All the examples have been renamed and substantially changed in accordance with the new startup procedure of applications and the respective API changes.

201 to 300 #

2.0.1 to 3.0.0

In the following text, abbreviations are used for breaking changes, new features, and bugfixes as follows.

• (C) - Breaking Change
• (F) - New Feature
• (B) - Bugfixes

Platform #

WLI NCI WiFi and Networking #

• (C) The modules WLI and NCI have been renamed to WlanConnect and NetworkConfig respectively
• (C) API function names have been changed to reflect the new module names
• (C) Return Types, Input Types and Enumerations have been changed for more uniformity

See the complete list of changes for further information:

201 to 300 #

2.0.1 to 3.0.0

In the following text, abbreviations are used for breaking changes, new features, and bugfixes as follows.

• (C) - Breaking Change
• (F) - New Feature
• (B) - Bugfixes

Basic #

The way the application is started on the XDK has changed significantly, from version 2.0.1 to 3.0.0. In that regard, changes have to be made to the implementation file which declares the function appInitSystem() as well as the entire content of main.c, which is automatically generated in every XDK Project.

An easy way to solve this, would be by creating a new project in the new Workbench version and to copy only the code written by the user.

Alternatively, the changes can be made manually, as follows.

First, adapt the declaration of appinitSystem()

from

void appInitSystem(xTimerHandle xTimer)
{
   (void) (xTimer);

   // Your Application Code
}

to

void appInitSystem(void * CmdProcessorHandle, uint32_t param2)
{
    if (CmdProcessorHandle == NULL)
    {
        printf("Command processor handle is null \n\r");
        assert(false);
    }
    AppCmdProcessorHandle = (CmdProcessor_T * s) CmdProcessorHandle;
    BCDS_UNUSED(param2);

    // add application code here
}

The function appInitSystem() was called within the context of a timer before. This has been changed in favor of a new feature called Command Processor, which is essentially a combination of tasks and queues. More information regarding Command Processors can be found in the FreeRTOS guide.

As a result, the main-function within the implementation file main.c has changed to accommodate that. As such, the content of main.c has to be adapted

from

/* basic header files */
#include "BCDS_Basics.h"

/* additional interface header files */
#include "XdkSystemStartup.h"

/* own header files */

/* functions */

int main(void)
{
   systemStartup();
}

to

#include "stdio.h"

/* system header files */
#include <BCDS_Basics.h>
#include "BCDS_CmdProcessor.h"
#include "BCDS_Assert.h"
#include "FreeRTOS.h"
#include "task.h"
#include "HAL_UART.h"

/* additional interface header files */
#include "XdkSystemStartup.h"

/* global variables ********************************************************* */

#define TASK_PRIO_MAIN_CMD_PROCESSOR                (UINT32_C(1))
#define TASK_STACK_SIZE_MAIN_CMD_PROCESSOR          (UINT16_C(700))
#define TASK_Q_LEN_MAIN_CMD_PROCESSOR               (UINT32_C(10))

void appInitSystem(void * CmdProcessorHandle, uint32_t param2);
static CmdProcessor_T MainCmdProcessor;

int main(void)
{
    Retcode_T returnValue = Retcode_Initialize(DefaultErrorHandlingFunc);
    if (RETCODE_OK == returnValue)
    {
        returnValue = systemStartup();
    }
    if (RETCODE_OK == returnValue)
    {
        returnValue = CmdProcessor_initialize(&MainCmdProcessor,
              (char *) "MainCmdProcessor", TASK_PRIO_MAIN_CMD_PROCESSOR,
              TASK_STACK_SIZE_MAIN_CMD_PROCESSOR, TASK_Q_LEN_MAIN_CMD_PROCESSOR);
    }
    if (RETCODE_OK == returnValue)
    {
        returnValue = CmdProcessor_enqueue(&MainCmdProcessor,
              appInitSystem, &MainCmdProcessor, UINT32_C(0));
    }
    if (RETCODE_OK != returnValue)
    {
        printf("System Startup failed");
        assert(false);
    }
    vTaskStartScheduler();
}

The three definitions

#define TASK_PRIO_MAIN_CMD_PROCESSOR                (UINT32_C(1))
#define TASK_STACK_SIZE_MAIN_CMD_PROCESSOR          (UINT16_C(700))
#define TASK_Q_LEN_MAIN_CMD_PROCESSOR               (UINT32_C(10))

control how the Main Command Processor is initialized. They define the underlying task’s priority, its stack size, and how many functions can be in queue at the same time. These defintions should be changed according to the user’s requirements.

Common #

Most Platform-specific configurations have been moved to Common/config. These configurations allow for enabling/disabling certain modules and features. Some of the modules that can be configured are:

• Platform/Drivers
• Platform/Essentials
• Platform/FOTA
• Libraries/FreeRTOS
• Libraries/FATfs

See SDK/xdk110/Common in the XDK-Workbench for more information.

Essentials BSP HAL Config #

It is possible to configure which BSP modules are activated in _Common/config/Essentials/BCDS_HALConfig.h_ via #define statements

For example:

#define BCDS_FEATURE_BSP_SD_CARD            1   /* Feature for SD CARD  */
#define BCDS_FEATURE_I2C                    1     /* Feature for I2C */
#define BCDS_FEATURE_BSP_USB                1     /* Feature for USB */
#define BCDS_FEATURE_SPI                    1     /* Feature for SPI */
#define BCDS_FEATURE_BSP_LED                1     /* Feature for LED */
#define BCDS_FEATURE_BSP_BUTTON             1     /* Feature for BUTTON */

Libraries #

ServalStack #

Some portions of the API may be unavailable, if it had been disabled during compilation. API is considered disabled, if the corresponding ENABLE define is set to 0 within the header-file Serval_Defines.h. Changing the corresponding defines does not have an effect on the availability of a module currently.

• HTTP

  • (F) Custom Headers can be serialized
  • (F) Host-Header and Range-Header can now be set

• REST

  • (F) Host-Header and Range-Header can now be set
  • (C) Host-Header and Range-Header must be explicitly set to NULL if not used, otherwise they may produce random header values.

• MQTT

  • (F) added MQTT module, made available since version 3.1.0

Platform #

Module Organization #

As Modularity Improvements, some modules have been reorganized.

• Platform/Essentials now contains:
  • Basics (previously Platform/Basics)
  • Control (previously Platform/Control)
• Platform/Drivers now contains:
  • MiscDrivers (previously Platform/MiscDrivers)
  • SensorDrivers (previously Platform/SensorDrivers)
  • portable and abstract API (regardless of the type of underlying hardware)
• Platform/BSP (Board Support Package) contains software for hardware-specific drivers.
• Platform/Peripherals removed, part of BSP and Drivers now
• Platform/Power removed, power configurations are part of the respective modules, instead of general power options.
• Platform/Utils now contains the following APIs:
  • BCDS_CmdProcessor.h
  • BCDS_EventHub.h
  • BCDS_GuardedTask.h
  • BCDS_Queue.h
  • BCDS_SleepControl.h
  • BCDS_TaskMonitor.h

FOTA #

• (C) Introduced Event Driven Base implementation
• (C) Renamed FotaStateMachine_CancelDownload() to FotaStateMachine_ControlDownload()
• (C) Introduced additional parameters for the following functions:
  • FotaStateMachine_Init()
  • FotaStateMachine_GetState()
  • DownloadClient_SetupNewDownload
• (F) New function provided in validation agent to verify the integrity of the firmware

SD Card Driver #

• API Interface has been moved to Platform/Drivers
• (C) Renamed SDCardDriver_Init(void) to SDCardDriver_Initialize(void)
• (C) Removed SDCardDriver_Disconnect(void)
• (F) Added Retcode_T SDCardDriver_Deinitialize(void)
• (C) Removed SDCardDriver_Connect(void)
• (C) Changed Return-Type of SDCardDriver_GetDiskStatus(..) from Retcode_T to SDCardDriver_DiskStatus_T

WLAN Driver #

• (C) Removed WlanDriver_InterruptEnable()
• (C) Removed WlanDriver_InterruptDisable()

BLE #

• (C) The entire BLE API has been replaced by a new event-driven implementation. Please refer to the BLE Guide for more information

Utils #

• Some API from 2.0.1 Platform/Control has been moved here (see chapter Platform - Module Organization)
• (F) Added BCDS_XProtocol.h interface
• (C) The following interface files have been renamed:
  • LB2C_lb2cProtocol_ih.h to BCDS_LeanB2CAP.h
  • LOG_module_ih.h to BCDS_Logging.h
  • RB_ringBuffer_ih.h to BCDS_RingBuffer.h
  • TLV_dataHandler_ih.h to BCDS_TLV.h
• DBG_assert_ih.h has been removed.

Workbench Examples #

SendAccelerometerDataOverBle and SendAccelDataOverUdpAndBle #

Since the entire BLE API has been replaced, it is recommended that users who created a project based on one of these examples create a new one in the workbench, while only copying the user-specific code into the new project.

For most use cases, sending and receiving are the most important functionalities for BLE. As such, the following list describes, which functions handled which functionality within the respective example.

• SendAccelerometerDataOverBle

  • Sending
    • Previously: bleAccelDataTransmit(..)
    • Now: BleAccelDataTransmit(..)
  • Receiving
    • Previously: bleAlpwDataExchangeService(..)
    • Now: BleDataReceivedCallBack(..)

• SendAccelDataOverUdpAndBle

  • Sending
    • Previously: sendAccelData(..)
    • Now: SendAccelDataoverBle(..)
  • Receiving
    • Previously: bleAlpwDataExchangeService(..)
    • Now: BleDataReceivedCallBack(..)

SdCardExample #

See chapter 2.0.1 to 3.0.0 - Platform - SD Card Driver for relevant changes