Entity types
Which entity domains are supported, what the dedicated card renderers do, what commands are available, and which domains are blocked for security reasons.
Tier overview
HArvest categorizes every HA entity domain into one of three tiers. The tier determines what UI is shown and whether the domain can be used at all.
| Tier | Description |
|---|---|
| Tier 1 | Dedicated card renderer with full UI controls. State displays, interactive controls, and history graph support where applicable. |
| Tier 2 | Generic card - shows icon, entity name, and current state text. Includes a basic toggle where the domain supports it. Any domain not in Tier 1 or 3 lands here. |
| Tier 3 | Blocked. Cannot be added to any token. The integration rejects these at token creation time. |
Tier 1 - Dedicated renderers
Every entity has universal settings available in the entity settings card: name override (custom display name replacing the HA friendly name), force color scheme (Auto, Light, or Dark per entity), access (Badge, Read only, or Control), companions (not available for Badge), gestures (not available for Badge), and excluded attributes. When access is set to Badge, the entity renders as a compact pill-shaped indicator showing only icon, name, and state. Badge-specific settings (show icon, show name, show state, icon color) replace the domain-specific and companion settings. Domain-specific settings are listed under each entity type below.
light
On/off toggle, brightness slider, color temperature slider. Hides controls that the physical device doesn't support (e.g. no brightness slider on a non-dimmable light). Supported features are read from the entity's supported_features bitmask.
Display settings: brightness, color temperature, and RGB color can each be individually toggled on or off in the entity settings card.
History graph: supported (configurable per entity in the panel)
switch
On/off toggle. Simple state display with device-class icon.
binary_sensor
Read-only. Displays current state with device-class appropriate icon and label (motion, door, window, smoke, etc.).
History graph: supported
sensor
Read-only. Three sub-renderers based on device class:
- temperature - large temperature value display with unit
- humidity - large humidity percentage display
- battery - percentage bar with color (green/amber/red by level)
- generic sensor - value + unit, works for any numeric sensor
History graph: supported (line or bar, configurable per entity)
fan
Toggle, speed percentage slider, oscillate toggle, direction selector (forward/reverse). The fan icon optionally spins when the entity is on (enabled via the Animate display setting in the panel). Controls that the physical device doesn't support are hidden.
Display settings: choose a display mode to override auto-detection: Auto (default), On/Off only (hides speed controls), Continuous (forces slider), Stepped (forces step buttons), or Cycle (forces cycle button).
climate
HVAC mode selector (heat, cool, heat_cool, auto, dry, fan_only, off), target temperature controls (up/down buttons with numeric display), current temperature read-only display, fan mode dropdown, preset mode dropdown. All controls respect the entity's supported modes.
Display settings: HVAC modes, presets, fan mode, and swing mode can each be individually toggled on or off.
cover
Open, stop, and close buttons. Position slider (0-100%). Controls are shown or hidden based on device capabilities (some covers are open/close only with no position support).
Display settings: position slider and tilt control can be individually toggled.
media_player
Play/pause, next track, previous track, volume slider, mute toggle. Current track title, artist, and source display. Album art is not supported in v1.
Display settings: transport controls, volume, and source selector can be individually toggled.
input_boolean
On/off toggle. Functionally equivalent to switch but for HA input helpers.
input_number
Range slider spanning the entity's min/max, with current value display. Step size respects the entity's configured step.
Display settings: choose between Slider (default) or Buttons mode.
History graph: supported
input_select
Dropdown selector showing all available options. Current option is pre-selected.
timer
Countdown display. Start/resume, pause, cancel, and finish buttons. State-aware: shows relevant buttons for current state (idle, active, paused).
remote
Activity chip grid (selectable activities), raw command input with a send button. Power toggle. Shows the device's configured activity list.
weather
Read-only. Displays current conditions: a large condition icon paired with the temperature, condition label, and a detail row showing humidity, wind speed, and pressure. A 5-day forecast strip appears below, showing day name, condition icon, and high/low temperatures for each day.
Forecast data is fetched directly from HA's weather/subscribe_forecast API and pushed to the widget automatically. This works correctly on HA 2024.4+ where the forecast state attribute was removed.
History graph: not supported.
harvest_action
A virtual entity domain for safe, panel-configured button actions. Each action is a pre-defined service call or automation trigger set up in the HArvest panel's Actions tab. The card renders as a full-width trigger button. Actions run with HA's full permissions but only execute the specific service calls you configured - visitors can't invoke arbitrary HA services.
Normal entities can only call services listed in ALLOWED_SERVICES. Harvest actions are different: they can call any HA service, including services in Tier 3 domains (lock, alarm, script, etc.). This is by design - they are admin-defined server-side mappings that give you full flexibility. The tradeoff is that a misconfigured action could expose a high-risk service to public visitors. Review your action definitions carefully, especially if they target security-sensitive domains.
Tier 2 - Generic cards
Any domain not in Tier 1 or Tier 3 gets the generic card renderer. It shows:
- Domain icon (MDI, best-match for the domain)
- Entity friendly name
- Current state as text
- A basic toggle, if the domain supports
turn_on/turn_off
Some examples of Tier 2 domains: number, select, text, date, time, event, calendar.
By default, Tier 2 domains are display-only. However, admins can enable commands for any Tier 2 domain by registering its allowed services in the panel under Settings > Custom Domains. See the Custom domains section for details.
Tier 3 - Blocked domains
These domains cannot be added to any token. The integration rejects them at token creation time in the panel - they won't appear in the entity picker at all.
| Domain | Why blocked |
|---|---|
alarm_control_panel | Security system - only arm/disarm from trusted interfaces |
lock | Physical security device - high risk if exposed publicly |
person | Location tracking - privacy risk |
device_tracker | Location tracking - privacy risk |
camera | Live video feed - significant bandwidth and privacy risk |
script | Arbitrary HA scripting - use harvest_action for controlled execution |
automation | Arbitrary HA automation triggers |
scene | Deferred to v2 review |
update | HA update management - admin-only operation |
button | Arbitrary HA button press - use harvest_action instead |
Use the harvest_action virtual domain. Create an action in the HArvest panel's Actions tab that points to your script or service call. The visitor gets a button that triggers the pre-defined action. This keeps you in control of exactly what can be executed.
Companion-eligible domains
Only these domains can be set as companions (secondary entities displayed inside another card):
| Domain | Access in companion role | Typical use |
|---|---|---|
light | Toggle on/off | Additional light in the same room shown as a pill |
switch | Toggle on/off | Related switch shown alongside a primary entity |
input_boolean | Toggle on/off | Boolean helper state |
fan | Toggle on/off | Fan power state alongside a climate or light card |
binary_sensor | Read-only | Motion, door/window state, occupancy indicator inside a light card |
sensor | Read-only | Temperature next to a climate card, power draw next to a switch |
cover | Read-only | Cover position indicator alongside a related entity |
remote | Read-only power state | Remote power status alongside a media player card |
There is no per-card companion limit. The total number of entities (primaries plus companions) per token is capped at 50. Companions are configured per-entity in the panel's entity display settings - no HTML attribute needed. When the companion is assigned, the server automatically subscribes it and delivers its state alongside the primary entity.
Each companion has a "Read only" toggle that defaults to on. When read-only, the companion shows state but cannot be interacted with, regardless of the domain. If the primary card's access is set to "Read only", all its companions are forced to read-only and the toggle is hidden.
Allowed service calls
HArvest enforces an explicit whitelist of allowed service calls. Any command not on this list is rejected by the integration before it reaches HA, regardless of what the widget requests. The table below covers all built-in Tier 1 domains. Page-level code and custom renderers cannot modify this list, but admins can extend it for additional domains using Settings > Custom Domains in the panel. See Custom domains below.
| Domain | Allowed services |
|---|---|
light | turn_on, turn_off, toggle |
switch | turn_on, turn_off, toggle |
input_boolean | turn_on, turn_off, toggle |
fan | turn_on, turn_off, toggle, set_percentage, oscillate, set_direction, set_preset_mode, increase_speed, decrease_speed |
cover | open_cover, close_cover, stop_cover, set_cover_position |
climate | turn_on, turn_off, set_temperature, set_hvac_mode, set_fan_mode, set_preset_mode, set_swing_mode |
input_number | set_value |
input_select | select_option |
timer | start, pause, cancel, finish |
media_player | media_play_pause, media_next_track, media_previous_track, volume_up, volume_down, volume_set, volume_mute, select_source, turn_on, turn_off |
remote | turn_on, turn_off, send_command |
harvest_action | trigger (executes the pre-configured service call defined in the panel) |
Custom domains
The built-in allowed services table covers Tier 1 domains only. For any Tier 2 domain, admins can register allowed services in the HArvest panel under Settings > Custom Domains. This is useful when a developer builds a custom card renderer (via HArvest.registerRenderer()) for a domain like vacuum, humidifier, or valve and needs commands to work.
To register a custom domain:
- Open the HArvest panel and go to Settings > Custom Domains.
- Select a domain from the dropdown. Only Tier 2 domains appear here; Tier 1 domains already have built-in service lists and Tier 3 domains are blocked entirely.
- Toggle on the specific HA services you want to allow for that domain.
- Save. Commands for those services are now permitted for entities in that domain.
Registering a custom domain only opens the server-side command whitelist. You still need a custom renderer (registered via HArvest.registerRenderer()) to provide the UI controls that send those commands. Without a custom renderer, the domain's entities will continue to use the generic card, which only shows state and a basic toggle.
Only enable the services your renderer actually uses. Each allowed service is a potential action a visitor can trigger, so keep the list minimal.