Home Assistant entities

Every entity that a Pinna device adds to Home Assistant, with its type, values and effect on the device.

When you add a Pinna device to Home Assistant, it creates the entities on this page. Object IDs are shown in code font. Home Assistant builds entity IDs from the device name and the entity name, for example light.echo_dot_2a914e_led_ring for a device named Echo Dot 2a914e. They keep the name the device had when you added it.

Controls

Entity Object ID Type Values What it does
LED ring led_ring Light Colour, brightness, effects Solid, Pulse and Flash Uses the ring as a light while the device is idle. See Light ring and buttons
Microphone mute microphone_mute Switch On, off Turns the microphones off in software. Shows on when the microphones are off for any reason, including the hardware button. Turning it off doesn’t open the hardware switch: after the Microphone off button or a request by voice turned the microphones off, press the button. See Microphone off
Wake word wake_word Switch (configuration) On, off Turns wake word detection on or off. The words themselves are chosen with the Wake word and Wake word 2 selectors on the device page. The Action button still starts a request
Listening direction listening_direction Switch (configuration) On, off While the device listens, points the light ring at the person speaking. Off shows the plain listening ring. On by default
Wake sound wake_sound Switch (configuration) On, off Plays a short chime when the device starts listening. The dashboard has the same switch, under Voice & sound
AirPlay airplay Switch (configuration) On, off Turns the AirPlay receiver on or off. While it is on, iPhones, Macs and Music Assistant on your network can play music to the device, without a password. Off by default. The dashboard has the same switch, under Voice & sound > Media sources
Bluetooth audio bluetooth Switch (configuration) On, off Turns Bluetooth on or off. While it is on, phones paired with the device can play music to it. Off by default. The dashboard has the same switch, under Voice & sound > Media sources
Bluetooth pairing bluetooth_pairing Switch On, off Turn it on to open the Bluetooth pairing window for two minutes, like Pair a phone on the dashboard; turn it off to close it. It turns itself off when the window closes, and stays off unless Bluetooth audio is on and ready. See Pair a phone
Sendspin sendspin Switch (configuration) On, off Turns the Sendspin player on or off. While it is on, Music Assistant 2.10.7 or later on your network can play to the device, in step with the other speakers of a group, without pairing. Experimental. Off by default. It stays off on a device without a working speaker. The dashboard has the same switch, under Voice & sound > Media sources. See Play music with Sendspin
Wake word calibration wake_word_calibration Switch (configuration) On, off Starts tuning the wake word sensitivity with the + and − buttons on the device, as Calibrate at the device describes. It turns itself off when calibration ends. It won’t turn on while the microphones or the wake word are off, or while a request or a timer alarm is active
Notification notification Switch On, off Turn it on to show a waiting notification on the ring. It turns off when someone clears it on the device or the dashboard. See Notifications
Group messages group_messages Switch On, off Lets the device take messages from the other satellites of its group in standalone mode. On by default. Turn it off to refuse new messages; messages the device already holds still play. Pinna has no schedule for it: to turn it off at night, use an automation. It does nothing in Home Assistant mode or outside a group. See Pass messages between satellites
Volume volume Number 0 to 100, in % Sets the speaker volume. 0 is silent
Reply volume reply_volume Number 0 to 100, in % Sets the volume of replies and announcements, on the same scale as Volume and never louder than it. Until it is set, it follows Volume; the dashboard’s Replies follow Volume switch makes it follow again. See Volume
Wake word sensitivity wake_word_sensitivity Number 0 to 100 Sets how easily the wake word triggers. Higher values trigger more easily, and more often by mistake. The default is 68. The dashboard’s Wake word page shows which setting catches or ignores each recent wake and near miss
LED brightness led_brightness Number 0 to 100, in % Sets the brightness of the whole ring
Cancel request cancel_request Button Stops a running request, a reply or an announcement, and silences a timer alarm. With none of them, it stops the music; with Sendspin, the whole group
Media player media_player Media player Play, pause, stop, volume, mute, announce Plays audio from a URL and announcements. See Media player
Updates update_channel Select (configuration) stable, beta, off Where the device looks for new releases, as on the dashboard’s System > Updates page. While a developer’s own update address replaces the channel, its only option is that address (Offer your own builds as updates). See How the satellite finds updates
Install updates install_updates Select (configuration) Manually, Automatically Whether the device installs a new release by itself, inside the install window. Manually is the default. The dashboard has the same setting, under System > Updates. See Install updates automatically
Install window start install_window_start Time (configuration) A time of day, 03:00 by default When the install window opens, in the device’s time zone. Used only while Install updates is Automatically
Install window end install_window_end Time (configuration) A time of day, 05:00 by default When the install window closes. It may be earlier than the start, for a window that crosses midnight. The device refuses an end that equals the start, and the entity shows the old time again
Voice mode assistant Select (configuration) Home Assistant, Standalone Who answers voice requests, as Mode on the dashboard’s Assistant page. Standalone works only once speech-to-text, the brain and text-to-speech have passed their check on the dashboard; until then the select goes back to Home Assistant. A change while the satellite answers a request (with its follow-up), plays an announcement or rings an alarm waits until that has ended. Switching deletes every timer and reconnects Home Assistant. See Set up standalone mode
Firmware firmware Update (configuration) Installed and latest version, summary, release notes, progress Shows a newer release on the device’s channel, and installs it. After an install from Home Assistant, the device restarts on its own once it is Idle with no timer set and nothing playing. Unknown until a check has succeeded, and while Updates is off. See Install an update from Home Assistant

Pinna saves the switch, number, select and time values on the device, so they survive a restart.

Sensors

Entity Object ID Type Value
Last wake word last_wake_word Text sensor The wake word heard most recently, for example Hey Jarvis. With two words active, it names the one that fired

Events

Events don’t have a state. Use them as triggers in automations.

Entity Object ID Event types Fires when
Action button action press, double_press, long_press The Action button is pressed. long_press fires after holding it for 2 seconds
Volume up button volume_up press, double_press The Volume up button is pressed
Volume down button volume_down press, double_press The Volume down button is pressed
Microphone mute button microphone_mute press, double_press The Microphone off button is pressed
Voice assistant voice_assistant wake_word, listening, thinking, replying, finished, stopped A voice request moves to the next step
Playback playback started, stopped The media player starts or stops playing
Timer timer started, updated, cancelled, finished A timer on the device changes
Notification notification cleared Someone clears the notification with the Action button or on the dashboard. It doesn’t fire when Home Assistant turns the switch off

replying fires when the reply starts to play, not when Home Assistant sends it. If the reply can’t play, there is no replying, and the request ends with finished.

A double_press fires when you press the same button twice within 0.4 seconds. The button still does its normal job for both presses. While wake word calibration runs, the volume buttons tune the sensitivity instead and don’t fire their events.

Media player

The media player plays two kinds of audio:

  • Media, such as music or a radio stream, from a URL. Pinna plays MP3, WAV, FLAC and Ogg Vorbis. While the device listens, works on a request or speaks, media gets quieter and comes back afterwards.
  • Announcements, from Home Assistant’s announcement actions. An announcement interrupts a running request. Home Assistant can ask the device to listen for an answer after the announcement. In standalone mode, only the media player’s announcements play: there is no Assist satellite to announce on or to ask for an answer.

It supports play, pause, stop, mute and volume. The volume up and down commands change the volume by 5. A new URL replaces what plays once its audio starts. If it doesn’t play, what played before keeps playing.

While AirPlay or Bluetooth plays, the media player’s volume is the music’s own, and pause stops the music.

While Sendspin plays, the media player’s volume and mute are the device’s own in Music Assistant, and play, pause and stop act on the whole group. After a pause from the device, the media player shows the group as paused, and play and stop act on the group; its volume is the device’s overall Volume meanwhile, not its volume in Music Assistant. After a stop, at the end of the queue, or after a pause in Music Assistant, the media player is idle. With no request running and no alarm ringing, Cancel request stops the group too.

The dashboard shows the same media player and plays a URL too. Its Now playing shows media that Home Assistant plays as From Home Assistant, without a title or a station’s name: Home Assistant converts the media for the device first, and that removes them. A radio station’s address played from the dashboard shows its titles.

Voice assistant and timers

In Home Assistant mode, the device works as an Assist satellite. It listens for the wake words chosen in Home Assistant or on the dashboard, up to two at once; see Choose the wake words. It supports timers: when you set a timer by voice, the ring shows an amber arc while it runs. When the timer ends, an alarm plays until you say the wake word, press the Action button, use Cancel request, or 5 minutes pass. The wake word only stops the alarm; it doesn’t start a request.

In standalone mode

In standalone mode, the device answers requests itself, with the services you set up on the dashboard. It reports no voice assistant features to Home Assistant, so Home Assistant shows no Assist satellite for it, and no wake word selectors. The device doesn’t send Home Assistant any microphone audio.

The other entities on this page keep working: the media player and its announcements, the volume, the microphone mute, the ring, the buttons and the events. The voice_assistant and timer events fire for the device’s own requests and timers.

The device ignores what only an Assist satellite does: Home Assistant’s requests, timers and wake word choice, and its announcements through the Assist satellite. The device keeps its timers itself, and the dashboard chooses the wake words. Switching the mode deletes every timer, Home Assistant’s included.

The Voice mode select stays, so you can switch back to Home Assistant from there, or say “switch to Home Assistant” to the satellite. Group messages stays too, so an automation can turn messages from the other satellites off and on. Install updates and the install window stay as well. Standalone mode’s other settings have no entities. You set them on the dashboard.

What’s next

Edit this page on GitHub