Local Schedule

This topic describes the local schedule feature.

Overview

Concepts

Compared to cloud-based schedules, the local schedule feature enables Bluetooth devices to run a schedule locally without requiring internet access.

Features

• A data point (DP) acts as a trigger.

• Multiple types of schedules are supported, including regular, random, recurring, and countdown.

• The accuracy of the schedule depends on the precision of the local clock.

How it works

1. After the app connects to the Bluetooth device, it queries device information. When responding to this query, the Bluetooth device adds a field to enable the local schedule feature.

2. When users open the app’s schedule interface, check if a sync is required depending on whether the local schedule feature is enabled.

3. The app requests the number of schedules as well as the maximum number of schedules allowed per transfer, which is determined by the device.

4. The app reads the schedules accordingly and compares the schedule ID and CRC32 checksum from the device with those in the cloud. If they do not match, the app syncs the differences with the device.

Data structure

tuya_ble_app_passthrough_data_t

typedef struct {
    uint16_t type;
    uint32_t data_len;
    uint8_t* p_data;
} tuya_ble_app_passthrough_data_t;

• type: The type of data pass-through. For local schedules, its value is fixed as 0x0000.

• data_len: The data length of the local schedule.

• p_data: The content of the local schedule.

tal_local_timer_info_t

typedef struct {
    uint8_t  type;
    uint16_t len;
    uint8_t  year; // the lower two bits
    uint8_t  month;
    uint8_t  day;
    uint8_t  hour;
    uint8_t  minute;
    uint8_t  loop;
    uint32_t timer_id;
    uint8_t* dp_data;
    uint32_t crc32;
} tal_local_timer_info_t;

• type: The type of the local schedule.

  • 0x01: Regular schedule.
  • 0x02: Random schedule (not yet supported by the panel).
  • 0x03: Recurring schedule (not yet supported by the panel).
  • 0x04: Countdown (not yet supported by the panel).

• len: The length of the data.

• year: Year (the lower two bits).

• month: Month.

• day: Day.

• hour: Hour.

• minute: Minute.

• loop: Recurring.

  • 0x00: Saturday.
  • 0x01: Friday.
  • 0x02: Thursday.
  • 0x03: Wednesday.
  • 0x04: Tuesday.
  • 0x05: Monday.
  • 0x06: Sunday.
  • 0x07: Reserved.

• timer_id: The schedule ID.

• dp_data: The DP, multiple DPs allowed.

  • dp_id (1 byte): The dp_id of the DP defined on the Developer Platform.

  • dp_type: 1 byte.

    • #define DT_RAW 0
    • #define DT_BOOL 1
    • #define DT_VALUE 2
    • #define DT_STRING 3
    • #define DT_ENUM 4
    • #define DT_BITMAP 5

  • dp_len (1 byte): The length of the data, up to 255 bytes.

  • dp_data: The data, dp_len long.

• crc32: The CRC32 checksum.

API description

Component initialization

API description

uint32_t tal_local_timer_init(void);

Local schedule command handler

API description

uint32_t tal_local_timer_handler(tuya_ble_app_passthrough_data_t* data);

Description

Parameter	Description
data	See the description of tuya_ble_app_passthrough_data_t in the preceding section.

Local schedule handler

Implement your logic for processing local schedule events.

API description

void tal_local_timer_parser_event(void);

Initialize storage

For simplicity, the demo uses tbs_storage_ib.c to store schedule data. It is recommended that you use your own storage logic.

API description

uint32_t tal_local_timer_storage_init(void);

Write data

Store the schedule data.

API description

uint32_t tal_local_timer_info_write(tal_local_timer_info_t* data);

Description

Parameter	Description
data	See the description of tal_local_timer_info_t in the preceding section.

Delete data

Delete the schedule data.

API description

uint32_t tal_local_timer_info_delete(uint32_t timer_id);

Description

Parameter	Description
timer_id	The ID of the local schedule.

Read DP event

Read the DP event associated with the schedule.

API description

uint32_t tal_local_timer_dp_item_read(uint8_t id, uint8_t* buf, uint32_t size);

Description

Parameter	Description
id	The storage ID.
buf	The DP data.
size	The length of the DP data.

Empty data

Clear all schedule data.

API description

uint32_t tal_local_timer_info_delete_all(void);

Get the number of local schedules

API description

uint32_t tal_local_timer_get_num(void);

How to use

Communication process

Code development

For more information, see tuyaos_demo_local_timer.

Functional testing

Prerequisites

• You have installed the Tuya Smart app on your phone.
• The device is in pairing mode.
• You use the embedded program from tuyaos_demo_local_timer.
• Your phone number has been added to the panel’s allowlist. Contact your product manager if you have not already done so.

Procedure

Communicate with the mobile app using a host that simulates a real device.

1. Add the target device to the Tuya Smart app.

2. Tap the + button.

   

3. Create a schedule.

   

   The host software looks like this:

   

4. The schedule runs at the specified time of 19:08.

   

   If you have any problems with host usage, see Logic Host User Guide.

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.