# Conditional sync

By default, the data management service syncs all captured data at a regular interval. Conditional sync lets you control _when_ sync happens, so data accumulates locally until your conditions are met: sync only during off-peak hours, when connected to WiFi, after a sensor reading crosses a threshold, or based on any other logic you define.

## How conditional sync works

Conditional sync uses a sensor component as a gate. You configure a sensor whose `Readings()` method returns `"should_sync": true` or `"should_sync": false`. At each sync interval, the data manager calls `Readings()` on this sensor before uploading. If the result is `true`, sync proceeds. If `false`, the cycle is skipped and data continues to accumulate locally.

The sensor is the only mechanism for conditional sync. There is no built-in rules engine or config-only option. Any logic you need goes in the sensor’s `Readings()` implementation. You can use an existing sensor module from the registry or write your own.

#### Important

If `selective_syncer_name` is configured but the sensor cannot be found, **scheduled sync is disabled** until the sensor becomes available. Make sure the sensor is correctly configured and added to the data manager’s `depends_on` field.

#### Conditional sync does not control capture

Conditional sync only controls _when data is uploaded_. Capture continues writing to local disk at the configured frequency regardless of whether sync is active. If the sync window is short or bandwidth is limited, the backlog from a full capture cycle may not clear in a single window. Monitor the capture directory size on constrained devices. See [Manage local storage](https://docs.viam.com/data/filter-at-the-edge/#manage-local-storage) for storage management guidance.

## Configure conditional sync

This example uses the [`sync-at-time/timesyncsensor`](https://app.viam.com/module/naomi/sync-at-time) sensor module to sync data only during a configured time window. You can substitute any sensor that returns `should_sync`.

### 1\. Add the sync sensor

1. On your machine’s **CONFIGURE** tab, click **+** next to your machine part and select **Component or service**.
2. Search for **sync-at-time/timesyncsensor** and select the result.
3. Enter a name (for example, `timesensor`) and click **Add to machine**.
4. Configure the time window in the sensor’s attributes:

```json
   {
        "start": "18:00:00",
        "end": "06:00:00",
        "zone": "America/New_York"
   }
   ```
   
   
   
   | Field | Type | Required | Description |
   | --- | --- | --- | --- |
   | `start` | string | Yes | Start of the sync window in `HH:MM:SS` format. |
   | `end` | string | Yes | End of the sync window in `HH:MM:SS` format. |
   | `zone` | string | Yes | An [IANA Time Zone Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) name. Examples: `"America/New_York"`, `"Europe/Berlin"`, `"Asia/Tokyo"`, `"UTC"`, `"CET"`. |

5. Click **Save**.

### 2\. Point the data manager at the sensor

The `selective_syncer_name` field is not available in the UI. Switch to **JSON** mode on the **CONFIGURE** tab.

Find the data management service in your config and add two fields:

- `selective_syncer_name`: the name of your sync sensor
- `depends_on`: include the sensor name so the data manager waits for it to be available

```json
   
   ```
   
   
   Click **Save**.

### 3\. Verify conditional sync is working

1. Confirm data capture is running: check the machine’s **LOGS** for capture activity.
2. If you are outside the sync window, data should accumulate locally but not appear in the **DATA** tab.
3. When the sync window opens, check the **DATA** tab. Captured data should begin appearing.
4. If data appears immediately regardless of the window, check that `selective_syncer_name` matches the sensor name exactly and that the sensor is in `depends_on`.

## Build a custom sync sensor

If no existing module fits your use case, you can write a sensor module that implements whatever sync logic you need: check network connectivity, compare sensor readings to a threshold, query an external API, or combine multiple conditions.

The sensor must implement the [sensor API](https://docs.viam.com/hardware/common-components/add-a-sensor/) and return a `"should_sync"` key with a boolean value from `Readings()`. The data manager checks this key at each sync interval. The sensor can return additional readings alongside `should_sync`.

The RDK provides a helper: `datamanager.CreateShouldSyncReading(bool)` returns a properly formatted readings map.

1. Follow the [module development guide](https://docs.viam.com/build-modules/write-a-driver-module/) to create a sensor module.
2. Implement `Readings()` to return `"should_sync": true` when sync should proceed and `"should_sync": false` otherwise.
3. Deploy the module and [configure the data manager](https://docs.viam.com/data/capture-sync/conditional-sync/#2-point-the-data-manager-at-the-sensor) with your sensor’s name.