IoT Platform:Example on how to port Link SDK for C

Prerequisites

The SDK is obtained. For more information, see Obtain Link SDK for C.

Architecture

Link SDK for C supports different operating systems or hardware platforms. Link SDK for C encapsulates system-related API operations to interact with operating systems or hardware platforms. When you develop a product, you must call the API operations in the SDK to implement business logic. You must also write code to define system-related API operations.

Description of system-related API operations

• System-related API operations decouple Link SDK for C from operating systems. You can call the operations to interact with different operating systems.

• The prototype definition of system-related API operations is aiot_sysdep_portfile_t. You must define a global variable named g_aiot_sysdep_portfile. The global variable is implemented by an API operation of the destination operating system to port the SDK.

• Common operations and mutex-related operations are easy to use. This topic does not describe how to call the operations. When you port the SDK, you must define all system-related API operations. You cannot specify NULL when you define the operations. Otherwise, errors occur.

List of system-related API operations

Configure parameters for a network operation

When you port Link SDK for C, you must configure the parameters for the core_sysdep_network_setopt operation.

• The following table describes the parameters that specify the socket-based network types. You can configure the parameters to establish TCP and UDP connections.

  Parameter	Description
  CORE_SYSDEP_SOCKET_TCP_CLIENT	The TCP client that supports the MQTT, HTTP, HTTP2, and WebSocket protocols. If you want to use the preceding features, you must configure the parameter.
  CORE_SYSDEP_SOCKET_UDP_CLIENT	The UDP client. If you want to establish a CoAP connection, you must configure the parameter.

• The following table describes the parameters that are required to establish connections.

  Parameter	Description
  CORE_SYSDEP_NETWORK_SOCKET_TYPE	The type of the socket that you want to create. Data type: (core_sysdep_socket_type_t *).
  CORE_SYSDEP_NETWORK_HOST	The domain name or IP address that is used to establish the connection. The memory is shared by the upper-layer modules. Data type: (char *)
  CORE_SYSDEP_NETWORK_BACKUP_IP	The backup IP address that is used if the DNS resolution fails. You do not need to specify this parameter.
  CORE_SYSDEP_NETWORK_PORT	The port number that is used to establish the connection. Data type: (uint16_t *)
  CORE_SYSDEP_NETWORK_CONNECT_TIMEOUT_MS	The timeout period to establish a connection. Data type: (uint32_t *)
  CORE_SYSDEP_NETWORK_MAX	This parameter is not used by Link SDK for C. You do not need to configure the parameter.

Sample code

The sample code is based on the POSIX standard. When you download Link SDK for C, set Device OS to POSIX Compliant on the SDK customization page. Link SDK for C provides sample code in the portfile/aiot_port/posix_port.c file. The sample code shows how to port the SDK based on the POSIX standard.

Verify the result

After you port Link SDK for C, perform the following steps to check whether the API operations of Link SDK for C work as expected:

1. Open the ./LinkSDK/demos/sysdep_api_test_demo.cfile and perform the following operations:

   1. Define a function to create tasks.

      Validate the concurrency capability. You must create a task in the destination system to which the SDK is ported.

   2. Specify the maximum size of a heap.

      This item is used to check whether heaps can be used by the SDK as expected.

   Sample code

   /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> TODO START >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
   /*
    * TODO: Call the function to create and execute a task. The function automatically exists after the task ends.
    * @param[in] entry  The beginning of the function.
    * @param[in] argv   The parameters of the function.
    */
   #include<pthread.h>
   void task_start(TASK_FUNC entry,void* argv)
   {
       pthread_t id;
       pthread_create(&id, NULL, (void*(*)(void *))entry, argv);
   }
   /*TODO: The maximum size of a heap. Unit: bytes. */
   #define HEAP_MAX    ( 20 * 1024 )
   /*<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< TODO END <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<*/

2. Compile and run a demo file named sysdep_api_test_demo.c.

3. View the result.

   • Successful

     If the following logs appear, the API operations of Link SDK for C that is ported work as expected.

     Line[804]: TOTAL TEST START
     Line[806]: TEST [1/5] [RANDOM_TEST ] .....................................[START]
     Line[812]: TEST [1/5] [RANDOM_TEST ] .....................................[SUCCESS]
     Line[806]: TEST [2/5] [HEAP_TEST   ] .....................................[START]
     Line[812]: TEST [2/5] [HEAP_TEST   ] .....................................[SUCCESS]
     Line[806]: TEST [3/5] [TIME_TEST   ] .....................................[START]
     Line[519]: sleep 30000 ms test
     Line[499]: sleep_test_task_1 enter wanna sleep: 10000ms
     Line[499]: sleep_test_task_2 enter wanna sleep: 10000ms
     Line[595]: sleep 10000ms start:[1642324352748] stop:[1642324362748] expected 
     Line[812]: TEST [3/5] [TIME_TEST   ] .....................................[SUCCESS]
     Line[806]: TEST [4/5] [NETWORK_TEST] .....................................[START]
     Line[372]: [NETWORK_TEST.RECV] test success
     Line[812]: TEST [4/5] [NETWORK_TEST] .....................................[SUCCESS]
     Line[806]: TEST [5/5] [MUTEX_TEST  ] .....................................[START]
     Line[692]: mutex lock task1, unlock task2 3000 ms
     Line[703]: task1 value [30 --> 30], task2 value [30 --> 60] 
     Line[715]: unlock task1, lock task2 3000 ms
     Line[725]: task1 value [30 --> 60], task2 value [60 --> 60] 
     Line[736]: unlock task1, lock task2 3000 ms
     Line[742]: task1 value [60 --> 90], task2 value [60 --> 90]
     Line[812]: TEST [5/5] [MUTEX_TEST  ] .....................................[SUCCESS]
     Line[816]: TOTAL TEST SUCCESS

   • Failed

     If the file cannot be run to the last line or an error message appears after the last line is run, troubleshoot the issue based on the following table.

     Error code	Description	Related API operations
     TEST_ERR_RANDOM	An exception occurred when the system tested the function that was called to generate random numbers.	core_sysdep_rand
     TEST_ERR_MALLOC	An exception occurred when the system tested the memory application feature.	core_sysdep_malloc
     TEST_ERR_HEAP	An exception occurred when the system tested the memory application and release features.	core_sysdep_malloc core_sysdep_free
     TEST_ERR_SLEEP	An exception occurred when the system tested the hibernation or system time feature.	core_sysdep_time core_sysdep_sleep
     TEST_ERR_MUTEX	An exception occurred when the system tested the mutex feature.	core_sysdep_mutex_init core_sysdep_mutex_lock core_sysdep_mutex_unlock core_sysdep_mutex_deinit
     TEST_ERR_NETWORK	An exception occurred when the system tested the network feature.	core_sysdep_network_init core_sysdep_network_setopt core_sysdep_network_establish core_sysdep_network_recv core_sysdep_network_send core_sysdep_network_deinit
     TEST_ERR_GENERIC	An unknown error occurred.	None