2026-01-24 11:40:41

天气预报服务功能

本文介绍如何使用涂鸦 MCU SDK 为设备获取天气数据。

打开获取天气数据功能

MCU 发送

字段

字节数

说明

帧头

0x55aa

版本

0x03

命令字

0x20

数据长度

N((L+K)+(L+K)+…)

数据

Data

L：占用 1 byte，表示 K 的长度 K：请求参数名称，支持的参数名称见附录一支持预报参数示例： L：0x0A K：w.humidity L：0x08 K：w.date.7 不支持预报参数示例： L：0x06 K：w.pm25

校验和

从帧头开始，按字节求和，得出的结果对 256 求余

例：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

支持预报的参数，再获取时需要添加上需要预报的数据天数，最多可支持获取 7 天内的数据。

示例：

w.humidity, w.date.1：要当天的空气湿度预报数据

w.humidity, w.date.7：要以当天为开始，7 天内的空气湿度预报数据

不支持预报的数据，获取时不可添加上天数内容。

示例：w.pm2.5

当获取的参数是和时间有关的参数时，需要搭配 t.unix 或者 t.local 使用，需要获取的参数数据是按照格林时间还是本地时间。

示例：

L: 0x0b K: w.sunRise

L: 0x0b K: w.date.7

L: 0x06 K: t.unix

模组返回的日出时间为格林时间。时间格式：年-月-日时:分

模组返回

字段

字节数

说明

帧头

0x55aa

版本

0x00

命令字

0x20

数据长度

0x0002

数据

0x00 表示失败 0x01 错误码，数据格式非法 0x02 错误码，异常错误 0x01 表示成功 0x00

校验和

从帧头开始，按字节求和，得出的结果对 256 求余

例：0x55aa 00 20 0002 0100 22

下发天气数据

下发天气数据，在打开天气数据功能后模组，定时下发。

模组发送

字段

字节数

说明

帧头

0x55aa

版本

0x00

命令字

0x21

数据长度

数据

0x00 表示失败 0x01 错误码，表示参数服务没权限，此时请确认您是否购买了该参数服务 0x01 表示成功 L：参数名长度 K：参数名 T：0x00 整形、0x01 字符串 L：字段名长度 V：字段值

校验和

从帧头开始，按字节求和，得出的结果对 256 求余

例：

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

MCU 模组返回

字段

字节数

说明

帧头

0x55aa

版本

0x00

命令字

0x21

数据长度

0x0000

数据

无

校验和

从帧头开始，按字节求和，得出的结果对 256 求余

例：0x55aa 00 21 0000 20

对应 MCU SDK 中相关函数

宏定义：

/******************************************************************************

是否开启天气功能

如需要请开启该宏，并在 protocol.c 文件内 weather_open_return_handle 与 weather_data_user_handle 两个用户处理函数中实现显示等代码

此两函数内#err 提示，完成函数后请删除该#err

开启天气功能，串口数据缓存区的大小要开大一些

******************************************************************************/

//#define WEATHER_ENABLE //打开天气功能

#ifdef WEATHER_ENABLE

/* 在 protocol.c 文件中 weather_choose 数组中可调整，然后将打开服务的类型数目写到此宏定义 */

#define WEATHER_CHOOSE_CNT 4 //选择的需要天气服务类型的数目

/* 在打开天气服务时，可以设置此宏定义选择天气预报的天数，1 表示当天天气(不需要预报可设置为 1)，最多为 7 天(不可以设置成 0 或大于 7) */

#define WEATHER_FORECAST_DAYS_NUM 1 //设置天气预报的天数

#endif

天气数据参数选择数组，用户可以自定义需要的参数：

#ifdef WEATHER_ENABLE

/**

* @var weather_choose

* @brief 天气数据参数选择数组

* @note 用户可以自定义需要的参数，注释或者取消注释即可，注意更改。以文档内容为准。

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

打开天气功能返回用户自处理函数：

/**

* @brief 打开天气功能返回用户自处理函数

* @param[in] {res} 打开天气功能返回结果

* @ref 0：失败

* @ref 1：成功

* @param[in] {err} 错误码

* @return Null

* @note MCU 需要自行实现该功能

void weather_open_return_handle(unsigned char res, unsigned char err)

{

#error "请自行完成打开天气功能返回数据处理代码,完成后请删除该行"

unsigned char err_num = 0;

if(res == 1) {

//打开天气返回成功

}else if(res == 0) {

//打开天气返回失败

//获取错误码

err_num = err;

}

天气数据用户自处理函数：

/**

* @brief 天气数据用户自处理函数

* @param[in] {name} 参数名

* @param[in] {type} 参数类型

* @ref 0：Int 型

* @ref 1：String 型

* @param[in] {data} 参数值的地址

* @param[in] {day} 哪一天的天气 0：表示当天取值范围：0~6

* @ref 0：今天

* @ref 1：明天

* @return Null

* @note MCU 需要自行实现该功能

void weather_data_user_handle(char *name, unsigned char type, const unsigned char *data, char day)

{

#error "这里仅给出示例，请自行完善天气数据处理代码，完成后请删除该行"

int value_int;

char value_string[50];//由于有的参数内容较多，这里默认为 50。您可以根据定义的参数，可以适当减少该值

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

//首先获取数据类型

if(type == 0) { //参数是 INT 型

value_int = data[0] << 24 | data[1] << 16 | data[2] << 8 | data[3];

}else if(type == 1) {

my_strcpy(value_string, data);

}

//注意要根据所选参数类型来获得参数值！！！

if(my_strcmp(name, "temp") == 0) {

printf("day:%d temp value is:%d\r\n", day, value_int); //int 型

}else if(my_strcmp(name, "humidity") == 0) {

printf("day:%d humidity value is:%d\r\n", day, value_int); //int 型

}else if(my_strcmp(name, "pm25") == 0) {

printf("day:%d pm25 value is:%d\r\n", day, value_int); //int 型

}else if(my_strcmp(name, "condition.num") == 0) {

printf("day:%d condition value is:%s\r\n", day, value_string); //string 型

}

MCU 仿真调试助手模拟

打开天气功能：

all 中列出了所有当前支持的天气信息，根据需要双击选择。

selected 中显示当前已选天气信息，双击可取消选择。

完成后点击打开天气功能，天气数据会自动下发，具体在模组首次上电或每隔 30min 下发一次。

命令解析

接收到的数据 RX：

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 表示获取天气数据成功，

以第二组数据 06 77 2e 70 6d 32 35 00 04 00 00 00 11 为例：

06：参数名 w.pm25 的长度，

77 2e 70 6d 32 35：转换为字符为 w.pm25，

00 04：天气为数值（00），天气长度 04，

00 00 00 11：转换为十进制数据为 17，表示当前 PM2.5 的数据量为 17。

天气预报服务功能示例

以下示例，以中国大陆地区的设备为参考示例。

查询当天实时数据

MCU 发送：{"w.temp","w.humidity"} 或 {"w.temp","w.humidity","w.currdate"}

模组返回：

{

"w.temp":13,

"w.humidity":100

}

只查询当天的预报数据

查询返回的数据，为预报型数据，请将当天的预报数据，与实时数据做好区别使用。

MCU 发送：{"w.humidity","w.date.1"}

模组返回：

{

"w.humidity.0":100

}

查询多天的数据

MCU 发送：{"w.humidity","w.date.3"}

模组返回：

{

"w.humidity.0":100,

"w.humidity.1":100,

"w.humidity.2":100

}

查询日出日落的天气数据

格林时间（以 UTC +8 时区为例）

MCU 发送：{ "w.humidity","w.sunrise","w.sunset","t.unix","w.date.3" }

模组返回：

{

"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"

}

本地时间（以 UTC +8 时区为例）

MCU 发送：{ "w.humidity","w.sunrise","w.sunset","t.local","w.date.3" }

模组返回：

{

"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"

}

掺杂不支持预报的参数获取示例

MCU 发送：{ "w.temp","w.humidity","w.pm10","w.pm25","w.date.3" }

模组返回：

{

"w.pm10.0":14,

"w.pm25.0":7,

"w.humidity.0":100,

"w.humidity.1":100,

"w.humidity.2":100

}

若 MCU 的入参 w.date.n 中，n >7 或者 n<=0 时，云端按照数据入参异常，此时无返回数据。

附录一：天气数据参数 ASCII 码

天气数据参数

含义

中国大陆

其他国家或地区

是否支持预报

长度

十六进制

w.temp

大气温度，单位：摄氏度 ℃

支持

支持 7 天内数据，中国大陆地区不支持

77 2e 74 65 6d 70

w.humidity

空气湿度

支持

支持 7 天内数据

77 2e 68 75 6d 69 64 69 74 79

w.conditionNum

天气概况数字编码

支持

支持 7 天内数据

77 2e 63 6f 6e 64 69 74 69 6f 6e 4e 75 6d

w.pressure

大气气压，单位：毫巴 mbar

支持

支持 7 天内数据，中国大陆地区不支持

77 2e 70 72 65 73 73 75 72 65

w.realFeel

体感温度

支持

不支持 7 天内数据

77 2e 72 65 61 6c 46 65 65 6c

w.uvi

紫外线指数

支持

支持 7 天内数据

77 2e 75 76 69

w.sunrise

日出

支持

支持 7 天内数据

77 2e 73 75 6e 72 69 73 65

w.sunset

日落

支持

支持 7 天内数据

77 2e 73 75 6e 73 65 74

t.unix

格林时间，搭配日出（w.sunrise）和日落（w.sunset）使用

74 2e 75 6e 69 78

t.local

本地时间，搭配日出（w.sunrise）和日落（w.sunset）使用

74 2e 6c 6f 63 61 6c

w.windSpeed

风速，单位：米/秒（m/s）

支持

支持 7 天内数据

77 2e 77 69 6e 64 53 70 65 65 64

w.windDir

风向

支持

支持 7 天内数据

77 2e 77 69 6e 64 44 69 72

w.windLevel

风级

仅中国大陆地区支持

不支持

支持 7 天内数据

77 2e 77 69 6e 64 4c 65 76 65 6c

w.aqi

空气质量指数，采用美国 EPA 标准：0 ~ 500

支持

仅有当天数据

77 2e 61 71 69

w.rank/w.quality

详细 AQI 实况及全国排名

仅中国大陆地区支持

不支持

仅有当天数据

77 2e 72 61 6e 6b / 77 2e 71 75 61 6c 69 74 79

w.pm10

可吸入颗粒物 PM10，单位：µg/m³

支持

仅有当天数据

77 2e 70 6d 31 30

w.pm25

细颗粒物 PM2.5，单位：µg/m³

支持

仅有当天数据

77 2e 70 6d 32 35

w.o3

臭氧浓度，单位：µg/m³

支持

仅有当天数据

77 2e 6f 33

w.no2

二氧化氮浓度，单位：µg/m³

支持

仅有当天数据

77 2e 6e 6f 32

w.co

一氧化碳浓度，单位：µg/m³

支持

仅有当天数据

77 2e 63 6f

w.so2

二氧化硫浓度，单位：µg/m³

支持

仅有当天数据

77 2e 73 6f 32

w.thigh

最高温度，单位：摄氏度 ℃）

支持

仅有预报数据

77 2e 74 68 69 67 68

w.tlow

最低温度，单位：摄氏度 ℃）

支持

仅有预报数据

77 2e 74 6c 6f 77

w.date.n

需要预报的天数，用 n 来表示天数，要求 1<= n <=7

支持

77 2e 64 61 74 65 2e 6e

w.currdate

实时天气获取

支持

77 2e 63 75 72 72 64 61 74 65

WindDir 为风向字段。为风向简码，详细编码表请参考附录五。

w.conditionNum 表示天气情况编码，详细编码表请参考附录四。

大气气压单位说明：

1 毫巴（mbar）=1 百帕斯卡(hPa)，即 1mbar = 100pa = 1hpa。

例如，中国大陆地区的墨迹天气数据单位是百帕斯卡(hPa)。

是否支持预报：携带 w.date.n 字段时，返回预报数据。

是否支持实时：当携带 w.date.n 字段访问时，若需要实时天气数据，请携带 w.currdate 字段。具体实时数据的访问方式，请参考天气预报服务功能示例。

附录二：城市服务参数 ASCII 码对照

标识

描述

类型

长度

十六进制

c.area

区县或城市名称

字符串

63 2e 61 72 65 61

c.city

城市名称

字符串

63 2e 63 69 74 79

c.province

省

字符串

63 2e 70 72 6f 76 69 6e 63 65

当天气服务访问时返回的数据仅有城市服务字段，且内容为空时，则说明设备无经纬度信息，无法获取天气数据。可打开手机应用的获取定位功能后，重新进行设备配网。

附录三：天气预报服务数值类型

标识

描述

类型

是否支持实时

是否支持预报

w.temp

温度

整数

是

仅中国大陆地区不支持

w.humidity

湿度

整数

是

w.conditionNum

天气概况数字编码

字符串

是

w.pressure

气压

整数

是

仅中国大陆地区不支持

w.realFeel

温度实感

整数

是

否

w.uvi

紫外线指数

整数

是

w.windDir

风向

字符串

是

w.windLevel

风等级

整数

仅中国大陆地区支持

否

w.windSpeed

风速

字符串，数据格式为 1.0；0.5

是

w.sunrise

日出时间

字符串，数据格式为 2017-04-24 05:24

是

w.sunset

日落时间

字符串，数据格式为 2017-04-24 18:32

是

w.aqi

空气质量指数

整数

是

否

w.pm25

PM 2.5

整数

是

否

w.so2

二氧化硫浓度

整数

是

否

w.rank/w.quality

空气评分

字符串，数据格式为 447/609

仅中国大陆地区支持

否

w.pm10

PM 10

整数

是

否

w.o3

臭氧（O3）浓度

整数

是

否

w.no2

二氧化氮（NO2）浓度

整数

是

否

w.co

一氧化碳（CO）浓度

整数

是

否

w.qualityLevel

空气质量评分等级

整形

是

否

w.thigh

最高温度

整形

否

是

w.tlow

最低温度

整形

否

是

天气参数中，字符串格式类型的数据内容为数字时，数字按照四舍五入的规则只保留一位小数位。示例：1.0；0.9。

是否支持实时：当携带 w.date.n 字段访问时，若需要实时天气数据请携带w.currdate字段。具体实时数据的访问方式，请参考天气预报服务功能示例。

是否支持预报：携带 w.date.n 字段时，返回预报数据。

附录四：中文天气 UTF-8 编码

编码表示（ASCII 码） w.conditionNum

十六进制

天气状况

120

31 32 30

晴

101

31 30 31

大雨

102

31 30 32

雷暴

103

31 30 33

沙尘暴

104

31 30 34

小雪

105

31 30 35

雪

106

31 30 36

冻雾

107

31 30 37

暴雨

108

31 30 38

局部阵雨

109

31 30 39

浮尘

110

31 31 30

雷电

111

31 31 31

小阵雨

112

31 31 32

雨

113

31 31 33

雨夹雪

114

31 31 34

尘卷风

115

31 31 35

冰粒

116

31 31 36

强沙尘暴

117

31 31 37

扬沙

118

31 31 38

小到中雨

119

31 31 39

大部晴朗

121

31 32 31

雾

122

31 32 32

阵雨

123

31 32 33

强阵雨

124

31 32 34

大雪

125

31 32 35

特大暴雨

126

31 32 36

暴雪

127

31 32 37

冰雹

128

31 32 38

小到中雪

129

31 32 39

少云

130

31 33 30

小阵雪

131

31 33 31

中雪

132

31 33 32

阴

133

31 33 33

冰针

134

31 33 34

大暴雨

136

31 33 36

雷阵雨伴有冰雹

137

31 33 37

冻雨

138

31 33 38

阵雪

139

31 33 39

小雨

140

31 34 30

霾

141

31 34 31

中雨

142

31 34 32

多云

143

31 34 33

雷阵雨

144

31 34 34

中到大雨

145

31 34 35

大到暴雨

146

31 34 36

晴朗

附录五：风向简码编码表

风向简码（字符串）

十六进制

描述

北

NNE

4e 4e 45

东北偏北

4e 45

东北

ENE

45 4e 45

东北偏东

东

ESE

45 53 45

东南偏东

53 45

东南

SSE

53 53 45

东南偏南

南

SSW

53 53 57

西南偏南

53 57

西南

WSW

57 53 57

西南偏西

西

WNW

57 4e 57

西北偏西

4e 57

西北

NNW

4e 4e 57

西北偏北

女生说你喜欢我哪该怎么回答
什么公什么私的成语