Unified protocol for Bluetooth Mesh local timers

Version history

Differentiating devices that support the unified protocol for Mesh local timers

To indicate that a device supports the unified protocol for Mesh local timers, you can set bit 5 of the FeatureFlag2 field in the device's UUID to 1. For more information about the Mesh device UUID format, see Mesh device UUID format definition.

Mesh device time synchronization protocol

AttrType and Opcode

Mesh devices must support the following two time synchronization instructions.

Tmall Genie speaker time synchronization instructions

Currently, Tmall Genie speakers use legacy instructions for time synchronization. These instructions use unicast, as shown in the following table:

Gateway and app time synchronization instructions

Gateways and apps use new instructions for time synchronization. These instructions use multicast with the address 0xCFFF for all categories, as shown in the following table:

Default time synchronization parameters

The device has the following default time synchronization parameters. To change these parameters, you can send an instruction to the device.

• Device time synchronization request interval: 180 minutes.
• Maximum retry interval after a failed request: 5 minutes. The device uses a discrete time interval for retries. The interval is 1 minute after the first failure, 3 minutes after the second, and 5 minutes after the third.
• Number of retries after a failed request: 3.

Notes

• If no Tmall Genie speaker or gateway is online, you can use an app to connect to the Mesh network to synchronize the time and set timers for a device. However, if the app disconnects, the device's periodic time synchronization requests will fail. This causes the local time on the device to drift and results in inaccurate timer operations.
• If no Tmall Genie speaker or gateway is online and the app does not reconnect to the Mesh network after the device restarts, the device's time will not be synchronized. This causes timer operations to fail.

Data examples

The following data examples demonstrate the time synchronization instructions for gateways and apps.

Set time (downlink)

s8_timezone: 1 byte. The time zone value. The parameter range is -12 to 14.

Query time (downlink)

Time information (uplink)

Set time synchronization parameters (downlink)

Query time synchronization parameters (downlink)

Time synchronization parameters (uplink)

Set time zone (downlink)

Query time zone (downlink)

Time zone information (uplink)

Request time update (uplink)

Update time (downlink)

s8_timezone: 1 byte. The time zone value. The parameter range is -12 to 14.

Mesh device timer protocol

AttrType and Opcode

Notes

• The device supports a maximum of 13 timers. For multi-element protocol devices, all elements share this limit. If the limit is exceeded, an error code is reported to indicate that the maximum number of timers has been reached.
• The device buffers a maximum of 4 timer execution records. When more than 4 records are generated, the oldest record is overwritten.
• Each timer setting instruction can contain only one timer index.
• Each timer setting instruction can contain a maximum of 4 opcodes.
• After the device receives a timer setting instruction, the device stores the instruction in flash memory. After a restart, the device must reload the instruction and actively report all current valid timer indexes.
• For a one-time timer, after the timer completes, the device must automatically delete the local timer and actively report all current valid timer indexes.

Data examples

Set one-time timer (downlink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• u32_time:

  The timer precision is one minute. Therefore, the seconds value of this data (a value less than 60) represents the number of opcodes that the timer will execute.

  For example, the data 0x5C2A3D01 corresponds to the decimal value 1546272001. Calculate 1546272001 / 60 and round down to get 25771200. Then, 25771200 × 60 = 1546272000, which corresponds to the time 2019/1/1 00:00:00.

  1546272001 mod 60 = 1, which indicates that there is only one operation group (switch). The maximum number of opcodes allowed is 4.

• u8_attr_para_len:

  1 byte. The length of attr_para. This value indicates the length of the following attr_para data. The maximum length is 8 bytes.

  Note For a one-time timer, after the timer executes, the device must automatically delete the local timer and actively report all current valid timer indexes.

Set one-time timer ACK (uplink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• Status:

  For the status code table, see Status code table.

  If the status is 0x00 or 0x01, the device's ACK reply includes all current timer indexes on the device.

  If the status is any other error code, the ACK reply from the device includes only the index of the timer that caused the error.

  Note Each timer setting instruction can contain only one timer setting.

Set recurring timer (downlink)

Recurring timer (only weekly recurrence is supported):

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• u16_time:

  Bits 0–11: Represent the minute of the day in a 24-hour format. For example, in the data 0x11E0, the lower 12 bits are 0x01E0, which corresponds to the decimal value 480. This represents the time 8:00 AM.

  Bits 12–15: Represent the number of opcodes that the timer will execute. For example, in the data 0x11E0, the higher 4 bits are 0x01, which indicates that there is only one operation group (switch). The maximum number of opcodes allowed is 4.

• s16_timezone:

  2 bytes. Represents the difference from UTC in minutes. The value ranges from -720 to 840.

  This accounts for countries or regions with time zones that are not full-hour offsets, such as Australia: UTC+08:45.

  For a list of time zones, see https://en.wikipedia.org/wiki/Time_zone.

• u8_schedule:

  Bits 0–6: Correspond to Monday–Sunday.

  If schedule is 0, it indicates a one-time timer. If the scheduled time is earlier than the current time, the timer executes the next day. Otherwise, it executes on the same day.

  After a one-time timer executes, the device must delete the local timer and actively report all current valid timer indexes.

• u8_attr_para_len:

  1 byte. The length of attr_para. This value indicates the length of the following attr_para data. The maximum length is 8 bytes.

  Note Each timer setting instruction can contain only one timer setting.

Set recurring timer ACK (uplink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• Status:

  For the status code table, see Status code table.

  If the status is 0x00 or 0x01, the device's ACK reply includes all current timer indexes on the device.

  If the status is any other error code, the ACK reply from the device includes only the index of the timer that caused the error.

Set loop timer (downlink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• u16_time:

  Bits 0–11: Represent the minute of the day in a 24-hour format. For example, in the data 0x11E0, the lower 12 bits are 0x01E0, which corresponds to the decimal value 480. This represents the time 8:00 AM.

  Bits 12–15: Represent the number of opcodes that the timer will execute. For example, in the data 0x11E0, the higher 4 bits are 0x01, which indicates that there is only one operation group (switch). The maximum number of opcodes allowed is 4.

• s16_timezone:

  2 bytes. Represents the difference from UTC in minutes. The value ranges from -720 to 840.

• u8_schedule:

  Bits 0–6: Correspond to Monday–Sunday.

  If schedule is 0, it indicates a one-time loop timer:

  • If the timer's start time is earlier than the current time but the end time is later, the loop timer will execute from the current time until the end time.
  • If both the start and end times are earlier than the current time, the loop timer will start executing at the scheduled start time the next day.

    After a one-time loop timer completes, the device must delete the local timer and actively report all current valid timer indexes.

• u16_duration:

  Bits 0–11: Represent the duration in minutes. For example, in the data 0x101e, the lower 12 bits are 0x01e, which corresponds to the decimal value 30. This indicates a duration of 30 minutes.

  Bits 12–15: Represent the number of opcodes to be executed during this duration. For example, in the data 0x101e, the higher 4 bits are 0x01, which indicates that there is only one operation group (switch). The maximum number of opcodes allowed is 2.

• u8_attr_para_len:

  1 byte. The length of attr_para. This value indicates the length of the following attr_para data. The maximum length is 8 bytes.

  Note Each timer setting instruction can contain only one timer setting.

Set loop timer ACK (uplink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• Status:

  For the status code table, see Status code table.

  If the status is 0x00 or 0x01, the device's ACK reply includes all current timer indexes on the device.

  If the status is any other error code, the ACK reply from the device includes only the index of the timer that caused the error.

  Note Each timer setting instruction can contain only one timer setting.

Enable/Disable timer (downlink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

  Note Each enable/disable timer message can contain one or more timer indexes. You can set the enabled/disabled status for each timer index individually.

Enable/Disable timer ACK (uplink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• Status:

  For the status code table, see Status code table.

  If the status is 0x00 or 0x01, the device's ACK reply includes all current timer indexes on the device.

  If the status is any other error code, the ACK reply from the device includes only the index of the timer that caused the error.

Delete timer (downlink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

  0xFF: Deletes all timers. Other values specify the index of the timer to be deleted.

  Note Each delete timer message can contain one or more timer indexes. An index of 0xFF deletes all timers.

Delete timer ACK (uplink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• Status:

  If the timer index exists on the device, the timer is deleted. If the timer index does not exist, no action is performed. In both cases, the status code 0x00 (Success) is returned. For more information, see Status code table.

  If the status is 0x00 or 0x01, the device's ACK reply includes all current timer indexes on the device. If the index field is NULL, this indicates that no local timers exist.

  If the status is any other error code, the ACK reply from the device includes only the index of the timer that caused the error.

Query timer (downlink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

  0xFF: Queries the indexes of all timers. The device replies with an ACK that contains all timer indexes.

  Other values: Query specific timer information for the corresponding index. The device replies with an ACK for that single timer. Only single-index timer queries are supported.

Query timer ACK (uplink)

Query all timer indexes ACK (uplink)

• u8_type:

  0xFF: Returns all timer indexes.

  0x01: One-time timer type.

  0x02: Recurring timer type.

  0x03: Loop timer type.

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• Status:

  For the status code table, see Status code table.

  If the status is 0x00 or 0x01, the device's ACK reply includes all current timer indexes on the device.

  If the status is any other error code, the ACK reply from the device includes only the index of the timer that caused the error.

Query single timer ACK (uplink)

• u8_type:

  0xFF: Returns all timer indexes.

  0x01: One-time timer type.

  0x02: Recurring timer type.

  0x03: Loop timer type.

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• Status:

  For the status code table, see Status code table.

Query timer record (downlink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

  0xFF: Queries the indexes of all timers. The device replies with an ACK that contains all timer indexes.

  Other values: Query specific timer information for the corresponding index. The device replies with an ACK for that single timer. Only single-index timer queries are supported.

  Note The device stores only the last 4 timer records. When more than 4 records are generated, the oldest record is overwritten based on the completion time.

Device timer record ACK (uplink)

Query all timer record indexes ACK (uplink)

• u8_type:

  0xFF: Returns all timer indexes.

  0x01: One-time timer type.

  0x02: Recurring timer type.

  0x03: Loop timer type.

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• Status:

  For the status code table, see Status code table.

  Note The device stores only the last 4 timer records. When more than 4 records are generated, the oldest record is overwritten based on the completion time.

Query single timer record ACK (uplink)

• u8_type:

  0xFF: Returns all timer indexes.

  0x01: One-time timer type.

  0x02: Recurring timer type.

  0x03: Loop timer type.

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

• u32_time:

  The UNIX time when the timer completed, in seconds.

• Status:

  For the status code table, see Status code table.

Report all timer indexes (uplink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

  Note

  • The device must include all its timer indexes. If the index field is NULL, this indicates that no local timers exist.
  • The device must actively report this full timer information after it is successfully provisioned, after a restart, or when a timer completes (if it involves deleting a local timer).

Report timer completion (uplink)

• u8_index:

  Bits 0–6: Represent the timer index. The value ranges from 0x01 to 0x7F. For example, in the data 0x81, the lower 7 bits are 0x01, which indicates that the timer index is 1.

  Bit 7: Represents the timer status. 0 indicates disabled, and 1 indicates enabled. For example, in the data 0x81, the highest bit is 1, which indicates that the timer is enabled.

  Note

  • When a timer is triggered on the device, the device must report this timer completion message. The message includes the index of the completed timer. If multiple timers are completed at the same time, they are reported together.
  • If it is a one-time timer, the device automatically deletes the local timer after it completes and must actively report the full current timer information.

Status code table

• Status codes 0x00 and 0x01 both indicate a successful operation. However, if the status code is 0x01, a notification is pushed to the user: "The device time has drifted because it has not been re-synchronized for more than 180 minutes. Timers may be inaccurate."
• Status code 0x80 indicates that the device's UNIX time is not set and has never been successfully synchronized. There are no local timers on the device.
• Status code 0x81 indicates that the device's UNIX time is not set, but local timers exist. The timers will not function correctly.