This article describes how to port Link SDK for C to connect a device that integrates a microcontroller unit (MCU) and cellular module to IoT Platform.

Background information

A device that cannot be directly connected to the Internet can integrate an MCU and cellular. The MCU controls the cellular module by using AT commands. This way, the device can be connected to the Internet. You can connect the device to IoT Platform by porting Link SDK for C.

This article describes how to port Link SDK for C on the MCU development board and connect the device to IoT Platform. In this example, the device integrates a common MCU and cellular module. After you connect the device to IoT Platform, you can manage the device and analyze device data by using IoT Platform.

Connection method

Before you begin

Before you port Link SDK, you must prepare the following components.

  • Hardware:
    Hardware type Description
    MCU development board
    • Name: STM32 Nucleo board
    • Model: STM32L476RG
    • System: FreeRTOS
    • Reference: NUCLEO-L476RG
    Cellular communication board
    SIM card
    • Interface model: Micro
    • Signal: 4G
  • Development tools:
    Tool Description
    STM32CubeMX The development tool that is used to generate initialization code for MCU peripherals. Version: 6.1.2.
    MDK-Arm The development tool that is used to integrate the development environment and debugging code. Version: 5.26.2.0.
    Serial port debugger The tool that is used to connect and debug devices. Baud rate: 115,200.
  • Link SDK for C:

    Log on to the IoT Platform console . On the SDK customization page, obtain the SDK.

    Note

    You can download the sample project file to view a porting example. Then, you can port Link SDK for C to the device by referring to the configurations.

  • Device authentication information:

    Before you port Link SDK, you must create a product and device in the IoT Platform console and obtain the device authentication information. In this example, the unique-certificate-per-device authentication method is used. For more information, see Obtain information for unique-certificate-per-device authentication.

Procedure

  1. Install the hardware.
    1. Insert the SIM card into the SIM0 card slot of the cellular communication board.
    2. Connect the UART1 serial port of the MCU development board to the UART1 serial port of the cellular communication board by using Dupont lines. The following figure shows the pins.
    3. Connect the UART3 serial port of the MCU development board to the serial port of the development tool by using Dupont lines. The following figure shows the pins.
      Dupont line No. Serial port pin of the MCU development board Serial port pin of the development tool
      ① PC4 RXD
      ② PC5 TXD
      ③ GND GND

      For more information about the diagram of pins on the MCU development board, see Figure 24 on Page 35 of the STM32 Nucleo-64 boards article.

    4. Use the Micro USB interface to power on the two boards, and long press Start on the communication board.

      After the boards are powered on, the PWR light is red, the NET light flashes yellow, and the LTE light is blue.

      Power on the boards
  2. Port the project.
    1. Open CubeMX to create and generate basic project code.

      For more information about how to use the CubeMX development tool, visit the CubeMX official website.

      The following figure describes the serial port and system settings to be configured.

      Note In the following table, the baud rate of UART1 and the memory size of FREERTOS are the recommended values. You can set the values based on your business needs.
      Serial port or system Description
      UART1
      • Output: asynchronous
      • Baud rate: 230,400
      • DMA: enabled
      • Receiving interrupt: enabled
      UART3
      • Output: asynchronous
      • Baud rate: 115,200
      FREERTOS Memory size: 81,920
    2. Use MDK-Arm to open the project file and import obtained Link SDK for C to the project.
      In the SDK, except for the ./LinkSDK/demo folder, you must import all .c and .h files in other folders to the project. For more information, see Add Source Files to Project.
    3. Write code in the project to configure the underlying system dependencies.
      The dependencies are included in the aiot_sysdep_portfile_t g_aiot_sysdep_portfile global variable. For more information, see Port the SDK.

      You can download the sample project and view the ./Linkkit/portfiles/aiot_port/freertos_tcp_modem_port.c sample code file.

    4. Write code in the project to drive the cellular module.
      • Configure AT commands for adaptation: Open the ./Linkkit/portfiles/aiot_port/aiot_at_api.c file and modify the AT commands.
      • Configure serial ports for adaptation:
        • Call the aiot_at_setopt operation to configure a data sending interface for the AT module.
        • Call the aiot_at_uart_recv operation to parse AT commands after serial ports receive data.

      You can download the sample project and view the ./Linkkit/portfiles/aiot_port/linkkit_wrapper.c sample code file.

    5. Open the ./linkkit_mcu_cellular_project/LinkKit/portfiles/aiot_port/mqtt_at_basic_demo.c file and configure the device authentication information.
      The following table describes the parameters.
      Parameter Example Description
      url iot-as-mqtt.cn-shanghai.aliyuncs.com The endpoint. In this example, the public instance in the China (Shanghai) region is used.
      • If you use a public instance, replace cn-shanghai with the ID of the region where the instance resides. You can view the region in the upper-left corner of the IoT Platform console. For more information about region IDs, see Regions and zones.
      • If you use an Enterprise Edition instance, you can click View Development Configurations on the Instance Details page to view the MQTT connection information about the device.
      product_key a18wP****** The device authentication information. This parameter indicates the device certificate that is obtained when you develop the device.

      You can also view the information on the Device Details page of the IoT Platform console.

      device_name stm32l4_mbedtls_cat1
      device_secret uwMTmVAMnGGHaAkqmeDY6cHxxB******
  3. Compile and run the code.
    1. Click to compile the project file.
    2. Click the Download icon icon to download the executable sample code file to the MUC development board.
    3. Click to run the executable sample code file on the MUC development board.

Running result

  • You can view logs on the device.
    • The following log data indicates that the device is connected to IoT Platform. 
      linkkit_init[2.222][LK-0313] MQTT user calls aiot_mqtt_connect api, connect
[2.266][LK-0317] stm32l4_mbedtls_cat1&a18wP******
[2.277][LK-0318] B4C45425D73E24B2935D73C1E98B6079A630FBE03F61E2A2031CEE7867******
unknown option, 2
unknown option, 5
[2.377][LK-1000] establish mbedtls connection with server(host='a18wP******.iot-as-mqtt.cn-shanghai.aliyuncs.com', port=[443])
[7.311][LK-1000] success to establish mbedtls connection,(cost 18686 bytes in total, max used 21294 bytes)
[7.500][LK-0313] MQTT connect success in 5286 ms
    • The following log data indicates that the device time is synchronized with the server time. For more information, see NTP service. 
      AIOT_MQTTEVT_CONNECT
[7.544][LK-0309] pub: /ext/ntp/a18wP******/stm32l4_mbedtls_cat1/request
[LK-030A] > 7B 22 64 65 76 69 63 65  53 65 6E 64 54 69 6D 65 | {"deviceSendTime
[LK-030A] > 22 3A 22 37 35 33 39 22  7D                      | ":"7539"}
[7.688][LK-0309] pub: /ext/ntp/a18wP******/stm32l4_mbedtls_cat1/response
local time: 1620915828805, 2021/05/13-22:23:48:805
heartbeat response
    • The following log data indicates that the device submits Thing Specification Language (TSL) data to IoT Platform. For more information, see What is a TSL model?. 
      [1620915829.788][LK-0309] pub: /sys/a18wP******/stm32l4_mbedtls_cat1/thing/config/log/get
[LK-030A] > 7B 22 69 64 22 3A 22 31  22 2C 22 76 65 72 73 69 | {"id":"1","versi
[LK-030A] > 6F 6E 22 3A 22 31 2E 30  22 2C 22 70 61 72 61 6D | on":"1.0","param
[LK-030A] > 73 22 3A 7B 22 67 65 74  54 79 70 65 22 3A 22 63 | s":{"getType":"c
[LK-030A] > 6F 6E 74 65 6E 74 22 2C  22 63 6F 6E 66 69 67 53 | ontent","configS
[LK-030A] > 63 6F 70 65 22 3A 22 64  65 76 69 63 65 22 7D 7D | cope":"device"}}
[1620915830.011][LK-0309] pub: /sys/a18wP******/stm32l4_mbedtls_cat1/thing/config/log/get_reply
[1620915830.033][LK-1507] LOGPOST user log config arrived
log switch state is: 1
[1620915835.066][LK-0309] pub: /sys/a18wP******/stm32l4_mbedtls_cat1/thing/log/post
[LK-030A] > 7B 22 69 64 22 3A 22 32  22 2C 22 76 65 72 73 69 | {"id":"2","versi
[LK-030A] > 6F 6E 22 3A 22 31 2E 30  22 2C 22 70 61 72 61 6D | on":"1.0","param
[LK-030A] > 73 22 3A 5B 7B 22 75 74  63 54 69 6D 65 22 3A 22 | s":[{"utcTime":"
[LK-030A] > 32 30 32 31 2F 35 2F 31  33 20 32 32 3A 32 33 3A | 2021/5/13 22:23:
[LK-030A] > 35 35 22 2C 22 6C 6F 67  4C 65 76 65 6C 22 3A 22 | 55","logLevel":"
[LK-030A] > 44 45 42 55 47 22 2C 22  6D 6F 64 75 6C 65 22 3A | DEBUG","module":
[LK-030A] > 22 41 50 50 22 2C 22 63  6F 64 65 22 3A 22 32 30 | "APP","code":"20
[LK-030A] > 30 22 2C 22 74 72 61 63  65 43 6F 6E 74 65 78 74 | 0","traceContext
[LK-030A] > 22 3A 22 30 22 2C 22 6C  6F 67 43 6F 6E 74 65 6E | ":"0","logConten
[LK-030A] > 74 22 3A 22 6C 6F 67 20  69 6E 20 77 68 69 6C 65 | t":"log in while
[LK-030A] > 28 31 29 22 7D 5D 7D                             | (1)"}]}
[1620915836.855][LK-0309] pub: /sys/a18wP******/stm32l4_mbedtls_cat1/thing/event/property/post
[LK-030A] > 7B 22 69 64 22 3A 22 33  22 2C 22 76 65 72 73 69 | {"id":"3","versi
[LK-030A] > 6F 6E 22 3A 22 31 2E 30  22 2C 22 70 61 72 61 6D | on":"1.0","param
[LK-030A] > 73 22 3A 7B 22 4C 69 67  68 74 53 77 69 74 63 68 | s":{"LightSwitch
[LK-030A] > 22 3A 20 30 7D 2C 22 73  79 73 22 3A 7B 22 61 63 | ": 0},"sys":{"ac
[LK-030A] > 6B 22 3A 31 7D 7D                                | k":1}}
[1620915837.099][LK-0309] pub: /sys/a18wP******/stm32l4_mbedtls_cat1/thing/event/Error/post
[1620915837.122][LK-0309] pub: /sys/a18wP******/stm32l4_mbedtls_cat1/thing/event/property/post_reply
[1620915837.177][LK-0A08] DM recv generic reply
demo_dm_recv_handler, type = 0
msg_id = 3, code = 200, data = {}, message = success
[1620915837.311][LK-0309] pub: /sys/a18wP******/stm32l4_mbedtls_cat1/thing/event/Error/post_reply
[1620915837.344][LK-0A08] DM recv generic reply
demo_dm_recv_handler, type = 0
msg_id = 4, code = 200, data = {}, message = success

  • You can log on to the IoT Platform console to view the device status and operation logs.

    • In the left-side navigation pane, choose Devices > Devices. Then, find the device and view the online status. The value Online in the State column indicates that the device is connected to IoT Platform.
    • In the left-side navigation pane, choose Maintenance > Device Log. Select a product to view device logs.