English
English
简体中文
Contact Us
Register
Log In
Language
English
English
简体中文
Contact Us
Log In
Register
Go to main website
App Develop

App Development Platform

App development platform provides multiple development methods such as no-code or IoT App SDK development to maximize the monetization of IoT apps.
layoutIndex

Weather Service

Last Updated on : 2021-08-24 06:18:28download

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

Enable the weather service

The MCU sends the following command:

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: 0x06 K: w.temp
  • 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 74 65 6d 70 06 77 2e 70 6d 32 35 08 77 2e 64 61 74 65 2e 37 32

  • 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.temp, w.date.1: the temperature of the current day.
    • w.temp, w.date.7: the temperature 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 Greenwich Mean Time (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 command:

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 command:

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.temp.0:35 w.temp.1:35 w.temp.2:35 w.temp.3:35 w.temp.4:35 w.temp.5:35 w.temp.6:35
    • w.pm25:14

    The MCU returns the following command:

    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 the supported parameters and comment out the undesired ones.
     */
    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 parameter value address.
     * @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

    Request current weather data

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

    • The module returns {"codes": "w.temp.0":13,"w.humidity.0":100}.

    Request daily forecasts

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

    • The module returns {"w.temp.0":13,"w.humidity.0":100, "w.temp.1":13,"w.humidity.1":100, "w.temp.2":13, "w.humidity.2":100}.

    Request the time of sunrise and sunset

    • GMT

      • The MCU sends { "w.temp","w.humidity", "w.sunRise", "w.sunSet", "t.unix","w.date.3"}.

      • The module returns:

        { "w.temp.0":13,"w.humidity.0":100, "w.sunRise.0":"2019-12-27
        22:54","w.sunSet.0":"2019:12:28:09:05","w.temp.1":13,"w.humidity.1":100, "w.sunRise.1":"2019-12-27
        22:54","w.sunSet.1":"2019-12-28
        09:05","w.temp.2":13,"w.humidity.2":100,"w.sunRise.2":"2019-12-27
        22:54","w.sunSet.2":"2019-12-28 09:05"}
        
    • Local time

      • The MCU sends { "w.temp","w.humidity", "w.sunRise", "w.sunSet", "t.local","w.date.3"}.

      • The module returns:

        { "w.temp.0":13,"w.humidity.0":100, "w.sunRise.0":"2019-12-28
        06:54","w.sunSet.0":"2019-12-28
        17:05","w.temp.1":13,"w.humidity.1":100, "w.sunRise.1":"2019-12-28
        06:54","w.sunSet.1":"2019-12-28
        17:05","w.temp.2":13,"w.humidity.2":100,"w.sunRise.2":"2019-12-28
        06:54","w.sunSet.2":"2019-12-28 17:05"}
        

    Request daily forecasts and measured air data

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

    • The module returns:

      {"w.pm10.0": 14, "w.pm25.0": 7, "w.temp.0":13,"w.humidity.0":100, "w.temp.1":13,"w.humidity.1":100, "w.temp.2":13,"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 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 Support Support N/A 6 77 2e 74 65 6d 70
    w.humidity Air humidity Support Support 7-day forecast 10 77 2e 68 75 6d 69 64 69 74 79
    w.condition.num Weather condition code Support Support 7-day forecast 11 77 2e 63 6f 6e 64 69 74 69 6f 6e
    w.pressure Atmospheric pressure Support Support 7-day forecast (except for mainland China) 10 77 2e 70 72 65 73 73 75 72 65
    w.realFeel Apparent temperature Support Support N/A 10 77 2e 72 65 61 6c 46 65 65 6c
    w.uvi Ultraviolet index Support Support 7-day forecast 5 77 2e 75 76 69
    w.sunRise Sunrise Support Support 7-day forecast 9 77 2e 73 75 6e 52 69 73 65
    w.sunSet Sunset Support Support 7-day forecast 8 77 2e 73 75 6e 53 65 74
    t.unix GMT (used for the time of sunrise and sunset) N/A N/A N/A 6 74 2e 75 6e 69 78
    t.local Local time (used for the time of sunrise and sunset) N/A N/A N/A 7 74 2e 6c 6f 63 61 6c
    w.windSpeed Wind speed Support Support 7-day forecast 11 77 2e 77 69 6e 64 53 70 65 65 64
    w.windDir Wind direction Support (Chinese character returned) Support (code returned) 7-day forecast 9 77 2e 77 69 6e 64 44 69 72
    w.windLevel Wind scale Support (mainland China only) N/A 7-day forecast 11 77 2e 77 69 6e 64 4c 65 76 65 6c
    w.aqi Air quality index Support Support Current day only 5 77 2e 61 71 69
    w.rank/w.quality AQI details and national ranking Support (mainland China only) N/A 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) Support Support Current day only 6 77 2e 70 6d 31 30
    w.pm25 PM2.5 (fine particulate matter) Support Support Current day only 6 77 2e 70 6d 32 35
    w.o3 Ozone level Support Support Current day only 4 77 2e 6f 33
    w.no2 Nitrogen dioxide level Support Support Current day only 5 77 2e 6e 6f 32
    w.co Carbon monoxide level Support Support Current day only 4 77 2e 63 6f
    w.so2 Sulfur dioxide level Support Support Current day only 5 77 2e 73 6f 32
    w.thigh The highest temperature Support Support Forecast only 7 77 2e 74 68 69 67 68
    w.tlow The lowest temperature Support Support Forecast only 6 77 2e 74 6c 6f 77
    w.date.n (1 ≤ n ≤ 7) How many days the forecast responses are returned Support Support N/A 8 77 2e 64 61 74 65 2e 6e
    • WindDir indicates the wind direction. This field is used for text display and does not support enum values or configuring multilingual text. For services available in mainland China and other regions, the text is displayed in Chinese and code respectively.
    • w.condition.num indicates weather condition code. For more information, see Appendix 4.

    Appendix 2: City service data in ASCII

    ID Description Type Length Hexadecimal value
    c.area County or district name String 6 63 2e 61 72 65 61
    c.city City name 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 enable the location on their mobile phone and pair the device with the mobile app again.

    Appendix 3: Weather forecast service data

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

    The number in the string is rounded to one decimal place. Example: 1.0; 0.9

    Appendix 4: Weather data in UTF-8 encoding

    Note that the text content varies depending on the configuration of multilingual text.

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