Port Link SDK for C

Prerequisites

You have obtained the SDK. Obtain Link SDK for C.

Architecture

Link SDK for C abstracts all OS and hardware interactions into system-dependent API operations. To use the SDK, you must call its API operations for business logic and implement the system-dependent operations for your target platform.

About system-dependent API operations

• System-dependent API operations decouple Link SDK for C from operating systems, enabling cross-platform portability.

• The prototype is defined in aiot_sysdep_portfile_t. You must define a global variable named g_aiot_sysdep_portfile, implemented with the target OS operations.

• You must define all system-dependent API operations when porting. Do not set any operation to NULL, or runtime errors will occur.

System-dependent API operations

Network operation parameters

Configure the following parameters for the core_sysdep_network_setopt operation when porting Link SDK for C.

• Socket-based network type parameters for TCP and UDP connections:

  Parameter	Description
  CORE_SYSDEP_SOCKET_TCP_CLIENT	TCP client supporting MQTT, HTTP, HTTP2, and WebSocket. Required for these protocols.
  CORE_SYSDEP_SOCKET_UDP_CLIENT	UDP client. Required for CoAP connections.

• Connection parameters:

  Parameter	Description
  CORE_SYSDEP_NETWORK_SOCKET_TYPE	Socket type to create. Data type: (core_sysdep_socket_type_t *).
  CORE_SYSDEP_NETWORK_HOST	Domain name or IP address for the connection. Memory is shared by upper-layer modules. Data type: (char *)
  CORE_SYSDEP_NETWORK_BACKUP_IP	Backup IP address used if DNS resolution fails. Optional.
  CORE_SYSDEP_NETWORK_PORT	Port number for the connection. Data type: (uint16_t *)
  CORE_SYSDEP_NETWORK_CONNECT_TIMEOUT_MS	Connection timeout period. Data type: (uint32_t *)
  CORE_SYSDEP_NETWORK_MAX	Not used by Link SDK for C. No configuration needed.

Sample code

The sample code uses the POSIX standard. When downloading Link SDK for C, set Device OS to POSIX Compliant on the SDK customization page. The SDK provides sample code in portfile/aiot_port/posix_port.c.

Verify the porting result

After porting Link SDK for C, verify that the system-dependent API operations work correctly:

1. Open ./LinkSDK/demos/sysdep_api_test_demo.c and complete the following configurations:

   1. Define a function to create tasks.

      This validates concurrency. Create a task function for the target OS.

   2. Specify the maximum size of a heap.

      This verifies that heap allocation works correctly for the SDK.

   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 sysdep_api_test_demo.c.

3. View the result.

   • Successful

     If the following logs appear, all ported API operations work correctly.

     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 demo fails to complete or reports an error, troubleshoot using the following table.

     Error code	Description	Related API operations
     TEST_ERR_RANDOM	Random number generation failed.	core_sysdep_rand
     TEST_ERR_MALLOC	Memory allocation failed.	core_sysdep_malloc
     TEST_ERR_HEAP	Memory allocation and release failed.	core_sysdep_malloc core_sysdep_free
     TEST_ERR_SLEEP	Hibernation or system time operation failed.	core_sysdep_time core_sysdep_sleep
     TEST_ERR_MUTEX	Mutex operation failed.	core_sysdep_mutex_init core_sysdep_mutex_lock core_sysdep_mutex_unlock core_sysdep_mutex_deinit
     TEST_ERR_NETWORK	Network operation failed.	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	Unknown error.	None