Weather Service

Weather service enables Bluetooth sub-devices to get required weather data from the cloud through mobile apps. This topic describes concepts, API descriptions, and usage methods.

Overview

Concepts

Provides a capability that allows Bluetooth Low Energy (LE) devices, through communication with the Tuya Smart app, to easily get weather information from the cloud, and use it for display or other related features. This provides users with convenient weather services and makes Bluetooth LE devices more functional and useful. For more information on currently available weather types, applicability inside and outside mainland China, and support for forecasts and other parameters, see Appendix 2: Weather service parameters. The following figure shows the main process.

Positioning and location

In order to get accurate weather data, users should grant location permissions to the Tuya Smart app. Two types of location information are currently available:

• Pairing location: The latitude and longitude information bound with the specified device when it is paired with the app.
• Current location of the phone: The current latitude and longitude information of the specified phone. That is, get the weather data of the current location where the phone is located. It is recommended to use the current location of the phone.

Data structure

tuya_ble_weather_key_type_t

/**@brief    Weather key type. */
typedef enum {
    WKT_TEMP        = (1 << 0),     /**< temperature. */
    WKT_THIHG       = (1 << 1),     /**< high temperature. */
    WKT_TLOW        = (1 << 2),     /**< low temperature. */
    WKT_HUMIDITY    = (1 << 3),     /**< humidity. */
    WKT_CONDITION   = (1 << 4),     /**< weather condition. */
    WKT_PRESSURE    = (1 << 5),     /**< pressure. */
    WKT_REALFEEL    = (1 << 6),     /**< sensible temperature. */
    WKT_UVI         = (1 << 7),     /**< uvi. */
    WKT_SUNRISE     = (1 << 8),     /**< sunrise. */
    WKT_SUNSET      = (1 << 9),     /**< sunset. */
    WKT_UNIX        = (1 << 10),    /**< Unix time, used with sunrise and sunset. */
    WKT_LOCAL       = (1 << 11),    /**< local time, used with sunrise and sunset. */
    WKT_WINDSPEED   = (1 << 12),    /**< wind speed. */
    WKT_WINDDIR     = (1 << 13),    /**< wind direction. */
    WKT_WINDLEVEL   = (1 << 14),    /**< wind speed scale/level. */
    WKT_AQI         = (1 << 15),    /**< aqi. */
    WKT_TIPS        = (1 << 16),    /**< tips. */
    WKT_RANK        = (1 << 17),    /**< detailed AQI status and national ranking. */
    WKT_PM10        = (1 << 18),    /**< pm10. */
    WKT_PM25        = (1 << 19),    /**< pm2.5. */
    WKT_O3          = (1 << 20),    /**< o3. */
    WKT_NO2         = (1 << 21),    /**< no2. */
    WKT_CO          = (1 << 22),    /**< co. */
    WKT_SO2         = (1 << 23),    /**< so2. */
    WKT_CONDITIONNUM= (1 << 24),    /**< weather condition mapping ID. */
    WKT_COMBINE_BITMAP_MAXVAL = (1 << SUPPORT_WEATHER_KEY_TYPE_MAX_NUMS),
} tuya_ble_weather_key_type_t;

Enumerate and define the supported weather types, where each bit corresponds to a weather type. For more information, see the definitions above.

tuya_ble_wd_object_t

/**@brief   Data structure to be called back to the application. */
typedef struct {
    UINT16_T object_count;    /**< weather data object counts. */
    UINT8_T location;         /**< location. */
    UINT8_T *p_data;          /**< weather data. For details, refer to tuya_ble_wd_object_t. */
    UINT16_T data_len;        /**< weather data length. */
}tuya_ble_weather_data_received_data_t;

/**@brief   Weather data object structure. */
 #pragma pack(1)
typedef struct {
    UINT8_T                         n_day;      /**< the specified day. */
    tuya_ble_weather_key_type_t     key_type;   /**< weather key type. */
    tuya_ble_weather_value_type_t   val_type;   /**< weather value type. */
    UINT8_T                         value_len;  /**< weather value length. */
    CHAR_T                          vaule[];    /**< weather values. */
} tuya_ble_wd_object_t;
#pragma pack()

When a request for weather data is successful, the mobile app returns the weather data. The SDK will combine it into the tuya_ble_weather_data_received_data_t data structure in a specified format and send callback events to the application layer. The application can parse the weather data in the above format, where p_data stores specific weather data of N tuya_ble_wd_object_t data types.

API description

Weather capability macro configuration

#define TUYA_BLE_FEATURE_WEATHER_ENABLE 1

Request weather data — phone’s current location

API description

Get weather data for the phone’s current location. You can combine weather types and the number of days requested as you like.

/**
 * @brief Function for requesting weather data. By default, request the current location of the mobile phone.
 *
 * @param[in] combine_type: Request combination types. For details, see the enum of tuya_ble_weather_key_type_t
 * @param[in] n_days: Request forecast days, ranging from [1-7]; 1-means only today, 2-means today+tomorrow …
 *
 * @return TUYA_BLE_SUCCESS on success. Others on error, please refer to tuya_ble_status_t
 *
 * @note Example 1: Request temperature & humidity for two days: tuya_ble_feature_weather_data_request((WKT_TEMP | WKT_HUMIDITY), 2)
 *       Example 2: Request sunrise date & time for one day: tuya_ble_feature_weather_data_request((WKT_SUNRISE | WKT_LOCAL), 1)
 *       Example 3: Request the highest temperature for seven days: tuya_ble_feature_weather_data_request((WKT_THIHG), 7)
 *       In addition, the request for sunrise/sunset must match WKT_UNIX/WKT_LOCAL, otherwise the received data is Unix time
 */
tuya_ble_status_t tuya_ble_feature_weather_data_request(UINT32_T combine_type, UINT8_T n_days);

Parameters

Parameters	Description
combine_type	The requested weather type, which can be combined. For detailed definitions, see Appendix 1: Enumeration of weather service types. For example, to request temperature + humidity, use the type WKT_TEMP + WKT_HUMIDITY. For example, to request wind speed + PM10 + UV, use the type WKT_WINDSPEED + WKT_PM10 + WKT_UVI. Note: The request for sunrise/sunset time must be used in conjunction with the time format. For example, to request the sunrise time in GMT, use WKT_SUNRISE + WKT_UNIX.
n_days	The number of days requested, ranging from 1 to 7. 1: Request the data for the current day. 2 to 7: Request the data for today and the next n-1 days.

Request weather data — specified location

API description

Get weather data for the specified location. You can combine weather types and the number of days requested as you like.

/**
 * @brief Function for requesting weather data with the specified location.
 *
 * @param[in] location_type: Request location types. For details, see the enum of tuya_ble_weather_location_type_t.
 * @param[in] combine_type: Request combination types. For details, see the enum of tuya_ble_weather_key_type_t
 * @param[in] n_days: Request forecast days, ranging from [1-7]; 1-means only today, 2-means today+tomorrow ...
 *
 * @return TUYA_BLE_SUCCESS on success. Others on error, please refer to tuya_ble_status_t
 */
tuya_ble_status_t tuya_ble_feature_weather_data_request_with_location(tuya_ble_weather_location_type_t location_type, UINT32_T combine_type, UINT8_T n_days);

Parameters

Parameters	Description
location_type	The type of the requested location. Valid values: WLT_PAIR_NETWORK_LOCATION: The location where the device is paired. WLT_APP_CURRENT_LOCATION: The current location of the phone.
combine_type	The requested weather type, which can be combined. For detailed definitions, see Appendix 1: Enumeration of weather service types.
n_days	The number of days requested, ranging from 1 to 7. 1: Request the data for the current day. 2 to 7: Request the data for today and the next n-1 days.

Callback event — response to the request

TUYA_BLE_CB_EVT_WEATHER_DATA_REQ_RESPONSE

Callback event	TUYA_BLE_CB_EVT_WEATHER_DATA_REQ_RESPONSE
Data structure	typedef struct { UINT8_T status; //!< 0-success, 1-failed } tuya_ble_weather_data_req_response_t;
Description	After the device calls the request API, the mobile app responds to the request and informs the device of the request result.
Notes	Call the request API on demand. If the API is called frequently, the mobile app will limit the calls and return failure.

Callback event — weather data

TUYA_BLE_CB_EVT_WEATHER_DATA_RECEIVED

Callback event	TUYA_BLE_CB_EVT_WEATHER_DATA_RECEIVED
Data structure	typedef struct { UINT16_T object_count; //!< weather data object counts. UINT8_T location; //!< location. UINT8_T *p_data; //!< weather data. UINT16_T data_len; //!< weather data length. } tuya_ble_weather_data_received_data_t; object_count: Indicates how many pieces of weather data there are under p_data. location: The value of the requested location. p_data: The weather data. For more information about the format, see tuya_ble_wd_object_t. data_len: The length of the weather data.
Description	The mobile app gets the requested weather data from the cloud and returns it to the device.

How to use

Communication process

Code development

1. Enable the weather service component in app_config.h and enable the corresponding macro configuration.

   #define TUYA_BLE_FEATURE_WEATHER_ENABLE 1
   

2. Add code to request the weather data. This is just an example.

   // Example 1: Request temperature & humidity for two days.
   tuya_ble_feature_weather_data_request((WKT_TEMP | WKT_HUMIDITY), 2);
   
   // Example 2: Request sunrise date & time for one day.
    tuya_ble_feature_weather_data_request((WKT_SUNRISE | WKT_LOCAL), 1);
   
   // Example 3: Request the highest temperature for seven days.
    tuya_ble_feature_weather_data_request((WKT_THIHG), 7);
   
   // Example 4: Request temperature & humidity for two days, and the location is where pairing is implemented.
    tuya_ble_feature_weather_data_request_with_location(WLT_PAIR_NETWORK_LOCATION, (WKT_TEMP | WKT_HUMIDITY), 2);
   

3. Add the following snippet in the callback event handler function of tuya_ble_protocol_callback.c to implement the basic functionality. If the test function TUYA_SDK_TEST is enabled, this code is active. Each API used in the code is described in the API documentation.

   #include "tuya_ble_weather.h"
   
   STATIC VOID_T tuya_ble_protocol_callback(tuya_ble_cb_evt_param_t* event)
   {
       switch(event->evt) {
           //...
   
   #if defined(TUYA_BLE_FEATURE_WEATHER_ENABLE) && (TUYA_BLE_FEATURE_WEATHER_ENABLE != 0)
           case TUYA_BLE_CB_EVT_WEATHER_DATA_REQ_RESPONSE: {
               TAL_PR_INFO("received weather data request response result code = %d", event->weather_req_response_data.status);
           } break;
   
           case TUYA_BLE_CB_EVT_WEATHER_DATA_RECEIVED: {
               tuya_ble_wd_object_t *object;
               UINT16_T object_len = 0;
               for (;;) {
                   object = (tuya_ble_wd_object_t *)(event->weather_received_data.p_data + object_len);
   
                   TAL_PR_DEBUG("recvived weather data, n_days = [%d] key = [0x%08x] val_type = [%d] val_len = [%d]", \
                                   object->n_day, object->key_type, object->val_type, object->value_len);
                   TAL_PR_HEXDUMP_INFO("vaule :", (UINT8_T *)object->vaule, object->value_len);
   
                   // Todo
   
                   object_len += (SIZEOF(tuya_ble_wd_object_t) + object->value_len);
                   if (object_len >= event->weather_received_data.data_len)
                       break;
               }
           } break;
   #endif
   
           //...
       }
   }
   

Functional testing

Prerequisites

• You have installed the Tuya Smart app on your phone and granted location permissions to the app.
• Your device has been paired.

Procedure

Communicate with the mobile app using a host that simulates a real device.

For information on how to modify weather parameters and their relationships, see Appendix 1: Enumeration of weather service types.

If you have any problems with host usage, see Logic Host User Guide.

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.

Appendix 1: Enumeration of weather service types

/**@brief    Weather key type. */
typedef enum {
    WKT_TEMP        = (1 << 0),     /**< temperature. */
    WKT_THIHG       = (1 << 1),     /**< high temperature. */
    WKT_TLOW        = (1 << 2),     /**< low temperature. */
    WKT_HUMIDITY    = (1 << 3),     /**< humidity. */
    WKT_CONDITION   = (1 << 4),     /**< weather condition. */
    WKT_PRESSURE    = (1 << 5),     /**< pressure. */
    WKT_REALFEEL    = (1 << 6),     /**< sensible temperature. */
    WKT_UVI         = (1 << 7),     /**< uvi. */
    WKT_SUNRISE     = (1 << 8),     /**< sunrise. */
    WKT_SUNSET      = (1 << 9),     /**< sunset. */
    WKT_UNIX        = (1 << 10),    /**< unix time, used with sunrise and sunset. */
    WKT_LOCAL       = (1 << 11),    /**< local time, used with sunrise and sunset. */
    WKT_WINDSPEED   = (1 << 12),    /**< wind speed. */
    WKT_WINDDIR     = (1 << 13),    /**< wind direction. */
    WKT_WINDLEVEL   = (1 << 14),    /**< wind speed scale/level. */
    WKT_AQI         = (1 << 15),    /**< aqi. */
    WKT_TIPS        = (1 << 16),    /**< tips. */
    WKT_RANK        = (1 << 17),    /**< detailed AQI status and national ranking. */
    WKT_PM10        = (1 << 18),    /**< pm10. */
    WKT_PM25        = (1 << 19),    /**< pm2.5. */
    WKT_O3          = (1 << 20),    /**< o3. */
    WKT_NO2         = (1 << 21),    /**< no2. */
    WKT_CO          = (1 << 22),    /**< co. */
    WKT_SO2         = (1 << 23),    /**< so2. */
    WKT_CONDITIONNUM= (1 << 24),    /**< weather condition mapping id. */
    WKT_COMBINE_BITMAP_MAXVAL = (1 << SUPPORT_WEATHER_KEY_TYPE_MAX_NUMS),
} tuya_ble_weather_key_type_t;

Appendix 2: Weather service parameters

Parameter	Meaning	Value type	Mainland China	Other countries/regions	Real-time weather	Weather forecast
w.temp	Temperature	Integer	Supported	Supported	Yes	No
w.thigh	Highest temperature	Integer	-	-	No	Yes
w.tlow	Lowest temperature	Integer	-	-	No	Yes
w.humidity	Humidity	Integer	Supported	Supported	Yes	7-day forecast
w.condition	The descriptive text for weather conditions, such as sunny or rainy. The content is not fixed and multilingual configuration must prevail. We recommend you use conditionNum to return the code of weather conditions.	String	Supported	Supported	Yes	7-day forecast
w.pressure	Air pressure	Integer	Not supported	Supported	Yes	7-day forecast
w.realFeel	Apparent temperature	Integer	Not supported	Supported	Yes	7-day forecast
w.uvi	Ultraviolet index	Integer	Not supported	Supported	Yes	7-day forecast
w.sunRise	Sunrise	String	Supported	Supported	Yes	7-day forecast
w.sunSet	Sunset	String	Supported	Supported	Yes	7-day forecast
t.unix	GMT (used for the time of sunrise and sunset)	-	-	-	-	-
t.local	Local time (used for the time of sunrise and sunset)	-	-	-	-	-
w.windSpeed	Wind speed	String	Supported	Supported	Yes	7-day forecast
w.windDir	Wind direction	String	Supported	Not supported	Yes	No
w.windLevel	Wind scale	Integer	Supported	Not supported	Yes	No
w.aqi	Air quality index	Integer	Supported	Not supported	Yes	No
w.tips	Weather tips	String	-	-	Yes	No
w.rank	AQI details and national ranking	String	Supported	Not supported	Yes	No
w.pm10	PM10 (inhalable particulate matter)	Integer	Supported	Not supported	Yes	No
w.pm25	PM2.5 (fine particulate matter)	Integer	Supported	Not supported	Yes	No
w.o3	Ozone index	Integer	Supported	Not supported	Yes	No
w.no2	Nitrogen dioxide index	Integer	Supported	Not supported	Yes	No
w.co	Carbon monoxide index	Integer	Supported	Not supported	Yes	No
w.so2	Sulfur dioxide concentration	Integer	Supported	Not supported	Yes	No
w.conditionNum	Weather conditions represented by a digit code	String	Supported	Supported	Yes	7-day forecast
w.date.n	The number of days for which weather forecast is returned, ranging from 1 to 7	-	-	-	-	-

Appendix 3: Weather condition codes

conditionNum	Condition	Chinese characters in UTF-8 (Hexadecimal)
120	Sunny	E699B4
101	Heavy rain	E5A4A7 E99BA8
102	Thunderstorm	E99BB7 E69AB4
103	Sandstorm	E6B299 E5B098 E69AB4
104	Light snow	E5B08F E99BAA
105	Snow	E99BAA
106	Freezing fog	E586BB E99BBE
107	Rainstorm	E69AB4 E99BA8
108	Isolated shower	E5B180 E983A8 E998B5 E99BA8
109	Dust	E6B5AE E5B098
110	Thunder and lightning	E99BB7 E794B5
111	Light shower	E5B08F E998B5 E99BA8
112	Rain	E99BA8
113	Sleet	E99BA8 E5A4B9 E99BAA
114	Dust devil	E5B098 E58DB7 E9A38E
115	Ice pellet	E586B0 E7B292
116	Strong sandstorm	E5BCBA E6B299 E5B098 E69AB4
117	Sand blowing	E689AC E6B299
118	Light to moderate rain	E5B08F E588B0 E4B8AD E99BA8
119	Mostly clear	E5A4A7 E983A8 E699B4 E69C97
121	Fog	E99BBE
122	Shower	E998B5 E99BA8
123	Heavy shower	E5BCBA E998B5 E99BA8
124	Heavy snow	E5A4A7 E99BAA
125	Extraordinary rainstorm	E789B9 E5A4A7 E69AB4 E99BA8
126	Blizzard	E69AB4 E99BAA
127	Hail	E586B0 E99BB9
128	Light to moderate snow	E5B08F E588B0 E4B8AD E99BAA
129	Partly cloudy	E5B091 E4BA91
130	Light snow shower	E5B08F E998B5 E99BAA
131	Moderate snow	E4B8AD E99BAA
132	Overcast	E998B4
133	Needle ice	E586B0 E99288
134	Downpour	E5A4A7 E69AB4 E99BA8
136	Thundershower and hail	E99BB7 E998B5 E99BA8 E4BCB4 E69C89 E586B0 E99BB9
137	Freezing rain	E586BB E99BA8
138	Snow shower	E998B5 E99BAA
139	Light rain	E5B08F E99BA8
140	Haze	E99CBE
141	Moderate rain	E4B8AD E99BA8
142	Cloudy	E5A49A E4BA91
143	Thundershower	E99BB7 E998B5 E99BA8
144	Moderate to heavy rain	E4B8AD E588B0 E5A4A7 E99BA8
145	Heavy rain to rainstorm	E5A4A7 E588B0 E69AB4 E99BA8
146	Clear	E699B4 E69C97

Appendix 4: Wind direction codes

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