Overview

This page summarizes the core APIs used by every tutorial on this site from the Ai-WB2 SDK (Ai-Thinker-Open/Ai-Thinker-WB2, version release_bl_iot_sdk_1.6.40), organized by function. Each card gives the function signature and a one-line description.

In plain words: the SDK is like a box of building blocks, and an API is each block's "interface manual" — want to know "how to light an LED" or "how to connect to Wi-Fi"? Come here, find the function name by category, then click the "Related Tutorial" to see its full usage.

🎯Page GoalSummarize the SDK's commonly used APIs by category, to quickly look up function names, parameters and their source tutorials.

📚How to UseEach category lists the function signature and a one-line description, with a "Related Tutorial" link at the end — click it to see the complete example code for that API.

🔗More APIsFor low-level interfaces not listed here, see the official SDK source headers (the `include` directory of each module under `components/`); this site only covers the interfaces used in its tutorials.

---

System & Kernel (FreeRTOS)

📂 Task Management (task.h)

xTaskCreate(pxTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask)

Creates a task and adds it to the ready queue for the scheduler to run by priority (the most common task-creation function).

xTaskCreateStatic(pxTaskCode, pcName, ulStackDepth, pvParameters, uxPriority, puxStackBuffer, pxTaskBuffer)

Creates a task using static memory (no heap allocation); for heap-less or memory-constrained systems.

xTaskCreateRestricted(pxTaskDefinition, pxCreatedTask)

Creates a task with MPU memory protection (for safety-critical systems).

xTaskCreateRestrictedStatic(pxTaskDefinition, pxCreatedTask)

Creates a task with MPU memory protection (static-memory version).

vTaskAllocateMPURegions(xTask, pxRegions)

Allocates MPU memory regions for a restricted task.

vTaskDelete(xTaskToDelete)

Deletes a task; a task deleting itself stops running (takes effect immediately).

vTaskDelay(xTicksToDelay)

Suspends the current task for the given ticks, yielding the CPU to other tasks (the most common delay).

vTaskDelayUntil(pxPreviousWakeTime, xTimeIncrement)

Delays by an absolute time, unaffected by task execution duration; ideal for precise periodic loops.

xTaskAbortDelay(xTask)

Aborts a task's delay, making it run again immediately.

uxTaskPriorityGet(xTask)

Gets a task's priority.

uxTaskPriorityGetFromISR(xTask)

Gets a task's priority from an ISR (ISR-safe).

eTaskGetState(xTask)

Gets a task's state (running/ready/blocked/suspended).

vTaskGetInfo(xTask, pxTaskStatus, xGetFreeStackSpace, eState)

Gets detailed task info (name, priority, stack high-water mark, etc.).

vTaskPrioritySet(xTask, uxNewPriority)

Sets a task's priority.

vTaskSuspend(xTaskToSuspend)

Suspends a task; it stops running until resumed by vTaskResume.

vTaskResume(xTaskToResume)

Resumes a suspended task.

xTaskResumeFromISR(xTaskToResume)

Resumes a task from an ISR (ISR-safe).

vTaskStartScheduler()

Starts the scheduler and begins task scheduling (does not return from main).

vTaskEndScheduler()

Stops the scheduler (debug use only).

vTaskSuspendAll()

Suspends the scheduler (disables task switching, like entering a critical section).

xTaskResumeAll()

Resumes a suspended scheduler.

xTaskGetTickCount()

Gets the system's current tick count (system uptime).

xTaskGetTickCount2(ticks, overflow)

Gets the tick count and whether it has overflowed.

xTaskGetTickCountFromISR()

Gets the tick count from an ISR (ISR-safe).

uxTaskGetNumberOfTasks()

Gets the total number of tasks in the system.

pcTaskGetName(xTaskToQuery)

Gets a task's name from its handle.

xTaskGetHandle(pcNameToQuery)

Gets a task's handle from its name.

uxTaskGetStackHighWaterMark(xTask)

Gets the minimum remaining stack space (stack-overflow checking).

uxTaskGetStackHighWaterMark2(xTask)

High-precision stack high-water mark (supports larger stacks).

vTaskSetApplicationTaskTag(xTask, pxHookFunction)

Sets a task's application tag (for hooking functions).

xTaskGetApplicationTaskTag(xTask)

Gets a task's application tag.

xTaskGetApplicationTaskTagFromISR(xTask)

Gets a task's application tag from an ISR.

vTaskSetThreadLocalStoragePointer(xTaskToSet, xIndex, pvValue)

Sets a task's thread-local storage pointer.

pvTaskGetThreadLocalStoragePointer(xTaskToQuery, xIndex)

Gets a task's thread-local storage pointer.

xTaskCallApplicationTaskHook(xTask, pvParameter)

Calls a task's registered application hook.

xTaskGetIdleTaskHandle()

Gets the idle task's handle.

uxTaskGetSystemState(pxTaskStatusArray, uxArraySize, pulTotalRunTime)

Gets a snapshot of all tasks' states (debug use).

vTaskList(pcWriteBuffer)

Prints all tasks' info into a string (debug use).

vTaskGetRunTimeStats(pcWriteBuffer)

Prints each task's run-time statistics (debug use).

xTaskGetIdleRunTimeCounter()

Gets the idle task's accumulated run time.

xTaskGenericNotify(xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue)

Sends a notification (value + action) to a task, waking it if waiting.

xTaskGenericNotifyFromISR(xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken)

Sends a task notification from an ISR (ISR-safe).

xTaskNotifyWait(ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait)

Blocks waiting for a task notification, with optional timeout.

vTaskNotifyGiveFromISR(xTaskToNotify, pxHigherPriorityTaskWoken)

Gives a task notification from an ISR (increments the counter).

ulTaskNotifyTake(xClearCountOnExit, xTicksToWait)

Waits for and consumes a task notification (counting style, optional timeout).

xTaskNotifyStateClear(xTask)

Clears a task's notification state.

xTaskIncrementTick()

Increments the system tick (internal kernel API; do not call directly).

vTaskPlaceOnEventList(pxEventList, xTicksToWait)

Places a task on the event waiting list (internal kernel API).

vTaskPlaceOnUnorderedEventList(pxEventList, xItemValue, xTicksToWait)

Places a task on an unordered event list (internal kernel API).

vTaskPlaceOnEventListRestricted(pxEventList, xTicksToWait, xWaitIndefinitely)

Restricted event-list placement (internal kernel API).

xTaskRemoveFromEventList(pxEventList)

Removes a task from the event list (internal kernel API).

vTaskRemoveFromUnorderedEventList(pxEventListItem, xItemValue)

Removes a task from an unordered event list (internal kernel API).

vTaskSwitchContext()

Task context switch (internal kernel API).

uxTaskResetEventItemValue()

Resets a task event item's value (internal kernel API).

xTaskGetCurrentTaskHandle()

Gets the currently running task's handle.

vTaskSetTimeOutState(pxTimeOut)

Sets timeout state (internal kernel API).

xTaskCheckForTimeOut(pxTimeOut, pxTicksToWait)

Checks whether a timeout has occurred (internal kernel API).

vTaskMissedYield()

Marks a missed task switch (internal kernel API).

xTaskGetSchedulerState()

Gets the scheduler state (running/suspended).

xTaskPriorityInherit(pxMutexHolder)

Priority inheritance (internal kernel API).

xTaskPriorityDisinherit(pxMutexHolder)

Releases priority inheritance (internal kernel API).

vTaskPriorityDisinheritAfterTimeout(pxMutexHolder, uxHighestPriorityWaitingTask)

Releases priority inheritance after timeout (internal kernel API).

uxTaskGetTaskNumber(xTask)

Gets a task's number (user-defined).

vTaskSetTaskNumber(xTask, uxHandle)

Sets a task's number (user-defined).

vTaskStepTick(xTicksToJump)

Steps the tick forward for low-power tickless mode (internal kernel API).

vTaskStepTickSafe(xTicksToJump)

Safe tick-forward version (internal kernel API).

eTaskConfirmSleepModeStatus()

Confirms whether the system may sleep (internal kernel API).

pvTaskIncrementMutexHeldCount()

Increments the mutex-held count (internal kernel API).

vTaskInternalSetTimeOutState(pxTimeOut)

Sets internal timeout state (internal kernel API).

xTaskNotify(pxTask, ulValue, eAction)

Sends a notification (value + action) to a task; the most common task-notification macro.

xTaskNotifyFromISR(pxTask, ulValue, eAction, pxHigherPriorityTaskWoken)

Sends a task notification from an ISR (ISR-safe).

xTaskNotifyGive(pxTask)

Gives a task a notification (increments the counter; no extra args).

xTaskNotifyAndQuery(pxTask, ulValue, eAction, pxPreviousNotificationValue)

Sends a notification and reads the task's previous value.

xTaskNotifyAndQueryFromISR(pxTask, ulValue, eAction, pxPreviousNotificationValue, pxHigherPriorityTaskWoken)

Sends a notification from an ISR and reads the previous value.

📂 Queues (queue.h)

xQueueGenericSend(xQueue, pvItemToQueue, xTicksToWait, xCopyPosition)

Low-level queue-send implementation (basis of xQueueSend and friends).

xQueuePeek(xQueue, pvBuffer, xTicksToWait)

Peeks the front item without removing it.

xQueuePeekFromISR(xQueue, pvBuffer)

Peeks the front item from an ISR (ISR-safe).

xQueueReceive(xQueue, pvBuffer, xTicksToWait)

Receives data from a queue with optional timeout (the most common receive).

uxQueueMessagesWaiting(xQueue)

Gets the number of messages waiting in the queue.

uxQueueSpacesAvailable(xQueue)

Gets the number of free slots in the queue.

vQueueDelete(xQueue)

Deletes a queue and frees its resources.

xQueueGenericSendFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken, xCopyPosition)

Sends data from an ISR (basis of xQueueSendFromISR).

xQueueGiveFromISR(xQueue, pxHigherPriorityTaskWoken)

Gives a semaphore from an ISR (basis of xSemaphoreGiveFromISR).

xQueueReceiveFromISR(xQueue, pvBuffer, pxHigherPriorityTaskWoken)

Receives data from an ISR (basis of xQueueReceiveFromISR).

xQueueIsQueueEmptyFromISR(xQueue)

Checks whether the queue is empty from an ISR.

xQueueIsQueueFullFromISR(xQueue)

Checks whether the queue is full from an ISR.

uxQueueMessagesWaitingFromISR(xQueue)

Queries the message count from an ISR.

xQueueCRSendFromISR(xQueue, pvItemToQueue, xCoRoutinePreviouslyWoken)

Co-routine send (deprecated; old code only).

xQueueCRReceiveFromISR(xQueue, pvBuffer, pxTaskWoken)

Co-routine receive (deprecated; old code only).

xQueueCRSend(xQueue, pvItemToQueue, xTicksToWait)

Co-routine send (deprecated; old code only).

xQueueCRReceive(xQueue, pvBuffer, xTicksToWait)

Co-routine receive (deprecated; old code only).

xQueueCreateMutex(ucQueueType)

Creates a mutex (basis of xSemaphoreCreateMutex).

xQueueCreateMutexStatic(ucQueueType, pxStaticQueue)

Creates a mutex (static-memory version).

xQueueCreateCountingSemaphore(uxMaxCount, uxInitialCount)

Creates a counting semaphore (basis of xSemaphoreCreateCounting).

xQueueCreateCountingSemaphoreStatic(uxMaxCount, uxInitialCount, pxStaticQueue)

Creates a counting semaphore (static-memory version).

xQueueSemaphoreTake(xQueue, xTicksToWait)

Takes a semaphore (basis of xSemaphoreTake).

xQueueGetMutexHolder(xSemaphore)

Gets the task holding the mutex.

xQueueGetMutexHolderFromISR(xSemaphore)

Gets the mutex holder from an ISR.

xQueueTakeMutexRecursive(xMutex, xTicksToWait)

Recursively takes a mutex (basis of xSemaphoreTakeRecursive).

xQueueGiveMutexRecursive(xMutex)

Recursively gives a mutex (basis of xSemaphoreGiveRecursive).

vQueueAddToRegistry(xQueue, pcQueueName)

Registers a queue in the queue registry (debug use).

vQueueUnregisterQueue(xQueue)

Unregisters a queue from the registry.

pcQueueGetName(xQueue)

Gets a queue's registered name.

xQueueGenericCreate(uxQueueLength, uxItemSize, ucQueueType)

Low-level queue creation (basis of xQueueCreate).

xQueueGenericCreateStatic(uxQueueLength, uxItemSize, pucQueueStorage, pxStaticQueue, ucQueueType)

Low-level queue creation (static-memory version).

xQueueCreateSet(uxEventQueueLength)

Creates a queue set (wait on multiple queues/semaphores at once).

xQueueAddToSet(xQueueOrSemaphore, xQueueSet)

Adds a queue or semaphore to a queue set.

xQueueRemoveFromSet(xQueueOrSemaphore, xQueueSet)

Removes a queue or semaphore from a queue set.

xQueueSelectFromSet(xQueueSet, xTicksToWait)

Selects an available queue from a queue set (optional timeout).

xQueueSelectFromSetFromISR(xQueueSet)

Selects from a queue set from an ISR (ISR-safe).

vQueueWaitForMessageRestricted(xQueue, xTicksToWait, xWaitIndefinitely)

Restricted wait for a message (internal kernel API).

xQueueGenericReset(xQueue, xNewQueue)

Resets a queue to its initial state.

vQueueSetQueueNumber(xQueue, uxQueueNumber)

Sets a queue number (debug use).

uxQueueGetQueueNumber(xQueue)

Gets a queue number (debug use).

ucQueueGetQueueType(xQueue)

Gets a queue's type (debug use).

xQueueCreate(uxQueueLength, uxItemSize)

Creates a queue (length, item size); the most common queue-creation macro.

xQueueCreateStatic(uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer)

Creates a queue (static-memory version).

xQueueSend(xQueue, pvItemToQueue, xTicksToWait)

Sends data to the queue tail (same as xQueueSendToBack; optional timeout).

xQueueSendToFront(xQueue, pvItemToQueue, xTicksToWait)

Sends data to the queue head (taken first).

xQueueSendToBack(xQueue, pvItemToQueue, xTicksToWait)

Sends data to the queue tail (FIFO order).

xQueueOverwrite(xQueue, pvItemToQueue)

Overwrites existing queue data (for length-1 queues only).

xQueueReset(xQueue)

Resets a queue to its initial state (clears data).

xQueueSendFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken)

Sends to the queue tail from an ISR (ISR-safe).

xQueueSendToFrontFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken)

Sends to the queue head from an ISR (ISR-safe).

xQueueSendToBackFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken)

Sends to the queue tail from an ISR (ISR-safe).

xQueueOverwriteFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken)

Overwrites queue data from an ISR (ISR-safe).

📂 Semaphores & Mutexes (semphr.h)

vSemaphoreCreateBinary(xSemaphore)

Creates a binary semaphore (legacy macro; prefer xSemaphoreCreateBinary).

xSemaphoreCreateBinary()

Creates a binary semaphore (the most common task-sync primitive).

xSemaphoreCreateBinaryStatic(pxSemaphoreBuffer)

Creates a binary semaphore (static-memory version).

xSemaphoreCreateCounting(uxMaxCount, uxInitialCount)

Creates a counting semaphore (counts resources, e.g. free buffers).

xSemaphoreCreateCountingStatic(uxMaxCount, uxInitialCount, pxSemaphoreBuffer)

Creates a counting semaphore (static-memory version).

xSemaphoreCreateMutex()

Creates a mutex (with priority inheritance against priority inversion).

xSemaphoreCreateMutexStatic(pxMutexBuffer)

Creates a mutex (static-memory version).

xSemaphoreCreateRecursiveMutex()

Creates a recursive mutex (the same task may take it multiple times).

xSemaphoreCreateRecursiveMutexStatic(pxMutexBuffer)

Creates a recursive mutex (static-memory version).

xSemaphoreTake(xSemaphore, xBlockTime)

Takes a semaphore with optional blocking timeout (most common).

xSemaphoreTakeFromISR(xSemaphore, pxHigherPriorityTaskWoken)

Takes a semaphore from an ISR (ISR-safe).

xSemaphoreTakeRecursive(xMutex, xBlockTime)

Recursively takes a mutex (re-entrant).

xSemaphoreGive(xSemaphore)

Gives a semaphore (most common).

xSemaphoreGiveFromISR(xSemaphore, pxHigherPriorityTaskWoken)

Gives a semaphore from an ISR (ISR-safe).

xSemaphoreGiveRecursive(xMutex)

Recursively gives a mutex.

xSemaphoreGetMutexHolder(xSemaphore)

Gets the task handle holding the mutex.

xSemaphoreGetMutexHolderFromISR(xSemaphore)

Gets the mutex holder from an ISR.

vSemaphoreDelete(xSemaphore)

Deletes a semaphore.

uxSemaphoreGetCount(xSemaphore)

Gets a semaphore's current count.

📂 Software Timers (timers.h)

xTimerCreate(pcTimerName, xTimerPeriodInTicks, uxAutoReload, pvTimerID, pxCallbackFunction)

Creates a software timer (periodic/one-shot; scheduled by the timer daemon task).

xTimerCreateStatic(pcTimerName, xTimerPeriodInTicks, uxAutoReload, pvTimerID, pxCallbackFunction, pxTimerBuffer)

Creates a software timer (static-memory version).

pvTimerGetTimerID(xTimer)

Gets a timer's ID value.

vTimerSetTimerID(xTimer, pvNewID)

Sets a timer's ID value.

xTimerIsTimerActive(xTimer)

Queries whether a timer is running.

xTimerGetTimerDaemonTaskHandle()

Gets the timer daemon task's handle.

xTimerPendFunctionCallFromISR(xFunctionToPend, pvParameter1, ulParameter2, pxHigherPriorityTaskWoken)

Queues a function into the daemon task from an ISR (ISR-safe).

xTimerPendFunctionCall(xFunctionToPend, pvParameter1, ulParameter2, xTicksToWait)

Queues a function into the daemon task's execution list.

pcTimerGetName(xTimer)

Gets a timer's name.

vTimerSetReloadMode(xTimer, uxAutoReload)

Sets a timer's auto-reload mode.

xTimerGetPeriod(xTimer)

Gets a timer's period.

xTimerGetExpiryTime(xTimer)

Gets a timer's expiry time (in ticks).

xTimerCreateTimerTask()

Creates the timer daemon task (internal kernel API).

xTimerGenericCommand(xTimer, xCommandID, xOptionalValue, pxHigherPriorityTaskWoken, xTicksToWait)

Low-level timer command (basis of xTimerStart and friends).

vTimerSetTimerNumber(xTimer, uxTimerNumber)

Sets a timer number (debug use).

uxTimerGetTimerNumber(xTimer)

Gets a timer number (debug use).

xTimerStart(xTimer, xBlockTime)

Starts a software timer (most common).

xTimerStartFromISR(xTimer, pxHigherPriorityTaskWoken)

Starts a timer from an ISR (ISR-safe).

xTimerStop(xTimer, xBlockTime)

Stops a software timer.

xTimerStopFromISR(xTimer, pxHigherPriorityTaskWoken)

Stops a timer from an ISR (ISR-safe).

xTimerChangePeriod(xTimer, xNewPeriod, xBlockTime)

Changes a timer's period (can start the timer too).

xTimerChangePeriodFromISR(xTimer, xNewPeriod, pxHigherPriorityTaskWoken)

Changes a period from an ISR (ISR-safe).

xTimerReset(xTimer, xBlockTime)

Resets a timer (restarts the full period).

xTimerResetFromISR(xTimer, pxHigherPriorityTaskWoken)

Resets a timer from an ISR (ISR-safe).

xTimerDelete(xTimer, xBlockTime)

Deletes a software timer.

📂 Event Groups (event_groups.h)

xEventGroupCreate()

Creates an event group (wait/set multiple event bits for inter-task event sync).

xEventGroupCreateStatic(pxEventGroupBuffer)

Creates an event group (static-memory version).

xEventGroupWaitBits(xEventGroup, uxBitsToWaitFor, xClearOnExit, xWaitForAllBits, xTicksToWait)

Waits for one or more specified event bits (optional timeout).

xEventGroupClearBits(xEventGroup, uxBitsToClear)

Clears specified event bits in the event group.

xEventGroupClearBitsFromISR(xEventGroup, uxBitsToClear)

Clears event bits from an ISR (ISR-safe).

xEventGroupSetBits(xEventGroup, uxBitsToSet)

Sets specified event bits, waking waiting tasks.

xEventGroupSetBitsFromISR(xEventGroup, uxBitsToSet, pxHigherPriorityTaskWoken)

Sets event bits from an ISR (ISR-safe).

xEventGroupSync(xEventGroup, uxBitsToSet, uxBitsToWaitFor, xTicksToWait)

Event-group sync: waits for all tasks, then sets and clears bits together.

xEventGroupGetBitsFromISR(xEventGroup)

Reads event bits from an ISR (ISR-safe).

vEventGroupDelete(xEventGroup)

Deletes an event group.

vEventGroupSetBitsCallback(pvEventGroup, ulBitsToSet)

Set-bits callback (used with xTimerPendFunctionCall).

vEventGroupClearBitsCallback(pvEventGroup, ulBitsToClear)

Clear-bits callback (used with xTimerPendFunctionCall).

uxEventGroupGetNumber(xEventGroup)

Gets an event group's number (debug use).

vEventGroupSetNumber(xEventGroup, uxEventGroupNumber)

Sets an event group's number (debug use).

📂 Stream & Message Buffers (stream_buffer.h)

xStreamBufferSend(xStreamBuffer, pvTxData, xDataLengthBytes, xTicksToWait)

Writes data into a stream buffer (byte stream, with timeout).

xStreamBufferSendFromISR(xStreamBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken)

Writes stream data from an ISR (ISR-safe).

xStreamBufferReceive(xStreamBuffer, pvRxData, xBufferLengthBytes, xTicksToWait)

Reads data from a stream buffer (optional timeout).

xStreamBufferReceiveFromISR(xStreamBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken)

Reads stream data from an ISR (ISR-safe).

vStreamBufferDelete(xStreamBuffer)

Deletes a stream buffer.

xStreamBufferIsFull(xStreamBuffer)

Checks whether the stream buffer is full.

xStreamBufferIsEmpty(xStreamBuffer)

Checks whether the stream buffer is empty.

xStreamBufferReset(xStreamBuffer)

Resets a stream buffer.

xStreamBufferSpacesAvailable(xStreamBuffer)

Gets free space in a stream buffer.

xStreamBufferBytesAvailable(xStreamBuffer)

Gets readable bytes in a stream buffer.

xStreamBufferSetTriggerLevel(xStreamBuffer, xTriggerLevel)

Sets the trigger level (wakes the receiver only after this many bytes).

xStreamBufferSendCompletedFromISR(xStreamBuffer, pxHigherPriorityTaskWoken)

Notifies that a send completed (internal kernel API).

xStreamBufferReceiveCompletedFromISR(xStreamBuffer, pxHigherPriorityTaskWoken)

Notifies that a receive completed (internal kernel API).

xStreamBufferGenericCreate(xBufferSizeBytes, xTriggerLevelBytes, xIsMessageBuffer)

Low-level stream-buffer creation (basis of xStreamBufferCreate).

xStreamBufferGenericCreateStatic(xBufferSizeBytes, xTriggerLevelBytes, xIsMessageBuffer, pucStreamBufferStorageArea, pxStaticStreamBuffer)

Low-level creation (static-memory version).

xStreamBufferNextMessageLengthBytes(xStreamBuffer)

Gets the next message's length (message buffers).

vStreamBufferSetStreamBufferNumber(xStreamBuffer, uxStreamBufferNumber)

Sets a stream-buffer number (debug use).

uxStreamBufferGetStreamBufferNumber(xStreamBuffer)

Gets a stream-buffer number (debug use).

ucStreamBufferGetStreamBufferType(xStreamBuffer)

Gets a stream-buffer type (debug use).

📂 Co-routines (croutine.h, legacy)

xCoRoutineCreate(pxCoRoutineCode, uxPriority, uxIndex)

Creates a co-routine (legacy FreeRTOS feature; use tasks in new code).

vCoRoutineSchedule()

Co-routine scheduler (deprecated).

xCoRoutineRemoveFromEventList(pxEventList)

Removes a co-routine from the event list (internal kernel API).

📂 Lists (list.h, internal)

vListInitialise(pxList)

Initializes a list (internal kernel API).

vListInitialiseItem(pxItem)

Initializes a list item (internal kernel API).

vListInsert(pxList, pxNewListItem)

Inserts an item into a list at the sorted position (internal kernel API).

vListInsertEnd(pxList, pxNewListItem)

Inserts an item at a list's tail (internal kernel API).

uxListRemove(pxItemToRemove)

Removes an item from a list (internal kernel API).

📖 Related Tutorials: GPIO Output (Light an LED) · TCP Client

System Init & Reset

📂 System Init & Reset

bl_sys_rstinfo_get(void)

Gets the reset information, such as the cause of the last system reset.

bl_sys_rstinfo_clr(void)

Clears the stored reset information of the system.

bl_sys_logall_enable(void)

Enables all system log output globally.

bl_sys_logall_disable(void)

Disables all system log output globally.

bl_sys_reset_por(void)

Triggers a power-on reset (POR) to restart the whole chip.

bl_sys_reset_system(void)

Resets the system through software, restarting the chip.

bl_sys_isxipaddr(uint32_t addr)

Checks whether a given address is an XIP (execute-in-place) address.

bl_sys_em_config(void)

Configures the low-level EM-related parameters of the system.

bl_sys_cache_config(void)

Configures the system cache working parameters.

bl_sys_pkg_config(void)

Configures the pins according to the chip package type.

bl_sys_default_active_config(void)

Restores the system to its default active configuration.

bl_sys_early_init(void)

Performs early system initialization, called first after power-on.

bl_sys_init(void)

Initializes the system: clock, pin mux and other low-level resources.

bl_sys_wdt_rst_count_get()

Gets the count of resets caused by the watchdog.

📖 Related Tutorials: Software Reboot · WS2812 RGB LED

Log Output (blog)

📂 Logging (blog)

📖 Related Tutorials: Log Output · HTTP GET Request

Software Timer (bl_os_timer)

📂 Software Timer (bl_os_timer)

bl_os_timer_create(void *func, void *argv)

Creates a software timer and binds a callback function to it.

bl_os_timer_delete(BL_Timer_t timerid, uint32_t tick)

Deletes the specified software timer.

bl_os_timer_stop(BL_Timer_t timerid, uint32_t tick)

Stops a running software timer.

bl_os_timer_start_once(BL_Timer_t timerid, long t_sec, long t_nsec)

Starts the timer to fire its callback once after the timeout.

bl_os_timer_start_periodic(BL_Timer_t timerid, long t_sec, long t_nsec)

Starts the timer to fire its callback periodically at fixed intervals.

📖 Related Tutorials: Software Timer

Low Power (Deep Sleep)

📂 Low Power (Deep Sleep)

hal_hbn_init(uint8_t *pinbuf, uint8_t pinbuf_size)

Initializes the HBN module to prepare for deep sleep.

hal_hbn_enter(uint32_t time)

Makes the chip enter deep sleep for a specified duration.

📖 Related Tutorials: Sleep Mode

GPIO

📂 hosal layer (hosal_gpio.h)

hosal_gpio_init(hosal_gpio_dev_t *gpio)

Initializes the GPIO pin according to the device configuration, setting its working mode (input or output) and pull-up/pull-down resistor options.

hosal_gpio_output_set(hosal_gpio_dev_t *gpio, uint8_t value)

Sets the GPIO pin output to a high or low level so the pin drives the connected device or signal.

hosal_gpio_input_get(hosal_gpio_dev_t *gpio, uint8_t *value)

Reads the current input level of the GPIO pin, returning the detected high or low state.

hosal_gpio_irq_set(hosal_gpio_dev_t *gpio, hosal_gpio_irq_trigger_t trigger_type, hosal_gpio_irq_handler_t handler, void *arg)

Configures the GPIO interrupt trigger type (edge or level) and registers a callback function that is called when the interrupt occurs.

hosal_gpio_irq_mask(hosal_gpio_dev_t *gpio, uint8_t mask)

Masks or unmasks the GPIO pin interrupt, temporarily preventing or allowing the interrupt from being triggered.

hosal_gpio_finalize(hosal_gpio_dev_t *gpio)

Releases the GPIO resources and disables the pin function, so the pin can be reconfigured for other purposes later.

📂 SDK driver layer (bl_gpio.h)

bl_gpio_enable_output(uint8_t pin, uint8_t pullup, uint8_t pulldown)

Configures the specified pin as an output, optionally enabling pull-up or pull-down resistors on it.

bl_gpio_enable_input(uint8_t pin, uint8_t pullup, uint8_t pulldown)

Configures the specified pin as an input, optionally enabling pull-up or pull-down resistors for stable reading.

bl_gpio_output_set(uint8_t pin, uint8_t value)

Sets the specified pin to output a high or low level, controlling whatever is connected to it.

bl_gpio_input_get(uint8_t pin, uint8_t *value)

Reads the input level state of the specified pin and stores the result in the provided value pointer.

bl_gpio_input_get_value(uint8_t pin)

Directly returns the current input level value of the specified pin, without using an output parameter.

bl_gpio_int_clear(uint8_t gpioPin,uint8_t intClear)

Clears the interrupt flag of the specified GPIO pin so the next interrupt can be detected normally.

bl_gpio_intmask(uint8_t gpiopin, uint8_t mask)

Masks or enables the GPIO interrupt for the specified pin, controlling whether its interrupt handler triggers.

bl_set_gpio_intmod(uint8_t gpioPin, uint8_t intCtrlMod, uint8_t intTrgMod)

Sets the interrupt control mode and trigger mode (edge or level) for the specified GPIO pin.

bl_gpio_register(gpio_ctx_t *pstnode)

Registers a GPIO pin in the system and associates it with its interrupt handler function.

📖 Related Tutorials: GPIO Output (Light an LED) · GPIO Input (Button) · EXTI External Interrupt

UART Serial

📂 hosal layer (hosal_uart.h)

hosal_uart_abr_get(hosal_uart_dev_t *uart, uint8_t mode)

Automatically detects the UART baud rate in the specified mode, so the receiver can match the sender.

hosal_uart_init(hosal_uart_dev_t *uart)

Initializes the UART according to the device configuration, enabling both data transmission and reception on the bus.

hosal_uart_init_only_tx(hosal_uart_dev_t *uart)

Initializes the UART in transmit-only mode, so the port can send data but does not receive anything.

hosal_uart_send(hosal_uart_dev_t *uart, const void *txbuf, uint32_t size)

Sends a block of data of the specified size through the UART port, typically in a blocking manner.

hosal_uart_receive(hosal_uart_dev_t *uart, void *data, uint32_t expect_size)

Receives data of the expected size from the UART port and stores it in the buffer.

hosal_uart_ioctl(hosal_uart_dev_t *uart, int ctl, void *p_arg)

Performs control operations on the UART, such as changing the baud rate or other settings.

hosal_uart_callback_set(hosal_uart_dev_t *uart, int callback_type, hosal_uart_callback_t pfn_callback, void *arg)

Registers a callback function for UART events such as data reception, transmission completion, and error conditions.

hosal_uart_finalize(hosal_uart_dev_t *uart)

Closes the UART port and releases its resources, so it can no longer be used for communication.

📂 SDK driver layer (bl_uart.h)

bl_uart_gpio_init(uint8_t id, uint8_t tx, uint8_t rx, uint8_t rts, uint8_t cts, int baudrate)

Initializes the GPIO pins (TX, RX, RTS, CTS) and baud rate used by the specified UART port.

bl_uart_init(uint8_t id, uint8_t tx_pin, uint8_t rx_pin, uint8_t cts_pin, uint8_t rts_pin, uint32_t baudrate)

Configures the UART pins and baud rate, completing full initialization of the specified UART port.

bl_uart_debug_early_init(uint32_t baudrate)

Performs early initialization of the debug UART port with the given baud rate during system boot.

bl_uart_early_init(uint8_t id, uint8_t tx_pin, uint32_t baudrate)

Performs early initialization of the UART during system boot, setting up only the transmit pin and baud rate.

bl_uart_int_rx_enable(uint8_t id)

Enables the receive interrupt of the UART port, so incoming data triggers the interrupt handler.

bl_uart_int_rx_disable(uint8_t id)

Disables the receive interrupt of the UART port, so incoming data no longer triggers interrupts.

bl_uart_int_tx_enable(uint8_t id)

Enables the transmit interrupt of the UART port, which fires when buffered data has been sent out.

bl_uart_int_tx_disable(uint8_t id)

Disables the transmit interrupt of the UART port, so it no longer fires after sending data.

bl_uart_string_send(uint8_t id, char *data)

Sends a null-terminated string through the specified UART port, which is handy for log output.

bl_uart_flush(uint8_t id)

Flushes the UART port buffers, clearing any pending transmit or receive data that has not been processed.

bl_uart_getdefconfig(uint8_t id, uint8_t *parity)

Reads the default configuration of the specified UART port, such as its parity check setting.

bl_uart_setconfig(uint8_t id, uint32_t baudrate, UART_Parity_Type parity)

Sets the UART port configuration, including the new baud rate and the parity check mode.

bl_uart_setbaud(uint8_t id, uint32_t baud)

Changes the baud rate of the specified UART port to the new value, so both sides communicate at the same speed.

bl_uart_data_send(uint8_t id, uint8_t data)

Sends a single byte of data through the specified UART port, typically used for small messages.

bl_uart_datas_send(uint8_t id, uint8_t *data, int len)

Sends multiple bytes of data of the given length through the specified UART port in one call.

bl_uart_data_recv(uint8_t id)

Reads a single byte of data from the specified UART port, returning what was received.

bl_uart_int_enable(uint8_t id)

Enables the overall interrupt function of the specified UART port, allowing for interrupt-driven data communication.

bl_uart_int_disable(uint8_t id)

Disables the overall interrupt function of the specified UART port, switching back to polling-based communication.

bl_uart_int_rx_notify_register(uint8_t id, cb_uart_notify_t cb, void *arg)

Registers a callback that notifies the application when data is received on the UART port via interrupt.

bl_uart_int_tx_notify_register(uint8_t id, cb_uart_notify_t cb, void *arg)

Registers a callback that notifies the application when transmission on the UART port completes via interrupt.

bl_uart_int_rx_notify_unregister(uint8_t id, cb_uart_notify_t cb, void *arg)

Unregisters the previously registered callback for UART receive-interrupt notifications, so the application stops being notified.

bl_uart_int_tx_notify_unregister(uint8_t id, cb_uart_notify_t cb, void *arg)

Unregisters the previously registered callback for UART transmit-interrupt notifications, so the application stops being notified.

📖 Related Tutorials: UART Serial Communication · BLE Advertising (iBeacon)

Hardware Timer (hosal_timer)

📂 Hardware Timer (hosal_timer)

hosal_timer_init(hosal_timer_dev_t *tim)

Initializes the hardware timer according to the device configuration, including its period, callback, and counting mode.

hosal_timer_start(hosal_timer_dev_t *tim)

Starts the hardware timer counting, so its callback fires when the configured period has elapsed.

hosal_timer_stop(hosal_timer_dev_t *tim)

Stops the hardware timer, so it stops counting and no further callbacks are triggered.

hosal_timer_finalize(hosal_timer_dev_t *tim)

Releases the resources of the hardware timer, so it can no longer be used until reinitialized.

📖 Related Tutorials: Hardware Timer

PWM (Register Level)

📂 Register level (bl702_pwm.h)

PWM_Channel_Init(PWM_CH_CFG_Type *chCfg)

Initializes a PWM channel with the given configuration, including period, thresholds, and divider (low-level register interface).

PWM_Channel_Update(PWM_CH_ID_Type ch, uint16_t period, uint16_t threshold1, uint16_t threshold2)

Updates the period and both threshold values of the PWM channel at the register level (low-level register interface).

PWM_Channel_Set_Div(PWM_CH_ID_Type ch, uint16_t div)

Sets the clock divider of the PWM channel, which scales the generated frequency (low-level register interface).

PWM_Channel_Set_Threshold1(PWM_CH_ID_Type ch, uint16_t threshold1)

Sets threshold 1 of the PWM channel, which defines the first level switching point (low-level register interface).

PWM_Channel_Set_Threshold2(PWM_CH_ID_Type ch, uint16_t threshold2)

Sets threshold 2 of the PWM channel, which defines the second level switching point (low-level register interface).

PWM_Channel_Set_Period(PWM_CH_ID_Type ch, uint16_t period)

Sets the period of the PWM channel, which determines the output frequency (low-level register interface).

PWM_Channel_Get(PWM_CH_ID_Type ch, uint16_t *period, uint16_t *threshold1, uint16_t *threshold2)

Reads the current period and both threshold values of the PWM channel (low-level register interface).

PWM_IntMask(PWM_CH_ID_Type ch, PWM_INT_Type intType, BL_Mask_Type intMask)

Masks or unmasks the given PWM interrupt type for the specified channel (low-level register interface).

PWM_Channel_Enable(PWM_CH_ID_Type ch)

Enables the output of the PWM channel, so it starts generating the waveform (low-level register interface).

PWM_Channel_Disable(PWM_CH_ID_Type ch)

Disables the output of the PWM channel, so it stops generating the waveform (low-level register interface).

PWM_SW_Mode(PWM_CH_ID_Type ch, BL_Fun_Type enable)

Switches the PWM channel to software control mode, where the output level is set by software (low-level register interface).

PWM_SW_Force_Value(PWM_CH_ID_Type ch, uint8_t value)

Forces the PWM output to a given value when the channel is in software control mode (low-level register interface).

PWM_Int_Callback_Install(PWM_CH_ID_Type ch, uint32_t intType, intCallback_Type *cbFun)

Installs a callback function that runs when the specified PWM interrupt occurs (low-level register interface).

PWM_Smart_Configure(PWM_CH_ID_Type ch, uint32_t frequency, uint8_t dutyCycle)

Quickly configures the PWM channel by frequency and duty cycle, computing the registers automatically (low-level register interface).

📂 SDK driver layer (bl_pwm.h)

bl_pwm_init(uint8_t id, uint8_t pin, uint32_t freq)

Initializes the PWM function on the given pin with the specified frequency, ready to output a waveform.

bl_pwm_start(uint8_t id)

Starts the PWM output, so the pin begins generating the configured waveform signal immediately after the call.

bl_pwm_stop(uint8_t id)

Stops the PWM output, so the pin stops generating the waveform signal and stays idle.

bl_pwm_set_freq(uint8_t id, uint32_t freq)

Changes the output frequency of the PWM channel to the given value, updating the waveform timing.

bl_pwm_set_duty(uint8_t id, float duty)

Sets the PWM duty cycle as a percentage from 0 to 100, controlling the on-time ratio.

bl_pwm_get_duty(uint8_t id, float *p_duty)

Gets the current duty cycle of the PWM channel and stores it in the given pointer.

📖 Related Tutorials: PWM Output

ADC

📂 hosal layer (hosal_adc.h)

hosal_adc_init(hosal_adc_dev_t *adc)

Initializes an ADC device and configures sampling channels.

hosal_adc_add_channel(hosal_adc_dev_t *adc, uint32_t channel)

Adds a sampling channel to the ADC device.

hosal_adc_remove_channel(hosal_adc_dev_t *adc, uint32_t channel)

Removes a specified sampling channel from the ADC device.

hosal_adc_add_reference_channel(hosal_adc_dev_t *adc, uint32_t refer_channel, float refer_voltage)

Adds a reference voltage channel to calibrate sampled values.

hosal_adc_remove_reference_channel(hosal_adc_dev_t *adc)

Removes the reference voltage channel of the ADC.

hosal_adc_device_get(void)

Gets a pointer to the available ADC device.

hosal_adc_value_get(hosal_adc_dev_t *adc, uint32_t channel, uint32_t timeout)

Reads the sampled voltage value of the specified ADC channel.

hosal_adc_tsen_value_get(hosal_adc_dev_t *adc)

Reads the temperature value from the built-in temperature sensor of the chip.

hosal_adc_sample_cb_reg(hosal_adc_dev_t *adc, hosal_adc_cb_t cb)

Registers a callback function for ADC sampling completion.

hosal_adc_start(hosal_adc_dev_t *adc, void *data, uint32_t size)

Starts continuous ADC sampling and fills the data buffer.

hosal_adc_stop(hosal_adc_dev_t *adc)

Stops continuous ADC sampling.

hosal_adc_finalize(hosal_adc_dev_t *adc)

Finalizes and releases the ADC device resources.

📂 SDK driver layer (bl_adc.h)

bl_adc_tsen_init(void)

Initializes the built-in temperature sensor of the chip.

bl_adc_tsen_get_val(void)

Gets the current temperature value of the temperature sensor.

bl_adc_tsen_dma_init(bl_adc_tsen_cfg_t *cfg)

Initializes the temperature sensor in DMA sampling mode.

bl_adc_tsen_dma_trigger(void)

Triggers one temperature sensor DMA sample.

bl_adc_tsen_dma_is_busy(void)

Checks whether temperature sensor DMA sampling is busy.

bl_adc_voice_init(bl_adc_voice_cfg_t *cfg)

Initializes the microphone voice capture function.

bl_adc_voice_start(void)

Starts microphone voice capture.

bl_adc_voice_stop(void)

Stops microphone voice capture.

📖 Related Tutorials: ADC Sampling · NTC Temperature Measurement

I2C Bus

📂 I2C Bus

hosal_i2c_init(hosal_i2c_dev_t *i2c)

Initializes the I2C device and configures its working mode.

hosal_i2c_master_send(hosal_i2c_dev_t *i2c, uint16_t dev_addr, const uint8_t *data, uint16_t size, uint32_t timeout)

Sends data to a slave device in master mode.

hosal_i2c_master_recv(hosal_i2c_dev_t *i2c, uint16_t dev_addr, uint8_t *data, uint16_t size, uint32_t timeout)

Receives data from a slave device in master mode.

hosal_i2c_slave_send(hosal_i2c_dev_t *i2c, const uint8_t *data, uint16_t size, uint32_t timeout)

Sends data to the master device in slave mode.

hosal_i2c_slave_recv(hosal_i2c_dev_t *i2c, uint8_t *data, uint16_t size, uint32_t timeout)

Receives data from the master device in slave mode.

hosal_i2c_mem_write(hosal_i2c_dev_t *i2c, uint16_t dev_addr, uint32_t mem_addr, uint16_t mem_addr_size, const uint8_t *data, uint16_t size, uint32_t timeout)

Writes data to the internal memory of a slave device over I2C.

hosal_i2c_mem_read(hosal_i2c_dev_t *i2c, uint16_t dev_addr, uint32_t mem_addr, uint16_t mem_addr_size, uint8_t *data, uint16_t size, uint32_t timeout)

Reads data from the internal memory of a slave device over I2C.

hosal_i2c_finalize(hosal_i2c_dev_t *i2c)

Finalizes and releases the I2C device resources.

📖 Related Tutorials: I2C Bus Communication · SHT30 Temp & Humidity Sensor · BH1750 Light Sensor

SPI & DMA

📂 SPI register level (bl702_spi.h)

SPI_Init(SPI_ID_Type spiNo, SPI_CFG_Type *spiCfg)

Initializes the SPI peripheral with the given parameters (low-level register interface).

SPI_DeInit(SPI_ID_Type spiNo)

Deinitializes and resets the SPI peripheral (low-level register interface).

SPI_SetClock(SPI_ID_Type spiNo, uint32_t clk)

Sets the clock frequency of the SPI peripheral (low-level register interface).

SPI_ClockConfig(SPI_ID_Type spiNo, SPI_ClockCfg_Type *clockCfg)

Configures the SPI clock source and divider (low-level register interface).

SPI_FifoConfig(SPI_ID_Type spiNo, SPI_FifoCfg_Type *fifoCfg)

Configures the SPI transmit and receive FIFOs (low-level register interface).

SPI_Enable(SPI_ID_Type spiNo, SPI_WORK_MODE_Type modeType)

Enables the specified working mode of the SPI (low-level register interface).

SPI_Disable(SPI_ID_Type spiNo, SPI_WORK_MODE_Type modeType)

Disables the specified working mode of the SPI (low-level register interface).

SPI_SetTimeOutValue(SPI_ID_Type spiNo, uint16_t value)

Sets the timeout value of SPI operations (low-level register interface).

SPI_SetDeglitchCount(SPI_ID_Type spiNo, uint8_t cnt)

Sets the input deglitch count of the SPI (low-level register interface).

SPI_RxIgnoreEnable(SPI_ID_Type spiNo, uint8_t startPoint, uint8_t stopPoint)

Enables the SPI receive data ignoring function (low-level register interface).

SPI_RxIgnoreDisable(SPI_ID_Type spiNo)

Disables the SPI receive data ignoring function (low-level register interface).

SPI_ClrTxFifo(SPI_ID_Type spiNo)

Clears the SPI transmit FIFO (low-level register interface).

SPI_ClrRxFifo(SPI_ID_Type spiNo)

Clears the SPI receive FIFO (low-level register interface).

SPI_ClrIntStatus(SPI_ID_Type spiNo, SPI_INT_Type intType)

Clears the specified interrupt status flag of the SPI (low-level register interface).

SPI_IntMask(SPI_ID_Type spiNo, SPI_INT_Type intType, BL_Mask_Type intMask)

Masks or unmasks the specified SPI interrupt (low-level register interface).

SPI_Int_Callback_Install(SPI_ID_Type spiNo, SPI_INT_Type intType, intCallback_Type *cbFun)

Installs an interrupt callback function for the SPI (low-level register interface).

SPI_SendData(SPI_ID_Type spiNo, uint32_t data)

Sends a single data word to the SPI peripheral (low-level register interface).

SPI_Send_8bits(SPI_ID_Type spiNo, uint8_t *buff, uint32_t length, SPI_Timeout_Type timeoutType)

Sends a data buffer in 8-bit width (low-level register interface).

SPI_Send_16bits(SPI_ID_Type spiNo, uint16_t *buff, uint32_t length, SPI_Timeout_Type timeoutType)

Sends a data buffer in 16-bit width (low-level register interface).

SPI_Send_24bits(SPI_ID_Type spiNo, uint32_t *buff, uint32_t length, SPI_Timeout_Type timeoutType)

Sends a data buffer in 24-bit width (low-level register interface).

SPI_Send_32bits(SPI_ID_Type spiNo, uint32_t *buff, uint32_t length, SPI_Timeout_Type timeoutType)

Sends a data buffer in 32-bit width (low-level register interface).

SPI_Recv_8bits(SPI_ID_Type spiNo, uint8_t *buff, uint32_t length, SPI_Timeout_Type timeoutType)

Receives data into a buffer in 8-bit width (low-level register interface).

SPI_Recv_16bits(SPI_ID_Type spiNo, uint16_t *buff, uint32_t length, SPI_Timeout_Type timeoutType)

Receives data into a buffer in 16-bit width (low-level register interface).

SPI_Recv_24bits(SPI_ID_Type spiNo, uint32_t *buff, uint32_t length, SPI_Timeout_Type timeoutType)

Receives data into a buffer in 24-bit width (low-level register interface).

SPI_Recv_32bits(SPI_ID_Type spiNo, uint32_t *buff, uint32_t length, SPI_Timeout_Type timeoutType)

Receives data into a buffer in 32-bit width (low-level register interface).

SPI_SendRecv_8bits(SPI_ID_Type spiNo, uint8_t *sendBuff, uint8_t *recvBuff, uint32_t length, SPI_Timeout_Type timeoutType)

Sends and receives data simultaneously in 8-bit width (low-level register interface).

SPI_SendRecv_16bits(SPI_ID_Type spiNo, uint16_t *sendBuff, uint16_t *recvBuff, uint32_t length, SPI_Timeout_Type timeoutType)

Sends and receives data simultaneously in 16-bit width (low-level register interface).

SPI_SendRecv_24bits(SPI_ID_Type spiNo, uint32_t *sendBuff, uint32_t *recvBuff, uint32_t length, SPI_Timeout_Type timeoutType)

Sends and receives data simultaneously in 24-bit width (low-level register interface).

SPI_SendRecv_32bits(SPI_ID_Type spiNo, uint32_t *sendBuff, uint32_t *recvBuff, uint32_t length, SPI_Timeout_Type timeoutType)

Sends and receives data simultaneously in 32-bit width (low-level register interface).

SPI_ReceiveData(SPI_ID_Type spiNo)

Reads a single data word received by the SPI (low-level register interface).

SPI_GetTxFifoCount(SPI_ID_Type spiNo)

Gets the entry count of the SPI transmit FIFO (low-level register interface).

SPI_GetRxFifoCount(SPI_ID_Type spiNo)

Gets the entry count of the SPI receive FIFO (low-level register interface).

SPI_GetIntStatus(SPI_ID_Type spiNo, SPI_INT_Type intType)

Queries the status of the specified SPI interrupt (low-level register interface).

SPI_GetFifoStatus(SPI_ID_Type spiNo, SPI_FifoStatus_Type fifoSts)

Queries the SPI transmit and receive FIFO status (low-level register interface).

SPI_GetBusyStatus(SPI_ID_Type spiNo)

Checks whether the SPI peripheral is busy (low-level register interface).

📂 DMA register level (bl702_dma.h)

DMA_Enable(void)

Enables the DMA controller (low-level register interface).

DMA_Disable(void)

Disables the DMA controller (low-level register interface).

DMA_Channel_Init(DMA_Channel_Cfg_Type *chCfg)

Initializes a DMA channel with the given configuration (low-level register interface).

DMA_Channel_Update_SrcMemcfg(uint8_t ch, uint32_t memAddr, uint32_t len)

Updates the source memory address of a DMA channel (low-level register interface).

DMA_Channel_Update_DstMemcfg(uint8_t ch, uint32_t memAddr, uint32_t len)

Updates the destination memory address of a DMA channel (low-level register interface).

DMA_Channel_TranferSize(uint8_t ch)

Gets the remaining transfer size of a DMA channel (low-level register interface).

DMA_Channel_Is_Busy(uint8_t ch)

Checks whether a DMA channel is busy (low-level register interface).

DMA_Channel_Enable(uint8_t ch)

Enables the specified DMA channel (low-level register interface).

DMA_Channel_Disable(uint8_t ch)

Disables the specified DMA channel (low-level register interface).

DMA_LLI_Init(uint8_t ch, DMA_LLI_Cfg_Type *lliCfg)

Initializes the DMA linked-list transfer configuration (low-level register interface).

DMA_LLI_Update(uint8_t ch, uint32_t LLI)

Updates the linked-list node address of a DMA channel (low-level register interface).

DMA_IntMask(uint8_t ch, DMA_INT_Type intType, BL_Mask_Type intMask)

Masks or unmasks the specified DMA interrupt (low-level register interface).

DMA_LLI_PpBuf_Start_New_Transmit(DMA_LLI_PP_Buf *dmaPpBuf)

Starts a new DMA transmission with the ping-pong buffer (low-level register interface).

DMA_LLI_PpBuf_Remove_Completed_List(DMA_LLI_PP_Buf *dmaPpBuf)

Removes completed linked-list nodes from the ping-pong buffer (low-level register interface).

DMA_LLI_PpBuf_Append(DMA_LLI_PP_Buf *dmaPpBuf, DMA_LLI_Ctrl_Type *dmaLliList)

Appends new linked-list nodes to the ping-pong buffer (low-level register interface).

DMA_LLI_PpBuf_Destroy(DMA_LLI_PP_Buf *dmaPpBuf)

Destroys the ping-pong buffer and frees its resources (low-level register interface).

DMA_Int_Callback_Install(DMA_Chan_Type dmaChan, DMA_INT_Type intType, intCallback_Type *cbFun)

Installs a DMA interrupt callback function (low-level register interface).

DMA_LLI_PpStruct_Start(DMA_LLI_PP_Struct *dmaPpStruct)

Starts the ping-pong struct DMA transmission (low-level register interface).

DMA_LLI_PpStruct_Stop(DMA_LLI_PP_Struct *dmaPpStruct)

Stops the ping-pong struct DMA transmission (low-level register interface).

DMA_LLI_PpStruct_Init(DMA_LLI_PP_Struct *dmaPpStruct)

Initializes the ping-pong struct DMA configuration (low-level register interface).

DMA_LLI_PpStruct_Set_Transfer_Len(DMA_LLI_PP_Struct *dmaPpStruct, uint16_t Ping_Transfer_len, uint16_t Pong_Transfer_len)

Sets the transfer length of each ping-pong struct buffer (low-level register interface).

📂 hosal layer (hosal_dma.h)

hosal_dma_init(void)

Initializes the DMA controller resources.

hosal_dma_chan_request(int flag)

Requests a free DMA channel.

hosal_dma_chan_release(hosal_dma_chan_t chan)

Releases a DMA channel.

hosal_dma_chan_start(hosal_dma_chan_t chan)

Starts a transfer on the specified DMA channel.

hosal_dma_chan_stop(hosal_dma_chan_t chan)

Stops the transfer on the specified DMA channel.

hosal_dma_irq_callback_set(hosal_dma_chan_t chan, hosal_dma_irq_t pfn, void *p_arg)

Sets the interrupt callback function for a DMA channel.

hosal_dma_finalize(void)

Finalizes and releases the DMA controller resources.

📖 Related Tutorials: SPI Bus Communication · DMA Data Transfer

Flash Storage & File System

📂 hosal layer (hosal_flash.h)

hosal_flash_open(const char *name, unsigned int flags)

Opens and initializes a flash partition.

hosal_flash_info_get(hosal_flash_dev_t *p_dev, hosal_logic_partition_t *partition)

Gets the information of a flash partition.

hosal_flash_erase(hosal_flash_dev_t *p_dev, uint32_t off_set, uint32_t size)

Erases data in a specified region of the flash partition.

hosal_flash_write(hosal_flash_dev_t *p_dev, uint32_t *off_set, const void *in_buf, uint32_t in_buf_size)

Writes data to a specified location in the flash partition.

hosal_flash_erase_write(hosal_flash_dev_t *p_dev, uint32_t *off_set, const void *in_buf, uint32_t in_buf_size)

Erases and then writes data to a specified flash region.

hosal_flash_read(hosal_flash_dev_t *p_dev, uint32_t *off_set, void *out_buf, uint32_t out_buf_size)

Reads data from a specified location in the flash partition.

hosal_flash_close(hosal_flash_dev_t *p_dev)

Closes the flash partition device.

hosal_flash_raw_read(void *buffer, uint32_t address, uint32_t length)

Reads flash data directly by physical address.

hosal_flash_raw_write(void *buffer, uint32_t address, uint32_t length)

Writes flash data directly by physical address.

hosal_flash_raw_erase(uint32_t start_addr, uint32_t length)

Erases flash data directly by physical address.

📂 VFS file system (vfs.h)

aos_open(const char *path, int flags)

Opens a file or device (VFS file system interface).

aos_close(int fd)

Closes an open file handle (VFS file system interface).

aos_read(int fd, void *buf, size_t nbytes)

Reads data from a file (VFS file system interface).

aos_write(int fd, const void *buf, size_t nbytes)

Writes data to a file (VFS file system interface).

aos_ioctl(int fd, int cmd, unsigned long arg)

Performs a control command on a file (VFS file system interface).

aos_poll(struct pollfd *fds, int nfds, int timeout)

Polls multiple files for readable or writable status (VFS file system interface).

aos_fcntl(int fd, int cmd, int val)

Sets or queries the control attributes of a file (VFS file system interface).

aos_lseek(int fd, off_t offset, int whence)

Moves the read and write position of a file (VFS file system interface).

aos_sync(int fd)

Synchronizes buffered file data to the storage device (VFS file system interface).

aos_stat(const char *path, struct stat *st)

Gets the status information of a file or directory (VFS file system interface).

aos_unlink(const char *path)

Deletes the specified file (VFS file system interface).

aos_rename(const char *oldpath, const char *newpath)

Renames a file or directory (VFS file system interface).

aos_opendir(const char *path)

Opens a directory (VFS file system interface).

aos_closedir(aos_dir_t *dir)

Closes an opened directory (VFS file system interface).

aos_readdir(aos_dir_t *dir)

Reads one entry from a directory (VFS file system interface).

aos_mkdir(const char *path)

Creates a new directory (VFS file system interface).

aos_rmdir(const char *path)

Removes an empty directory (VFS file system interface).

aos_rewinddir(aos_dir_t *dir)

Resets the directory stream position to the beginning (VFS file system interface).

aos_telldir(aos_dir_t *dir)

Gets the current read position in a directory (VFS file system interface).

aos_seekdir(aos_dir_t *dir, long loc)

Sets the read position in a directory (VFS file system interface).

aos_statfs(const char *path, struct statfs *buf)

Gets file system space information (VFS file system interface).

aos_access(const char *path, int amode)

Checks whether a file exists and its access permissions (VFS file system interface).

📖 Related Tutorials: Flash Read/Write · MQTTS Connection (Read Certificates)

Wi-Fi Management

📂 Wi-Fi manager (wifi_mgmr_ext.h)

wifi_mgmr_psk_cal(char *password, char *ssid, int ssid_len, char *output)

Calculates the WPA PSK key from the password and SSID.

wifi_mgmr_drv_init(wifi_conf_t *conf)

Initializes the low-level Wi-Fi driver with the given configuration.

wifi_mgmr_init(void)

Initializes the Wi-Fi manager module.

wifi_mgmr_start(void)

Starts the Wi-Fi manager.

wifi_mgmr_start_background(wifi_conf_t *conf)

Starts the Wi-Fi manager in the background with the given config.

wifi_mgmr_get_wifi_channel_conf(wifi_conf_t *wifi_chan_conf)

Gets the current Wi-Fi channel configuration.

wifi_mgmr_sta_enable(void)

Enables Wi-Fi station (STA) mode.

wifi_mgmr_sta_disable(wifi_interface_t *interface)

Disables Wi-Fi station (STA) mode and releases the interface.

wifi_mgmr_sta_netif_get(void)

Gets the network interface of the station mode.

wifi_mgmr_ap_netif_get(void)

Gets the network interface of the AP (hotspot) mode.

wifi_mgmr_sta_mac_set(uint8_t mac[6])

Sets the MAC address used in station mode.

wifi_mgmr_sta_mac_get(uint8_t mac[6])

Gets the MAC address used in station mode.

wifi_mgmr_sta_ip_get(uint32_t *ip, uint32_t *gw, uint32_t *mask)

Gets the IP address, gateway and netmask of the station.

wifi_mgmr_sta_ip_set(uint32_t ip, uint32_t mask, uint32_t gw, uint32_t dns1, uint32_t dns2)

Manually sets the station IP, mask, gateway and DNS servers.

wifi_mgmr_sta_dns_get(uint32_t *dns1, uint32_t *dns2)

Gets the DNS server addresses used in station mode.

wifi_mgmr_sta_ip_unset(void)

Clears the manually-set station IP and restores automatic assignment.

wifi_mgmr_sta_connect_mid(wifi_interface_t *wifi_interface, char *ssid, char *psk, char *pmk, uint8_t *mac, uint8_t band, uint8_t chan_id, uint8_t use_dhcp, uint32_t flags)

Connects the station to a router with extra options like band and channel.

wifi_mgmr_sta_connect(wifi_interface_t *wifi_interface, char *ssid, char *psk, char *pmk, uint8_t *mac, uint8_t band, uint8_t chan_id)

Connects the station to the given router using SSID and password.

wifi_mgmr_sta_disconnect(void)

Disconnects the station from the router.

wifi_mgmr_sta_state_get(int *state)

Gets the current connection state of the station.

wifi_mgmr_sta_ps_enter(uint32_t ps_level)

Puts the station into Wi-Fi power-saving mode.

wifi_mgmr_sta_ps_exit()

Takes the station out of Wi-Fi power-saving mode.

wifi_mgmr_sta_autoconnect_enable(void)

Enables automatic reconnection for the station.

wifi_mgmr_sta_autoconnect_disable(void)

Disables automatic reconnection for the station.

wifi_mgmr_sta_autoconnect_set(int interval_second, int repeat_count)

Sets the reconnection interval and retry count.

wifi_mgmr_sta_ssid_set(char *ssid)

Sets the SSID that the station will connect to.

wifi_mgmr_sta_passphr_set(char *passphr)

Sets the Wi-Fi password for the station connection.

wifi_mgmr_sta_psk_set(char *psk) attribute ((deprecated ("use wifi_mgmr_sta_passphr_set instead")))

Sets the PSK key (deprecated, use wifi_mgmr_sta_passphr_set instead).

wifi_mgmr_sta_connect_ind_stat_get(wifi_mgmr_sta_connect_ind_stat_info_t *wifi_mgmr_ind_stat)

Gets the connection indication statistics of the station.

wifi_mgmr_ap_enable(void)

Enables the Wi-Fi AP (hotspot) mode.

wifi_mgmr_ap_mac_set(uint8_t mac[6])

Sets the MAC address of the AP hotspot.

wifi_mgmr_ap_mac_get(uint8_t mac[6])

Gets the MAC address of the AP hotspot.

wifi_mgmr_ap_ip_get(uint32_t *ip, uint32_t *gw, uint32_t *mask)

Gets the IP, gateway and netmask of the AP hotspot.

wifi_mgmr_ap_ip_set(uint32_t ip, uint32_t gw, uint32_t mask)

Manually sets the IP, gateway and netmask of the AP hotspot.

wifi_mgmr_ap_dhcp_get(int *enable)

Checks whether the DHCP service of the AP hotspot is enabled.

wifi_mgmr_ap_dhcp_enable(void)

Enables the DHCP auto-assignment service of the AP.

wifi_mgmr_ap_dhcp_disable(void)

Disables the DHCP auto-assignment service of the AP.

wifi_mgmr_ap_dhcp_range_get(uint32_t *ip, uint32_t *mask, int *start, int *end)

Gets the IP range that the AP DHCP assigns to clients.

wifi_mgmr_ap_dhcp_range_set(uint32_t ip, uint32_t mask, int start, int end)

Sets the IP range that the AP DHCP assigns to clients.

wifi_mgmr_ap_stop(wifi_interface_t *interface)

Stops the AP hotspot and releases its interface.

wifi_mgmr_ap_start(wifi_interface_t *interface, char *ssid, int hidden_ssid, char *passwd, int channel)

Starts an AP hotspot with SSID, password and channel.

wifi_mgmr_ap_chan_switch(wifi_interface_t *interface, int channel, uint8_t cs_count)

Switches the AP hotspot to a different channel.

wifi_mgmr_ap_start_adv(wifi_interface_t *interface, char *ssid, int hidden_ssid, char *passwd, int channel, uint8_t use_dhcp)

Starts an AP hotspot with an extra option to enable DHCP.

wifi_mgmr_ap_start_atcmd(wifi_interface_t *interface, char *ssid, int hidden_ssid, char *passwd, int channel, int max_sta_supported)

Starts an AP hotspot with a limit on connected stations.

wifi_mgmr_ap_sta_cnt_get(uint8_t *sta_cnt)

Gets the number of stations currently connected to the AP.

wifi_mgmr_ap_sta_info_get(struct wifi_sta_basic_info *sta_info, uint8_t idx)

Gets the info of a station connected to the AP by index.

wifi_mgmr_ap_sta_delete(uint8_t sta_idx)

Disconnects a specified station from the AP hotspot.

wifi_mgmr_ap_set_gateway(char *gateway)

Sets the gateway address of the AP hotspot.

wifi_mgmr_sniffer_enable(void)

Enables Wi-Fi sniffer (packet capture) mode.

wifi_mgmr_sniffer_disable(void)

Disables Wi-Fi sniffer (packet capture) mode.

wifi_mgmr_rate_config(uint16_t config)

Configures the Wi-Fi rate-related parameters.

wifi_mgmr_conf_max_sta(uint8_t max_sta_supported)

Sets the maximum number of stations that can join the AP.

wifi_mgmr_sniffer_register(void *env, sniffer_cb_t cb)

Registers a callback to receive captured sniffer packets.

wifi_mgmr_sniffer_unregister(void *env)

Unregisters the sniffer data callback.

wifi_mgmr_sniffer_register_adv(void *env, sniffer_cb_adv_t cb)

Registers an advanced sniffer callback with more packet info.

wifi_mgmr_sniffer_unregister_adv(void *env)

Unregisters the advanced sniffer callback.

wifi_mgmr_state_get(int *state)

Gets the overall Wi-Fi working state.

wifi_mgmr_detailed_state_get(int *state, int *state_detailed)

Gets the Wi-Fi state and its detailed substate.

wifi_mgmr_status_code_get(int *s_code)

Gets the status code of a failed Wi-Fi connection.

wifi_mgmr_rssi_get(int *rssi)

Gets the RSSI (signal strength) of the current connection.

wifi_mgmr_channel_get(int *channel)

Gets the current Wi-Fi channel in use.

wifi_mgmr_channel_set(int channel, int use_40Mhz)

Sets the Wi-Fi channel, optionally with 40 MHz bandwidth.

wifi_mgmr_all_ap_scan(wifi_mgmr_ap_item_t **ap_ary, uint32_t *num)

Scans all nearby Wi-Fi hotspots and returns the list.

wifi_mgmr_scan_filter_hidden_ssid(int filter)

Sets whether hidden-SSID hotspots are filtered from scans.

wifi_mgmr_scan(void *data, scan_complete_cb_t cb)

Starts a Wi-Fi scan and notifies via callback when done.

wifi_mgmr_scan_adv(void *data, scan_complete_cb_t cb, uint16_t *channels, uint16_t channel_num, const uint8_t bssid[6], const char *ssid, uint8_t scan_mode, uint32_t duration_scan)

Advanced scan filtered by channel, BSSID, SSID and more.

wifi_mgmr_cfg_req(uint32_t ops, uint32_t task, uint32_t element, uint32_t type, uint32_t length, uint32_t *buf)

Sends a general configuration request to the Wi-Fi manager.

wifi_mgmr_scan_complete_callback()

Callback invoked when a scan completes (for internal use).

wifi_mgmr_scan_ap(char *ssid, wifi_mgmr_ap_item_t *item)

Looks up a specific Wi-Fi hotspot by its SSID.

wifi_mgmr_scan_ap_all(wifi_mgmr_ap_item_t *env, uint32_t *param1, scan_item_cb_t cb)

Iterates over all scanned hotspots with a callback per item.

wifi_mgmr_raw_80211_send(uint8_t *pkt, int len)

Sends a raw 802.11 data frame directly.

wifi_mgmr_set_country_code(char *country_code)

Sets the Wi-Fi country code, affecting channels and power.

wifi_mgmr_get_country_code(char *country_code)

Gets the current Wi-Fi country code.

wifi_mgmr_set_hostname(char *hostname)

Sets the device hostname, used when reporting to DHCP.

wifi_mgmr_status_code_str(uint16_t status_code)

Converts a Wi-Fi status code into a readable string.

wifi_mgmr_beacon_interval_set(uint16_t beacon_int)

Sets the beacon interval of the AP hotspot.

wifi_mgmr_conn_result_get(uint16_t *status_code, uint16_t *reason_code)

Gets the status and reason codes of a failed connection.

wifi_mgmr_set_wifi_active_time(uint32_t ms)

Sets the Wi-Fi active time in milliseconds.

wifi_mgmr_set_listen_interval(uint16_t itv)

Sets the listen interval used in power-saving mode.

📂 Event mechanism (aos/yloop.h)

aos_register_event_filter(uint16_t type, aos_event_cb cb, void *priv)

Registers an event filter callback (event mechanism, used with event filtering).

aos_unregister_event_filter(uint16_t type, aos_event_cb cb, void *priv)

Unregisters an event filter callback (event mechanism, used with event filtering).

aos_post_event(uint16_t type, uint16_t code, unsigned long value)

Posts an event to trigger registered filter callbacks (event mechanism, used with event filtering).

aos_poll_read_fd(int fd, aos_poll_call_t action, void *param)

Registers a read event on a file descriptor to invoke the callback when readable.

aos_cancel_poll_read_fd(int fd, aos_poll_call_t action, void *param)

Cancels the read event registered on a file descriptor.

aos_post_delayed_action(int ms, aos_call_t action, void *arg)

Schedules an action to run after a delay in milliseconds.

aos_cancel_delayed_action(int ms, aos_call_t action, void *arg)

Cancels a previously scheduled delayed action.

aos_schedule_call(aos_call_t action, void *arg)

Schedules an action to run immediately on the event loop.

aos_loop_init(void)

Initializes the event loop.

aos_current_loop(void)

Gets the event loop of the current thread.

aos_loop_run(void)

Runs the event loop, processing events continuously.

aos_loop_exit(void)

Requests the event loop to exit.

aos_loop_destroy(void)

Destroys the event loop and frees its resources.

aos_loop_schedule_call(aos_loop_t *loop, aos_call_t action, void *arg)

Schedules an action to run on the given event loop.

aos_loop_schedule_work(int ms, aos_call_t action, void *arg1, aos_call_t fini_cb, void *arg2)

Schedules a delayed task on the event loop with a finish callback.

aos_cancel_work(void *work, aos_call_t action, void *arg1)

Cancels a task previously scheduled on the event loop.

📂 lwIP stack (tcpip.h)

tcpip_init(tcpip_init_done_fn tcpip_init_done, void *arg)

Initializes the lwIP TCP/IP protocol stack.

tcpip_try_callback(tcpip_callback_fn function, void *ctx)

Tries to post a callback to be executed on the tcpip thread.

tcpip_callback(tcpip_callback_fn function, void *ctx)

Posts a callback to be executed on the tcpip thread.

📂 Other APIs

wifi_sta_ip4_addr_get(uint32_t *addr, uint32_t *mask, uint32_t *gw, uint32_t *dns)

Gets the station IPv4 address, mask, gateway and DNS.

📖 Related Tutorials: Connect Wi-Fi · Soft-AP Mode · BluFi Provisioning

Network Communication (lwIP Socket)

📂 lwIP implementation (sockets.h)

lwip_accept(int s, struct sockaddr *addr, socklen_t *addrlen)

Accepts an incoming client connection (low-level implementation behind the accept() macro).

lwip_bind(int s, const struct sockaddr *name, socklen_t namelen)

Binds a local address to a socket (low-level implementation behind the bind() macro).

lwip_close(int s)

Closes a socket and frees its resources (low-level implementation behind the close() macro).

lwip_connect(int s, const struct sockaddr *name, socklen_t namelen)

Connects to a remote server (low-level implementation behind the connect() macro).

lwip_fcntl(int s, int cmd, int val)

Runs an fcntl control command on a socket (low-level implementation behind the fcntl() macro).

lwip_getpeername(int s, struct sockaddr *name, socklen_t *namelen)

Gets the address of the connected peer (low-level implementation behind the getpeername() macro).

lwip_getsockname(int s, struct sockaddr *name, socklen_t *namelen)

Gets the local address of a socket (low-level implementation behind the getsockname() macro).

lwip_getsockopt(int s, int level, int optname, void *optval, socklen_t *optlen)

Reads a socket option value (low-level implementation behind the getsockopt() macro).

lwip_inet_ntop(int af, const void *src, char *dst, socklen_t size)

Converts a binary IP address into a text string (low-level implementation behind the inet_ntop() macro).

lwip_inet_pton(int af, const char *src, void *dst)

Converts an IP address text string into binary form (low-level implementation behind the inet_pton() macro).

lwip_ioctl(int s, long cmd, void *argp)

Runs an ioctl control command on a socket (low-level implementation behind the ioctl() macro).

lwip_listen(int s, int backlog)

Listens for incoming connections (low-level implementation behind the listen() macro).

lwip_poll(struct pollfd *fds, nfds_t nfds, int timeout)

Polls the status of multiple sockets (low-level implementation behind the poll() macro).

lwip_read(int s, void *mem, size_t len)

Reads data from a socket (low-level implementation behind the read() macro).

lwip_readv(int s, const struct iovec *iov, int iovcnt)

Reads data into multiple buffers (low-level implementation behind the readv() macro).

lwip_recv(int s, void *mem, size_t len, int flags)

Receives data from a socket (low-level implementation behind the recv() macro).

lwip_recvfrom(int s, void *mem, size_t len, int flags, struct sockaddr *from, socklen_t *fromlen)

Receives data and gets the sender address (low-level implementation behind the recvfrom() macro).

lwip_recvmsg(int s, struct msghdr *message, int flags)

Receives a message with optional control information (low-level implementation behind the recvmsg() macro).

lwip_select(int maxfdp1, fd_set *readset, fd_set *writeset, fd_set *exceptset, struct timeval *timeout)

Monitors multiple sockets for events at once (low-level implementation behind the select() macro).

lwip_send(int s, const void *dataptr, size_t size, int flags)

Sends data over a socket (low-level implementation behind the send() macro).

lwip_sendmsg(int s, const struct msghdr *message, int flags)

Sends a message with control information (low-level implementation behind the sendmsg() macro).

lwip_sendto(int s, const void *dataptr, size_t size, int flags, const struct sockaddr *to, socklen_t tolen)

Sends data to a specified destination address (low-level implementation behind the sendto() macro).

lwip_setsockopt(int s, int level, int optname, const void *optval, socklen_t optlen)

Sets a socket option (low-level implementation behind the setsockopt() macro).

lwip_shutdown(int s, int how)

Shuts down sending and receiving on a socket (low-level implementation behind the shutdown() macro).

lwip_socket(int domain, int type, int protocol)

Creates a socket (low-level implementation behind the socket() macro).

lwip_socket_thread_cleanup(void)

Cleans up and exits the socket worker thread (low-level implementation behind the socket() API).

lwip_socket_thread_init(void)

Initializes the socket worker thread (low-level implementation behind the socket() API).

lwip_write(int s, const void *dataptr, size_t size)

Writes data to a socket (low-level implementation behind the write() macro).

lwip_writev(int s, const struct iovec *iov, int iovcnt)

Writes data from multiple buffers (low-level implementation behind the writev() macro).

📂 Macro API (standard socket functions)

accept(sock, addr, addrlen)

Accepts a client connection and returns a new connected socket (TCP server).

bind(sock, addr, addrlen)

Binds a socket to a local address and port (servers must bind first).

close(sock)

Closes a socket and frees its connection resources.

connect(sock, addr, addrlen)

Connects to a remote server address and port (TCP client).

fcntl(int s, int cmd, ...)

Sets socket descriptor attributes (e.g. non-blocking mode).

freeaddrinfo(res)

Frees the address list returned by getaddrinfo.

getaddrinfo(nodname, servname, hints, res)

Resolves a hostname and service into an address list (with DNS support).

getpeername(sock, name, namelen)

Gets the peer (remote end) address and port of a connection.

getsockname(sock, name, namelen)

Gets a socket's own address and port.

getsockopt(sock, level, optname, optval, optlen)

Gets a socket's current option value.

inet_addr(cp)

Converts a dotted-decimal string into a 32-bit network-order address.

inet_aton(cp, addr)

Converts a dotted-decimal string into an IP address struct.

inet_ntoa(addr)

Converts an IP address struct into a dotted-decimal string.

ioctl(sock, cmd, argp)

Runs a control command on a socket (e.g. query readable bytes).

listen(sock, backlog)

Puts a socket into listening state, waiting for client connections (TCP server).

poll(fds, nfds, timeout)

Like select: polls the status of multiple sockets.

read(sock, mem, len)

Reads data from a socket (same as recv).

recv(sock, buf, len, flags)

Receives data from a connected socket (TCP receive, may block).

recvfrom(sock, buf, len, flags, from, fromlen)

Receives a datagram and returns the sender address (UDP receive).

select(maxfdp1, readset, writeset, exceptset, timeout)

Monitors multiple sockets for readability/writability/errors at once (multiplexing).

send(sock, buf, len, flags)

Sends data over a connected socket (TCP send).

sendto(sock, buf, len, flags, to, tolen)

Sends a datagram to a specified address (UDP send, connectionless).

setsockopt(sock, level, optname, optval, optlen)

Sets socket options (timeout, address reuse, buffer size, etc.).

shutdown(sock, how)

Shuts down a socket's send or receive direction (half-close).

socket(domain, type, protocol)

Creates a socket and returns its file descriptor (macro for lwip_socket).

write(sock, dataptr, len)

Writes data to a socket (same as send).

📖 Related Tutorials: TCP Client · TCP Server · UDP Client · UDP Broadcast · UDP Multicast · HTTP Request · Soft-AP Mode

SNTP Time Sync

📂 SNTP time sync

sntp_getoperatingmode(void)

Gets the current SNTP operating mode.

sntp_init(void)

Initializes and starts the SNTP time sync service.

sntp_stop(void)

Stops the SNTP time sync service.

sntp_enabled(void)

Checks whether SNTP is enabled.

sntp_setserver(u8_t idx, const ip_addr_t *addr)

Sets the NTP server address by its index.

sntp_getserver(u8_t idx)

Gets the NTP server address by its index.

sntp_getreachability(u8_t idx)

Checks by index whether the NTP server is reachable.

sntp_setservername(u8_t idx, const char *server)

Sets the NTP server hostname by its index.

sntp_getservername(u8_t idx)

Gets the NTP server hostname by its index.

sntp_servermode_dhcp(int set_servers_from_dhcp)

Enables or disables taking NTP servers from DHCP.

sntp_get_time(uint32_t *seconds, uint32_t *frags)

Gets the time obtained from SNTP synchronization.

sntp_settimesynccb(ntp_sync_cb cb)

Registers a callback invoked when time sync completes.

sntp_setupdatedelay(uint32_t delay)

Sets the delay between two time sync updates.

sntp_getoperatingmode(void)

Gets the current SNTP operating mode.

sntp_init(void)

Initializes and starts the SNTP time sync service.

sntp_stop(void)

Stops the SNTP time sync service.

sntp_enabled(void)

Checks whether SNTP is enabled.

sntp_setserver(u8_t idx, const ip_addr_t *addr)

Sets the NTP server address by its index.

sntp_getserver(u8_t idx)

Gets the NTP server address by its index.

sntp_getreachability(u8_t idx)

Checks by index whether the NTP server is reachable.

sntp_setservername(u8_t idx, const char *server)

Sets the NTP server hostname by its index.

sntp_getservername(u8_t idx)

Gets the NTP server hostname by its index.

sntp_servermode_dhcp(int set_servers_from_dhcp)

Enables or disables taking NTP servers from DHCP.

utils_time_date_from_epoch(unsigned int epoch, utils_time_date_t *date)

Converts an epoch timestamp into a date and time structure.

📖 Related Tutorials: SNTP Time Sync

BLE & Provisioning

📂 BLE stack (bluetooth.h)

bt_enable(bt_ready_cb_t cb)

Initializes and enables the Bluetooth stack.

bt_set_name(const char *name)

Sets the name of the Bluetooth device.

bt_get_name(void)

Gets the name of the Bluetooth device.

bt_set_id_addr(const bt_addr_le_t *addr)

Sets the local Bluetooth identity address.

bt_id_get(bt_addr_le_t *addrs, size_t *count)

Gets the configured Bluetooth identity addresses.

bt_id_create(bt_addr_le_t *addr, u8_t *irk)

Creates a new Bluetooth identity.

bt_id_reset(u8_t id, bt_addr_le_t *addr, u8_t *irk)

Resets the specified Bluetooth identity.

bt_id_delete(u8_t id)

Deletes the specified Bluetooth identity.

bt_le_adv_update_data(const struct bt_data *ad, size_t ad_len, const struct bt_data *sd, size_t sd_len)

Updates the advertising data and scan response data.

bt_le_adv_stop(void)

Stops BLE advertising.

bt_le_scan_cb_t(const bt_addr_le_t *addr, s8_t rssi, u8_t adv_type, struct net_buf_simple *buf)

BLE scan callback type, called when a device is found.

bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb)

Starts BLE scanning with the given parameters.

bt_le_scan_stop(void)

Stops BLE scanning.

bt_le_whitelist_add(const bt_addr_le_t *addr)

Adds a device to the scan whitelist.

bt_le_whitelist_rem(const bt_addr_le_t *addr)

Removes a device from the scan whitelist.

bt_le_whitelist_clear(void)

Clears the scan whitelist.

bt_le_set_chan_map(u8_t chan_map[5])

Sets the BLE channel map to use.

bt_data_parse(struct net_buf_simple *ad, bool (*func)(struct bt_data *data, void *user_data), void *user_data)

Parses the AD structures inside advertising data.

bt_le_oob_get_local(u8_t id, struct bt_le_oob *oob)

Gets the local out-of-band (OOB) pairing data.

bt_br_discovery_cb_t(struct bt_br_discovery_result *results, size_t count)

Classic Bluetooth discovery callback type.

bt_br_discovery_start(const struct bt_br_discovery_param *param, struct bt_br_discovery_result *results, size_t count, bt_br_discovery_cb_t cb)

Starts discovering classic Bluetooth devices.

bt_br_discovery_stop(void)

Stops discovering classic Bluetooth devices.

bt_disable(void)

Disables and tears down the Bluetooth stack.

bt_br_oob_get_local(struct bt_br_oob *oob)

Gets the local OOB data for classic Bluetooth.

bt_addr_from_str(const char *str, bt_addr_t *addr)

Parses a string into a Bluetooth address.

bt_addr_le_from_str(const char *str, const char *type, bt_addr_le_t *addr)

Parses a LE Bluetooth address with its address type from a string.

bt_br_set_discoverable(bool enable)

Sets the classic Bluetooth discoverable mode.

bt_br_set_connectable(bool enable)

Sets the classic Bluetooth connectable mode.

bt_unpair(u8_t id, const bt_addr_le_t *addr)

Unpairs and unbonds a paired device.

bt_foreach_bond(u8_t id, void (*func)(const struct bt_bond_info *info, void *user_data), void *user_data)

Iterates over all bonded devices.

bt_br_write_local_name(char *name)

Writes the local name for classic Bluetooth.

bt_br_write_eir(u8_t fec, u8_t *data)

Writes the EIR extended data for classic Bluetooth.

📂 BluFi provisioning (blufi_init.h)

_blufi_host_and_cb_init(_blufi_callbacks_t *example_callbacks)

Initializes BLUFI provisioning and registers its callbacks.

btc_blufi_protocol_handler(uint8_t type, uint8_t *data, int len)

Handles data received by the BLUFI protocol.

btc_blufi_send_encap(uint8_t type, uint8_t *data, int data_len)

Encapsulates and sends a BLUFI packet.

btc_blufi_set_callbacks(_blufi_callbacks_t *callbacks)

Sets the BLUFI callback set.

btc_blufi_cb_deep_copy(btc_msg_t *msg, void *p_dest, void *p_src)

Deep copies a BLUFI callback message.

btc_blufi_cb_deep_free(btc_msg_t *msg)

Frees the memory of a deep-copied message.

📖 Related Tutorials: Ai-WB2 BLE Introduction · BLE Advertising (iBeacon) · BluFi Provisioning

MQTT & Cloud Platforms

📂 Axk MQTT client (mqtt_client.h)

axk_mqtt_client_init(const axk_mqtt_client_config_t *config)

Initializes an MQTT client (Ai-Thinker MQTT).

axk_mqtt_client_set_uri(axk_mqtt_client_handle_t client, const char *uri)

Sets the MQTT broker URI (Ai-Thinker MQTT).

axk_mqtt_client_start(axk_mqtt_client_handle_t client)

Starts the MQTT client and connects (Ai-Thinker MQTT).

axk_mqtt_client_reconnect(axk_mqtt_client_handle_t client)

Reconnects to the MQTT broker (Ai-Thinker MQTT).

axk_mqtt_client_disconnect(axk_mqtt_client_handle_t client)

Disconnects the current MQTT connection (Ai-Thinker MQTT).

axk_mqtt_client_stop(axk_mqtt_client_handle_t client)

Stops the MQTT client and releases it (Ai-Thinker MQTT).

axk_mqtt_client_subscribe(axk_mqtt_client_handle_t client, const char *topic, int qos)

Subscribes to an MQTT topic (Ai-Thinker MQTT).

axk_mqtt_client_unsubscribe(axk_mqtt_client_handle_t client, const char *topic)

Unsubscribes from an MQTT topic (Ai-Thinker MQTT).

axk_mqtt_client_publish(axk_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain)

Publishes a message to a topic (Ai-Thinker MQTT).

axk_mqtt_client_enqueue(axk_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain, bool store)

Queues a message for sending later (Ai-Thinker MQTT).

axk_mqtt_client_destroy(axk_mqtt_client_handle_t client)

Destroys the MQTT client and frees resources (Ai-Thinker MQTT).

axk_mqtt_set_config(axk_mqtt_client_handle_t client, const axk_mqtt_client_config_t *config)

Updates the MQTT client configuration (Ai-Thinker MQTT).

axk_mqtt_client_register_event(axk_mqtt_client_handle_t client, axk_mqtt_event_id_t event, axk_event_handler_t event_handler, void *event_handler_arg)

Registers an MQTT event callback (Ai-Thinker MQTT).

axk_mqtt_client_get_outbox_size(axk_mqtt_client_handle_t client)

Gets the length of the outbox message queue (Ai-Thinker MQTT).

📂 Aliyun IoT SDK (aiot_mqtt_api.h)

aiot_mqtt_init(void)

Initializes the Alibaba Cloud IoT MQTT client (Alibaba Cloud IoT SDK).

aiot_mqtt_setopt(void *handle, aiot_mqtt_option_t option, void *data)

Sets an MQTT connection option (Alibaba Cloud IoT SDK).

aiot_mqtt_deinit(void **handle)

Deinitializes and frees the MQTT client (Alibaba Cloud IoT SDK).

aiot_mqtt_connect(void *handle)

Connects to the MQTT broker (Alibaba Cloud IoT SDK).

aiot_mqtt_disconnect(void *handle)

Disconnects the MQTT connection (Alibaba Cloud IoT SDK).

aiot_mqtt_reconn(void *handle)

Attempts to reconnect to the MQTT broker (Alibaba Cloud IoT SDK).

aiot_mqtt_heartbeat(void *handle)

Sends a heartbeat message to keep the connection alive (Alibaba Cloud IoT SDK).

aiot_mqtt_process(void *handle)

Processes MQTT I/O and callbacks (Alibaba Cloud IoT SDK).

aiot_mqtt_pub(void *handle, char *topic, uint8_t *payload, uint32_t payload_len, uint8_t qos)

Publishes a message to a specified topic (Alibaba Cloud IoT SDK).

aiot_mqtt_sub(void *handle, char *topic, aiot_mqtt_recv_handler_t handler, uint8_t qos, void *userdata)

Subscribes to a topic with a receive callback (Alibaba Cloud IoT SDK).

aiot_mqtt_unsub(void *handle, char *topic)

Unsubscribes from a specified topic (Alibaba Cloud IoT SDK).

aiot_mqtt_recv(void *handle)

Receives one MQTT message actively (Alibaba Cloud IoT SDK).

📂 AWS IoT SDK (aws_iot_mqtt_client_interface.h)

aws_iot_mqtt_init(AWS_IoT_Client *pClient, const IoT_Client_Init_Params *pInitParams)

Initializes the AWS IoT MQTT client (AWS IoT SDK).

aws_iot_mqtt_connect(AWS_IoT_Client *pClient, const IoT_Client_Connect_Params *pConnectParams)

Establishes an MQTT connection with connect params (AWS IoT SDK).

aws_iot_mqtt_publish(AWS_IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen, IoT_Publish_Message_Params *pParams)

Publishes a message to a specified topic (AWS IoT SDK).

aws_iot_mqtt_subscribe(AWS_IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen, QoS qos, pApplicationHandler_t pApplicationHandler, void *pApplicationHandlerData)

Subscribes to a topic with a message handler (AWS IoT SDK).

aws_iot_mqtt_resubscribe(AWS_IoT_Client *pClient)

Resubscribes to all previously subscribed topics (AWS IoT SDK).

aws_iot_mqtt_unsubscribe(AWS_IoT_Client *pClient, const char *pTopicFilter, uint16_t topicFilterLen)

Unsubscribes from a specified topic filter (AWS IoT SDK).

aws_iot_mqtt_disconnect(AWS_IoT_Client *pClient)

Disconnects the AWS IoT MQTT connection (AWS IoT SDK).

aws_iot_mqtt_yield(AWS_IoT_Client *pClient, uint32_t timeout_ms)

Keeps the connection alive and processes MQTT I/O and callbacks (AWS IoT SDK).

aws_iot_mqtt_attempt_reconnect(AWS_IoT_Client *pClient)

Attempts to reconnect to AWS IoT (AWS IoT SDK).

📖 Related Tutorials: MQTT Connection · MQTTS Connection · Connect Alibaba Cloud IoT · Connect AWS IoT · Connect Tencent Cloud IoT

---

FAQ

❓ Can't find the API I want?
This page only covers the interfaces used in this site's tutorials. For the complete API list, see the official SDK source headers: the include directory of each module under components/ (e.g. components/hosal_driver/include/hosal_uart.h), or the official repository Ai-Thinker-Open/Ai-Thinker-WB2.

❓ Why are there several API prefixes like bl_, hosal_, and bl_os_ for the same kind of function?
It's the SDK's layered design: bl_* interfaces are chip-level (directly manipulating registers), hosal_* is the unified hardware abstraction layer (hides chip differences, recommended), bl_os_* is the OS adaptation layer, axk_* is the Ai-Thinker wrapper, and aiot_* / aws_iot_* / IOT_Template_* are the official SDKs of the respective cloud platforms. Beginners should prefer hosal_* and the tutorial examples.

❓ Can't remember the function parameters?
Every category ends with "Related Tutorials" pointing to complete compilable example projects — just follow the example code's call style; each tutorial also has an "API Summary for This Tutorial" section explaining every parameter.

Usage Tips

When programming, first think "what do I want to do" → find the matching category on this page → copy the call style from the related tutorial → tweak the parameters as needed. Interfaces may shift slightly after SDK upgrades — defer to your local SDK headers.