### SDK Directory Structure
```
├── app
│ ├── build-all.py
│ ├── light
│ ├── sensor
│ ├── smart_plug
│ └── switch
├── doc
│ ├── datasheet
│ ├── SPEC
│ ├── docking standard
│ └── development manual
├── include
│ ├── hal_adc.h
│ ├── hal_battery.h
│ ├── hal_flash.h
│ ├── hal_gpio.h
│ ├── hal_i2c.h
│ ├── hal_pwm.h
│ ├── hal_spi.h
│ ├── hal_systick_timer.h
│ ├── hal_timer.h
│ ├── hal_uart.h
│ ├── tuya_app_timer.h
│ ├── tuya_mcu_os.h
│ ├── tuya_mf_test.h
│ ├── tuya_oem_kit.h
│ ├── tuya_tools.h
│ ├── tuya_zigbee_modules.h
│ ├── tuya_zigbee_sdk.h
│ ├── tuya_zigbee_stack.h
│ ├── type_def.h
│ ├── zigbee_attr.h
│ ├── zigbee_cmd.h
│ ├── zigbee_dev_template.h
│ ├── zigbee_modules.h
│ └── zigbee_raw_cmd_api.h
├── lib
│ ├── gcc_lib
│ └── iar_lib
├── sdk
│ ├── platform
│ └── tool
└── tools
├── gcc-arm-none-eabi-9-2019-q4-major
├── gcc-arm-none-eabi-9-2019-q4-major.tar.bz2
├── gcc_boot
└── iar_tools
```
Directory Introduction
| Directory | Explanation |
| --------- | --------------------------------------------------------------------------------------------- |
| app | The entry path of the application project, which contains example codes of various categories |
| doc | Zigbee related files |
| include | SDK interface file |
| lib | SDK library files are divided into IAR version library and GCC version library |
| sdk | Some tools and link scripts |
| tools | Related tools and scripts used in compilation |
### SDK Overall process
#### User-implemented function interface
**dev\_power\_on\_init()**
```
/**
* @note (MUST) This is the first function after the hardware starts.
* The CPU and base clock are initialized before calling this function.
* You need to implement the creation of Zigbee devices and
* determine the parameters of Zigbee device behavior.
* Include device roles(router, end device), device networking(join),
* rejoin parameters, and more. Refer to the TUYA Zigbee SDK demo for details.
* @param none
* @return none
*/
void dev_power_on_init(void);
```
**Instructions**
Zigbee SDK will call this function according to the system flowchart，Users need to at least create Zigbee devices，network parameter setting。
**Sample code snippet**
```
void dev_power_on_init(void)
{
join_config_t cfg;
zg_dev_config_t zg_dev_config;
/**
Register Zigbee Basic，Including information such as endpoint, cluster, attributes, etc.
*/
dev_register_zg_ep_infor((dev_description_t *)g_dev_des, EP_SUMS);
memset(&zg_dev_config, 0, sizeof(zg_dev_config_t));
zg_dev_config.dev_type = ZG_ROUTER;
dev_register_zg_dev_config(&zg_dev_config);
memset(&cfg, 0, sizeof(cfg));
cfg.auto_join_power_on_flag = TRUE;
cfg.auto_join_remote_leave_flag = TRUE;
cfg.join_timeout = ZIGBEE_JOIN_MAX_TIMEOUT;
dev_zg_join_config(&cfg);
//TODO: others task
return;
}
```
**dev\_system\_on\_init()**
```
/**
* @note (MUST) This is the first function after system startup.
* Before calling this function, Zigbee stack and some basic
* components have been started. You can use all API except individual ones.
* API limits refer to the API limits description table
* @param none
* @return none
*/
void dev_system_on_init(void);
```
**Instructions** Zigbee SDK will call this function according to the system flowchart，Users can realize Zigbee attribute operation, hardware initialization, software timing processing and other initialization. **Sample code snippet**
```
static void __uart_rx_callback(uint8_t *data, uint16_t len)
{
//TODO: Serial port receiving and processing
}
static void __dev_evt_callback(uint8_t evt)
{
switch(evt) {
case EVT_LOCK_CANCEL: {
//TODO: Custom processing
break;
}
default: {
break;
}
}
}
void dev_system_on_init(void)
{
user_uart_config_t *p_default_cfg = mf_test_uart_config();
user_uart_config_t uart_cfg;
memcpy(&uart_cfg, p_default_cfg, sizeof(user_uart_config_t));
uart_cfg.func = __uart_rx_callback;
user_uart_init(&uart_cfg);
dev_timer_start_with_callback(EVT_LOCK_CANCEL, 1000, __dev_evt_callback);
dev_change_power(11, 19);
return;
}
```
**nwk\_state\_changed\_callback()**
```
/**
* @note (MUST) This function is invoked when the network state changes.
* Handling network-related matters at this function is recommended.
* @param[in] {state} Refer to NET_EVT_T for more detal.
* @return none
*/
void nwk_state_changed_callback(NET_EVT_T state);
```
**Instructions** Zigbee SDK will call this function according to the system flowchart，Users can implement Zigbee network status processing. **Sample code snippet**
```
void nwk_state_changed_callback(NET_EVT_T state)
{
switch(state) {
case NET_POWER_ON_LEAVE: {
//TODO: No network status after power on
break;
}
case NET_JOIN_START: {
//TODO: Start networking
break;
}
case NET_JOIN_TIMEOUT: {
//TODO: Start networking
break;
}
case NET_POWER_ON_ONLINE: {
//TODO: Power up has network status
break;
}
case NET_JOIN_OK: {
//TODO: Successful networking
break;
}
case NET_REJOIN_OK: {
//TODO: Reconnect successful
break;
}
case NET_LOST: {
//TODO: Lost with parent
break;
}
case NET_REMOTE_LEAVE: {
//TODO: Remote off-net notification
break;
}
case NET_LOCAL_LEAVE: {
//TODO: Local off-net notification break;
}
case NET_MF_TEST_LEAVE: {
//TODO: Production Test Off-Grid Notification
break;
}
default: {
break;
}
}
}
```
#### Quick development guide
The SDK development kit contains documentation and examples, and the use of and attribute sample code is the only rule of quick start. It is recommended to compile, run, and network with the sample code first, and then try to modify the code to achieve personalized functions.
Example description
| Directory | Explanation |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| light | Projects including Zigbee lamps, including lamp switching and brightness adjustment functions |
| sensor | The project including Zigbee door sensor, including door sensor opening, closing and battery power reporting function |
| smart\_plug | Including the Zigbee socket project, including the opening and closing function of the socket |
| switch | Including Zigbee relay switch project, including relay on and off functions |
Document description
| Document directory | Explanation |
| ------------------ | -------------------------------------------------- |
| datasheet | Zigbee chip data sheet |
| SPEC | Contains Zigbee Alliance Standard Reference Manual |
| Development Manual | All documents used for development |
API call restrictions
```
| dev_timer_start |
Start a delayed execution event，If the event has set an event handler function，
The subsequent call does not need to set the event handler function every time
```
```
|
| dev_timer_get_valid_flag |
Determine whether an event is valid (that is, the event has not been reached)
```
```
|
| dev_timer_get_remaining_time |
Get how many ms remain before an event is executed
```
```
|
|
|
|
|
zigbeeDevice creation
basic configuration |
dev_register_zg_ep_infor |
Register a complete zigbee device, including an endpoint describing the zigbee device，
cluster，attributes etc. |
Can only be called in dev_power_on_init |
| dev_register_zg_dev_config |
Configure the device role of zigbee, whether it is routing or end device and join, rejoin parameters |
Can only be called in dev_power_on_init |
| dev_zg_join_config |
Configure networking policies for power-on and remote deletion |
Can only be called in dev_power_on_init |
|
|
|
|
| Network operation |
dev_zigbee_join_start |
Exit the network and enter the network |
Call afterdev_system_on_init ，It will involve the handling of events and network status |
| dev_zigbee_join_stop |
Stop networking early |
Call afterdev_system_on_init ，It will involve the handling of events and network status |
|
|
|
|
| zigbee 3.0 related |
zg_report_table_init |
Configure the default report table |
Can only be called in dev_power_on_init, Called after dev_register_zg_ep_infor |
| ext_plugin_identify_client_enable |
zigbee 3.0 used，Open the identify client service |
Can only be called in dev_power_on_init, Called after dev_register_zg_ep_infor |
| ext_plugin_identify_server_enable |
zigbee 3.0 used，Open the identify service
```
```
| Can only be called in dev_power_on_init, Called after dev_register_zg_ep_infor |
|
| ext_plugin_green_power_client_enable |
zigbee 3.0 used，Start green power client service |
Can only be called in dev_power_on_init, Called after dev_register_zg_ep_info |
| ext_plugin_reporting_enable |
zigbee 3.0 used，Open reporting service
```
```
| Can only be called in dev_power_on_init, Called after dev_register_zg_ep_infor |
|
| ext_plugin_register_cmd_handle |
Register cluster command processing |
Can only be called in dev_power_on_init |
|
|
|
|
| 电池采集相关 |
hal_battery_config |
Configuration of battery collection function |
Need to be called after dev_system_on_init |
| hal_battery_set_battery_type |
Dynamically configure battery type and whether the device wakes up frequently，
SDK According to these parameters, the internal collection strategy will be made internally |
call afer hal_battery_config |
| hal_battery_report_policy_config |
Battery special strategy configuration |
call after hal_battery_config |
|
|
|
|
| flash 操作 |
flash_block_raw_write |
Write flash in blocks，One block is 250 bytes |
Currently only the big flash version of lib is available该函数，目前只有门锁在用 |
| flash_block_raw_read |
Read flash by block，One block is 250 bytes |
| flash_addr_raw_write |
Write flash according to virtual address |
| flash_addr_raw_read |
Write flash according to virtual address |
|
|
|
| user_flash_data_write |
Application flash write，Leave 250 bytes of bottom flash area for APP development |
Call after dev_system_on_init
```
```
|
| user_flash_data_read |
Application flash write，Leave 250 bytes of bottom flash area for APP development |
|
|
|
|
| Off-grid self-recovery network |
nwk_disable_self_recovery_once |
Disable the self-recovery function |
call after dev_system_on_init |
| nwk_enable_self_recovery_once |
Enable self-recovery |
| nwk_self_recovery_manual |
Self-recovery immediately |
|
|
|
|
| Get all kinds of information |
zigbee_get_net_info |
Obtain device networking parameter information |
call after dev_system_on_init |
| zg_get_join_type |
Acquisition networking method: centralized, distributed, not networking |
call after dev_system_on_init |
| zg_get_join_gw_type |
Obtain networking gateways: Tuya gateway, other gateways, non-gateway (unnetworked / distributed) |
call after dev_system_on_init |
| zg_is_zll_net |
Query whether it is ZLL networking |
Call after dev_system_on_init ， zll lib dedicated
```
```
|
|
|
|
|
| General configuration |
dev_heartbeat_set |
Heartbeat configuration |
Call after dev_system_on_init |
| dev_change_power |
Configure transmit power |
Call afterdev_system_on_init |
| disable_gw_change_power |
Disable the gateway to change the transmit power |
Called in dev_power_on_init |
|
|
|
|
| poll 相关 |
zg_poll_interval_change |
Change poll interval |
Called in dev_register_zg_dev_config |
| zg_poll_start |
The call will always be poll |
| zg_poll_end |
Stop generating new polls，Stop after sending the remaining polls |
| zg_poll_clear |
Stop poll now ， |
|
|
|
|
| 属性，endpoint |
dev_set_endpoint_alias |
Append an alias to an endpoint ，Mainly solves the compatibility problem of endpoint processing when docking with other gateways and Tuya gateways
|
Called after dev_register_zg_ep_infor |
| dev_endpint_enable_disable |
Dynamically disable and enable an endpoint，After disabling an endpoint，
Remote and local cannot access the endpoint |
call after dev_system_on_init ，It will involve the handling of events |
| dev_attr_recovery |
Do not use it for the time being, the PID will be restored to the default value instead of the PID value of the production test |
|
```
Call after Call after
| **Functional category** | **Function name** | **Features** | **Restrictions** |
| ------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **hardware** | **user\_uart\_init** | Single serial port configuration, including serial port hardware parameters and serial port data receiving callback function，
The receiving function is already a function after receiving queue processing，n ot interrupting the environment
| dev\_system\_on\_init ，Don't call it in dev\_power\_on\_init ，
It will be conflicted with the serial port production test
|
| **gpio\_raw\_init** | **gpio Original initialization** | **If it is multiplexed with serial port IO, it needs to be called after dev\_system\_on\_init and after. If there is no multiplexing, there is no limit to call** | |
| **gpio\_int\_register** | **gpio Interrupt initialization** | **If it is multiplexed with serial port IO, it needs to be called after dev\_system\_on\_init and after. If there is no multiplexing, there is no calling limit** | |
| | | | |
| **Software delay event** | **dev\_timer\_stop** | **Stop a delayed execution event early** | dev\_system\_on\_init ，Don't call it in dev\_power\_on\_init，
Calling too early will cause an exception，The event frame has not been initialized。If called in an interrupt，
At least ensure that the interrupt is generated after dev\_system\_on\_init \ \
|
| **dev\_timer\_start\_with\_callback** | **Start a delayed execution event and set the event processing function** | | |
### appendix
#### Glossary
| noun | Explanation |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| IoT platform | iot.tuya.com |
| Zigbee SDK | Based on Silicon branch Zigbee protocol stack after cutting、Optimized packaged Tuya’s Zigbee SDK |
| Attribute | Attribute （属性）Is a data value reflecting the physical quantity or state |
| Cluster | Cluster （群集）Is a cluster containing one or more attributes |
| EndPoint | EndPoint （端点）It is the entrance of the application layer of the protocol stack, that is, the entrance address, and it can also understand where the application object exists. It is a group of clusters defined for the realization of a device description. |
| Device Id | The serial number defined for each device in Zigbee |
| Weak current equipment | Refers to battery-powered equipment，A device called sleep end device in the Zigbee protocol |
| Powerful equipment | Refers to a device that uses mains electricity or is powered from a mains voltage-stabilized power supply, which is called a router in the Zigbee protocol |
| PID | product ID，Each product created on the Tuya IoT platform will generate a unique product number, which is associated with the product specific function points, APP control panel, shipping information, etc. |
| SOC | system on chip，The hardware itself has no MCU, and the control program is written into the network module |
| SDK | Software Development Kit，A software development kit, a collection of related documents, examples, and tools to assist in the development of a certain type of software. In order to encourage developers to use their systems or languages, many SDKs are provided free of charge, as are Tuya's |
| Firmware | Firmware is a program written in EROM (Erasable Read Only Memory) or EEPROM (Electrically Erasable Programmable Read Only Memory). Firmware refers to the device "driver" stored inside the device. Through the firmware, the operating system can implement the operation of a specific machine according to the standard device driver. For example, the optical drive and the recorder have internal firmware. Firmware is the software that serves as the most basic and lowest level of a system |
| OTA | It means firmware upgrade, we support OTA |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.ifreeq.com/developer/device-development/access-mode-link/zigbee-chip-sdk/tuya-zigbee-sdk-document.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.