Skip to content

Commit 9bb6bc5

Browse files
flyingcysflyingcys
committed
add tuya-wifi-mcu-sdk-arduino-library
0 parents  commit 9bb6bc5

24 files changed

+4024
-0
lines changed

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
*.o
2+
*.d

‎README.md

+279
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
# Tuya MCU SDK Arduino Library
2+
3+
[English](./README.md) | [中文](./README_zh.md)
4+
5+
Tuya MCU SDK Arduino Library is developed based on the Tuya Wi-Fi general integration solution. The device's MCU is connected to a Wi-Fi module through a serial port to implement a network connection. **The development is based on general firmware, which supports the adaptative 9600 and115200 baud rate. Please read this document carefully before development.**
6+
7+
<div align='center'>
8+
<img src="https://images.tuyacn.com/smart/shiliu_zone/Tuya_Arduino_library/mcu_wifi_connect.png"/>
9+
</div>
10+
11+
12+
13+
## Document introduction
14+
15+
```bash
16+
├── config.h // Configuration file. Add and define features in the MCU SDK with macros.
17+
├── examples // The folder to save routines.
18+
├── keywords.txt
19+
├── library.properties
20+
├── README.md
21+
└── src // The folder to save Tuya MCU SDK Arduino Library.
22+
├── TuyaWifi.cpp // The APIs for users.
23+
├── TuyaDataPoint.cpp // The class of DP operations.
24+
├── TuyaDataPoint.h
25+
├── TuyaDefs.h // Some constants.
26+
├── TuyaWifi.h
27+
├── TuyaTools.cpp // Tools used by the MCU SDK.
28+
├── TuyaTools.h
29+
├── TuyaUart.cpp // Functions for serial communications and data buffer.
30+
└── TuyaUart.h
31+
```
32+
33+
34+
35+
## Important functions
36+
37+
When you use this library for development with Arduino, you must add the header file `TuyaWifi.h` in your Arduino project.
38+
39+
### 1. Initialization
40+
41+
Every product that is created on the Tuya IoT Platform will have a unique product ID (PID). The PID is associated with all information related to this product, including specific DP, app control panel, and delivery information.
42+
43+
In `unsigned char TuyaWifi::init(unsigned char *pid, unsigned char *mcu_ver)`, the PID is obtained after you create a product on the [Tuya IoT Platform](https://iot.tuya.com/?_source=97c44038fafc20e9c8dd5fdb508cc9c2). The PID of a Wi-Fi product is typically 16 bytes. The `mcu_ver` parameter is the version number of the software. Pay attention to this parameter if you want to support OTA updates of the MCU.
44+
> **Note**: The current version of the library does not support the OTA feature.
45+
46+
```c
47+
#include <TuyaWifi.h>
48+
49+
TuyaWifi my_device;
50+
...
51+
void setup()
52+
{
53+
Serial.begin(9600);
54+
...
55+
my_device.init("xxxxxxxxxxxxxxxx", "1.0.0");// "xxxxxxxxxxxxxxxx": the PID on the Tuya IoT Platform. "1.0.0" is the default value. You can change "1.0.0" to the actual version number of the current software.
56+
57+
...
58+
}
59+
60+
void loop()
61+
{
62+
...
63+
my_device.uart_service();
64+
...
65+
}
66+
...
67+
```
68+
69+
70+
71+
### 2. Pass in the DP information to the MCU SDK
72+
73+
Create products on the [Tuya IoT Platform](https://iot.tuya.com/?_source=97c44038fafc20e9c8dd5fdb508cc9c2) and get information on product DP points.
74+
75+
A data point (DP) represents a smart device function.
76+
77+
+ Tuya abstracts each function into a data point. DPs are defined in different data types, such as Boolean, enumeration, and integer.
78+
+ DPs have read and write attributes. For example, a 2-gang switch has two Boolean DPs, and each DP has either a `True` or `False` value, which is readable and writable.
79+
+ To read means to get the current value of the switch, and to write means to change the current value of the switch.
80+
81+
DPID: specifies the ID of a DP event under a communication protocol.
82+
83+
84+
The MCU SDK needs to know which DPs you have created and what type they are. Pass them to the MCU SDK through the `void TuyaWifi::set_dp_cmd_total(unsigned char dp_cmd_array[][2], unsigned char dp_cmd_num)` function.
85+
The Tuya IoT Platform has six types of DPs:
86+
87+
```c
88+
#define DP_TYPE_RAW 0x00 // Raw type
89+
#define DP_TYPE_BOOL 0x01 // Boolean type
90+
#define DP_TYPE_VALUE 0x02 // Numeric type
91+
#define DP_TYPE_STRING 0x03 // String type
92+
#define DP_TYPE_ENUM 0x04 // Enum type
93+
#define DP_TYPE_BITMAP 0x05 // Fault type
94+
```
95+
96+
In the `void TuyaWifi::set_dp_cmd_total(unsigned char dp_cmd_array[][2], unsigned char dp_cmd_num)` function, `dp_cmd_array[][2]` is the array that stores DP information, and `dp_cmd_num` is the total number of DPs.
97+
98+
99+
100+
Assume that a light has three functions, corresponding to three DPs as below:
101+
* Switch (DP ID: 20, DP type: Boolean type).
102+
* Brightness (DP ID: 21, DP type: numeric type).
103+
* Light mode (DP ID: 22, DP type: enum type).
104+
105+
```c
106+
#include <TuyaWifi.h>
107+
108+
TuyaWifi my_device;
109+
...
110+
#define DPID_SWITCH 20 // The switch DP of the light.
111+
#define DPID_LIGHT 21 // The brightness DP of the light.
112+
#define DPID_MODE 22 // The working mode DP of the light.
113+
114+
// Note: array[][0] is DP ID, and array[][1] is DP type.
115+
unsigned char dp_id_array[][2] = {
116+
/* DPID | DP type */
117+
{DPID_SWITCH, DP_TYPE_BOOL},
118+
{DPID_LIGHT, DP_TYPE_VALUE},
119+
{DPID_MODE, DP_TYPE_ENUM},
120+
};
121+
...
122+
void setup()
123+
{
124+
...
125+
my_device.set_dp_cmd_total(dp_id_array, 3);
126+
...
127+
}
128+
```
129+
130+
131+
132+
### 3. Pairing mode setting
133+
134+
Call `void TuyaWifi::mcu_set_wifi_mode(unsigned char mode)` to enter the pairing mode.
135+
136+
```c
137+
/**
138+
* @description: The MCU sets Wi-Fi working mode
139+
* @param {unsigned char} mode: Enter the specified mode
140+
* 0(SMART_CONFIG): Enter SmartConfig (Wi-Fi Easy Connect) mode
141+
* 1(AP_CONFIG): Enter AP mode
142+
* @return {*}
143+
*/
144+
void TuyaWifi::mcu_set_wifi_mode(unsigned char mode);
145+
```
146+
147+
148+
149+
150+
151+
### 4. Send and process DP data
152+
153+
After the cloud sends data, the sent data must be parsed through the `unsigned char TuyaWifi::mcu_get_dp_download_data(unsigned char dpid, const unsigned char value[], unsigned short len)` function.
154+
Currently, this function only supports three types: `DP_TYPE_BOOL`, `DP_TYPE_VALUE`, and `DP_TYPE_ENUM`. `DP_TYPE_BITMAP` refers to the data of fault type, in which the data is only reported to the cloud. You do not need to handle this type. `DP_TYPE_RAW` and `DP_TYPE_STRING` must be implemented yourself.
155+
156+
```c
157+
/**
158+
* @description: The MCU gets Boolean, numeric, and enum types to send DP value. (The data of the raw and string types shall be handled at the user's discretion. The data of the fault type can only be reported.)
159+
* @param {unsigned char} dpid: Data point (DP) ID
160+
* @param {const unsigned char} value: DP data buffer address
161+
* @param {unsigned short} len: Data length
162+
* @return {unsigned char} Parsed data
163+
*/
164+
unsigned char TuyaWifi::mcu_get_dp_download_data(unsigned char dpid, const unsigned char value[], unsigned short len);
165+
```
166+
167+
168+
169+
### 5. Register a function to process DP sending
170+
171+
The app sends DP control commands to the device through the cloud. After data parsing, the device executes the specified actions accordingly.
172+
173+
A callback function is required to process the sent commands, so a processing function must be registered. We can call `void TuyaWifi::dp_process_func_register(tuya_callback_dp_download _func)` to register the callback function.
174+
175+
```c
176+
#include <TuyaWifi.h>
177+
178+
TuyaWifi my_device;
179+
...
180+
181+
void setup()
182+
{
183+
...
184+
// Register DP download processing callback function
185+
my_device.dp_process_func_register(dp_process);
186+
...
187+
}
188+
189+
/**
190+
* @description: DP download callback function.
191+
* @param {unsigned char} dpid
192+
* @param {const unsigned char} value
193+
* @param {unsigned short} length
194+
* @return {unsigned char}
195+
*/
196+
unsigned char dp_process(unsigned char dpid,const unsigned char value[], unsigned short length)
197+
{
198+
switch(dpid) {
199+
case DPID_SWITCH:
200+
switch_value = my_device.mcu_get_dp_download_data(dpid, value, length);
201+
if (switch_value) {
202+
// Turn on
203+
204+
} else {
205+
// Turn off
206+
207+
}
208+
// Status changes must be reported.
209+
my_device.mcu_dp_update(dpid, value, length);
210+
break;
211+
212+
default:break;
213+
}
214+
return SUCCESS;
215+
}
216+
```
217+
218+
219+
220+
### 6. Report device status
221+
222+
Reporting the device status is to report the values of all DPs. It is also implemented through function registration.
223+
224+
Six data types of DPs are defined as follows:
225+
226+
DP reporting function:
227+
228+
```c
229+
/**
230+
* @description: DP data upload
231+
* @param {unsigned char} dpid
232+
* @param {const unsigned char} value
233+
* @param {unsigned short} length
234+
* @return {*}
235+
*/
236+
unsigned char mcu_dp_update(unsigned char dpid, const unsigned char value[], unsigned short len);//update raw, string type
237+
unsigned char mcu_dp_update(unsigned char dpid, unsigned long value, unsigned short len);
238+
unsigned char mcu_dp_update(unsigned char dpid, unsigned int value, unsigned short len);
239+
```
240+
241+
242+
Example of registering a device status reporting function
243+
244+
```c
245+
#include <TuyaWifi.h>
246+
247+
TuyaWifi my_device;
248+
249+
#define DPID_SWITCH 20
250+
// Record the current status of the LED
251+
unsigned char switch_value = 0;
252+
...
253+
void setup()
254+
{
255+
...
256+
// Register DP download processing callback function
257+
my_device.dp_update_all_func_register(dp_update_all);
258+
...
259+
}
260+
261+
/**
262+
* @description: Upload all DP status of the current device.
263+
* @param {*}
264+
* @return {*}
265+
*/
266+
void dp_update_all(void)
267+
{
268+
my_device.mcu_dp_update(DPID_SWITCH, switch_value, 1);
269+
}
270+
```
271+
272+
## Technical Support
273+
274+
You can get support for Tuya by using the following methods:
275+
276+
- Developer Centre: https://developer.tuya.com
277+
- Help Centre: https://support.tuya.com/help
278+
- Technical Support Work Order Centre: https://service.console.tuya.com
279+

0 commit comments

Comments
 (0)