Version history

V3.0.1

V3.0.1 was released in March 2019. It includes the following changes from V2.3.0, which was released in November 2018.

Added support for source code porting

• Supports development on hosts that run 64-bit Ubuntu 16.04, Windows XP, Windows 7, or Windows 10.

• You can select features by running the make menuconfig command on Ubuntu or by running the config.bat script on Windows.

• After you select the features, you can extract the required source files by running the extract.sh command on Ubuntu or by running the extract.bat script on Windows.

• You can then add these source files to your project and compile them on any host using your preferred method.

All Hardware Abstraction Layer (HAL) function interfaces that require implementation are automatically consolidated into a single file at output/eng/wrappers/wrapper.c. You must implement these functions.

This enhancement resolves the issue that prevented users from cross-compiling the SDK, which significantly improves the portability and usability of the SDK.

*Note: The original compilation system and usage methods are still available. For more information, see *GNU Make-based compilation system.

Directory structure

• To improve usability, the V3.0.1 SDK uses a flat directory structure for its source code. For example, the src/mqtt folder contains all header and source files for the MQTT cloud connection feature. All src/xxxx directories are self-contained.

• The arrangement of all source files corresponds one-to-one with the SDK features. Except for the basic src/infra directory, each src/xxx directory now corresponds to a specific SDK feature. The number of src/xxx directories equals the number of features. For example:

  • src/dynamic_register: Contains all source files related to one-type-one-secret dynamic registration.

  • src/dev_sign: Contains all source files related to device signing.

  • src/mqtt: Contains all source files related to MQTT cloud connection.

  • src/ota: Contains all source files related to OTA firmware download.

  • src/dev_model: Stores the source files for Thing Specification Language model management and sub-device management.

Presentation of API and HAL interfaces

Previously, the SDK had only two global header files: iot_import.h and iot_export.h. These files listed the underlying HAL_XXX() interfaces required by the SDK and the user-facing IOT_XXX() APIs provided by the SDK.

We received feedback from some users who felt overwhelmed. They mistakenly believed they had to implement all 100+ HAL interfaces listed in iot_import.h and learn all 200+ APIs listed in iot_export.h.

Therefore, we removed this design.

• The SDK no longer has monolithic iot_import.h and iot_export.h files.

• The top-level include directory has also been removed.

• Instead, source files are organized into directories by feature. This design ensures that you only see code relevant to your needs.

Now

• When you use the V3.0.1 SDK, you first identify the available features, such as MQTT cloud connection and OTA download. Then, you can select and configure the required features using a graphical interface.

• Next, you can use the extraction tool (extract.sh script on Ubuntu or extract.bat on Windows) to obtain the source files for these features in the output directory.

• You can then use the SDK. All external SDK interfaces follow the design principles described below.

  • output/eng/xxx contains the files for the xxx feature. These files are sourced from src/xxx.

  • output/eng/xxx/xxx_api.h contains the user-facing APIs for the xxx feature. These files are sourced from src/xxx/xxx_api.h.

  • output/eng/wrappers/wrapper.c is an automatically generated file that lists all the underlying HAL_XXX() interfaces you must implement for your target embedded platform.

• In other words:

  • You only need to check src/xxx/xxx_api.h or output/eng/xxx/xxx_api.h for the features you need. This prevents you from seeing declarations for APIs you do not use.

  • All functions that you must implement are listed in output/eng/wrappers/wrapper.c. Functions that do not require implementation are not included. This prevents you from seeing definitions for HAL interfaces you do not need.

For example, in the simplest scenario, you may only need the SDK's ability to calculate signatures for MQTT cloud connections. This feature is provided by the src/dev_sign or output/eng/dev_sign directory.

• You will see only one API, which is listed in dev_sign_api.h.

• You will not see any HAL interfaces or even the wrapper.c file because this feature has no dependencies and can be used without implementing any C functions.

make.settings file

• Developers who use hosts that run Windows XP, Windows 7, or Windows 10 can now use the config.bat tool to graphically configure features, which removes the need for a Linux host.

• The names of the FEATURE_XXX options have been changed.

• Added the following options:

  • FEATURE_AWSS_SUPPORT_SMARTCONFIG_WPS: Peer-to-peer mode for Wi-Fi provisioning.

  • FEATURE_AWSS_SUPPORT_DEV_AP: Device hot spot mode for Wi-Fi provisioning.

MQTT function interfaces

• The IOT_SetupConnInfo() function is no longer required. To establish an MQTT connection, you only need to use the IOT_MQTT_Construct() function.

• You are no longer required to prepare input parameters. When you call IOT_MQTT_Construct(), you can leave most connection parameters empty. The SDK automatically populates the default values instead of returning an error.

New features and interfaces

• The device signing feature has been added. This is the simplest form of the SDK.

  • This feature has only one API: IOT_Sign_MQTT().

  • For more information, see Device Signing Developer Guide.

• The one-type-one-secret feature has been added. This feature is for scenarios where you do not need to burn a unique device certificate (ProductKey, DeviceName, and DeviceSecret) for each device.

  • This feature has only one API: IOT_Dynamic_Register().

  • For more information, see One-Type-One-Secret Developer Guide.

• The device reset feature has been added. This feature can be used in scenarios where a device notifies the cloud to unbind it, or to unbind a sub-device from a gateway.

  • This feature has only one API: IOT_DevReset_Report().

  • For more information, see Device Reset Developer Guide.

• The HTTP/2 file upload feature has been added. This feature can be used to stream large file uploads to the cloud.

  • This feature has three APIs: IOT_HTTP2_UploadFile_Connect(), IOT_HTTP2_UploadFile_Request(), and IOT_HTTP2_UploadFile_Disconnect().

  • For more information, see HTTP/2 File Upload Developer Guide.

Removed features

• Support for the cmake-based compilation method has been removed because you can now use source file porting or GNU Make porting.

V2.3.0

V2.3.0 was released in November 2018. It includes the following changes from V2.2.1, which was released on August 31, 2018.

make.settings file

• Developers who use a 64-bit host that runs Ubuntu 16.04 can use the make menuconfig command to graphically edit the make.settings file.

• The names of the FEATURE_XXX options have been changed.

• Added the following options:

  • FEATURE_DEVICE_BIND_ENABLED: Enables or disables the device binding feature. This option is required only for customers who connect to the Feiyan platform. It is used to enable device control through the public app.

  • FEATURE_ALCS_CLIENT_ENABLED: Enables or disables the client component of the local communication feature. This option is required only for devices that need to control other IoT devices, such as edge gateways.

  • FEATURE_ALCS_SERVER_ENABLED: Enables or disables the server-side component of the local communication feature. This option must be enabled for devices that need to accept control from a mobile app or an edge gateway over a local area network.

  • FEATURE_AWSS_SUPPORT_SMARTCONFIG: One-click mode for Wi-Fi provisioning.

  • FEATURE_AWSS_SUPPORT_ZEROCONFIG: Zero-configuration mode for Wi-Fi provisioning.

  • FEATURE_AWSS_SUPPORT_ROUTER: Router mode for Wi-Fi provisioning.

  • FEATURE_AWSS_SUPPORT_PHONEASAP: Mobile hot spot mode for Wi-Fi provisioning.

• Removed the following option:

  • FEATURE_COAP_DTLS_SUPPORT: Specifies whether to encrypt CoAP cloud connections using Datagram Transport Layer Security (DTLS). This option is removed because encryption is now always enabled and no longer requires user configuration.

Global function interfaces

• IOT_OpenLog() and IOT_CloseLog() have been removed. You can now use IOT_SetLogLevel() to control the level of detail for SDK log printing or to disable it.

• The IOT_LOG_EMERG log level has been removed. It is replaced by IOT_LOG_NONE, which is used with IOT_SetLogLevel(IOT_LOG_NONE) to disable the logging feature.

• IOT_Linkkit_Ioctl() has been removed. Its functionality is merged into IOT_Ioctl(). For all parameter options, see the iotx_ioctl_option_t enumeration definition.

• IOT_Ioctl() has been enhanced. The new options IOTX_IOCTL_SET_MQTT_DOMAIN and IOTX_IOCTL_SET_HTTP_DOMAIN allow you to pass custom MQTT or HTTP domain names for connections. This is used for new sites outside China.

MQTT function interfaces

• In both the original Basic Edition interfaces and the new interfaces, you can pass NULL as the handle parameter. This indicates that you want to create a connection with default parameters or use the default connection. This applies to the following interfaces:

  • IOT_MQTT_Construct

  • IOT_MQTT_Destroy

  • IOT_MQTT_Yield

  • IOT_MQTT_LogPost

  • IOT_MQTT_CheckStateNormal

  • IOT_MQTT_Subscribe

  • IOT_MQTT_Unsubscribe

  • IOT_MQTT_Publish

  • IOT_MQTT_Subscribe_Sync

  • IOT_MQTT_Publish_Simple

• The pwrite_buf and pread_buf members have been removed from the iotx_mqtt_param_t struct.

• The IOT_MQTT_Publish_Simple() interface has been added. You can use this interface to pass the topic and payload as string parameters.

  int IOT_MQTT_Publish_Simple(void *handle, const char *topic_name, int qos, void *data, int len);
                      

• The IOT_MQTT_Subscribe_Sync() interface has been added. You can use this interface to perform a blocking, synchronous subscription. The function does not return until the subscription is successful.

  int IOT_MQTT_Subscribe_Sync(void *handle,
                              const char *topic_filter,
                              iotx_mqtt_qos_t qos,
                              iotx_mqtt_event_handle_func_fpt topic_handle_func,
                              void *pcontext,
                              int timeout_ms);
                      

• The IOT_MQTT_Subscribe() interface has been optimized. You can now perform an offline subscription before the MQTT connection is established. The C-SDK sends the subscription message immediately after the connection is successfully established.

OTA function interfaces

• Because you can pass NULL as the handle parameter of MQTT function interfaces, you can also pass NULL as the third parameter of the Basic Edition OTA function interface IOT_OTA_Init. This indicates that you want to use the default connection.

  void *IOT_OTA_Init(const char *product_key, const char *device_name, void *ch_signal);
                      

Linkkit function interfaces

For more information, see API reference.

Removed interfaces

The legacy linkkit_xxx() and linkkit_gateway_xxx() interfaces are now optional at compile-time and are disabled by default.

Note: You can still enable the legacy Linkkit interfaces by adding the following statement to the make.settings file. When you do this, the new interfaces are hidden and the legacy interfaces are used instead.

FEATURE_DEPRECATED_LINKKIT=y
            

Note: To reduce memory consumption on the device, the SDK no longer checks the correctness of the data format when you call an SDK API to upload property or event notifications to the cloud. Therefore, you are no longer required to export the TSL JSON file from the cloud, convert it to a C string, and then include it in your C code.

HAL function interfaces

• HAL_Sys_reboot has been removed because it was a duplicate of the existing HAL_Reboot interface.