天气服务

更新时间：2024-07-30 03:09:54下载pdf

天气服务 是指蓝牙子设备支持通过 App 从云端获取所需的天气数据，本文从概念、接口说明、使用方法等维度逐一介绍。

概述

概念介绍

提供一种能力，通过与涂鸦智能 App 的通信，蓝牙 LE 设备可以方便地获取云端天气信息，并将其用于显示或其他相关功能。这为用户提供了便捷的天气服务，并增加了蓝牙 LE 设备的功能和实用性。当前支持的天气类型、国内外支持情况、以及是否支持预报等参数，详见附录二：天气服务参数表。主要流程如下图所示：

定位与位置

为了获取准确的天气数据，您需要在 涂鸦智能 App 中授权定位权限。当前支持两种位置信息：

配网位置：设备配网时所绑定的经纬度信息。
手机当前位置：手机当前经纬度信息。也就是获取当前所在区域的天气数据，推荐使用。

数据结构

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;

支持的天气类型枚举定义，每个 bit 对应一种天气类型，详见上述各项定义。

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()

当请求天气成功时 App 返回天气数据，SDK 按一定格式将其组合成 tuya_ble_weather_data_received_data_t 数据结构，并发送回调事件到应用层。应用在解析天气数据时可按上述格式解析，其中 p_data 下存放的是 N 个 tuya_ble_wd_object_t 数据类型的天气具体数据信息。

接口说明

天气能力宏配置

#define TUYA_BLE_FEATURE_WEATHER_ENABLE 1

请求天气数据-手机当前位置

接口说明

获取 手机当前位置 的天气数据，支持自定义组合天气类型以及请求天数。

/**
 * @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);

参数说明

参数	说明
combine_type	请求天气类型，支持组合形式，定义详见附录一：天气服务类型枚举例如，请求温度 + 湿度，类型为 `WKT_TEMP + WKT_HUMIDITY` 例如，请求风速 + PM10 + 紫外，类型为 `WKT_WINDSPEED + WKT_PM10 + WKT_UVI` 说明：请求日出/日落时间，必须搭配时间格式使用，例如请求日出的格林时间，`WKT_SUNRISE + WKT_UNIX`
n_days	请求天数，取值范围 `1`–`7` `1`：请求当天 `2`–`7`：请求当天以及未来 n-1 天

请求天气数据-指定位置

接口说明

获取 指定位置 的天气数据，支持自定义组合天气类型以及请求天数。

/**
 * @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);

参数说明

参数	说明
location_type	请求位置类型 `WLT_PAIR_NETWORK_LOCATION`：配网位置 `WLT_APP_CURRENT_LOCATION`：手机当前位置
combine_type	请求天气类型，支持组合形式，定义详见附录一：天气服务类型枚举
n_days	请求天数，取值范围 `1`–`7` `1`：请求当天 `2`–`7`：请求当天以及未来 n-1 天

回调事件-请求响应

TUYA_BLE_CB_EVT_WEATHER_DATA_REQ_RESPONSE

回调事件	TUYA_BLE_CB_EVT_WEATHER_DATA_REQ_RESPONSE
数据结构	typedef struct { UINT8_T status; //!< 0-success, 1-failed } tuya_ble_weather_data_req_response_t;
描述	设备调用请求 API 接口后，App 响应请求，告知设备请求结果
备注	按需调用请求接口，高频调用 App 会限制并返回失败

回调事件-天气数据

TUYA_BLE_CB_EVT_WEATHER_DATA_RECEIVED

回调事件 TUYA_BLE_CB_EVT_WEATHER_DATA_RECEIVED

数据结构

回调事件	TUYA_BLE_CB_EVT_WEATHER_DATA_RECEIVED
数据结构	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`：指 `p_data` 下有多少条天气数据 `location`：对应请求位置值 `p_data`：天气数据，格式详见 `tuya_ble_wd_object_t` `data_len`：天气数据长度
描述	App 从云端拉取到对应请求天气数据后，返回给设备

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：指 p_data 下有多少条天气数据
location：对应请求位置值
p_data：天气数据，格式详见 tuya_ble_wd_object_t
data_len：天气数据长度

描述 App 从云端拉取到对应请求天气数据后，返回给设备

使用方法

通信流程

代码开发

在 app_config.h 中启用天气服务组件，使能对应的宏配置。
```
#define TUYA_BLE_FEATURE_WEATHER_ENABLE 1
```

添加请求天气数据代码，以下仅作为示例。

// 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);

在 tuya_ble_protocol_callback.c 里的 回调事件处理函数 下添加如下代码，即可实现基本功能。如果测试功能 TUYA_SDK_TEST 是开启的，这些代码已经启用了。代码中涉及到的每个 API 在接口说明中都有涉及。

#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

        //...
    }
}

功能测试

前置条件

您已经下载了涂鸦智能 App，并已 授权开启定位权限。
确认您的设备已完成配网。

操作步骤

通过上位机（模拟实际产品）和手机 App 进行数据交互，如下图所示：

关于修改天气参数及对应关系，参考附录一：天气服务类型枚举。

上位机使用的相关问题，请访问 Logic 上位机使用指南。

支持与帮助

在开发过程遇到问题，您可以登录 TuyaOS 开发者论坛 TuyaOS-蓝牙设备开发版块进行沟通咨询。

咨询前建议首先查阅官方资料或参考已有帖子，并认真阅读发帖规范。

附录一：天气服务类型枚举

/**@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;

附录二：天气服务参数表

对国内/外以及实时/预报情况云端会持续更新，下表统计数据为文档编辑时支持情况。

天气数据参数	含义	值类型	国内	国外	是否支持实时	是否支持预报
w.temp	温度	整形	支持	支持	是	否
w.thigh	最高温度	整形	-	-	否	是
w.tlow	最低温度	整形	-	-	否	是
w.humidity	湿度	整形	支持	支持	是	支持 7 天内数据
w.condition	天气状况描述文本，如晴、雨等，非固定，以多语言配置为准。建议用 `conditionNum` 天气状况枚举	字符串	支持	支持	是	支持 7 天内数据
w.pressure	气压	整形	不支持	支持	是	支持 7 天内数据
w.realFeel	体感温度	整形	不支持	支持	是	支持 7 天内数据
w.uvi	紫外线指数	整形	不支持	支持	是	支持 7 天内数据
w.sunRise	日出	字符串	支持	支持	是	支持 7 天内数据
w.sunSet	日落	字符串	支持	支持	是	支持 7 天内数据
t.unix	格林时间（搭配日出/日落使用）	-	-	-	-	-
t.local	本地时间（搭配日出/日落使用）	-	-	-	-	-
w.windSpeed	风速	字符串	支持	支持	是	支持 7 天内数据
w.windDir	风向	字符串	支持	不支持	是	否
w.windLevel	风等级	整形	支持	不支持	是	否
w.aqi	空气质量指数	整形	支持	不支持	是	否
w.tips	天气贴士	字符串	-	-	是	否
w.rank	详细 AQI 实况及全国排名	字符串	支持	不支持	是	否
w.pm10	PM10（可吸入颗粒物）	整形	支持	不支持	是	否
w.pm25	PM2.5（细颗粒物）	整形	支持	不支持	是	否
w.o3	o3 指数	整形	支持	不支持	是	否
w.no2	no2 指数	整形	支持	不支持	是	否
w.co	co 指数	整形	支持	不支持	是	否
w.so2	二氧化硫浓度	整形	支持	不支持	是	否
w.conditionNum	天气状况，以数字编码方式表示	字符串	支持	支持	是	支持 7 天内数据
w.date.n	需要预报天数（1-7）	-	-	-	-	-

附录三：天气状况编码对照表

编码 conditionNum	天气-中文 condition	中文 UTF-8 编码（16 进制）
120	晴	E699B4
101	大雨	E5A4A7 E99BA8
102	雷暴	E99BB7 E69AB4
103	沙尘暴	E6B299 E5B098 E69AB4
104	小雪	E5B08F E99BAA
105	雪	E99BAA
106	冻雾	E586BB E99BBE
107	暴雨	E69AB4 E99BA8
108	局部阵雨	E5B180 E983A8 E998B5 E99BA8
109	浮尘	E6B5AE E5B098
110	雷电	E99BB7 E794B5
111	小阵雨	E5B08F E998B5 E99BA8
112	雨	E99BA8
113	雨夹雪	E99BA8 E5A4B9 E99BAA
114	尘卷风	E5B098 E58DB7 E9A38E
115	冰粒	E586B0 E7B292
116	强沙尘暴	E5BCBA E6B299 E5B098 E69AB4
117	扬沙	E689AC E6B299
118	小到中雨	E5B08F E588B0 E4B8AD E99BA8
119	大部晴朗	E5A4A7 E983A8 E699B4 E69C97
121	雾	E99BBE
122	阵雨	E998B5 E99BA8
123	强阵雨	E5BCBA E998B5 E99BA8
124	大雪	E5A4A7 E99BAA
125	特大暴雨	E789B9 E5A4A7 E69AB4 E99BA8
126	暴雪	E69AB4 E99BAA
127	冰雹	E586B0 E99BB9
128	小到中雪	E5B08F E588B0 E4B8AD E99BAA
129	少云	E5B091 E4BA91
130	小阵雪	E5B08F E998B5 E99BAA
131	中雪	E4B8AD E99BAA
132	阴	E998B4
133	冰针	E586B0 E99288
134	大暴雨	E5A4A7 E69AB4 E99BA8
136	雷阵雨伴有冰雹	E99BB7 E998B5 E99BA8 E4BCB4 E69C89 E586B0 E99BB9
137	冻雨	E586BB E99BA8
138	阵雪	E998B5 E99BAA
139	小雨	E5B08F E99BA8
140	霾	E99CBE
141	中雨	E4B8AD E99BA8
142	多云	E5A49A E4BA91
143	雷阵雨	E99BB7 E998B5 E99BA8
144	中到大雨	E4B8AD E588B0 E5A4A7 E99BA8
145	大到暴雨	E5A4A7 E588B0 E69AB4 E99BA8
146	晴朗	E699B4 E69C97

附录四：风向简码编码表

风向简码（字符串）	十六进制	描述
N	4e	北
NNE	4e 4e 45	东北偏北
NE	4e 45	东北
ENE	45 4e 45	东北偏东
E	45	东
ESE	45 53 45	东南偏东
SE	53 45	东南
SSE	53 53 45	东南偏南
S	53	南
SSW	53 53 57	西南偏南
SW	53 57	西南
WSW	57 53 57	西南偏西
W	57	西
WNW	57 4e 57	西北偏西
NW	4e 57	西北
NNW	4e 4e 57	西北偏北

上一篇时间服务

下一篇OTA 升级