developers.home-assistant/docs/core/entity/assist-satellite.md

title	sidebar_label
Assist satellite entity	Assist satellite

An Assist Satellite entity represents the Assist pipeline-powered voice assistant capabilities of a device. Devices with such entities can allow users to control Home Assistant using their voice.

An Assist satellite entity is derived from the homeassistant.components.assist_satellite.AssistSatelliteEntity.

Properties

Name	Type	Default	Description
pipeline_entity_id	str; None	None	Id of the select entity with the pipeline id or None.
vad_sensitivity_entity_id	str; None	None	Id of the select entity with the voice activity detection sensitivity or None.
tts_options	dict; None	None	Options passed to the text-to-speech system when responding.

States

The state of an AssistSatelliteEntity follows its currently running pipeline. The AssistSatelliteState enum stores the possible states.

:::tip You must call the tts_response_finished method on your entity when a text-to-speech response has finished playing to return to the IDLE state. :::

Constant	Description
IDLE	Device is waiting for user input, such as a wake word or a button press.
LISTENING	Device is streaming audio with the voice command to Home Assistant.
PROCESSING	Home Assistant is processing the voice command.
RESPONDING	Device is speaking the response.

Supported features

Supported features are defined by using values in the AssistSatelliteEntityFeature enum and are combined using the bitwise or (|) operator.

Value	Description
ANNOUNCE	Device supports remotely triggered announcements. Implement the async_announce method to play back the provided media_id from AssistSatelliteAnnouncement. This method should only return once the announcement has finished playing on the device.

Methods

Running a pipeline and handling events

Satellite entities should only run Assist pipelines using the async_accept_pipeline_from_satellite method. Events from the pipeline are handled by implementing the on_pipeline_event method.

The satellite entity's state is automatically updated when a pipeline is run, with the exception of RESPONDING to IDLE. The tts_response_finished method must be called by the developer when the satellite has finished speaking the response on the device.

Get configuration

The async_get_configuration method must return a (cached) AssistSatelliteConfiguration. If the entity must communicate with the device to retrieve the configuration, this should be during initialization.

A websocket command is available for getting an entity's configuration.

Set configuration

The async_set_configuration method updates the device's configuration, and must only return once the device's and Home Assistant's AssistSatelliteConfiguration are synchronized.

A websocket command is available for setting the active wake words.

Announcements

If the device has the ANNOUNCE supported feature, then the async_announce method should be implemented to announce the provided media_id within AssistSatelliteAnnouncement. The async_announce method should only return when the announcement is finished playing on the device.

An announce action is available for automating announcements.

WebSocket API

Intercepting wake words

The integration offers a websocket API to intercept wake word detections and announce them to the user. This is used by the voice wizard to help the user onboard and get familiar with the wake word.

{
  "type": "assist_satellite/intercept_wake_word",
  "entity_id": "assist_satellite.living_room"
}

The entity id must be of an Assist satellite entity which supports the ANNOUNCE feature.

Once a wake word is detected, a response is returned like:

{
  "wake_word_phrase": "okay nabu"
}

Getting the satellite configuration

The current configuration for the satellite, including available and active wake words, can get retrieved with:

{
  "type": "assist_satellite/get_configuration",
  "entity_id": ENTITY_ID
}

A response will be returned like this:

{
  "active_wake_words": [
    "1234"
  ],
  "available_wake_words": [
    {
      "id": "1234",
      "trained_languages": [
        "en"
      ],
      "wake_word": "okay nabu"
    },
    {
      "id": "5678",
      "trained_languages": [
        "en"
      ],
      "wake_word": "hey jarvis"
    }
  ],
  "max_active_wake_words": 1,
  "pipeline_entity_id": "select.pipeline_entity",
  "vad_entity_id": "select.vad_entity"
}

The active_wake_words list contains the ids of wake words from available_wake_words.

The pipeline_entity_id contains the id of the select entity which controls the pipeline that the device will run. The vad_entity_id contains the id of the select entity with the voice activity detector (VAD) sensitivity level.

Setting the active wake words

Set the active wake words using:

{
  "type": "assist_satellite/set_wake_words",
  "entity_id": ENTITY_ID,
  "wake_word_ids": ["1234", "5678"]
}

The wake_word_ids must contain ids from the available_wake_words list from the assist_satellite/get_configuration command. The size of wake_word_ids should also not exceed max_active_wake_words.