Three different starters let you schedule an automation in advance:

1. [`Time.ScheduledTimeEvent`](https://developers.home.google.com/reference/kotlin/com/google/home/google/Time.ScheduledTimeEvent.md.txt)
2. [`Time.RecurringClockTimeScheduledEvent`](https://developers.home.google.com/reference/kotlin/com/google/home/google/Time.RecurringClockTimeScheduledEvent.md.txt)
3. [`Time.RecurringSolarTimeScheduledEvent`](https://developers.home.google.com/reference/kotlin/com/google/home/google/Time.RecurringSolarTimeScheduledEvent.md.txt)

> [!NOTE]
> **Note:** For these starters to work, the structure needs to have been assigned a street address (either when creating the structure or using the [Google Home app (GHA)](https://play.google.com/store/apps/details?id=com.google.android.apps.chromecast.app)). [Change Google home
> address](https://support.google.com/googlenest/answer/7551002) explains how a user can enter or update the structure address in the Google Home app. If the address is missing, `createAutomation()` saves and returns an `Automation` where `isValid == false`, with an `UnsupportedEntityEvent` validation issue containing `MissingStructureAddressSetup`.

The first, [`Time.ScheduledTimeEvent`](https://developers.home.google.com/reference/kotlin/com/google/home/google/Time.ScheduledTimeEvent.md.txt),
lets you schedule an automation to start at either a single precise instant in
the future, or on a recurring basis, based on either clock time or a solar event
(that is, sunrise or sunset).

For example, this starter starts the automation at 10:00pm every day:

```kotlin
starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(Time.ScheduledTimeEvent.clockTime(LocalTime.of(22, 0, 0, 0)))
}
```

Alternatively, you can specify solar time event instead of clock time. The
parameter for this type of starter is a
[`SolarTimeStruct`](https://developers.home.google.com/reference/kotlin/com/google/home/google/TimeTrait.SolarTimeStruct.md.txt)
consisting of:

1. [`type`](https://developers.home.google.com/reference/kotlin/com/google/home/google/TimeTrait.SolarTimeStruct.md.txt#type()), which is either [`SolarTimeType.Sunrise`](https://developers.home.google.com/reference/kotlin/com/google/home/google/TimeTrait.SolarTimeType.md.txt#Sunrise) or [`SolarTimeType.Sunset`](https://developers.home.google.com/reference/kotlin/com/google/home/google/TimeTrait.SolarTimeType.md.txt#Sunset).
2. [`offset`](https://developers.home.google.com/reference/kotlin/com/google/home/google/TimeTrait.SolarTimeStruct.md.txt#offset()), which lets you shift the start time relative to the solar event by any amount of time. Positive values introduce a delay *after* the solar event, and negative values cause the starter to trigger *before* the solar event.

The following example is a starter that starts the automation 15 minutes before
sunrise every day:

```kotlin
starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(
    Time.ScheduledTimeEvent.solarTime(
      SolarTimeStruct(SolarTimeType.Sunrise, java.time.Duration.ofMinutes(-15))
    )
  )
}
```

The second two starters are *recurring scheduled event starters*, which let you
create automations that run periodically according to more specific criteria
that can include both time- and calendar-based conditions.

[`Time.RecurringClockTimeScheduledEvent`](https://developers.home.google.com/reference/kotlin/com/google/home/google/Time.RecurringClockTimeScheduledEvent.md.txt)
lets you schedule an automation based on one or more time or date conditions.
This starter uses a syntax that is similar to the one used by the Unix `cron`
utility to specify the schedule for a recurring automation.

[`Time.RecurringSolarTimeScheduledEvent`](https://developers.home.google.com/reference/kotlin/com/google/home/google/Time.RecurringSolarTimeScheduledEvent.md.txt)
lets you schedule an automation based on either the sunrise or sunset time,
optionally in combination with a calendar-based condition.

### `cron` expressions

You may already be familiar with `cron`, a command used on Unix and Linux
systems to schedule recurring jobs.

Recurring scheduled event starters use a scheduling expression syntax that is
similar to the one used by `cron`, and for this reason, the scheduling
expressions used with these starters are referred to as *`cron` expressions*.

There are several different 'flavors' of `cron`, and several variations of
syntax across these implementations. Recurring scheduled event starter `cron`
expressions use the same syntax as the [Quartz
scheduler](https://www.quartz-scheduler.org/).
Quartz `cron` expression syntax is explained in [the documentation for Quartz's
`CronExpression`](https://www.quartz-scheduler.org/api/2.3.0/org/quartz/CronExpression.html).

> [!IMPORTANT]
> **Important:** The **Second** field in recurring scheduled event `cron` expressions is strictly limited to **numeric values** between 0 and 59. You cannot use any other symbols in this field. Due to this restriction, a recurring event starter cannot trigger more often than once per minute.

#### Examples

Here are a few examples to illustrate.

| Use case | Second | Minute | Hour | Day-of-Month | Month | Day-of-Week | Year |
|---|---|---|---|---|---|---|---|
| Run every 24 hours, at midnight | `0` | `0` | `0` | `?` | `*` | `*` | `*` |
| Run at 6:00am every Tuesday | `0` | `30` | `19` | `?` | `*` | `3` | `*` |
| Run at quarter past the hour, every hour, during the month of February | `0` | `15` | `*` | `?` | `2` | `*` | `*` |
| Run once an hour | `0` | `0` | `*` | `?` | `*` | `*` | `*` |
| Run every 24 hours, at midnight, from January to March, on the weekday closest to the 1st of the month | `0` | `0` | `0` | `?` | `1-3` | `1W` | `*` |
| On the second Thursday of February, once an hour, at a quarter past | `0` | `15` | `*` | `?` | `2` | `5#2` | `*` |
| Run at quarter past the hour, every hour, on the last day of the month of February | `0` | `15` | `*` | `L` | `2` | `?` | `*` |
| Run at 6:00am every Tuesday and Thursday | `0` | `30` | `19` | `?` | `*` | `3,5` | `*` |

### `RecurringClockTimeScheduledEvent`

In a `RecurringClockTimeScheduledEvent` starter, the `cron` expression string is
assigned to the
[`Time.RecurringClockTimeScheduledEvent.cronExpression`](https://developers.home.google.com/reference/kotlin/com/google/home/google/Time.RecurringClockTimeScheduledEvent.md.txt#cronExpression())
field.

The following is an example of a `RecurringClockTimeScheduledEvent` starter that
starts the automation at 8:00pm, every Wednesday in April:

```kotlin
starter<_>(structure, event = Time.RecurringClockTimeScheduledEvent) {
  parameter(Time.RecurringClockTimeScheduledEvent.cronExpression("0 0 20 ? 4 4 *"))
}
```

## `RecurringSolarTimeScheduleEvent`

The `RecurringSolarTimeScheduleEvent` starter takes two parameters:

1. A [`SolarTimeStruct`](https://developers.home.google.com/reference/kotlin/com/google/home/google/TimeTrait.SolarTimeStruct.md.txt).
2. `cronExpression`: A subset of a `cron` expression consisting of only the Day-of-Month, Month, Day-of-Week, and Year fields. The solar time determines the exact time the automation will start, therefore the Second, Minute, and Hour fields are omitted.

The following example is a starter that causes an automation to start one hour
after sunrise, every Wednesday in April:

```kotlin
starter<_>(structure, event = Time.RecurringSolarTimeScheduledEvent) {
  parameter(
    Time.RecurringSolarTimeScheduledEvent.solarTime(
      TimeTrait.SolarTimeStruct(SolarTimeType.Sunrise, Duration.ofHours(1))
    )
  )
  parameter(Time.RecurringSolarTimeScheduledEvent.cronExpression("? 4 4 *"))
}
```