Time Service

Last Updated on : 2024-05-10 09:59:45download

This topic describes the time service that enables you to get the current date and time for display or logic processing. The MCU can request the Greenwich Mean Time (GMT) and local time through the Wi-Fi or Wi-Fi and Bluetooth combo module. After the module is connected to the cloud, the MCU can request the current system time.

The MCU automatically synchronizes time with the server during each data interaction or every six hours in case of no interaction. The module comes with a software real-time clock (RTC) that provides time for the MCU. Therefore, even when the module is offline, the MCU can also get the time. The module supports time service notifications. After the Wi-Fi or Wi-Fi and Bluetooth combo module is powered on and connected, it will notify the MCU when the time sync is completed.

To get the accurate time data on the first time request, the MCU should send the command five seconds after the module is connected to the cloud. For later requests, the frequency can vary depending on applications but should be more than one second.
The time offset between the built-in RTC time and the server time is less than 10 seconds within 24 hours.
The accuracy of the module’s software RTC relies on time sync with the server. If the module fails to connect to the cloud after restarting while offline, it cannot get the accurate time.

Commands

Time service commands:

Command	Description
0x0c	Get the GMT
0x1c	Get the local time
0x34 (subcommand: 0x01)	Enable time service notifications
0x34 (subcommand: 0x02)	Time service notifications

Get the GMT (0x0c)

As the international standard of civil time, GMT is independent of the time zone and daylight saving time (DST). After connecting to the network, the module returns success and valid time data after the local timestamp is synced.

With a Wi-Fi and Bluetooth combo module, the MCU can request the time data when it receives the Bluetooth status value 0x03. When the device connects to the mobile app, the app must have access to the internet.
When the MCU receives the network status value 0x04, the module will start syncing time with the time server.
If you do not want the MCU to poll the time data after power on, you can turn on time service notifications to enable the module to send the time data to the MCU after it finishes time sync.

It takes time to sync time. If the MCU requests the time data immediately after receiving the network status from the module, the request might fail. In this case, the MCU should try to send the request again.
For Wi-Fi and Bluetooth combo modules, update to the latest firmware to support time sync over Bluetooth.

The MCU sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x0c
Data length	2	0x0000
Data	0	None
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 03 0c 00 00 0e

The module returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x0c
Data length	2	0x0007
Data	7	The data length is seven bytes. Data[0] indicates whether the time is obtained successfully. `0`: Failure. `1`: Success. Data[1] indicates the year. `0x00` indicates the year 2000. Data[2] indicates the month, ranging from 1 to 12. Data[3] indicates the day, ranging from 1 to 31. Data[4] indicates the hour, ranging from 0 to 23. Data[5] indicates the minute, ranging from 0 to 59. Data[6] indicates the second, ranging from 0 to 59.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 05:06:07 on April 19, 2016 in GMT.

55 aa 00 0c 00 07 01 10 04 13 05 06 07 4c

Get the local time (0x1c)

The local time is calculated by adding the time zone offset and DST to the GMT. The time zone is where the device is activated. After connecting to the network, the module returns success and valid time data after the local timestamp is synced.

The local time indicates the system time zone on the mobile app that is paired with the device.

With a Wi-Fi and Bluetooth combo module, the MCU can request the time data when it receives the Bluetooth status value 0x03. When the device connects to the mobile app, the app must have access to the internet.
When the MCU receives the network status value 0x04, the module will start syncing time with the time server.
If you do not want the MCU to poll the time data after power on, you can turn on time service notifications to enable the module to send the time data to the MCU after it finishes time sync.

It takes time to sync time. If the MCU requests the time data immediately after receiving the network status from the module, the request might fail. In this case, the MCU should try to send the request again.
For Wi-Fi and Bluetooth combo modules, update to the latest firmware to support time sync over Bluetooth.

The MCU sends the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x1c
Data length	2	0x0000
Data	0	None
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 03 1c 00 00 1e

The module returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x1c
Data length	2	0x0008
Data	8	The data length is eight bytes. Data[0] indicates whether the time is obtained successfully. `0`: Failure. `1`: Success. Data[1] indicates the year. `0x00` indicates the year 2000. Data[2] indicates the month, ranging from 1 to 12. Data[3] indicates the day, ranging from 1 to 31. Data[4] indicates the hour, ranging from 0 to 23. Data[5] indicates the minute, ranging from 0 to 59. Data[6] indicates the second, ranging from 0 to 59. Data[7] indicates the day of the week, ranging from 1 to 7, with Monday as 1.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Enable time service notifications (0x34 & 0x01)

The module synchronizes time with the server approximately 10 seconds after connecting to the cloud. The time service notification is disabled by default after the module is powered on, during which the MCU will keep attempting to request the time. With time service notifications enabled, the Wi-Fi or Wi-Fi and Bluetooth combo module will notify the MCU when the time sync is completed.

After power-on, the MCU sends the command to enable time service notifications and selects the time service. The module enables the notification accordingly and returns the result.

After a power cycle, time service notifications are disabled by default.
After time service notifications are enabled, the module will send the time data to the MCU through a notification.
If the time service has already been enabled, the module will reject the repeated enablement request unless it is restarted. Typically, the MCU can use the ordinary time request command to get the time data.

The MCU sends the following data.

Field	Length	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x34
Data length	2	0x0002
Data	1	0x01 (subcommand)
	1	`0x00`: GMT `0x01`: Local time
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 03 34 00 02 01 01 3a

The module returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x34
Data length	2	0x0002
Data	1	0x01 (subcommand)
	1	`0x00`: The service is enabled successfully. `0x01`: Failed to enable the service.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 00 34 00 02 01 00 36

Time service notifications (0x34 & 0x02)

With time service notifications enabled, the module sends the time data to the MCU after it synchronizes time with the server.

After a power cycle, time service notifications are disabled by default. The MCU needs to manually enable time service notifications.

The module sends the following data.

Field	Length	Description
Header	2	0x55aa
Version	1	0x00
Command	1	0x34
Data length	2	0x0009
Data	1	0x02 (subcommand)
	1	`0x00`: GMT `0x01`: Local time
	7	The data length is six bytes. Data[0] indicates the year. `0x00` indicates the year 2000. Data[1] indicates the month, ranging from 1 to 12. Data[2] indicates the day, ranging from 1 to 31. Data[3] indicates the hour, ranging from 0 to 23. Data[4] indicates the minute, ranging from 0 to 59. Data[5] indicates the second, ranging from 0 to 59. Data[6] indicates the day of the week, ranging from 1 to 7, with Monday as 1.
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: If the local time is Monday at 18:35:28 on August 23, 2021, the module sends the following data.

55 aa 00 34 00 09 02 01 15 08 17 12 23 1c 01 c5

The MCU returns the following data.

Field	Bytes	Description
Header	2	0x55aa
Version	1	0x03
Command	1	0x34
Data length	2	0x0001
Data	1	0x02 (subcommand)
Checksum	1	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: 55 aa 03 34 00 01 02 39

Example

Get the GMT

Enable SUPPORT_GREEN_TIME to turn on the GMT service.

#define         SUPPORT_GREEN_TIME                //Turn on the GMT service.

The MCU calls mcu_get_green_time() in mcu_api.c to request the GMT.

/**
 * @brief The MCU gets the GMT.
 * @param Null
 * @return Null
 * @note   To be implemented by you.
 */
void mcu_get_green_time(void)
{
    wifi_uart_write_frame(GET_ONLINE_TIME_CMD, MCU_TX_VER, 0);
}

The MCU gets the time data from data_handle() and calls mcu_get_greentime() to proceed with the next operation.

void data_handle(unsigned short offset)
{
    ......
        #ifdef SUPPORT_GREEN_TIME
        case GET_ONLINE_TIME_CMD:                               //Get the GMT.
                mcu_get_greentime((unsigned char *)(wifi_data_process_buf + offset + DATA_START));
        break;
        #endif
    ......
}

Get the GMT. This function needs to be implemented by you.

/**
 * @brief Get the GMT.
 * @param[in] {time} The GMT.
 * @return Null
 * @note  To be implemented by you.
 */
void mcu_get_greentime(unsigned char time[])
{
    #error "Complete the code and delete this row"
    /*
    time[0] indicates whether the time is obtained successfully. `0`: failure. `1`: success.
    time[1] indicates the year. `0x00` indicates the year 2000.
    time[2] indicates the month, ranging from 1 to 12.
    time[3] indicates the day, ranging from 1 to 31.
    time[4] indicates the hour, ranging from 0 to 23.
    time[5] indicates the minute, ranging from 0 to 59.
    time[6] indicates the second, ranging from 0 to 59.
    */
    if(time[0] == 1) {
        // Correct GMT is received.

    }else {
        // Correct GMT is not received. It might be because the module is not connected to the network.
    }
}

Module Debugging Assistant

Get the local time

Enable SUPPORT_MCU_RTC_CHECK to turn on the local time service.

#define         SUPPORT_MCU_RTC_CHECK                //Enable time sync with the cloud server.

The MCU calls mcu_get_system_time() in mcu_api.c to request the local time.

/**
 * @brief The MCU gets the system time to sync with its local clock.
 * @param Null
 * @return Null
 * @note   The MCU calls `mcu_write_rtctime` to sync time with the RTC time.
 */
void mcu_get_system_time(void)
{
    wifi_uart_write_frame(GET_LOCAL_TIME_CMD, MCU_TX_VER, 0);
}

The MCU gets the time data from data_handle() and calls mcu_write_rtctime() to proceed with the next operation.

void data_handle(unsigned short offset)
{
    ......
    #ifdef SUPPORT_MCU_RTC_CHECK
    case GET_LOCAL_TIME_CMD:               // Get the local time.
        mcu_write_rtctime((unsigned char *)(wifi_data_process_buf + offset + DATA_START));
    break;
    #endif
    ......
}

Get the local time to sync with the local RTC. This function needs to be implemented by you.

/**
 * @brief The MCU syncs time with the local RTC.
 * @param[in] {time} The local time.
 * @return Null
 * @note  To be implemented by you.
 */
void mcu_write_rtctime(unsigned char time[])
{
    #error "Complete the code for time sync with RTC and delete this row"
   /*
    Time[0] indicates whether the time is obtained successfully. `0`: failure. `1`: success.
    Time[1] indicates the year. `0x00` indicates the year 2000.
    Time[2] indicates the month, ranging from 1 to 12.
    Time[3] indicates the day, ranging from 1 to 31.
    Time[4] indicates the hour, ranging from 0 to 23.
    Time[5] indicates the minute, ranging from 0 to 59.
    Time[6] indicates the second, ranging from 0 to 59.
    Time[7] indicates the day of the week, ranging from 1 to 7. `1` indicates Monday.
*/
    if(time[0] == 1) {
        // The correct local time is received.

    }else {
        // Correct local time is not received. It might be because the module is not connected to the network.
   }
}

Module Debugging Assistant

Enable time service notifications

Enable MODULE_EXPANDING_SERVICE_ENABLE to turn on extended features.

#define         MODULE_EXPANDING_SERVICE_ENABLE        // Enable the extended feature.

The MCU calls open_module_time_serve() in mcu_api.c to enable time service notifications and select the time service.

/**
 * @brief Enable the time service notification.
 * @param[in] {time_type} The type of time service.
 * @ref       0x00: GMT
 * @ref       0x01: local time
 * @return Null
 * @note   To be implemented by you.
 */
void open_module_time_serve(unsigned char time_type)
{
    unsigned short send_len = 0;
    send_len = set_wifi_uart_byte(send_len, 0x01);
    send_len = set_wifi_uart_byte(send_len, time_type);
    wifi_uart_write_frame(MODULE_EXTEND_FUN_CMD, MCU_TX_VER, send_len);
}

The MCU gets the enablement result from data_handle() and calls open_module_time_serve_result() to proceed with the next operation.

void data_handle(unsigned short offset)
{
    ......
    #ifdef MODULE_EXPANDING_SERVICE_ENABLE
    case MODULE_EXTEND_FUN_CMD:                             // The extended service.
        total_len = (wifi_data_process_buf[offset + LENGTH_HIGH] << 8) | wifi_data_process_buf[offset + LENGTH_LOW];
        open_module_time_serve_result((unsigned char *)(wifi_data_process_buf + offset + DATA_START), total_len);
        break;
    #endif
    ......
}

Get the result of enabling time service notifications. This function needs to be implemented by you.

/**
 * @brief The result of enabling the time service notification.
 * @param[in] {value} The buffer.
 * @param[in] {length} The data length.
 * @return Null
 * @note  To be implemented by you.
 */
void open_module_time_serve_result(const unsigned char value[], unsigned short length)
{
    ......
    case 0x01: { //The subcommand to enable the time service notification.
        if(0x02 != length) {
            // Data length error.
            return;
            }

            if(value[1] == 0) {
                // The service is enabled.
            } else {
                // Failed to enable the service.
            }
    }
    break;
    ......
}

Module Debugging Assistant

Send time service notifications

Enable MODULE_EXPANDING_SERVICE_ENABLE to turn on extended features.

#define         MODULE_EXPANDING_SERVICE_ENABLE        // Enable the extended feature.

The MCU gets the enablement result from data_handle() and calls open_module_time_serve_result() to proceed with the next operation.

void data_handle(unsigned short offset)
{
    ......
    #ifdef MODULE_EXPANDING_SERVICE_ENABLE
        case MODULE_EXTEND_FUN_CMD:                             // The extended feature.
            total_len = (wifi_data_process_buf[offset + LENGTH_HIGH] << 8) | wifi_data_process_buf[offset + LENGTH_LOW];
            open_module_time_serve_result((unsigned char *)(wifi_data_process_buf + offset + DATA_START), total_len);
            break;
    #endif
    ......
}

Get the time service notification. This function needs to be implemented by you.

/**
 * @brief The time notification from the module.
 * @param[in] {value} The buffer.
 * @param[in] {length} The data length.
 * @return Null
 * @note  To be implemented by you.
 */
void open_module_time_serve_result(const unsigned char value[], unsigned short length)
{
    ......
    case 0x02: { //The subcommand to notify the MCU of the time service.
        if(0x09 != length) {
            //Data length error.
            return;
        }
        unsigned char time_type = value[1]; //0x00: the GMT. 0x01: the local time.
        unsigned char time_data[7];
        my_memcpy(time_data, value + 2, length - 2);
        /*
            Data[0] indicates the year. `0x00` indicates the year 2000.
            Data[1] indicates the month, ranging from 1 to 12.
            Data[2] indicates the day, ranging from 1 to 31.
            Data[3] indicates the hour, ranging from 0 to 23.
            Data[4] indicates the minute, ranging from 0 to 59.
            Data[5] indicates the second, ranging from 0 to 59.
            Data[6] indicates the day of the week, ranging from 1 to 7. `1` indicates Monday.
        */
    //Implement the time data handler. `time_type` indicates the type of time service.
    unsigned short send_len = 0;
    send_len = set_wifi_uart_byte(send_len,sub_cmd);
        wifi_uart_write_frame(MODULE_EXTEND_FUN_CMD, MCU_TX_VER, send_len);
    }
    break;
    ......
}

Module Debugging Assistant

Prev DocProduction Testing

Next DocWeather Service