Development Environment Setup When Using Tuya Wi-Fi SDK
Last updated
Last updated
Version
Description
Date
1.0.0
The initial version.
20200601
The Tuya device OS is a proprietary IoT operating system, which provides abundant components and you can make SDK customization according to your business requirements. It has the characteristic of lightweight, interconnection, secure transmission, fully functional components and rapid development, effectively lowering the development threshold and shortening the development cycle. It can be widely used in wearable devices, video monitors, compute gateways, smart speakers, smart locks and other smart home appliances.
The Tuya Wi-Fi SDK is developed based on Tuya device OS technology and tailored according to the Wi-Fi application in the Internet of Things scenarios. It is applicable to any Wi-Fi chip that is configured according to the Tuya Smart platform interconnection rules.
For different developing requirement, Tuya provides different strategies and services. If you have independent development ability and can develop the underlying hardware and drivers, you can use the provided SDK to adapt to the abstract interface of the development environment, so as to achieve higher flexibility for device functions.
This topic describes how to set up the development environment for Tuya Wi-Fi SDK. The development environment includes the tool chain, script, library file and other information. However, it is not necessary if you use the module provided by Tuya, or Tuya has designed the SDK to work well with the specific chip platforms. The SDK products released by Tuya have completed the compilation adaptation, interface adaptation and other configuration, you can see the README.md file for more information.
The development environment includes the tool chain, script, library file and other information provided by the chip manufacturer, which are necessary to compile the Tuya Wi-Fi SDK. Therefore, you must set up the development environment according to the following rules to compile the SDK and firmware.
Collect the tools, libraries, and scripts of the genuine chip, send them together with compilation option and functional requirement to your Tuya account manager.
Upon receiving the material, Tuya engineers make adaptation to the toolchain of genuine chip according your requirement. Taking the RTL8720CF as an example, see the following description for details.
Create a toolchain folder under the root directory of the tool chain provided by the chip manufacturer.
Create a build_path folder to export the compilation location for the toolchain.
TUYA_SDK_TOOLCHAIN_ZIP: identifies the location of toolchain compression package. During the compilation, if this value is detected, the compression package will be decompressed.
TUYA_SDK_BUILD_PATH: identifies the location of compiler. The Tuya automated compilation system uses this path as a prefix for the compilation tool.
Create a platform.mk folder to interact with the Tuya continuous integration system, and perform automated SDK compilation according to your requirement.
TUYA_PLATFORM_DIR: identifies the location of current development environment.
TUYA_PLATFORM_CFLAGS: adds CFLAGS and the requested compilation options.
Create a build.conf folder to customize your functional features requirement. For more information, see Appendix.
After you receive the compiled Tuya Wi-Fi SDK, you can adjust the firmware compilation process according to the following section to compile the firmware, and then burn it to the chip for implementation.
After decompressing the compiled Tuya Wi-Fi SDK, the directory is shown in the following table.
Directory
Subdirectory
Description
Reference
apps
/
Stores your application and samples of the Tuya Wi-Fi SDK. It is better to create a folder for every application or sample.
See the sample of Tuya Wi-Fi SDK for usage instruction.
one_plug_demo
Contains one or more samples.
N/A.
sdk
sdk
Stores the header files and library files of Tuya Wi-Fi SDK.
See the API reference section for details.
include
Stores all of the APIs provided by Tuya Wi-Fi SDK.
N/A
lib
The libtuya_iot.a file that is compiled by Tuya Wi-Fi SDK.
N/A
platforms
/
Stores the development environment and toolchains of Tuya Wi-Fi SDK. The platform is an empty folder at first. Related toolchains are downloaded automatically to this folder during compiling.
N/A.
build_app.sh
/
The compiling entry point for applications and samples. Sets up development and compilation environment.
N/A.
CHANGELOG.md
/
Records all the notable changes for each version.
N/A.
README.md
/
User guide written in Markdown.
N/A.
Based on this environment, Tuya provides a set of compilation features. You can also customize the compilation process. The following instructions taking the one_plug_demo to describe the firmware compilation process.
one_plug_demo: downloads the development environment packages to perform the compilation script. Alternatively, the shell script and makefile are supported for compilation.
./apps/one_plug_demo/build.sh: enters into the development environment, run the compile script, and make packages.
The compiled product will be saved to the apps/one_plug_demo/output/ directory.
The tuya_common is stored in the Tuya Wi-Fi SDK package.
It is included in the development environment that are configured by running build_app.sh. You can directly use the related functions in the tuya_common folder.
The tuya_os_adapter uses a widely applicable registration method, which provides interface description and definition, and realizes the relevant interfaces and registration, so as to achieve the platform independence of Tuya Wi-Fi SDK. You need to implement tuya_os_adapter manually and place it in the root directory of development environment.
The Tuya HAL System provides several interfaces of the operating system. For Linux platforms, the Tuya Wi-Fi SDK provides a set of widely-used system related interfaces. These interfaces can be implemented for your customization requirements.
os_adapter_get_systemtickcount
Description
Gets the current ticket value of the system.
Parameter
None.
Return value
The current tick value of the system.
os_adapter_get_tickratems
Description
How many milliseconds to get a ticket for the system.
Parameter
None.
Return value
How many milliseconds is 1 ticket in the system.
os_adapter_system_sleep
Description
Thread sleep.
Parameter
Input or output
Parameter name
Description
[in]
msTime
System sleep time, unit: ms.
Return value
None.
os_adapter_system_isrstatus
Description
Gets whether the system is in the interrupt routine.
Parameter
None.
Return value
TRUE: in interrupt routine.
FALSE: not in interrupt routine.
os_adapter_system_reset
Description
Restarts the system.
Parameter
None.
Return value
None.
os_adapter_system_getheapsize
Description
Gets the remaining memory size of the system.
Parameter
None.
Return value
Remaining memory.
os_adapter_system_get_rst_info
Description
Gets the reason for system restart.
TY_RST_REASON_E
——
TY_RST_POWER_OFF
Power restart
TY_RST_HARDWARE_WATCHDOG
Hardware watchdog reset
TY_RST_FATAL_EXCEPTION
Exception
TY_RST_SOFTWARE_WATCHDOG
Software watchdog restart
TY_RST_SOFTWARE
Software reset
TY_RST_DEEPSLEEP
Deep sleep
TY_RST_HARDWARE
Hardware reset
TY_RST_OTHER
Other causes
TY_RST_UNSUPPORT
Not supported
Parameter
None.
Return value
Reason for restart.
os_adapter_get_random_data
Description
Generates a random number.
Parameter
Input or output
Parameter name
Description
[in]
range
Random number range
Return value
A random value.
Notice
True random number.
os_adapter_set_cpu_lp_mode
Description
Sets CPU low power consumption mode.
mode
——
TY_CPU_SLEEP
Low power consumption mode, os auto wake up, within 15mA.
TY_CPU_DEEP_SLEEP
Deep sleep.
Parameter
Input or output
Parameter name
Description
[in]
en
Whether to enable CPU low power mode.
[in]
mode
CPU low power mode.
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_CPU_LPMODE_SET_FAILED: fail
Tuya HAL Memory provides several interfaces for memory application and release. For Linux platforms, the Tuya Wi-Fi SDK provides a set of widely-used system related interfaces. These interfaces can be implemented for your customization requirements.
os_adapter_system_malloc
Description
Memory allocation.
Parameter
Input or output
Parameter name
Description
[in]
size
Allocated memory size.
Return value
NULL: Memory allocation failed.
Other: Assigned successfully.
Notice
Other file APIs of the adaptation layer need to apply for memory, and all calls to os_adapter_system_malloc.
os_adapter_system_free
Description
Frees up memory.
Parameter
Input or output
Parameter name
Description
[in]
ptr
Free memory address.
Return value
None.
Notice
The other file APIs of the adaptation layer need to release memory, and all calls to os_adapter_system_free.
Tuya HAL Semaphore provides several interfaces for semaphore operations. For Linux platforms, the Tuya Wi-Fi SDK provides a set of widely-used system related interfaces. These interfaces can be implemented for your customization requirements.
os_adapter_semaphore_create_init
Description
Creates and initializes semaphore.
Parameter
Input or output
Parameter name
Description
[out]
pHandle
Pointer to semaphore handle.
[in]
semCnt
Number of initialization semaphores.
[in]
sem_max
Maximum semaphore number.
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_MALLOC_FAILED: failed to apply for memory
OPRT_OS_ADAPTER_THRD_CREAT_FAILED: fail
os_adapter_semaphore_wait
Description
Waits for semaphore.
Parameter
Input or output
Parameter name
Description
[in]
semHandle
Semaphore handle
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_SEM_WAIT_FAILED: fail
os_adapter_semaphore_post
Description
Sends semaphore.
Parameter
Input or output
Parameter name
Description
[in]
mutexHandle
Semaphore handle.
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_SEM_POST_FAILED: fail
Notice
You need to distinguish between thread context and interrupt context.
os_adapter_semaphore_release
Description
Frees up semaphore resources.
Parameter
Input or output
Parameter name
Description
[in]
semHandle
Semaphore handle
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_SEM_RELEASE_FAILED: fail
Tuya HAL Mutex provides a mutex operation interface, these interfaces can be implemented for your customization requirements. If it is a Linux platform, it may not be provided. Tuya Wi-Fi SDK provides a set of common interfaces for Linux platforms.
os_adapter_mutex_create_init
Description
Creates and initializes a mutex.
Parameter
Input or output
Parameter name
Description
[out]
pMutexHandle
Pointer to the mutex handle
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_MALLOC_FAILED: failed to apply for memory
OPRT_OS_ADAPTER_MUTEX_CREAT_FAILED: fail
os_adapter_mutex_release
Description
Releases mutex resources.
Parameter
Input or output
Parameter name
Description
[in]
mutexHandle
Semaphore handle
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_MUTEX_RELEASE_FAILED: fail
os_adapter_mutex_lock
Description
Locks mutex.
Parameter
Input or output
Parameter name
Description
[in]
mutexHandle
Semaphore handle
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_MUTEX_LOCK_FAILED: fail
os_adapter_mutex_unlock
Description
Unlocks mutex.
Parameter
Input or output
Parameter name
Description
[in]
mutexHandle
Semaphore handle
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_MUTEX_UNLOCK_FAILED: fail
Notice
You need to distinguish between thread context and interrupt context.
Tuya HAL Thread provides interfaces for thread creation and release, these interfaces can be implemented for your customization requirements. If it is a Linux platform, it may not be provided. Tuya Wi-Fi SDK provides a set of common interfaces for Linux platforms.
os_adapter_thread_create
Description
Creates and starts a thread.
Parameter
Input or output
Parameter name
Description
[out]
thread
Pointer to thread handle
[in]
name
Thread name
[in]
stack_size
Thread stack size, unit is byte, not 4 bytes
[in]
priority
Thread priority
[in]
func
Thread function
[in]
arg
User parameters
Return value
OPRT_OS_ADAPTER_OK: create success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_MALLOC_FAILED: failed to apply for memory
OPRT_OS_ADAPTER_THRD_CREAT_FAILED: fail
Notice
The stack_size parameter is 1 byte as a unit.
Tuya business will use six thread priorities of 0, 1, 2, 3, 4, and 5, a lower number indicates a higher priority.
os_adapter_thread_release
Description
Releases thread resources.
Parameter
Input or output
Parameter name
Description
[in]
thread
Semaphore handle
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_THRD_RELEASE_FAILED: fail
os_adapter_thread_is_self
Description
Determines whether the running context is in the specified thread.
Parameter
Input or output
Parameter name
Description
[in]
thread
Semaphore handle
[out]
is_self
Is the specified thread
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_THRD_JUDGE_SELF_FAILED: fail
Tuya HAL Watch Dog provides an interface for Watch Dog creation and refresh, which can be implemented for your customization requirements.
os_adapter_watchdog_init_start
Description
Initializes and runs watchdog.
Parameter
Input or output
Parameter name
Description
[in]
timeval
Watchdog time
Return value
int Watchdog time actually set by the chip.
Notice
The upper layer of the graffiti will set the watchdog time to 60s. If the chip does not support the 60s watchdog, the actual set time will be returned.
os_adapter_watchdog_refresh
Description
Refreshes watch dog.
Return value
void
os_adapter_watchdog_stop
Description
Stops watch dog.
Return value
void
Tuya HAL RTC provides an interface for RTC operation and requires different platforms to implement it, which can be implemented for your customization requirements.
os_adapter_rtc_init
Description
Initializes the internal RTC of the chip.
Return value
void no return value.
os_adapter_rtc_set_time
Description
Sets time to RTC inside the chip.
Parameter
Input or output
Parameter name
Description
[in]
write_time
Timestamp in seconds
Return value
Void.
os_adapter_rtc_get_time
Description
Gets the time from the internal RTC clock of chip.
Parameter
Input or output
Parameter name
Description
[in]
void
None.
Return value
time_t RTC: time inside the chip, in seconds.
Tuya HAL OTA provides an interface for OTA operation, which requires different platforms to implement it.
os_adapter_ota_start_inform
Description
Sends the notification of upgrade start.
Parameter
Input or output
Parameter name
Description
[in]
file_size
Total firmware upgrade package size.
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_MALLOC_FAILED: failed to apply for memory
OPRT_OS_ADAPTER_OTA_START_INFORM_FAILED: fail
Notice
Inform the HAL layer that the OTA upgrade is about to start. The HAL layer needs to apply in advance to upgrade OTA management resources and record the size of the OTA firmware package.
os_adapter_ota_data_process
Description
Processes The OTA packet.
Parameter
Input or output
Parameter name
Description
[in]
total_len
The OTA upgrade firmware total size.
[in]
offset
The offset of data pointer in OTA upgrade firmware.
[in]
data
The buffer pointer of this OTA packet.
[in]
len
The length of this OTA packet.
[out]
remain_len
Length of data packets that have been delivered but not processed
[in]
pri_data
Keep parameters, not used for now
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_INVALID_PARM: pass parameter error
OPRT_OS_ADAPTER_MALLOC_FAILED: failed to apply for memory
OPRT_OS_ADAPTER_OTA_PROCESS_FAILED: fail
Notice
This function is used to support OTA upgrade, which needs to be implemented in conjunction with the Tuya upgrade package pull service. There are currently two upgrade methods in Tuya:
HTTP firmware upgrade.
Private serial port protocol firmware upgrade; but for the HAL function, there is no need to care about the source of the data packet.
During the OTA upgrade process, Tuya Wi-Fi SDK will receive packets in a loop and notify this function to the OTA data packet. This function completes the work of writing the OTA data packet into the flash.
os_adapter_ota_end_inform
Description
Informs the end of OTA data download.
Parameter
Input or output
Parameter name
Description
[in]
reset
Inform the hal layer whether the download needs to be restarted.
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_OTA_VERIFY_FAILED: verification failed
OPRT_OS_ADAPTER_OTA_END_INFORM_FAILED: fail
Notice
This notification function will be called after the transmission of the OTA data packet is completed, which needs to be implemented in the secondary function: 1. Release the resources requested by the HAL layer at the beginning of OTA. 2. Do firmware integrity check 3. Modify the OTA parameter area and run the new firmware after restarting 4. Decide whether to restart according to the input parameter reset (restart logic after successful Tuya serial port upgrade is not implemented in this API)
Tuya HAL Storage provides an interface for flash operations, which can be implemented for your customization requirements.
os_adapter_flash_read
Description
Reads data from flash.
Parameter
Input or output
Parameter name
Description
[in]
addr
The first flash address read.
[out]
dst
The buffer pointer that receives the read data.
[in]
size
The size of the buffer read.
Return value
0: success；
Other: failure error code
Notice
Since it is possible for multiple threads on the Tuya upper layer to call the OS_adapter_FLASH layer API interface simultaneously, the os_adapter_flash_read, OS_adapter_flash_write, and OS_adapter_flash_erase three operation functions need to share the mutex. If the called chip Flash API itself is mutually exclusive, no locking is required.If the calling chip Flash API itself is not mutex exclusive, a mutex is added to the OS_adapter_FLASH layer.
If supported to run on the chip, operating flash may cause the system to tick, after operating Flash need to make up system tick (important).
Read a sector within 3ms.
os_adapter_flash_write
Description
Writes data to flash.
Parameter
Input or output
Parameter name
Description
[in]
addr
Writes the first flash address.
[in]
dst
A buffer pointer to which data is written.
[in]
size
The size of the buffer to be written.
Return value
0: success
Other: failure error code
Notice
Write a sector within 20ms.
os_adapter_flash_erase
Description
Erases flash block.
Parameter
Input or output
Parameter name
Description
[in]
addr
Erase the flash first address.
[in]
size
Flash size erased.
Return value
0: success；
Other: failure error code
Notice
Wipe a sector within 65ms.
os_adapter_storage_get_desc
Description
Gets the KV(key-value) -Flash partition information of the chip SDK for data partitioning of graffiti application.
Parameter
None.
Return value
UNI_STORAGE_DESC_S*: KV- Flash partition information structure pointer.
Notice
You can define a static structure variable in os_adapter_storge.c that describes the KV-Flash partition information of the chip for Tuya application data partitioning. For example:
Recommended area:
The partition name
Description
Length (recommended value）
instructions
SIMPLE_FLASH
KV data
0x10000(64K)
At least 32 k
SIMPLE_FLASH_SWAP
Backup area for KV data
0x4000(16K)
At least 12 k
SIMPLE_FLASH_KEY_ADDR
KV encryption key storage area
0x1000(4K)
Size immutable
After KV Flash has determined the Flash partition, it cannot be changed. If there is any change, forward compatibility is not supported.
Tuya authorization information is stored in KV zone.
os_adapter_uf_get_desc
Description
Gets the UF_file-Flash partition information of the chip SDK for the data of the graffiti application.
Parameter
None.
Return value
UF_PARTITION_TABLE_S*: Uf_file-flash partition information structure pointer.
Notice
Tuya Uf-file is a Flash storage component of Linux file IO operation API (Open, Write,read,close, etc.). It supports the application layer to operate Flash through uf_file.h interface.
You can define a static structure variable in OS_adapter_storge. C that describes the uf_file-Flash partition information that the chip USES to partition data for Tuya.For example,
Recommended partitions (the combined size of several partitions is not less than 128K) :
partition name
Description
Description length (recommended)
instructions
UF_FILE_1
UF_FILE data 1 block
0x8000(32K)
32K, starting position can be adjusted
UF_FILE_2
UF_FILE data area 2
0x18000(96K)
96K, starting position can be adjusted
The Tuya HAL Output interface provides interfaces for redirecting logs, such as printing to a file or the cloud. These interfaces can be implemented for your customization requirements.
os_adapter_output_log
Description
Prints a string.
Parameter
Input or output
Parameter name
Description
[in]
str
String pointer
Return value
Void.
os_adapter_log_close
Description
Closes the log I/O pin. The business needs to use log UART IO as normal IO to turn off the UART function.
Parameter
Input or output
Parameter name
Description
[in]
str
String pointer
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_LOG_CLOSE_FAILED: fail
os_adapter_log_open
Description
Restores the log I/O pin.
Parameter
None.
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_LOG_OPEN_FAILED: fail
Tuya HAL Wi-Fi provides interfaces for Wi-Fi operations that requires different platforms to implement.
os_adapter_wifi_all_ap_scan
Description
Scans all AP information for the current environment.
Parameter
Input or output
Parameter name
Description
[out]
ap_ary
Scan results
[out]
num
Number of SCANNED AP
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_AP_SCAN_FAILED: fail
Notice
blocking function.
can only scan AP in the current country code channel list.
The ap_ary needs to allocate memory within the API (scan multiple APS, need to allocate contiguous memory space).
The memory is released by the Tuya SDK which actively calls os_adapter_wifi_release_ap.
os_adapter_wifi_assign_ap_scan
Description
Scans AP information for the SSID specified in the current environment.
Parameter
Input or output
Parameter name
Description
[in]
ssid
Specify the ssid
[out]
ap
Scan results
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_AP_SCAN_FAILED: Scan failed
Notice
Blocking function.
Only scan AP in the current country code channel list.
When an AP specifying an SSID exists in the environment, the success rate of scanning the SSID is more than 98%.
AP needs to allocate memory within the API (scanning multiple APS requires allocating continuous memory space).
The memory is released by the Tuya SDK which actively calls os_adapter_wifi_release_ap.
os_adapter_wifi_release_ap
Description
Frees up the AP information resources.
Parameter
Input or output
Parameter name
Description
[in]
ap
Ap information that needs to be released
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_AP_RELEASE_FAILED: fail
os_adapter_wifi_set_cur_channel
Description
Sets the signal channel.
Parameter
Input or output
Parameter name
Description
[in]
chan
channel
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_CHAN_SET_FAILED: fail
Notice
Failed to set a channel signal outside the current national code channel range.
support to set channels in sniffer callback.
os_adapter_wifi_get_cur_channel
Description
Gets the current channel.
Parameter
Input or output
Parameter name
Description
[out]
chan
channel
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_CHAN_GET_FAILED: fail
os_adapter_wifi_get_ip
Description
Gets WIFI IP information (IP address, gateway address, address mask).
Parameter
Input or output
Parameter name
Description
[in]
wf
Wi-Fi model
[out]
ip
IP information
--------
--------
WF_STATION
station type
WF_AP
ap type
Return value
OPRT_OS_ADAPTER_OK: success
OPRT_OS_ADAPTER_IP_GET_FAILED: fail
Notice