### Configuring multiple scheduler cards with tags
Source: https://github.com/nielsfaber/scheduler-card/blob/main/README.md
Example setup for separating normal and holiday schedules into different cards.
```yaml
type: custom:scheduler-card
title: Normal schedule
#...rest of card configuration
tags: none
```
```yaml
type: custom:scheduler-card
title: Holiday schedule
#...rest of card configuration
tags: holiday
```
--------------------------------
### Climate Domain Action Example
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-actions.md
Example configuration entry for the climate domain.
```typescript
climate: {
set_temperature: {
target: {},
fields: {
temperature: {
supported_features: 1
},
hvac_mode: {
optional: true
}
}
}
}
```
--------------------------------
### Example ConditionConfig Implementation
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-conditions.md
Demonstrates how to instantiate a ConditionConfig object with multiple conditions.
```typescript
const conditions: ConditionConfig = {
type: TConditionLogicType.And,
items: [
{
entity_id: 'sensor.temperature',
match_type: TConditionMatchType.Above,
value: 20,
attribute: 'state'
},
{
entity_id: 'binary_sensor.motion',
match_type: TConditionMatchType.Equal,
value: 'on',
attribute: 'state'
}
],
track_changes: false
};
```
--------------------------------
### Example: Compute Action Icon
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-display.md
Demonstrates how to retrieve an icon for a specific action.
```typescript
const icon = computeActionIcon({
service: 'light.turn_on',
service_data: {}
});
// Returns 'hass:lightbulb'
```
--------------------------------
### Condition Match Type Examples
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-conditions.md
Examples of creating conditions for binary states, numeric thresholds, and string inequality.
```typescript
// Match binary state
const condition: Condition = {
entity_id: 'binary_sensor.motion',
match_type: TConditionMatchType.Equal,
value: 'on',
attribute: 'state'
};
// Match numeric threshold
const condition: Condition = {
entity_id: 'sensor.humidity',
match_type: TConditionMatchType.Above,
value: 60,
attribute: 'state'
};
// Match string state (not equal)
const condition: Condition = {
entity_id: 'climate.thermostat',
match_type: TConditionMatchType.Unequal,
value: 'off',
attribute: 'state'
};
```
--------------------------------
### Clone and build the project
Source: https://github.com/nielsfaber/scheduler-card/blob/main/CONTRIBUTING.md
Commands to clone the repository, install dependencies, and build the project.
```bash
git clone https://github.com/nielsfaber/scheduler-card.git
```
```bash
cd scheduler-card
```
```bash
npm install --no-package-lock
```
```bash
npm start
```
```bash
npm run build
```
--------------------------------
### Set card configuration
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-card-config.md
Example of initializing the card configuration object.
```typescript
const config: CardConfig = {
include: ['light', 'climate'],
time_step: 15,
show_header_toggle: true
};
card.setConfig(config);
```
--------------------------------
### Fetch Tags Usage Example
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-store.md
Demonstrates how to retrieve and process the list of available tags.
```typescript
const tags = await fetchTags(hass);
const tagNames = tags.map(t => t.name);
console.log('Available tags:', tagNames);
```
--------------------------------
### Render card UI
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-card-config.md
Example HTML structure rendered by the component.
```html
Add
```
--------------------------------
### Configure SchedulerCard in YAML
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-card-config.md
Example configuration for the custom card in a Lovelace dashboard.
```yaml
type: custom:scheduler-card
title: "My Schedule"
show_header_toggle: true
show_add_button: true
discover_existing: true
time_step: 15
include:
- light
- climate
- fan
exclude:
- light.bedroom
display_options:
primary_info: "{entity}: {action}"
secondary_info: relative-time
icon: action
sort_by:
- relative-time
- state
customize:
light.kitchen:
name: "Kitchen Light"
icon: "hass:lightbulb"
```
--------------------------------
### Define Condition Configurations
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-conditions.md
Examples of configuring complex conditions using AND or OR logic.
```typescript
// Execute only if temperature is above 20 AND motion detected
const andConditions: ConditionConfig = {
type: TConditionLogicType.And,
items: [
{
entity_id: 'sensor.temperature',
match_type: TConditionMatchType.Above,
value: 20,
attribute: 'state'
},
{
entity_id: 'binary_sensor.motion',
match_type: TConditionMatchType.Equal,
value: 'on',
attribute: 'state'
}
],
track_changes: false
};
// Execute if EITHER temperature is above 25 OR motion detected
const orConditions: ConditionConfig = {
type: TConditionLogicType.Or,
items: [
{
entity_id: 'sensor.temperature',
match_type: TConditionMatchType.Above,
value: 25,
attribute: 'state'
},
{
entity_id: 'binary_sensor.motion',
match_type: TConditionMatchType.Equal,
value: 'on',
attribute: 'state'
}
],
track_changes: false
};
```
--------------------------------
### Example display configurations
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
Various configurations for customizing the schedule list appearance, including support for HTML formatting.
```yaml
# Default format (entity: action on first line, relative time on second)
display_options:
primary_info:
- "{entity}: {action}"
- additional-tasks
secondary_info: relative-time
icon: action
# Show more information
display_options:
primary_info: "{entity}: {action}"
secondary_info:
- "{time} on {days}"
- relative-time
icon: entity
# Minimal display
display_options:
primary_info: "{entity}"
secondary_info: relative-time
icon: action
# With HTML formatting
display_options:
primary_info: "{entity}: {action}"
secondary_info: relative-time
```
--------------------------------
### Customized display_options example
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-display.md
Demonstrates the use of HTML tags and multiple template variables within the display configuration.
```yaml
display_options:
primary_info: "{entity}: {action}"
secondary_info:
- "{time} on {days}"
- relative-time
icon: entity
```
--------------------------------
### Compute Entity Display Usage Example
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-display.md
Demonstrates how to use computeEntityDisplay with a custom configuration object.
```typescript
const name = computeEntityDisplay('light.kitchen_main', hass, {
customize: {
'light.kitchen_main': {
name: 'Main Light'
}
}
});
// 'Main Light'
```
--------------------------------
### Example: Format Action Display
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-display.md
Demonstrates how to use formatActionDisplay to convert an action object into a descriptive string.
```typescript
const action: Action = {
service: 'light.turn_on',
service_data: { brightness: 200 }
};
const display = formatActionDisplay(action, hass);
// 'Turn on at {brightness}'
```
--------------------------------
### Complete Scheduler Card Configuration
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
A full YAML configuration example demonstrating entity inclusion/exclusion, display settings, and specific entity customization.
```yaml
type: custom:scheduler-card
title: "My Schedules"
show_header_toggle: true
show_add_button: true
time_step: 15
default_editor: single
include:
- light
- climate
- fan
- switch
- input_boolean
exclude:
- light.bedroom_bed # Specific exclusion
- "*_test" # Wildcard exclusion
discover_existing: true
sort_by:
- relative-time
- state
display_options:
primary_info:
- "{entity}: {action}"
- additional-tasks
secondary_info: relative-time
icon: action
tags: everyday
exclude_tags: holiday
customize:
light.kitchen:
name: "Kitchen Light"
icon: "hass:ceiling-light"
actions:
- service: light.turn_on
service_data:
brightness: 200
color_temp: 300
name: "Turn on warm"
variables:
brightness:
name: Brightness
min: 0
max: 255
step: 10
scale_factor: 1
optional: false
climate.living_room:
name: "Living Room Thermostat"
states:
min: 10
max: 30
step: 0.5
unit: "°C"
```
--------------------------------
### Define Condition Interface and Example
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/types.md
Defines the structure for individual entity conditions and provides a usage example.
```typescript
export interface Condition {
entity_id: string;
match_type: TConditionMatchType;
value: string | number;
attribute: string;
}
```
```typescript
{
entity_id: 'sensor.temperature',
match_type: TConditionMatchType.Below,
value: 20,
attribute: 'state'
}
```
--------------------------------
### Initialize numericSelector
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-selectors.md
Example usage of numericSelector with a configuration object defining bounds and scaling.
```typescript
const varConfig: VariableConfig = {
name: 'Brightness',
min: 0,
max: 100,
step: 5,
unit: '%',
scale_factor: 2.55 // Converts 0-100 to 0-255 for HA
};
const selector = numericSelector(varConfig);
```
--------------------------------
### Validate State Configuration Formats
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/errors.md
Examples of valid and invalid state configurations for the scheduler card.
```yaml
# Valid - list of strings
states: ['on', 'off']
# Valid - numeric range
states:
min: 0
max: 100
step: 1
unit: "%"
# Invalid - wrong format
states: "on" # Should be array
```
--------------------------------
### Configure Timeslot Conditions
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-conditions.md
Example showing how to define AND/OR logic for conditions within specific schedule slots.
```typescript
schedule.entries[0].slots = [
{
start: '08:00:00',
stop: '12:00:00',
actions: [...],
conditions: {
type: TConditionLogicType.And,
items: [
{ entity_id: 'binary_sensor.weekday', match_type: 'is', value: 'on', attribute: 'state' }
],
track_changes: false
}
},
{
start: '12:00:00',
stop: '18:00:00',
actions: [...],
conditions: {
type: TConditionLogicType.Or,
items: [], // No conditions, always executes
track_changes: false
}
}
];
```
--------------------------------
### computeActionsForDomain Usage Example
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-actions.md
Demonstrates how to invoke the function with a specific configuration and iterate over the returned actions.
```typescript
const actions = computeActionsForDomain(hass, 'light', {
customize: {
'light.kitchen': {
exclude_actions: ['turn_off']
}
}
});
actions.forEach(a => {
console.log(`${a.name}: ${a.description}`);
});
```
--------------------------------
### Sort Schedules Usage Example
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-schedule-helpers.md
Demonstrates sorting schedules based on relative time and state configuration.
```typescript
// Sort by time until next trigger, then by state
const config: CardConfig = {
sort_by: ['relative-time', 'state']
};
const sorted = sortSchedules(schedules, config, hass);
```
--------------------------------
### Time Format Reference
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-time.md
Reference guide for time and date string formats used within the system.
```APIDOC
## Time Format Reference
### Fixed Time Format
`HH:MM:SS` (Hours 00-23, Minutes 00-59, Seconds 00-59)
### Sunrise/Sunset Format
`sunrise±HH:MM:SS` or `sunset±HH:MM:SS` (Base time with optional offset)
### Date Format
`YYYY-MM-DD` (ISO 8601 date format)
### Timestamp Format
`YYYY-MM-DDTHH:MM:SS` (ISO 8601 full format)
```
--------------------------------
### Define and Use Action Interface
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/types.md
Defines the structure for Home Assistant service actions and provides an example object.
```typescript
export interface Action {
service: string;
service_data: Record;
target?: {
entity_id?: string[] | string
}
}
```
```typescript
{
service: 'light.turn_on',
service_data: {
brightness: 200,
color_temp: 350
},
target: {
entity_id: 'light.kitchen'
}
}
```
--------------------------------
### Get Available Actions for Entity
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Retrieves and logs available actions for a specific domain, requiring the Home Assistant instance and entity configuration.
```typescript
import { computeActionsForDomain } from './data/actions/compute_actions_for_domain';
const actions = computeActionsForDomain(hass, 'light', {
customize: config.customize || {}
});
actions.forEach(action => {
console.log(`${action.name}: ${action.description}`);
console.log(`Icon: ${action.icon}`);
console.log(`Service: ${action.action.service}`);
});
```
--------------------------------
### Validate Schedule Usage Example
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-schedule-helpers.md
Demonstrates how to invoke validation and handle specific error types.
```typescript
const error = validateSchedule(schedule, hass, config.customize);
if (error === ValidationError.OverlappingTime) {
alert('Timeslots cannot overlap!');
} else if (error) {
alert(`Validation error: ${error}`);
}
```
--------------------------------
### Update Schedule Usage Example
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-store.md
Demonstrates how to update an existing schedule by setting the schedule_id and calling the update function.
```typescript
schedule.schedule_id = 'schedule_123';
schedule.name = 'Updated Name';
await updateSchedule(hass, schedule);
```
--------------------------------
### Delete Schedule Usage Example
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-store.md
Demonstrates how to delete a schedule using its entity ID.
```typescript
await deleteSchedule(hass, 'scheduler.my_schedule');
```
--------------------------------
### Identify MissingServiceParameter Error
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/errors.md
Example of an action configuration missing a required service parameter.
```typescript
// climate.set_temperature requires 'temperature' parameter
action: {
service: 'climate.set_temperature',
service_data: {} // Missing required 'temperature'
}
```
--------------------------------
### Configure Xiaomi Air Purifier Speed Variable
Source: https://github.com/nielsfaber/scheduler-card/blob/main/README.md
Example configuration for setting a fan speed variable using the xiaomi_miio integration.
```yaml
customize:
fan.xiaomi_purifier:
actions:
- service: xiaomi_miio.fan_set_favorite_level
name: "set speed"
variables:
level:
name: "Speed"
min: 1
max: 16
```
--------------------------------
### Identify MissingAction Error
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/errors.md
Example of a schedule configuration where timeslots lack defined actions.
```typescript
slots: [
{ start: '08:00:00', stop: '12:00:00', actions: [] }, // Empty!
{ start: '12:00:00', stop: '16:00:00', actions: [] } // Empty!
]
```
--------------------------------
### moveTimeslot
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-schedule-helpers.md
Changes the start and stop times of a timeslot.
```APIDOC
## moveTimeslot
### Description
Changes the start and stop times of a timeslot. The function ensures no overlaps with adjacent slots, validates that the start time is before the stop time, and maintains contiguous coverage.
### Signature
`export const moveTimeslot = (schedule: Schedule, position: number, start: string, stop?: string): Schedule`
### Parameters
- **schedule** (Schedule) - Required - Schedule to modify
- **position** (number) - Required - Slot index
- **start** (string) - Required - New start time (HH:MM:SS)
- **stop** (string) - Optional - New stop time
### Returns
- **Schedule** - New schedule with slot repositioned
```
--------------------------------
### computeStatesForEntity
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-conditions.md
Gets available states or values for an entity based on its type and configuration.
```APIDOC
## computeStatesForEntity
### Description
Gets available states/values for an entity based on its type and configuration, following a specific resolution order.
### Signature
`computeStatesForEntity(entity_id: string, hass: HomeAssistant, customize?: CustomConfig): StateConfig`
### Parameters
- **entity_id** (string) - Required - Entity ID
- **hass** (HomeAssistant) - Required - Home Assistant instance
- **customize** (CustomConfig) - Optional - Custom entity configuration
### Returns
- **StateConfig** - State configuration for entity (list or numeric range)
### Example
```typescript
// Binary sensor (on/off)
const states = computeStatesForEntity('binary_sensor.motion', hass);
// { type: 'list', states: ['on', 'off'] }
// Climate entity (numeric temperature)
const states = computeStatesForEntity('climate.thermostat', hass);
// { type: 'numeric', min: 5, max: 35, step: 0.5 }
```
```
--------------------------------
### Identify MissingTargetEntity Error
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/errors.md
Example of an action configuration missing the required target entity.
```typescript
// Service turn_on on a light requires a target
action: {
service: 'light.turn_on',
service_data: { brightness: 200 }
// Missing: target: { entity_id: 'light.kitchen' }
}
```
--------------------------------
### Project File Structure
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/README.md
Visual representation of the source directory layout and module responsibilities.
```text
src/
├── scheduler-card.ts # Main component → api-reference-card-config.md
├── scheduler-card-editor.ts # Config UI
├── types.ts # Type definitions → types.md
├── const.ts # Constants
├── data/
│ ├── store/ # Persistence → api-reference-store.md
│ ├── schedule/ # Schedule logic → api-reference-schedule-helpers.md
│ ├── actions/ # Action discovery → api-reference-actions.md
│ ├── time/ # Time handling → api-reference-time.md
│ ├── selectors/ # Selector framework → api-reference-selectors.md
│ ├── format/ # Display formatting → api-reference-display.md
│ └── (conditions & validation)
├── components/ # Lit components
├── dialogs/ # Dialog components
└── localize/ # Translations
```
--------------------------------
### Move a timeslot
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-schedule-helpers.md
Updates the start and stop times of a timeslot, validating that no overlaps occur.
```typescript
export const moveTimeslot = (schedule: Schedule, position: number, start: string, stop?: string): Schedule
```
```typescript
const updated = moveTimeslot(schedule, 1, '09:00:00', '17:30:00');
```
--------------------------------
### Entity Inclusion Check
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-actions.md
Utility function signature and usage example for checking entity inclusion.
```typescript
export const entityIncludedByConfig = (entity_id: string, config: entityConfig): boolean
```
```typescript
const isIncluded = entityIncludedByConfig('light.kitchen', {
include: ['light', 'climate'],
exclude: ['light.bedroom']
});
```
--------------------------------
### Configure Time Step
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
Set the time picker increment in minutes.
```yaml
time_step: 5 # 5-minute increments
time_step: 15 # 15-minute increments
time_step: 30 # 30-minute increments
```
--------------------------------
### Include Entities Configuration
Source: https://github.com/nielsfaber/scheduler-card/blob/main/README.md
Use the include key to specify entities, domains, or wildcard patterns for scheduling.
```yaml
include:
- climate.my_thermostat # include an individual entity
- light # include all light entities
- "*garden*" # include all entities containing the word 'garden'
...
```
--------------------------------
### Basic Scheduler Card Configuration
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
A minimal YAML configuration to initialize the scheduler-card with specific entity types.
```yaml
type: custom:scheduler-card
title: "Home Schedules"
include:
- light
- climate
- switch
```
--------------------------------
### Get default selector value
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-selectors.md
Retrieves the default value based on the provided selector configuration.
```typescript
export const defaultSelectorValue = (selector: Selector): any
```
```typescript
const selector: NumberSelector = {
number: { min: 0, max: 255, step: 1 }
};
const defaultValue = defaultSelectorValue(selector);
// 0
```
--------------------------------
### Identify OverlappingTime Error
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/errors.md
Example of a schedule configuration where time slots overlap, triggering a validation error.
```typescript
slots: [
{ start: '08:00:00', stop: '12:00:00', actions: [...] },
{ start: '11:00:00', stop: '16:00:00', actions: [...] } // Overlaps previous!
]
```
--------------------------------
### Complete End-to-End Schedule Lifecycle
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Demonstrates the full workflow of defining, validating, saving, and displaying a schedule object.
```typescript
// 1. Define schedule
const schedule: Schedule = {
entries: [{
weekdays: [TWeekday.Workday],
slots: [{
start: '08:00:00',
actions: [{
service: 'light.turn_on',
service_data: { brightness: 200 },
target: { entity_id: 'light.kitchen' }
}],
conditions: {
type: TConditionLogicType.And,
items: [{
entity_id: 'sensor.ambient_light',
match_type: TConditionMatchType.Below,
value: 100,
attribute: 'state'
}],
track_changes: false
}
}]
}],
next_entries: [],
timestamps: [],
repeat_type: TRepeatType.Repeat,
enabled: true,
name: 'Kitchen light at 8am if dark'
};
// 2. Validate
const error = validateSchedule(schedule, hass, config.customize);
if (error) {
console.error(`Validation failed: ${error}`);
return;
}
// 3. Save
try {
const success = await saveSchedule(hass, schedule);
if (success) {
console.log('Schedule created successfully');
}
} catch (err) {
console.error('Failed to save schedule:', err);
}
// 4. Fetch and display
const schedules = await fetchItems(hass);
const sorted = sortSchedules(schedules, config, hass);
sorted.forEach(schedule => {
const display = computeScheduleDisplay(
schedule,
['{entity}: {action}'],
hass,
config.customize
);
console.log(display.join(' '));
});
```
--------------------------------
### Configure Default Editor Mode
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
Set the initial editor mode when creating a new schedule.
```yaml
default_editor: scheme # Open time scheme editor by default
```
--------------------------------
### Customize light entity actions
Source: https://github.com/nielsfaber/scheduler-card/blob/main/README.md
Defines a custom action for a light entity to set brightness to 40% using the turn_on service.
```yaml
customize:
light.my_lamp:
name: "Dining light"
icon: "hass:ceiling-light"
actions:
- service: turn_on
service_data:
brightness: 100 # note that brightness is from 0-255 so 100 = 40%
name: "Turn on at 40%"
icon: "hass:lightbulb-on-outline"
```
--------------------------------
### Configure Header Toggle
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
Enable or disable the global toggle switch in the card header.
```yaml
show_header_toggle: true
```
--------------------------------
### Configure Add Button Visibility
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
Control the visibility of the add button.
```yaml
show_add_button: false # Hide add button
```
--------------------------------
### Configure display options in YAML
Source: https://github.com/nielsfaber/scheduler-card/blob/main/README.md
Defines the primary and secondary information lines and the icon for the scheduler card overview.
```yaml
display_options:
primary_info:
- "{entity}: {action}"
- additional-tasks
secondary_info: relative-time
icon: "hass:action"
```
--------------------------------
### Get Selector for Service Field
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Retrieves the configuration schema for a specific service field using the selectorConfig utility.
```typescript
import { selectorConfig } from './data/selectors/selector_config';
const brightnessSelector = selectorConfig(
'light.turn_on',
'light.kitchen',
'brightness',
hass
);
// Returns: { number: { min: 0, max: 255, step: 1 } }
```
--------------------------------
### Time and Date Format Patterns
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-time.md
Standard string patterns for time, sunrise/sunset offsets, dates, and timestamps.
```text
HH:MM:SS
```
```text
sunrise±HH:MM:SS
sunset±HH:MM:SS
```
```text
YYYY-MM-DD
```
```text
ISO 8601 full format: YYYY-MM-DDTHH:MM:SS
```
--------------------------------
### POST /api/scheduler/add
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/INDEX.md
Creates a new schedule entry.
```APIDOC
## POST /api/scheduler/add
### Description
Creates a new schedule.
### Method
POST
### Endpoint
/api/scheduler/add
```
--------------------------------
### Fetch all schedules with fetchItems
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-store.md
Retrieves all schedules from the backend. Converts legacy formats to the current structure.
```typescript
export const fetchItems = (hass: HomeAssistant): Promise
```
```typescript
const schedules = await fetchItems(hass);
console.log(`Found ${schedules.length} schedules`);
```
--------------------------------
### parseTimeBar(input: string): Array<{ start: string, stop?: string }>
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-time.md
Extracts a timeslot structure from a visual time bar string, typically used in the time scheme editor.
```APIDOC
## parseTimeBar
### Description
Extracts timeslot structure from visual time bar.
### Parameters
- **input** (string) - Required - Time bar string with positions
### Returns
- **Array<{ start, stop }>** - Array of timeslot boundaries
### Example
```typescript
const slots = parseTimeBar('00:00,08:00,17:00,24:00');
// [{ start: '00:00:00', stop: '08:00:00' }, ...]
```
```
--------------------------------
### Configure Scheduler Card in Lovelace
Source: https://github.com/nielsfaber/scheduler-card/blob/main/README.md
Add this configuration to your ui-lovelace.yaml file to display the scheduler card.
```yaml
type: custom:scheduler-card
domains:
...
entities:
...
```
--------------------------------
### Define component properties
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-card-config.md
Property definitions for the Home Assistant instance, configuration object, and schedule storage.
```typescript
@property({ attribute: false }) public hass!: HomeAssistant
```
```typescript
@property() _config: CardConfig = {}
```
```typescript
@state() public schedules?: ScheduleStorageEntry[]
```
--------------------------------
### fetchItems
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-store.md
Fetches all schedules from the scheduler backend via WebSocket.
```APIDOC
## fetchItems
### Description
Fetches all schedules from the scheduler backend via WebSocket.
### Signature
`fetchItems(hass: HomeAssistant): Promise`
### Parameters
- **hass** (HomeAssistant) - Required - Home Assistant instance
### Returns
- **Promise** - Array of all stored schedules
### Example
```typescript
const schedules = await fetchItems(hass);
console.log(`Found ${schedules.length} schedules`);
```
```
--------------------------------
### Configure display_options in CardConfig
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-display.md
Defines the structure of the schedule list using primary_info, secondary_info, and icon settings.
```yaml
display_options:
primary_info: # First line
- "{entity}: {action}"
- additional-tasks
secondary_info: # Second line
- relative-time
icon: action # 'action' or 'entity'
```
--------------------------------
### Subscribe to scheduler updates
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/INDEX.md
Use this message to initiate a subscription for real-time updates from the scheduler.
```json
{ type: 'scheduler_updated' }
```
--------------------------------
### Create Schedule with Conditions
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Defines a schedule that triggers based on sunrise offsets and binary sensor/sensor state conditions.
```typescript
import { Condition, TConditionMatchType } from './types';
const schedule: Schedule = {
entries: [{
weekdays: [TWeekday.Daily],
slots: [{
start: 'sunrise+00:30:00', // 30 minutes after sunrise
actions: [{
service: 'switch.turn_on',
service_data: {},
target: { entity_id: 'switch.water_pump' }
}],
conditions: {
type: TConditionLogicType.And,
items: [
{
entity_id: 'binary_sensor.rain',
match_type: TConditionMatchType.Equal,
value: 'off', // Only if not raining
attribute: 'state'
},
{
entity_id: 'sensor.soil_moisture',
match_type: TConditionMatchType.Below,
value: 50, // Only if soil dry
attribute: 'state'
}
],
track_changes: false
}
}]
}],
next_entries: [],
timestamps: [],
repeat_type: TRepeatType.Repeat,
enabled: true,
name: 'Water garden when needed'
};
await saveSchedule(hass, schedule);
```
--------------------------------
### computeActionsForDomain
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Retrieves a list of available actions for a specific Home Assistant domain.
```APIDOC
## computeActionsForDomain(hass, domain, options)
### Description
Computes the available actions for a given entity domain, such as 'light' or 'climate', based on the provided Home Assistant instance and configuration.
### Parameters
- **hass** (Object) - Required - The Home Assistant instance.
- **domain** (String) - Required - The entity domain (e.g., 'light').
- **options** (Object) - Required - Configuration object containing customize settings.
```
--------------------------------
### fetchItems(hass)
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Fetches all existing schedules.
```APIDOC
## fetchItems(hass)
### Description
Retrieves a list of all schedules from the system.
### Parameters
- **hass** (object) - The Home Assistant instance
### Response
- **Promise** - Returns a promise that resolves to an array of schedule objects.
```
--------------------------------
### Configure Card Title
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
Set the display title for the card.
```yaml
title: "My Schedules" # Custom title
title: true # Default title
title: false # No title
```
--------------------------------
### View scheduler-card version in browser console
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/errors.md
Displays the version badge in the browser console to help identify if an issue is resolved in newer releases.
```javascript
// Console shows version badge at top
```
--------------------------------
### formatActionDisplay
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-display.md
Formats an action object into a human-readable string based on Home Assistant service data and custom configurations.
```APIDOC
## formatActionDisplay
### Description
Formats an action into a human-readable string. It uses custom names if configured, translates service names, and appends service_data parameters.
### Signature
`formatActionDisplay(action: Action, hass: HomeAssistant, customize?: CustomConfig): string`
### Parameters
- **action** (Action) - Required - Action to format
- **hass** (HomeAssistant) - Required - Home Assistant instance
- **customize** (CustomConfig) - Optional - Custom action configuration
### Returns
- **string** - Formatted action description
### Example
```typescript
const action: Action = {
service: 'light.turn_on',
service_data: { brightness: 200 }
};
const display = formatActionDisplay(action, hass);
// 'Turn on at {brightness}'
```
```
--------------------------------
### Configure display options
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
Defines the structure for primary and secondary information display in the schedule list.
```yaml
display_options:
primary_info: # First line(s)
secondary_info: # Second line(s)
icon: # Which icon to show
```
--------------------------------
### Define script sequence for climate control
Source: https://github.com/nielsfaber/scheduler-card/blob/main/README.md
Implement the script logic in scripts.yaml to handle variables passed from the scheduler-card.
```yaml
set_climate_livingroom:
alias: Set climate livingroom
description: "Sets climate parameters for scheduler-card"
variables:
target_entity: climate.my_airconditioner
sequence:
- service: climate.set_temperature
data:
temperature: "{{ temperature }}" # match with variable in the card config
target:
entity_id: "{{ target_entity }}"
- delay: # wait a bit, otherwise the next service call may fail
seconds: 1
- service: climate.set_fan_mode
target:
entity_id: "{{ target_entity }}"
data:
fan_mode: "{{ fan_mode }}" # match with variable in the card config
- delay: # wait a bit, otherwise the next service call may fail
seconds: 1
- service: climate.set_hvac_mode
target:
entity_id: "{{ target_entity }}"
data:
hvac_mode: "{{ hvac_mode }}" # match with variable in the card config
mode: single
icon: mdi:air-conditioner
```
--------------------------------
### Format Schedule for Display
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Computes a human-readable representation of a schedule using custom display templates.
```typescript
import { computeScheduleDisplay } from './data/format/compute_schedule_display';
const display = computeScheduleDisplay(
schedule,
['{entity}: {action}', 'additional-tasks'],
hass,
config.customize
);
console.log(display);
// ['Kitchen Light: Turn on at 50%', '+2 more actions']
```
--------------------------------
### Retrieve selector configuration
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-selectors.md
Fetches the Home Assistant selector configuration for a specific service field. Returns null if no configuration is found.
```typescript
export const selectorConfig = (
service: string,
target: string | string[] | undefined,
field: string,
hass: HomeAssistant,
customize?: CustomConfig
): Selector | null
```
```typescript
const brightnessSelector = selectorConfig(
'light.turn_on',
'light.kitchen',
'brightness',
hass
);
// Returns: { number: { min: 0, max: 255, step: 1 } }
```
--------------------------------
### Configure Schedule Discovery
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
Control whether existing schedules not explicitly included are shown.
```yaml
discover_existing: true # Show all schedules (in expandable section if filtered)
discover_existing: false # Only show schedules matching include/exclude
```
--------------------------------
### Configure custom script actions in scheduler-card
Source: https://github.com/nielsfaber/scheduler-card/blob/main/README.md
Define custom variables and service calls in the scheduler-card YAML configuration to trigger scripts.
```yaml
customize:
script.set_climate_livingroom:
actions:
- service: script.set_climate_livingroom
name: Set climate
icon: mdi:air-conditioner
variables:
hvac_mode:
name: HVAC mode
options:
- value: heat
icon: mdi:fire
- value: cool
icon: mdi:snowflake
- value: 'off'
icon: mdi:power
temperature:
name: Temperature
min: 12
max: 30
fan_mode:
name: Fan mode
options:
- value: auto
icon: mdi:fan-auto
- value: high
icon: mdi:fan-speed-3
- value: quiet
icon: mdi:fan-speed-1
```
--------------------------------
### parseCustomVariable
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-selectors.md
Converts a custom variable configuration into a Home Assistant selector.
```APIDOC
## parseCustomVariable
### Description
Converts custom variable configuration to Home Assistant selector.
### Signature
`export const parseCustomVariable = (config: VariableConfig): Selector`
### Parameters
- **config** (VariableConfig) - Required - Custom variable config from customize
### Conversion Logic
- List options → SelectSelector
- Numeric min/max → NumberSelector
- Other → Generic selector
### Returns
`Selector` - Appropriate HA selector
```
--------------------------------
### actionConfig
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-actions.md
Retrieves the configuration for a specific action or service, optionally using custom configuration.
```APIDOC
## actionConfig
### Description
Gets configuration for a specific action (service).
### Signature
`export const actionConfig = (action: Action, customize?: CustomConfig): ActionConfig | null`
### Parameters
- **action** (Action) - Required - Action object with service
- **customize** (CustomConfig) - Optional - Custom configuration
### Returns
- **ActionConfig | null** - Service configuration or null if not found
```
--------------------------------
### formatActionDisplay
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Formats an individual action into a human-readable string.
```APIDOC
## formatActionDisplay(action, hass, customize)
### Description
Converts an action object into a user-friendly display string.
### Parameters
- **action** (object) - The action to format.
- **hass** (object) - The Home Assistant instance.
- **customize** (object) - Custom configuration settings.
### Returns
- **text** (string) - The formatted action string.
```
--------------------------------
### Validate Configuration
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Uses a try-catch block to validate user configuration objects, logging errors if validation fails.
```typescript
import { validateConfig } from './data/validate_config';
try {
const validConfig = validateConfig(userConfig);
// Config is valid
} catch (error) {
console.error(`Configuration error: ${error.message}`);
// Invalid configuration
}
```
--------------------------------
### selectorConfig(service, target, field, hass, customize)
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-selectors.md
Retrieves the Home Assistant selector configuration for a specific action service field.
```APIDOC
## selectorConfig
### Description
Gets the Home Assistant selector configuration for an action service field.
### Signature
`export const selectorConfig = (service: string, target: string | string[] | undefined, field: string, hass: HomeAssistant, customize?: CustomConfig): Selector | null`
### Parameters
- **service** (string) - Required - Service name (e.g., 'light.turn_on')
- **target** (string | string[]) - Optional - Entity ID being targeted
- **field** (string) - Required - Service field name (e.g., 'brightness')
- **hass** (HomeAssistant) - Required - Home Assistant instance
- **customize** (CustomConfig) - Optional - Custom field configuration
### Returns
- **Selector | null** - HA selector config or null if not found
```
--------------------------------
### Configure Entity Inclusion
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
Define which entities or domains to include in the scheduler.
```yaml
include:
- light # All lights
- climate.my_thermostat # Specific entity
- "*_garden" # Wildcard pattern
- "script.*" # All scripts
```
--------------------------------
### computeActionsForDomain
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-actions.md
Retrieves all available actions for a domain, combining built-in actions with custom ones defined in the entity configuration.
```APIDOC
## computeActionsForDomain
### Description
Retrieves all available actions for a domain. Combines built-in actions with custom ones.
### Signature
`export const computeActionsForDomain = (hass: HomeAssistant, domain: string, config: entityConfig): actionItem[]`
### Parameters
- **hass** (HomeAssistant) - Required - Home Assistant instance
- **domain** (string) - Required - Entity domain (e.g., 'light', 'climate')
- **config** (entityConfig) - Required - Entity configuration (include/exclude/customize)
### Returns
- **actionItem[]** - Array of available actions
### actionItem Structure
- **key** (string) - Unique key for this action
- **name** (string) - Display name
- **description** (string) - Help text
- **icon** (string) - MDI icon name
- **action** (Action) - Action object to use
### Example
```typescript
const actions = computeActionsForDomain(hass, 'light', {
customize: {
'light.kitchen': {
exclude_actions: ['turn_off']
}
}
});
actions.forEach(a => {
console.log(`${a.name}: ${a.description}`);
});
```
```
--------------------------------
### Format Action Text
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Converts an action object into a localized display string based on Home Assistant configuration.
```typescript
import { formatActionDisplay } from './data/format/format_action_display';
const text = formatActionDisplay(action, hass, config.customize);
console.log(text); // 'Turn on at {brightness}'
```
--------------------------------
### Configure custom entity actions
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/configuration.md
Defines specific service calls and variable ranges for entity actions.
```yaml
customize:
light.bedroom:
actions:
- service: light.turn_on
service_data:
brightness: 100
color_temp: 350
name: "Warm white"
variables:
brightness:
min: 0
max: 255
step: 1
scale_factor: 1
color_temp:
min: 150
max: 500
step: 10
```
--------------------------------
### Export Schedule to Legacy Format
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-store.md
Converts an internal Schedule object into a backend-compatible LegacyScheduleConfig format.
```typescript
export const exportSchedule = (schedule: Schedule): LegacyScheduleConfig
```
--------------------------------
### fetchItem
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-store.md
Fetches a single schedule by entity ID.
```APIDOC
## fetchItem
### Description
Fetches a single schedule by entity ID.
### Signature
`fetchItem(hass: HomeAssistant, entity_id: string): Promise`
### Parameters
- **hass** (HomeAssistant) - Required - Home Assistant instance
- **entity_id** (string) - Required - Entity ID of schedule
### Returns
- **Promise** - The requested schedule
### Example
```typescript
const schedule = await fetchItem(hass, 'scheduler.my_schedule');
```
```
--------------------------------
### Compare Actions Utility
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-actions.md
Determines if two actions are equivalent by comparing service names, data keys, and target entities while ignoring variables.
```typescript
export const compareActions = (action1: Action, action2: Action): boolean
```
--------------------------------
### Compute Schedule Display Usage
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-display.md
Demonstrates how to invoke the computeScheduleDisplay function with a specific display format array.
```typescript
const display = computeScheduleDisplay(
schedule,
['entity: action', 'relative-time'],
hass,
customize
);
// Returns: ['Kitchen Light: Turn on', 'in 2 hours 15 minutes']
```
--------------------------------
### Create Single-Action Schedule Programmatically
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Defines a basic schedule object and saves it using the saveSchedule utility.
```typescript
import { saveSchedule } from './data/store/save_schedule';
import { Schedule, TWeekday, TRepeatType, TConditionLogicType } from './types';
const schedule: Schedule = {
entries: [{
weekdays: [TWeekday.Workday],
slots: [{
start: '08:00:00',
actions: [{
service: 'light.turn_on',
service_data: { brightness: 200 },
target: { entity_id: 'light.kitchen' }
}],
conditions: {
type: TConditionLogicType.Or,
items: [],
track_changes: false
}
}]
}],
next_entries: [],
timestamps: [],
repeat_type: TRepeatType.Repeat,
enabled: true,
name: 'Kitchen morning light'
};
await saveSchedule(hass, schedule);
```
--------------------------------
### Fetch all schedules via WebSocket
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/INDEX.md
Use this message to retrieve the current list of schedules from the backend.
```json
{ type: 'scheduler' }
```
--------------------------------
### Time Utility Functions
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Functions for parsing, formatting, offsetting, and rounding time strings.
```APIDOC
## Time Utility Functions
### timeToString(hours, minutes, seconds)
Converts numeric time components into a 'HH:MM:SS' string.
### parseTimeString(timeStr)
Parses a 'HH:MM:SS' string into an object with hours, minutes, and seconds.
### computeTimeOffset(timeStr, mode, hass)
Calculates the offset of a fixed time string relative to sunrise or sunset.
### addTimeOffset(base, offset, mode, hass)
Creates a time string relative to sunrise or sunset with a specified offset.
### roundTime(timeStr, interval)
Rounds a 'HH:MM:SS' string to the nearest specified minute interval.
```
--------------------------------
### Calculate Sunrise/Sunset Times
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/usage-examples.md
Computes time offsets relative to solar events using the Home Assistant instance.
```typescript
import { computeTimeOffset, addTimeOffset } from './data/time/compute_time_offset';
// Get offset of fixed time from sunrise
const offset = computeTimeOffset('08:00:00', TimeMode.Sunrise, hass);
// '-00:15:00' if sunrise is 08:15
// Create sunrise-relative time
const sunriseTime = addTimeOffset('sunrise', '+01:00:00', TimeMode.Sunrise, hass);
// 'sunrise+01:00:00'
// Create sunset-relative time
const sunsetTime = addTimeOffset('sunset', '-00:30:00', TimeMode.Sunset, hass);
// 'sunset-00:30:00'
```
--------------------------------
### Scheduler Card Data Flow
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/README.md
Visual representation of the data flow from user configuration to the Home Assistant backend.
```text
User Configuration (YAML)
↓
validateConfig → CardConfig object
↓
SchedulerCard (Lit component)
↓
├→ fetchItems → Schedule[]
├→ sortSchedules → Sorted Schedule[]
├→ isIncludedSchedule → Filter
├→ computeScheduleDisplay → Render text
└→ computeActionsForDomain → UI for actions
↓
Home Assistant Backend
↓
scheduler-component (Integration)
```
--------------------------------
### compareActions
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-actions.md
Compares two action objects for equality based on service name, data keys, and target entities, ignoring variables.
```APIDOC
## compareActions
### Description
Compares two actions for equality. Used to identify matching actions.
### Signature
`export const compareActions = (action1: Action, action2: Action): boolean`
### Parameters
- **action1** (Action) - Required - First action to compare
- **action2** (Action) - Required - Second action to compare
### Returns
- **boolean** - True if equivalent
```
--------------------------------
### Compute Action Domains
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-actions.md
Retrieves a list of available domains for scheduling, filtered by include/exclude patterns and wildcard support.
```typescript
export const computeActionDomains = (hass: HomeAssistant, config: CardConfig): string[]
```
```typescript
const domains = computeActionDomains(hass, {
include: ['light', 'climate', '*_fan'],
exclude: ['light.bedroom']
});
```
--------------------------------
### Core TypeScript Type Hierarchy
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/README.md
Summary of the primary configuration, schedule, display, and time-related types used within the project.
```typescript
// Configuration
CardConfig
// Schedule definition
Schedule → ScheduleEntry → Timeslot
└→ Action, ConditionConfig → Condition
// Display
DisplayItem
// Time
Time, TimeMode
// Enums
EditorMode, TWeekday, TRepeatType
TConditionLogicType, TConditionMatchType
```
--------------------------------
### Format Action Display
Source: https://github.com/nielsfaber/scheduler-card/blob/main/_autodocs/api-reference-display.md
Defines the function signature for formatting actions into human-readable strings.
```typescript
export const formatActionDisplay = (
action: Action,
hass: HomeAssistant,
customize?: CustomConfig
): string
```