Weather Service

This topic describes how to use Tuya’s MCU SDK to get the weather data for your product.

Enable the weather service

The MCU sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x20
Data length	2	N((L+K)+(L+K)+…)
Data	Data	L: a 1-byte value, representing the length of K. K: the name of the request parameter. For more information about the supported parameter, see Appendix 1. Example of parameters that can be forecast: L: 0x0A K: w.humidity L: 0x08 K: w.date.7 Example of parameters that cannot be forecast: L: 0x06 K: w.pm25
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 0x55aa 03 20 0010 06 77 2e 68 75 6d 69 64 69 74 79 06 77 2e 70 6d 32 35 08 77 2e 64 61 74 65 2e 37 e9

• To get the weather data that can be forecast, you must specify the number of days for which the API returns forecast data (up to 7 days).

  Example:

  • w.humidity, w.date.1: the humidity forecast of the current day.
  • w.humidity, w.date.7: the humidity forecast for the next 7 days starting from the current day.

• To get the weather data that cannot be forecast, you must not specify the number of days for which the API returns forecast data.

  Example: w.pm2.5

• To get the time-dependent weather data, you must use the t.unix or t.local parameter to request data in GMT or local time.

  Example:

  • L: 0x0b K: w.sunRise
  • L: 0x0b K: w.date.7
  • L: 0x06 K: t.unix

• The module returns the sunrise time in GMT. The time takes the format of Year-Month-Date Hour: Minute.

The module returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x20
Data length	2	0x0002
Data	2	0x00: Request failed. 0x01: Invalid data format. 0x02: Exception error. 0x01: Request succeeded. 0x00
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 0x55aa 00 20 0002 0100 22

Send weather data

After the weather service is enabled, the module regularly sends weather data received from the cloud to the MCU.

The module sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x21
Data length	2	N
Data	2	0x00: Request failed. 0x01: Error code. Check whether you have subscribed to the weather service. 0x01: Request succeeded. L: length of the parameter name. K: parameter name. T: 0x00 indicates an integer and 0x01 indicates a string. L: length of the field name. V: value of the field.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example:

• w.humidity.0:100 w.humidity.1:100 w.humidity.2:100 w.humidity.3:100 w.humidity.4:100 w.humidity.5:100
  w.humidity.6:100
• w.pm25:14

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x21
Data length	2	0x0000
Data	2	None
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 0x55aa 00 21 0000 20

Implement functions

Macro definitions

Specify whether to enable the weather service.

/******************************************************************************
					Specify whether to enable the weather service
To use the weather service, you must enable this macro and implement the code for data display on the mobile app in the functions `weather_open_return_handle` and `weather_data_user_handle` in the `protocol.c` file.
Remember to delete the `#err` message after you edit these functions.
When you enable the weather service, the serial data buffer must be increased accordingly.
******************************************************************************/
//#define         WEATHER_ENABLE                  // Enable the weather service.
#ifdef          WEATHER_ENABLE
/*  You can set the weather data parameters in the `weather_choose` array in the `protocol.c` and write the number of weather data types to this macro.  */
#define         WEATHER_CHOOSE_CNT              4   // Specify the number of weather data parameters.
/*  When you enable the weather service, you can set this macro to specify the number of days for which the API returns forecast data. The valid value ranges from 1 to 7. Setting to `1` returns the weather of the current day, without a forecast.  */
#define         WEATHER_FORECAST_DAYS_NUM       1   // Specify the number of days for which the API returns forecast data.
#endif

Weather parameters

Specify the required weather data parameters.

#ifdef WEATHER_ENABLE
/**
* @var    weather_choose
* @brief  The array of weather parameters.
* @note  You can define a parameter and comment out or uncomment code as needed. The content specified in the documentation prevails.
*/
const char *weather_choose[WEATHER_CHOOSE_CNT] = {
	"temp",
	"humidity",
	"pm25",
	/*"pressure",
	"realFeel",
	"uvi",
	"tips",
	"windDir",
	"windLevel",
	"windSpeed",
	"sunrise",
	"sunset",
	"aqi",
	"so2 ",
	"rank",
	"pm10",
	"o3",
	"no2",
	"co",
	"conditionNum",*/
};
#endif

Return values

The value that the function for enabling weather service returns is intended to be implemented by the developer.

/**
* @brief   The value that the function for enabling weather service returns.
* @param[in] {res}   The result of enabling the weather service.
* @ref       0: Failed
* @ref       1: Succeeded
* @param[in] {err} The error code.
* @return Null
* @note   To be implemented by the developer.
*/
void weather_open_return_handle(unsigned char res, unsigned char err)
{
	#error "Complete the code and delete this row."
	unsigned char err_num = 0;

	if(res == 1) {
		// Return success.
	}else if(res == 0) {
		// Return failure.
		// Get the error code.
		err_num = err;
	}
}

Data processing

The function for processing weather data is intended to be implemented by the developer.

/**
* @brief  The function for processing weather data.
* @param[in] {name}  The parameter name.
* @param[in] {type} The parameter type.
* @ref       0: The integer type.
* @ref       1: The string type.
* @param[in] {data} The address of the parameter value.
* @param[in] {day}  The number of days for which the API returns forecast data. The value ranges from 0 to 6 and 0 indicates the current day.
* @ref       0: Today.
* @ref       1: Tomorrow.
* @return Null
* @note   To be implemented by the developer.
*/
void weather_data_user_handle(char *name, unsigned char type, const unsigned char *data, char day)
{
	#error "Complete the code and delete this row."
	int value_int;
	char value_string[50];// Defaults to 50. You can adjust it based on your defined parameters.

		my_memset(value_string, '\0', 50);

	// Get the data type.
	if(type == 0) { // The integer type.
			value_int = data[0] << 24 | data[1] << 16 | data[2] << 8 | data[3];
	}else if(type == 1) {
			my_strcpy(value_string, data);
	}

	// Note that you must request the parameter value according to the selected parameters.
	 if(my_strcmp(name, "temp") == 0) {
		printf("day:%d temp value is:%d\r\n", day, value_int);          // The integer type.
	}else if(my_strcmp(name, "humidity") == 0) {
		printf("day:%d humidity value is:%d\r\n", day, value_int);      // The integer type.
	}else if(my_strcmp(name, "pm25") == 0) {
		printf("day:%d pm25 value is:%d\r\n", day, value_int);          // The integer type.
	}else if(my_strcmp(name, "condition.num") == 0) {
		printf("day:%d condition value is:%s\r\n", day, value_string);  // The string type.
	}
}

Debug with MCU simulator

To enable the weather service, perform the following steps:

1. Double-click the required weather data parameter.

2. The selected parameter is checked. You can double-click to deselect it.

3. When you click Turn on Weather, the module sends weather data to the MCU on first-time power-on and then every 30 minutes.

   

Parse commands

The MCU receives weather data from the module:

55 aa 00 21 00 2f 01 06 77 2e 74 65 6d 70 00 04 00 00 00 23 06 77 2e 70 6d 32 35 00 04 00 00 00 11 c7

01 indicates that weather data is successfully obtained.

• Take the second group of data 06 77 2e 70 6d 32 35 00 04 00 00 00 11 as an example to explain the return data.

• 06: the length of the parameter name w.pm25.

• 77 2e 70 6d 32 35: the parameter name. The converted character is w.pm25.

• 00 04: the weather condition is a value 00, with a length of 04.

• 00 00 00 11: the converted decimal is 17, indicating the current value of PM2.5 is 17.

Examples of weather data request

Request the real-time weather data

• The MCU sends {"w.temp","w.humidity"} or {"w.temp","w.humidity","w.currdate"}

• The module returns the following data.

  {
  	"w.temp":13,
  	"w.humidity":100
  }
  

Request current weather data only

• The MCU sends {"w.humidity","w.date.1"}.

• The module returns the following data.

  {	
  	"w.humidity.0":100
  }
  

Request daily forecasts

• The MCU sends {"w.humidity","w.date.3"}.

• The module returns the following data.

  {
  	"w.humidity.0":100,
  	"w.humidity.1":100,
  	"w.humidity.2":100
  }
  

Request daily forecasts and real-time weather data

• The MCU sends {"w.temp","w.humidity","w.date.3","w.currdate"}.

• The module returns the following data.

  {
          "w.temp":13,
  	"w.humidity":100
  	"w.humidity.0":100,
  	"w.humidity.1":100,
  	"w.humidity.2":100
  }
  

Request the time of sunrise and sunset

• GMT (using UTC+8 as an example)

  • The MCU sends { "w.humidity","w.sunrise","w.sunset","t.unix","w.date.3" }.

  • The module returns the following data.

    		{
    			"w.humidity.0":100,
    			"w.sunrise.0":"2019-12-27 00:05",
    			"w.sunset.0":"2019-12-27 10:54",
    			"w.humidity.1":100,
    			"w.sunrise.1":"2019-12-28 00:05",
    			"w.sunset.1":"2019-12-28 10:54",
    			"w.humidity.2":100,
    			"w.sunrise.2":"2019-12-29 00:05",
    			"w.sunset.2":"2019-12-29 10:54"
    		}
    

• Local time (using UTC+8 as an example)

  • The MCU sends { "w.humidity","w.sunrise","w.sunset","t.local","w.date.3" }.

  • The module returns the following data.

    		{
    			"w.humidity.0":100,
    			"w.sunrise.0":"2019-12-27 08:05",
    			"w.sunset.0":"2019-12-27 18:54",
    			"w.humidity.1":100,
    			"w.sunrise.1":"2019-12-28 08:05",
    			"w.sunset.1":"2019-12-28 18:54",
    			"w.humidity.2":100,
    			"w.sunrise.2":"2019-12-29 08:05",
    			"w.sunset.2":"2019-12-29 18:54"
    		}
    

Request daily forecasts and measured air data

• The MCU sends { "w.temp","w.humidity","w.pm10","w.pm25","w.date.3" }.

• The module returns the following data.

  	{
  		"w.pm10.0":14,
  		"w.pm25.0":7,
  		"w.humidity.0":100,
  		"w.humidity.1":100,
  		"w.humidity.2":100
  	}
  

  If the value n you specified for the parameter w.date.n is greater than 7 or not greater than 0, the server takes it as an input parameter error and returns nothing.

Appendix 1: Weather data in ASCII

Parameter	Description	Mainland China	Other countries/regions	Forecast	Length	Hexadecimal value
w.temp	Atmospheric temperature in °C	Supported	Supported	7-day forecast (except for mainland China)	6	77 2e 74 65 6d 70
w.humidity	Air humidity	Supported	Supported	7-day forecast	10	77 2e 68 75 6d 69 64 69 74 79
w.conditionNum	Weather condition No.	Supported	Supported	7-day forecast	14	77 2e 63 6f 6e 64 69 74 69 6f 6e 4e 75 6d
w.pressure	Atmospheric pressure in mbar	Supported	Supported	7-day forecast (except for mainland China)	10	77 2e 70 72 65 73 73 75 72 65
w.realFeel	Apparent temperature	Supported	Supported	N/A	10	77 2e 72 65 61 6c 46 65 65 6c
w.uvi	Ultraviolet index	Supported	Supported	7-day forecast	5	77 2e 75 76 69
w.sunrise	Sunrise	Supported	Supported	7-day forecast	9	77 2e 73 75 6e 72 69 73 65
w.sunset	Sunset	Supported	Supported	7-day forecast	8	77 2e 73 75 6e 73 65 74
t.unix	GMT, used for the time of sunrise (w.sunrise) and sunset (w.sunset)	N/A	N/A	N/A	6	74 2e 75 6e 69 78
t.local	Local time, used for the time of sunrise (w.sunrise) and sunset (w.sunset)	N/A	N/A	N/A	7	74 2e 6c 6f 63 61 6c
w.windSpeed	Wind speed in m/s	Supported	Supported	7-day forecast	11	77 2e 77 69 6e 64 53 70 65 65 64
w.windDir	Wind direction	Supported	Supported	7-day forecast	9	77 2e 77 69 6e 64 44 69 72
w.windLevel	Wind scale	Supported	Not supported	7-day forecast	11	77 2e 77 69 6e 64 4c 65 76 65 6c
w.aqi	Air quality index US EPA standard: 0 to 500	Supported	Supported	Current day only	5	77 2e 61 71 69
w.rank/w.quality	AQI details and national ranking	Supported	Not supported	Current day only	6	77 2e 72 61 6e 6b / 77 2e 71 75 61 6c 69 74 79
w.pm10	PM10 (inhalable particulate matter) in µg/m³	Supported	Supported	Current day only	6	77 2e 70 6d 31 30
w.pm25	PM2.5 (fine particulate matter) in µg/m³	Supported	Supported	Current day only	6	77 2e 70 6d 32 35
w.o3	Ozone level in µg/m³	Supported	Supported	Current day only	4	77 2e 6f 33
w.no2	Nitrogen dioxide level in µg/m³	Supported	Supported	Current day only	5	77 2e 6e 6f 32
w.co	Carbon monoxide level in µg/m³	Supported	Supported	Current day only	4	77 2e 63 6f
w.so2	Sulfur dioxide level in µg/m³	Supported	Supported	Current day only	5	77 2e 73 6f 32
w.thigh	The highest temperature in °C	Supported	Supported	Forecast only	7	77 2e 74 68 69 67 68
w.tlow	The lowest temperature in °C	Supported	Supported	Forecast only	6	77 2e 74 6c 6f 77
w.date.n (1 ≤ n ≤ 7)	How many days the forecast responses are returned	Supported	Supported	N/A	8	77 2e 64 61 74 65 2e 6e
w.currdate	Current weather	Supported	Supported	-	10	77 2e 63 75 72 72 64 61 74 65

Appendix 2: City service data in ASCII

Parameter	Description	Types	Length	Hexadecimal value
c.area	County or district name	String	6	63 2e 61 72 65 61
c.city	The name of the city	String	6	63 2e 63 69 74 79
c.province	Province	String	10	63 2e 70 72 6f 76 69 6e 63 65

Appendix 3: Weather forecast service data

Parameter	Description	Types	Real-time	Forecast
w.temp	Temperature	Interger	Yes	Yes (except for mainland China)
w.humidity	Humidity	Interger	Yes	Yes
w.conditionNum	Weather condition No.	String	Yes	Yes
w.pressure	Air pressure	Interger	Yes	Yes (except for mainland China)
w.realFeel	Apparent temperature	Interger	Yes	No
w.uvi	Ultraviolet index	Interger	Yes	Yes
w.windDir	Wind direction	String	Yes	Yes
w.windLevel	Wind level	Interger	Yes (mainland China only)	No
w.windSpeed	Wind speed	String (format example: 1.0; 0.5)	Yes	Yes
w.sunrise	Sunrise time	String (format example: 2017-04-24 05:24)	Yes	Yes
w.sunset	Sunset time	String (format example: 2017-04-24 18:32)	Yes	Yes
w.aqi	Air quality index	Interger	Yes	No
w.pm25	PM2.5	Interger	Yes	No
w.so2	Sulfur dioxide level	Interger	Yes	No
w.rank/w.quality	Air quality rating	String (format example: 447/609)	Yes (mainland China only)	No
w.pm10	PM10	Interger	Yes	No
w.o3	Ozone level	Interger	Yes	No
w.no2	Nitrogen dioxide level	Interger	Yes	No
w.co	Carbon monoxide level	Interger	Yes	No
w.qualityLevel	Air quality rating	Integer	Yes	No
w.thigh	The highest temperature	Integer	No	Yes
w.tlow	The lowest temperature	Integer	No	Yes

Appendix 4: Weather data in UTF-8 encoding

ASCII code w.conditionNum	Hexadecimal value	Weather conditions
120	31 32 30	Sunny
101	31 30 31	Heavy rain
102	31 30 32	Thunderstorm
103	31 30 33	Sandstorm
104	31 30 34	Light snow
105	31 30 35	Snow
106	31 30 36	Freezing fog
107	31 30 37	Rainstorm
108	31 30 38	Isolated shower
109	31 30 39	Dust
110	31 31 30	Thunder and lightning
111	31 31 31	Light shower
112	31 31 32	Rain
113	31 31 33	Sleet
114	31 31 34	Dust devil
115	31 31 35	Ice pellet
116	31 31 36	Strong sandstorm
117	31 31 37	Sand blowing
118	31 31 38	Light to moderate rain
119	31 31 39	Mostly clear
121	31 32 31	Fog
122	31 32 32	Shower
123	31 32 33	Heavy shower
124	31 32 34	Heavy snow
125	31 32 35	Extraordinary rainstorm
126	31 32 36	Blizzard
127	31 32 37	Hail
128	31 32 38	Light to moderate snow
129	31 32 39	Partly cloudy
130	31 33 30	Light snow shower
131	31 33 31	Moderate snow
132	31 33 32	Overcast
133	31 33 33	Needle ice
134	31 33 34	Downpour
136	31 33 36	Thundershower and hail
137	31 33 37	Freezing rain
138	31 33 38	Snow shower
139	31 33 39	Light rain
140	31 34 30	Haze
141	31 34 31	Moderate rain
142	31 34 32	Cloudy
143	31 34 33	Thundershower
144	31 34 34	Moderate to heavy rain
145	31 34 35	Heavy rain to rainstorm
146	31 34 36	Clear

Appendix 5: Wind direction code

Code (string)	Hexadecimal value	Description
N	4e	North
NNE	4e 4e 45	Northeast by north
NE	4e 45	Northeast
ENE	45 4e 45	Northeast by east
E	45	East
ESE	45 53 45	Southeast by east
SE	53 45	Southeast
SSE	53 53 45	Southeast by south
S	53	South
SSW	53 53 57	Southwest by south
SW	53 57	Southwest
WSW	57 53 57	Southwest by west
W	57	West
WNW	57 4e 57	Northwest by west
NW	4e 57	Northwest
NNW	4e 4e 57	Northwest by north