Weather Service

Last Updated on : 2023-02-08 06:06:33download

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.

    Weather Service

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

The following example uses the device for mainland China to illustrate.

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 response data is the current day’s forecast, which should be distinguished from the real-time weather data.

  • 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
  • WindDir indicates the wind direction. For more information about the wind direction code, see Appendix 5.
  • w.conditionNum indicates the weather condition code. For more information, see Appendix 4.
  • Atmospheric pressure conversion: 1 mbar = 100 pa = 1 hPa.
  • Support for forecast: If w.date.n is carried, the return data is the weather forecast.
  • Support for real-time weather data: For weather requests with w.date.n carried, w.currdate can be carried to get the real-time weather data at the same time. For more information, see Examples of weather data request.

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

If the weather service API returns service city only without any content, it indicates the device does not provide its latitude and longitude, so the request failed. To resolve this issue, you should guide users to allow their mobile app to access the location and pair the device with the mobile app again.

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
  • The number in the string is rounded to one decimal place. Example: 1.0; 0.9
  • Support for forecast: If w.date.n is carried, the return data is the weather forecast.
  • Support for real-time weather data: For weather requests with w.date.n carried, w.currdate can be carried to get the real-time weather data at the same time. For more information, see Examples of weather data request.

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