### Light Entity Setup Example Device Mapping

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/entities.md

Illustrates the conditional logic for creating different light entity types based on the detected device class.

```python
if isinstance(rest_device, RestPlus):
    # Creates LightRestEntity
elif isinstance(rest_device, RestoreIot | RestoreV5):
    # Creates LightRestoreIotEntity and LightRiotClockEntity
```

--------------------------------

### Turn On Light with RGBW Color Examples

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Examples demonstrating how to turn on the light with specific RGBW colors and brightness levels.

```yaml
# Set pure white
service: light.turn_on
target:
  entity_id: light.restore_3_light
data:
  rgbw_color: [0, 0, 0, 255]

# Set blue with white tint
service: light.turn_on
target:
  entity_id: light.restore_3_light
data:
  rgbw_color: [0, 0, 255, 100]
  brightness: 200
```

--------------------------------

### Select Sound Mode Example

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Example of how to select a sound mode using the media_player.select_sound_mode service in Home Assistant.

```yaml
service: media_player.select_sound_mode
target:
  entity_id: media_player.rest_plus_media_player
data:
  sound_mode: "Ocean"
```

--------------------------------

### HatchEntity Constructor Example

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/entities.md

Example of how to instantiate the HatchEntity class with necessary parameters.

```python
entity = HatchEntity(
    coordinator=coordinator,
    thing_name="abc123xyz",
    entity_type="Light"
)
# Results in:
# unique_id: "abc123xyz_light"
# name: "Device Name Light"
```

--------------------------------

### Set Volume Level Example

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Example of how to set the volume level using the media_player.volume_set service in Home Assistant.

```yaml
service: media_player.volume_set
target:
  entity_id: media_player.rest_plus_media_player
data:
  volume_level: 0.5  # 50%
```

--------------------------------

### Set Volume Level Example

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Example of how to use the media_player.volume_set service to set the volume level to 75% for a RestIot media player.

```yaml
service: media_player.volume_set
target:
  entity_id: media_player.restore_3_media_player
data:
  volume_level: 0.75  # 75%
```

--------------------------------

### Options Flow UI Example

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/config-flow.md

Illustrates the user interface elements presented during the options flow for integration settings.

```yaml
# User interface shows:
# Turn on light when adjusting brightness: [toggle]
# Turn on media when selecting sound: [toggle]
# Show numbered preset scenes: [toggle]
```

--------------------------------

### Select Built-in Sound Mode Example

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Example of how to use the media_player.select_sound_mode service to play a built-in sound named 'Ocean' on a RestIot device.

```yaml
# Play built-in sound
service: media_player.select_sound_mode
target:
  entity_id: media_player.restore_3_media_player
data:
  sound_mode: "Ocean"
```

--------------------------------

### Select Favorite Sound Mode Example

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Example of how to use the media_player.select_sound_mode service to play a custom favorite sound named 'Custom Favorite' on a RestIot device.

```yaml
# Play favorite (if not in built-in list)
service: media_player.select_sound_mode
target:
  entity_id: media_player.restore_3_media_player
data:
  sound_mode: "Custom Favorite"
```

--------------------------------

### User Configuration Success Response

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/config-flow.md

Example of the data structure returned upon successful user configuration.

```python
{
    "type": "create_entry",
    "title": "user@example.com",
    "data": {
        "email": "user@example.com",
        "password": "password123"
    }
}
```

--------------------------------

### Turn on LightRestEntity with specific brightness and color

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Example of how to use the `light.turn_on` service in Home Assistant to control the brightness and RGB color of a Rest+ light.

```yaml
service: light.turn_on
target:
  entity_id: light.rest_plus_light
data:
  brightness: 200
  rgb_color: [255, 128, 0]  # Orange

```

--------------------------------

### Set Alarm Wake Time Service Example

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/other-entities.md

Example of how to use the time.set_value service to configure a new wake time for a device alarm.

```yaml
service: time.set_value
target:
  entity_id: time.device_alarm_wake_time
data:
  time: "06:45:00"

```

--------------------------------

### Media Player Entity Setup Function

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/entities.md

Asynchronously sets up media player entities. It maps device types to appropriate media entity classes and handles configuration options.

```python
async def async_setup_entry(
    hass: HomeAssistant,
    config_entry: ConfigEntry,
    async_add_entities: AddEntitiesCallback
) -> None:
```

--------------------------------

### Light Entity Setup Function

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/entities.md

Asynchronously sets up light entities based on device type. It maps specific device classes to corresponding light entity implementations.

```python
async def async_setup_entry(
    hass: HomeAssistant,
    config_entry: ConfigEntry,
    async_add_entities: AddEntitiesCallback
)
```

--------------------------------

### Setup Specific ha_hatch Configuration Entry

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/integration-setup.md

Sets up a specific configuration entry when a user adds the Hatch integration. It extracts credentials, creates a data coordinator, refreshes device data, sets up platform entities, and starts periodic alarm refresh tasks. This function is called automatically by Home Assistant.

```python
async def async_setup_entry(hass: HomeAssistant, config_entry: ConfigEntry)

```

--------------------------------

### Setup Scene Entry

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/entities.md

Sets up favorite/preset scenes for devices. Scene names can include preset numbers, and activation calls the device's set_favorite() method.

```python
async def async_setup_entry(
    hass: HomeAssistant,
    config_entry: ConfigEntry,
    async_add_entities: AddEntitiesCallback
) -> None
```

--------------------------------

### media_play Method

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Starts playback of the currently selected sound or the first available sound if none is selected.

```APIDOC
## media_play MediaRiotEntity

### Description
Starts playback of the currently selected sound or the first available sound if none is selected.

### Behavior
- Checks if already playing; returns if so.
- Gets the current sound_mode or uses the first available sound.
- Calls `select_sound_mode` with the determined sound_mode.
```

--------------------------------

### MediaRestEntity.media_play

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Starts media playback.

```APIDOC
## MediaRestEntity.media_play

### Description
Starts media playback.

### Method
`media_play()`
```

--------------------------------

### MediaRiotEntity.media_play

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Starts media playback for a Riot-enabled media entity.

```APIDOC
## MediaRiotEntity.media_play

### Description
Starts media playback for a Riot-enabled media entity.

### Method
`media_play() -> None`
```

--------------------------------

### Example Unique IDs for Alarm Entities

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/other-entities.md

Provides concrete examples of unique IDs for different types of alarm entities, such as switches, repeat patterns, and wake times.

```python
"abc123xyz_alarm_5_switch"      # Alarm 5 switch
"abc123xyz_alarm_5_repeat"      # Alarm 5 repeat sensor
"abc123xyz_alarm_5_wake_time"   # Alarm 5 wake time

```

--------------------------------

### Set Alarm Weekdays Automation Example

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/services.md

An example of how to use the set_alarm_weekdays service within a Home Assistant automation to schedule alarm days.

```yaml
# Using Home Assistant automation
automation:
  - trigger:
      platform: time
      at: "22:00:00"
    action:
      service: ha_hatch.set_alarm_weekdays
      target:
        entity_id: switch.restore_3_alarm_switch
      data:
        weekdays:
          - monday
          - tuesday
          - wednesday
          - thursday
          - friday
```

--------------------------------

### Setup Time Entry

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/entities.md

Sets up alarm wake time entities. Allows setting and adjusting alarm wake times and registers a callback for alarm updates.

```python
async def async_setup_entry(
    hass: HomeAssistant,
    config_entry: ConfigEntry,
    async_add_entities: AddEntitiesCallback,
)
```

--------------------------------

### Example Alarm Refresh Callback Usage

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/types.md

Demonstrates how to define and register an asynchronous callback function for alarm refresh events.

```python
async def on_alarm_refresh():
    # Handle alarm refresh
    pass

unsub = coordinator.async_add_alarm_refresh_callback(on_alarm_refresh)
```

--------------------------------

### MediaRiotEntity Media Play Method

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Starts playback of the current or the first available sound. It handles cases where playback is already in progress and selects the appropriate sound mode.

```python
def media_play(self) -> None:
    # Starts playback of current or first sound.
    # 1. Check if already playing; return if so
    # 2. Get current sound_mode or use first available sound
    # 3. Call `select_sound_mode(sound_mode)`
    if self.is_playing:
        return
    sound_mode = self.sound_mode or self.sound_mode_list[0]
    self.select_sound_mode(sound_mode)
```

--------------------------------

### Example Diagnostic Output Structure

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/favorites-diagnostics.md

Illustrates the typical JSON structure of a diagnostic file generated by the Hatch integration. It includes configuration entry details and device-specific information.

```json
{
  "entry": {
    "version": 2,
    "domain": "ha_hatch",
    "title": "user@example.com",
    "data": {
      "email": "****@****",
      "password": "****"
    },
    "options": {
      "turn_on_light": true,
      "turn_on_media": true,
      "numbered_preset_scenes": false
    }
  },
  "abc123xyz": {
    "device_name": "Bedroom Restore 3",
    "thing_name": "abc123xyz",
    "is_online": true,
    "battery_level": 85,
    "firmware_version": "2.45.1",
    "mac": "AA:BB:CC:DD:EE:FF",
    "device": {
      "id": "device_id_123",
      "name": "Bedroom Restore 3",
      "entities": {
        "light.bedroom_restore_3_light": {
          "entity_id": "light.bedroom_restore_3_light",
          "platform": "ha_hatch",
          "unique_id": "abc123xyz_light",
          "original_name": "Bedroom Restore 3 Light",
          "state": {
            "state": "on",
            "attributes": {
              "brightness": 200,
              "color_mode": "rgb",
              "rgb_color": [255, 127, 0]
            }
          }
        },
        "switch.bedroom_restore_3_alarm_switch": {
          "entity_id": "switch.bedroom_restore_3_alarm_switch",
          "platform": "ha_hatch",
          "unique_id": "abc123xyz_alarm_5_switch",
          "original_name": "Bedroom Restore 3 Default Alarm",
          "state": {
            "state": "on",
            "attributes": {
              "repeat": "Weekdays",
              "weekdays": ["monday", "tuesday", "wednesday", "thursday", "friday"]
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Hatch Option Flow Handler Class

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/config-flow.md

Defines the handler for editing integration options after initial setup.

```python
class HatchOptionFlowHandler(config_entries.OptionsFlow)
```

--------------------------------

### async_start_alarm_refresh

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/hatch-coordinator.md

Starts periodic refresh of alarm data every 10 minutes. This method is idempotent.

```APIDOC
## async_start_alarm_refresh

### Description
Starts periodic refresh of alarm data every 10 minutes.

### Parameters
None

### Returns
None

### Behavior
- Initializes recurring interval task if not already running
- Uses `async_track_time_interval` to trigger refresh every `ALARM_REFRESH_INTERVAL` (10 minutes)
- Calls `_async_handle_alarm_refresh_interval` callback

### Idempotent
Can be called multiple times safely; does nothing if already running

### Example
```python
coordinator.async_start_alarm_refresh()
```
```

--------------------------------

### ConfigFlowHandler Async Get Options Flow

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Returns the options flow handler. This is a static, non-asynchronous callback.

```python
@staticmethod
@callback
def async_get_options_flow(config_entry)

```

--------------------------------

### Get Options Flow Handler

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/config-flow.md

Static method to create an options flow handler for editing integration settings.

```python
@staticmethod
@callback
def async_get_options_flow(config_entry)
```

--------------------------------

### Configuration Entry Data Structure

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/config-flow.md

Defines the structure of data stored in the configuration entry after user setup, containing account credentials.

```python
{
    "email": str,        # User's Hatch account email
    "password": str      # User's Hatch account password
}
```

--------------------------------

### Config Entry Data Structure

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/types.md

Represents the data structure stored in `config_entry.data` for user setup via ConfigFlow, containing account credentials.

```json
{
    "email": str,        # Hatch account email address
    "password": str,     # Hatch account password
}
```

--------------------------------

### async_setup

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/integration-setup.md

Initializes the ha_hatch integration globally and registers custom services.

```APIDOC
## async_setup

### Description
Initializes the ha_hatch integration globally. Registers custom services for the integration.

### Method
async def

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Called automatically by Home Assistant
# No manual invocation needed
```

### Response
#### Success Response (bool)
- True if setup succeeded

#### Response Example
None provided
```

--------------------------------

### HatchDataUpdateCoordinator Start Alarm Refresh

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Starts the periodic alarm refresh task. This is a synchronous function.

```python
def async_start_alarm_refresh(self) -> None

```

--------------------------------

### async_setup_entry

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/integration-setup.md

Sets up a specific configuration entry when a user adds the Hatch integration.

```APIDOC
## async_setup_entry

### Description
Sets up a specific configuration entry when a user adds the Hatch integration. Extracts credentials, creates a coordinator, and sets up platform entities.

### Method
async def

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Called automatically by Home Assistant when user adds integration
# Do not call manually
```

### Response
#### Success Response (bool)
- True if setup succeeded

#### Response Example
None provided

### Error Handling
- ConfigEntryAuthFailed: if credentials are invalid
```

--------------------------------

### async_setup_entry

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Sets up a configuration entry for the integration. This is an asynchronous function that returns a boolean value.

```APIDOC
## async_setup_entry

### Description
Sets up a configuration entry.

### Method
async def

### Parameters
- **hass** (HomeAssistant) - Required - The Home Assistant instance.
- **config_entry** (ConfigEntry) - Required - The configuration entry to set up.

### Returns
- **bool** - True if the entry was set up successfully, False otherwise.
```

--------------------------------

### brightness (Restore)

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Gets the current brightness of the light in Home Assistant scale (0-255) for Restore devices. It converts the device's brightness (0-100) to the HA scale.

```APIDOC
## brightness (Restore)

### Description
Gets the current brightness of the light in Home Assistant scale (0-255) for Restore devices. It converts the device's brightness (0-100) to the HA scale.

### Returns
- **brightness** (int | None) - Brightness in Home Assistant scale (0-255)

### Conversion
Device brightness (0-100) × 255 / 100
```

--------------------------------

### async_setup

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Registers services for the integration. This is an asynchronous function that returns a boolean value.

```APIDOC
## async_setup

### Description
Registers services for the integration.

### Method
async def

### Parameters
- **hass** (HomeAssistant) - Required - The Home Assistant instance.
- **_config** (dict) - Required - The configuration for the integration.

### Returns
- **bool** - True if setup was successful, False otherwise.
```

--------------------------------

### Start Periodic Alarm Refresh

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/hatch-coordinator.md

Starts a recurring task to refresh alarm data every 10 minutes. This method is idempotent and can be called multiple times safely.

```python
def async_start_alarm_refresh(self) -> None
```

```python
coordinator.async_start_alarm_refresh()
```

--------------------------------

### LightRiotEntity Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Initializes the LightRiotEntity with a data coordinator and device name.

```python
def __init__(self, coordinator: HatchDataUpdateCoordinator, thing_name: str)

```

--------------------------------

### HatchOptionFlowHandler.async_step_init

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Handles option configuration. This is an asynchronous function that returns a dictionary.

```APIDOC
## HatchOptionFlowHandler.async_step_init

### Description
Handles option configuration.

### Method
async def

### Parameters
- **user_input** (dict[str, Any] | None) - Optional - User input data.

### Returns
- **dict** - A dictionary containing the result of the option configuration.
```

--------------------------------

### Check Alarm Wake Times

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/alarm-utilities.md

Validates if an alarm dictionary contains valid start and end time data. Returns False for invalid start times, and checks end time validity or sunrise duration if end time is missing.

```python
def alarm_has_valid_wake_times(alarm: dict[str, Any]) -> bool:
    # Checks if alarm has valid start and end time data.
    pass
```

```python
if alarm_has_valid_wake_times(alarm):
    wake_time = alarm_wake_time(alarm)
```

--------------------------------

### Initialize MediaRestEntity

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Constructor for the MediaRestEntity class. Requires a coordinator, thing name, and configuration for turning media on.

```python
def __init__(self, coordinator: HatchDataUpdateCoordinator, thing_name: str, config_turn_on_media: bool):
    pass
```

--------------------------------

### Options Flow Initialization Step

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/config-flow.md

The initial and only step for the options flow, presenting and saving updated integration settings.

```python
async def async_step_init(self, user_input: dict[str, Any] | None = None)
```

--------------------------------

### alarm_has_valid_wake_times

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/alarm-utilities.md

Checks if an alarm dictionary contains valid start and end time data. It returns false if the start time is invalid. If an end time is present, it checks its validity. If the end time is missing, it verifies the existence of a sunrise duration. Otherwise, it returns false.

```APIDOC
## alarm_has_valid_wake_times

### Description
Checks if alarm has valid start and end time data.

### Parameters
#### Path Parameters
- **alarm** (dict) - Required - Alarm dictionary

### Returns
`bool` — True if alarm has valid times

### Behavior:
- Returns False if startTime is invalid
- If endTime exists, returns True if it's valid
- If endTime missing, returns True if sunrise duration exists
- Otherwise returns False

### Example:
```python
if alarm_has_valid_wake_times(alarm):
    wake_time = alarm_wake_time(alarm)
```
```

--------------------------------

### HatchDataUpdateCoordinator.async_start_alarm_refresh

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Starts the periodic alarm refresh task. This is a synchronous function.

```APIDOC
## HatchDataUpdateCoordinator.async_start_alarm_refresh

### Description
Starts periodic alarm refresh task.

### Method
def

### Returns
- **None**
```

--------------------------------

### LightRiotEntity.__init__

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Initializes a LightRiotEntity. This constructor is used to set up a light entity that communicates via Riot.

```APIDOC
## LightRiotEntity.__init__

### Description
Initializes a LightRiotEntity. This constructor is used to set up a light entity that communicates via Riot.

### Parameters
- **coordinator** (HatchDataUpdateCoordinator) - Required - The data update coordinator.
- **thing_name** (str) - Required - The name of the thing.
```

--------------------------------

### alarm_unique_id_prefix

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Gets the unique ID prefix for an alarm. This is a synchronous, public function.

```python
def alarm_unique_id_prefix(thing_name: str) -> str
```

--------------------------------

### MediaRiotEntity.__init__

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Initializes a MediaRiotEntity. This constructor is used to set up a media player entity that communicates via Riot.

```APIDOC
## MediaRiotEntity.__init__

### Description
Initializes a MediaRiotEntity. This constructor is used to set up a media player entity that communicates via Riot.

### Parameters
- **coordinator** (HatchDataUpdateCoordinator) - Required - The data update coordinator.
- **thing_name** (str) - Required - The name of the thing.
```

--------------------------------

### alarm_unique_id_prefix

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Gets the unique ID prefix for alarms. This function is synchronous and publicly accessible.

```APIDOC
## alarm_unique_id_prefix

### Description
Gets the unique ID prefix for alarms.

### Method
`alarm_unique_id_prefix(thing_name: str) -> str`

### Parameters
- **thing_name** (str) - The name of the thing.
```

--------------------------------

### LightRiotEntity.turn_on

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Turns on the light. This method can accept additional keyword arguments for specific configurations.

```APIDOC
## LightRiotEntity.turn_on

### Description
Turns on the light. This method can accept additional keyword arguments for specific configurations.

### Method
`turn_on(**kwargs)`
```

--------------------------------

### Integration Initialization Functions

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/api-index.md

These are the core asynchronous functions for setting up, configuring, updating options, and unloading the Home Assistant integration.

```python
async def async_setup(hass: HomeAssistant, _config)
async def async_setup_entry(hass: HomeAssistant, config_entry: ConfigEntry)
async def async_update_options(hass: HomeAssistant, config_entry: ConfigEntry)
async def async_unload_entry(hass: HomeAssistant, config_entry: ConfigEntry)
```

--------------------------------

### rgb_color (Riot)

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Gets the current RGB color of the light. This is applicable to Riot platform devices.

```APIDOC
## rgb_color (Riot)

### Description
Gets the current RGB color of the light. This is applicable to Riot platform devices.

### Returns
- **rgb_color** (tuple[int, int, int] | None) - (red, green, blue) 0-255
```

--------------------------------

### Turn On MediaRestEntity

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Method to turn on the media player.

```python
def turn_on(self):
    pass
```

--------------------------------

### HatchEntity.rest_device

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Gets the RestDevice associated with this Hatch entity. This is a property that returns either a RestDevice object or None.

```APIDOC
## HatchEntity.rest_device

### Description
Gets the RestDevice associated with this Hatch entity. This is a property that returns either a RestDevice object or None.

### Property
`rest_device`

### Returns
`RestDevice | None`
```

--------------------------------

### turn_on (Restore)

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Turns on the light with optional RGBW color and brightness for Restore devices. It handles color restoration, white offset logic, and brightness conversion.

```APIDOC
## turn_on (Restore)

### Description
Turns on the light with optional RGBW color and brightness for Restore devices. It handles color restoration, white offset logic, and brightness conversion.

### Method
`turn_on(**kwargs)`

### Parameters
#### Optional Parameters
- **brightness** (int) - 0-255 brightness
- **rgbw_color** (tuple) - (r,g,b,w) 0-255

### Behavior
- If no kwargs: restore to last known on-state colors.
- If kwargs provided:
  1. Extract brightness (0-255) or use current → convert to 0-100.
  2. Extract RGBW or use current.
  3. Apply white offset: If white > 0, add white offset to R, G, B to prevent black display. Offset = min(white, max(0, 255 - max(r,g,b))).
  4. Call `rest_device.set_color(r, g, b, white, brightness)`.

### White Offset Logic
```python
if white > 0:
    max_value = max(red, green, blue)
    offset = max(0, min(min(white, 255 - max_value), 255))
    red += offset
    green += offset
    blue += offset
```
This prevents the Hatch Restore app from displaying the color as black when white is enabled.

### Example
```yaml
# Set pure white
service: light.turn_on
target:
  entity_id: light.restore_3_light
data:
  rgbw_color: [0, 0, 0, 255]

# Set blue with white tint
service: light.turn_on
target:
  entity_id: light.restore_3_light
data:
  rgbw_color: [0, 0, 255, 100]
  brightness: 200
```
```

--------------------------------

### MediaRestEntity.turn_on

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Turns on the media player.

```APIDOC
## MediaRestEntity.turn_on

### Description
Turns on the media player.

### Method
`turn_on()`
```

--------------------------------

### User Configuration Step

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/config-flow.md

Initial step for user configuration, prompting for Hatch account credentials. Handles validation and entry creation.

```python
async def async_step_user(self, user_input: dict[str, Any] | None = None)
```

--------------------------------

### Get Rest Device Property

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Retrieves the associated RestDevice object for a Hatch entity. This property is asynchronous and public.

```python
def rest_device(self) -> RestDevice | None:
    pass
```

--------------------------------

### HatchPowerSwitch.__init__

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Initializes the HatchPowerSwitch. This is a constructor method and is publicly accessible.

```APIDOC
## HatchPowerSwitch.__init__

### Description
Initializes the HatchPowerSwitch.

### Method
`__init__(self, coordinator: HatchDataUpdateCoordinator, thing_name: str)`

### Parameters
- **coordinator** (HatchDataUpdateCoordinator) - The data update coordinator.
- **thing_name** (str) - The name of the thing.
```

--------------------------------

### HatchOptionFlowHandler Async Step Init

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Handles option configuration. This is an asynchronous function.

```python
async def async_step_init(self, user_input: dict[str, Any] | None = None)

```

--------------------------------

### Initialize LightRestEntity

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Constructor for the LightRestEntity class. It requires a coordinator, thing name, and a configuration for turning the light on.

```python
def __init__(self, coordinator: HatchDataUpdateCoordinator, thing_name: str, config_turn_on_light: bool):
    pass
```

--------------------------------

### Get Alarm Unique ID Prefix

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/alarm-utilities.md

Retrieves the standard prefix used for generating unique alarm entity IDs for a specific device.

```python
def alarm_unique_id_prefix(thing_name: str) -> str:
    # Gets the prefix for alarm unique IDs for a device.
    pass
```

--------------------------------

### turn_on (Riot)

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Turns on the light with optional color and brightness for Riot devices. It supports setting specific RGB colors or restoring the last known state.

```APIDOC
## turn_on (Riot)

### Description
Turns on the light with optional color and brightness for Riot devices. It supports setting specific RGB colors or restoring the last known state.

### Method
`turn_on(**kwargs)`

### Parameters
#### Optional Parameters
- **brightness** (int) - 0-255 brightness
- **rgb_color** (tuple[int,int,int]) - RGB color (red, green, blue)

### Behavior
- If kwargs provided: set to specified color/brightness. Brightness converted 0-255 → 0-100. White value set to 0 unless RGB is [255,255,255]. Calls `rest_device.set_color(r, g, b, white, brightness)`.
- If no kwargs: restore to last known on-state colors. Calls with stored r, g, b, white=0, brightness.

### Example
```yaml
# Turn on with specific color
service: light.turn_on
target:
  entity_id: light.riot_device_light
data:
  rgb_color: [0, 255, 0]  # Green

# Turn on with last known state
service: light.turn_on
target:
  entity_id: light.riot_device_light
```
```

--------------------------------

### Turn On LightRestEntity

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Method to turn on the light. Accepts arbitrary keyword arguments.

```python
def turn_on(self, **kwargs):
    pass
```

--------------------------------

### Get RGB Color

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Retrieves the current RGB color of the light. Returns a tuple of (red, green, blue) values ranging from 0 to 255.

```python
def rgb_color(self) -> tuple[int, int, int] | None:
    pass
```

--------------------------------

### LightRestEntity brightness Property

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Gets the light's brightness, converting the device's 0-100 scale to Home Assistant's 0-255 scale.

```python
@property
def brightness(self) -> int | None:

```

--------------------------------

### LightRestEntity Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Initializes the LightRestEntity with a data coordinator, device name, and configuration for auto-enabling the light.

```python
def __init__(self, coordinator: HatchDataUpdateCoordinator, thing_name: str, config_turn_on_light: bool)

```

--------------------------------

### Set Alarm Weekdays Service Call

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/api-index.md

Example of how to call the `ha_hatch.set_alarm_weekdays` service to configure repeating days for an alarm. Ensure the target entity supports this capability.

```yaml
service: ha_hatch.set_alarm_weekdays
target:
  entity_id: switch.device_alarm_switch
data:
  weekdays:
    - monday
    - wednesday
    - friday
```

--------------------------------

### MediaRiotEntity Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Initializes the MediaRiotEntity with a data coordinator and device name. Sets up attributes for media content type, device class, sound modes, state attributes, and supported features.

```python
def __init__(self, coordinator: HatchDataUpdateCoordinator, thing_name: str)
```

--------------------------------

### LightRiotEntity Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Initializes the LightRiotEntity for controlling light on RestIot platform devices. It takes a data coordinator and the device's thing name.

```APIDOC
## LightRiotEntity Constructor

### Description
Initializes the LightRiotEntity for controlling light on RestIot platform devices. It takes a data coordinator and the device's thing name.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```python
def __init__(self, coordinator: HatchDataUpdateCoordinator, thing_name: str)
```

### Parameters
- **coordinator** (HatchDataUpdateCoordinator) - Required - Data coordinator
- **thing_name** (str) - Required - Device thing_name
```

--------------------------------

### LightRestoreIotEntity.__init__

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Initializes a LightRestoreIotEntity. This constructor is used to set up a light entity that restores its state via IoT.

```APIDOC
## LightRestoreIotEntity.__init__

### Description
Initializes a LightRestoreIotEntity. This constructor is used to set up a light entity that restores its state via IoT.

### Parameters
- **coordinator** (HatchDataUpdateCoordinator) - Required - The data update coordinator.
- **thing_name** (str) - Required - The name of the thing.
```

--------------------------------

### MediaRestEntity turn_on Method

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Powers on the RestPlus device. This is a no-operation for RestMini devices as they are always powered.

```python
def turn_on(self):
    # Powers on RestPlus device
```

--------------------------------

### rgbw_color (Restore)

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Gets the current RGBW color of the light for Restore devices. Returns a tuple of (red, green, blue, white) values, each ranging from 0 to 255.

```APIDOC
## rgbw_color (Restore)

### Description
Gets the current RGBW color of the light for Restore devices. Returns a tuple of (red, green, blue, white) values, each ranging from 0 to 255.

### Returns
- **rgbw_color** (tuple[int, int, int, int] | None) - (red, green, blue, white) 0-255
```

--------------------------------

### ConfigFlowHandler.async_step_user

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Initial configuration step for user credentials. This is an asynchronous function that returns a dictionary.

```APIDOC
## ConfigFlowHandler.async_step_user

### Description
Initial configuration step for user credentials.

### Method
async def

### Parameters
- **user_input** (dict[str, Any] | None) - Optional - User input data.

### Returns
- **dict** - A dictionary containing the result of the configuration step.
```

--------------------------------

### Initialize HatchDataUpdateCoordinator

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/hatch-coordinator.md

Initializes the coordinator with Hatch account credentials and configuration entry. Requires Home Assistant instance, email, password, and config entry.

```python
def __init__(
    self,
    hass: HomeAssistant,
    email: str,
    password: str,
    config_entry: ConfigEntry,
) -> None
```

```python
from homeassistant.core import HomeAssistant
from homeassistant.config_entries import ConfigEntry
from custom_components.ha_hatch import HatchDataUpdateCoordinator

coordinator = HatchDataUpdateCoordinator(
    hass=hass,
    email="user@example.com",
    password="password123",
    config_entry=config_entry,
)
```

--------------------------------

### RiotScene Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/other-entities.md

Initializes a RiotScene object with necessary parameters including coordinator, device details, and favorite information.

```python
def __init__(
    self,
    coordinator: HatchDataUpdateCoordinator,
    thing_name: str,
    name: str,
    favorite_name: str,
    favorite_id: int,
    extra_state_attributes: dict[str, Any],
) -> None

```

--------------------------------

### LightRestEntity.__init__

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Initializes a LightRestEntity. This constructor is used to set up a light entity that communicates via REST.

```APIDOC
## LightRestEntity.__init__

### Description
Initializes a LightRestEntity. This constructor is used to set up a light entity that communicates via REST.

### Parameters
- **coordinator** (HatchDataUpdateCoordinator) - Required - The data update coordinator.
- **thing_name** (str) - Required - The name of the thing.
- **config_turn_on_light** (bool) - Required - Configuration to determine if the light should turn on.
```

--------------------------------

### RiotScene Activate Method

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/other-entities.md

Activates the scene by playing the associated favorite. Calls rest_device.set_favorite with a formatted name-ID string.

```python
def activate(self, **kwargs: Any) -> None

```

--------------------------------

### Media Play MediaRiotEntity

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Method to play media. Returns None.

```python
def media_play(self) -> None:
    pass
```

--------------------------------

### LightRestoreIotEntity Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Initializes the LightRestoreIotEntity for Restore platform devices. It requires a data coordinator and the device's thing name.

```APIDOC
## LightRestoreIotEntity Constructor

### Description
Initializes the LightRestoreIotEntity for Restore platform devices. It requires a data coordinator and the device's thing name.

### Method
`__init__(coordinator: HatchDataUpdateCoordinator, thing_name: str)`

### Parameters
#### Required Parameters
- **coordinator** (HatchDataUpdateCoordinator) - Data coordinator
- **thing_name** (str) - Device thing_name

### Attributes
- `_attr_color_mode = ColorMode.RGBW`
- `_attr_supported_color_modes = {ColorMode.RGBW}`
- `_last_light_on_colors` — Memory of last on-state (includes white)
```

--------------------------------

### HatchPowerSwitch.turn_on

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Turns on the power switch. This is a synchronous, public method.

```python
def turn_on(self, **kwargs)
```

--------------------------------

### MediaRestEntity Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Initializes a MediaRestEntity instance. Requires a data coordinator, device name, and a configuration for auto-enabling media playback.

```python
def __init__(self, coordinator: HatchDataUpdateCoordinator, thing_name: str, config_turn_on_media: bool)
```

--------------------------------

### ConfigFlowHandler Async Step User

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Initial configuration step for user credentials. This is an asynchronous function.

```python
async def async_step_user(self, user_input: dict[str, Any] | None = None)

```

--------------------------------

### LightRestoreIotEntity.turn_on

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Turns on the light. This method can accept additional keyword arguments for specific configurations.

```APIDOC
## LightRestoreIotEntity.turn_on

### Description
Turns on the light. This method can accept additional keyword arguments for specific configurations.

### Method
`turn_on(**kwargs)`
```

--------------------------------

### Turn On Media Option

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/configuration.md

A boolean option to automatically turn on the device when selecting a sound or favorite. Defaults to True.

```python
config_turn_on_media = config_entry.options.get(
    CONFIG_TURN_ON_MEDIA, CONFIG_TURN_ON_DEFAULT
)
# Passed to MediaRestEntity constructor
```

--------------------------------

### MediaRestEntity.__init__

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Initializes a MediaRestEntity. This constructor is used to set up a media player entity that communicates via REST.

```APIDOC
## MediaRestEntity.__init__

### Description
Initializes a MediaRestEntity. This constructor is used to set up a media player entity that communicates via REST.

### Parameters
- **coordinator** (HatchDataUpdateCoordinator) - Required - The data update coordinator.
- **thing_name** (str) - Required - The name of the thing.
- **config_turn_on_media** (bool) - Required - Configuration to determine if the media player should turn on.
```

--------------------------------

### LightRestoreIotEntity Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Initializes the LightRestoreIotEntity with a data coordinator and device name. It sets the color mode to RGBW and initializes memory for the last light on colors.

```python
def __init__(self, coordinator: HatchDataUpdateCoordinator, thing_name: str):
    pass
```

--------------------------------

### LightRestEntity.turn_on

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Turns on the light. This method can accept additional keyword arguments for specific configurations.

```APIDOC
## LightRestEntity.turn_on

### Description
Turns on the light. This method can accept additional keyword arguments for specific configurations.

### Method
`turn_on(**kwargs)`
```

--------------------------------

### MediaRiotEntity Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Initializes a MediaRiotEntity instance. It requires a data coordinator and the device's unique thing name.

```APIDOC
## __init__ MediaRiotEntity

### Description
Initializes a MediaRiotEntity instance. It requires a data coordinator and the device's unique thing name.

### Parameters
#### Path Parameters
- **coordinator** (HatchDataUpdateCoordinator) - Required - Data coordinator
- **thing_name** (str) - Required - Device thing_name
```

--------------------------------

### HatchEntity.__init__

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Base class initializer for all Hatch entities. This is a synchronous function.

```APIDOC
## HatchEntity.__init__

### Description
Base class for all Hatch entities.

### Method
def

### Parameters
- **coordinator** (HatchDataUpdateCoordinator) - Required - The data update coordinator.
- **thing_name** (str) - Required - The name of the thing.
- **entity_type** (str) - Required - The type of the entity.
```

--------------------------------

### HatchEntity Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/entities.md

Initializes a HatchEntity instance. Requires a data coordinator, a device name, and an entity type.

```python
def __init__(self, coordinator: HatchDataUpdateCoordinator, thing_name: str, entity_type: str)
```

--------------------------------

### HatchAlarmSwitch Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/other-entities.md

Initializes the HatchAlarmSwitch entity with necessary parameters like coordinator, device name, alarm ID, and unique ID.

```python
def __init__(
    self,
    coordinator: HatchDataUpdateCoordinator,
    thing_name: str,
    alarm_id: int | str,
    alarm_name: str,
    unique_id: str,
)

```

--------------------------------

### Turn On Light Option

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/configuration.md

A boolean option to automatically turn on the Rest+ device when adjusting light settings. Defaults to True.

```python
config_turn_on_light = config_entry.options.get(
    CONFIG_TURN_ON_LIGHT, CONFIG_TURN_ON_DEFAULT
)
# Passed to LightRestEntity constructor
```

--------------------------------

### File Organization Structure

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/README.md

This snippet shows the directory structure of the documentation files for the Home Assistant Hatch integration. It helps in navigating and understanding the location of various documentation topics.

```text
Documentation Files:
├── README.md (this file)
├── api-index.md (start here!)
├── methods-reference.md
├── integration-setup.md
├── config-flow.md
├── configuration.md
├── hatch-coordinator.md
├── services.md
├── types.md
├── entities.md
├── light-entities.md
├── media-entities.md
├── other-entities.md
├── alarm-utilities.md
└── favorites-diagnostics.md
```

--------------------------------

### Manifest Configuration for Hatch Integration

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/configuration.md

The manifest.json file defines the core properties of the Home Assistant integration, including its domain, name, version, and dependencies.

```json
{
  "domain": "ha_hatch",
  "name": "Hatch Rest Mini/Plus",
  "codeowners": ["@dahlb"],
  "config_flow": true,
  "documentation": "https://github.com/dahlb/ha_hatch",
  "iot_class": "cloud_push",
  "issue_tracker": "https://github.com/dahlb/ha_hatch/issues",
  "loggers": ["ha_hatch", "hatch_rest_api"],
  "requirements": ["hatch_rest_api==1.33.0"],
  "version": "1.30.0"
}
```

--------------------------------

### Platform Constants for Integration

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/types.md

Lists the entity platforms that are supported and enabled by this Home Assistant integration.

```python
PLATFORMS = [
    Platform.BINARY_SENSOR,
    Platform.LIGHT,
    Platform.MEDIA_PLAYER,
    Platform.SCENE,
    Platform.SENSOR,
    Platform.SWITCH,
    Platform.TIME,
]
```

--------------------------------

### HatchPowerSwitch.turn_on

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Turns on the power switch. This method is synchronous and publicly accessible.

```APIDOC
## HatchPowerSwitch.turn_on

### Description
Turns on the power switch.

### Method
`turn_on(self, **kwargs)`
```

--------------------------------

### LightRiotClockEntity.turn_on

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Turns on the light. This method can accept additional keyword arguments for specific configurations.

```APIDOC
## LightRiotClockEntity.turn_on

### Description
Turns on the light. This method can accept additional keyword arguments for specific configurations.

### Method
`turn_on(**kwargs)`
```

--------------------------------

### HatchPowerSwitch turn_on Method

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/other-entities.md

Powers on the device by calling the underlying rest_device.set_on(True) method.

```python
def turn_on(self, **kwargs)

```

--------------------------------

### HatchAlarmSwitch async_turn_on Method

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/other-entities.md

Asynchronously enables the alarm by calling rest_device.set_alarm_enabled and scheduling a state update.

```python
async def async_turn_on(self, **kwargs)

```

--------------------------------

### LightRiotClockEntity turn_on

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Turns on the clock display with an optional brightness level. The brightness is converted from the Home Assistant scale (0-255) to the device scale (0-100) before being applied.

```APIDOC
## LightRiotClockEntity turn_on

### Description
Turns on clock display with optional brightness.

### Method
POST

### Endpoint
/light/turn_on

### Parameters
#### Request Body
- **brightness** (int) - Optional - 0-255 brightness

### Request Example
```yaml
service: light.turn_on
target:
  entity_id: light.device_clock
data:
  brightness: 200
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### LightRiotClockEntity.__init__

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Initializes a LightRiotClockEntity. This constructor is used to set up a light entity with clock functionality via Riot.

```APIDOC
## LightRiotClockEntity.__init__

### Description
Initializes a LightRiotClockEntity. This constructor is used to set up a light entity with clock functionality via Riot.

### Parameters
- **coordinator** (HatchDataUpdateCoordinator) - Required - The data update coordinator.
- **thing_name** (str) - Required - The name of the thing.
```

--------------------------------

### LightRestEntity Methods

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/light-entities.md

Provides methods to control the light, allowing it to be turned on with specific color and brightness settings, or turned off.

```APIDOC
## LightRestEntity Methods

### Description
Provides methods to control the light, allowing it to be turned on with specific color and brightness settings, or turned off.

### Methods
#### turn_on
```python
def turn_on(self, **kwargs)
```
Turns on light with optional color and brightness.

**Parameters:**
- **brightness** (int) - 0-255 brightness (optional)
- **rgb_color** (tuple[int,int,int]) - RGB color (optional)
- **hs_color** (tuple[float,float]) - HS color (optional, converted)
- **xy_color** (tuple[float,float]) - XY color (optional, converted)

**Behavior:**
1. Extract brightness (0-255) or use current
2. Convert to device scale (0-100): `brightness * 100 / 255`
3. Extract RGB color or use current
4. Call `rest_device.set_color(r, g, b, brightness)`
5. If config_turn_on_light=True: also call `rest_device.set_on(True)`

**Example:**
```yaml
service: light.turn_on
target:
  entity_id: light.rest_plus_light
data:
  brightness: 200
  rgb_color: [255, 128, 0]  # Orange
```

#### turn_off
```python
def turn_off(self)
```
Turns off light by setting brightness to 0.

**Behavior:**
- Calls `rest_device.set_color(current_r, current_g, current_b, 0)`
- Preserves color, only sets brightness to 0
```

--------------------------------

### HA Hatch Configuration Entry Options

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/config-flow.md

These are the options stored in `config_entry.options` after a user configures the integration. They control features like automatically turning on lights and media.

```python
{
    "turn_on_light": bool,              # Default: True
    "turn_on_media": bool,              # Default: True
    "numbered_preset_scenes": bool      # Default: False
}
```

--------------------------------

### MediaRestEntity media_play Method

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/media-entities.md

Resumes playback of the current sound. If configured, it will also power on the device.

```python
def media_play(self):
    # Resumes playing current sound
```

--------------------------------

### HatchDataUpdateCoordinator.__init__

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Initializes the data coordinator. This is a synchronous function.

```APIDOC
## HatchDataUpdateCoordinator.__init__

### Description
Initializes the data coordinator.

### Method
def

### Parameters
- **hass** (HomeAssistant) - Required - The Home Assistant instance.
- **email** (str) - Required - The user's email.
- **password** (str) - Required - The user's password.
- **config_entry** (ConfigEntry) - Required - The configuration entry.
```

--------------------------------

### HatchAlarmSwitch.async_turn_on

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/methods-reference.md

Asynchronously turns on the alarm switch. This method is publicly accessible.

```APIDOC
## HatchAlarmSwitch.async_turn_on

### Description
Asynchronously turns on the alarm switch.

### Method
`async_turn_on(self, **kwargs)`
```

--------------------------------

### Options Flow Schema

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/types.md

Defines the schema for the options flow, including settings for turning on lights and media, and configuring preset scenes.

```python
{
    vol.Required("turn_on_light", default=True): bool,
    vol.Required("turn_on_media", default=True): bool,
    vol.Required("numbered_preset_scenes", default=False): bool,
}
```

--------------------------------

### Initialize ha_hatch Integration Globally

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/integration-setup.md

Initializes the ha_hatch integration globally and registers custom services. This function is called automatically by Home Assistant and requires no manual invocation.

```python
async def async_setup(hass: HomeAssistant, _config)

```

--------------------------------

### Options Flow Constructor

Source: https://github.com/dahlb/ha_hatch/blob/main/_autodocs/config-flow.md

Initializes the options flow handler with the configuration entry to be edited.

```python
def __init__(self, config_entry: config_entries.ConfigEntry) -> None
```