Python library for controlling a Pioneer AVR via its built-in API.
Used by the pioneer_async integration for Home Assistant, which was inspired by the original Pioneer Home Assistant integration. Originally developed and tested on a VSX-930 (Main Zone and HDZone outputs) but has since been tested on a larger set of models by the community.
There are several types of parameters that modify the library's functionality. These are listed below in order of increasing priority:
set_user_params
methodWhere a parameter is specified at more than one level, the higher priority parameter takes precedence. So a user specified parameter will override any value that is determined by the AVR model.
NOTE: YAML syntax is used in the table below. Use Python equivalents (false
-> False
, true
-> True
, null
-> None
etc.) when calling the Python API directly, and JSON syntax if manually specifying via the Home Assistant integration.
Name | Type | Default | Description |
---|---|---|---|
ignored_zones |
list | [] |
List of zones to ignore even if they are auto-discovered. Specify Zone IDs as strings: "1", "2", "3" and "Z". |
command_delay |
float | 0.1 |
Insert a delay between sequential commands that are sent to the AVR. This appears to make the AVR behave more reliably during status polls. Increase this value if debug logging shows that your AVR times out between commands. |
max_source_id |
int | 60 |
Maximum source ID that the source discovery queries. Reduce this if your AVR returns errors. |
max_volume |
int | 185 |
Maximum volume for the Main Zone. |
max_volume_zonex |
int | 185 |
Maximum volume for zones other than the Main Zone. |
power_on_volume_bounce |
bool | false |
On some AVRs (eg. VSX-930) where a power-on is set, the initial volume is not reported by the AVR correctly until a volume change is made. This option enables a workaround that sends a volume up and down command to the AVR on power-on to correct the reported volume without affecting the power-on volume. |
volume_step_only |
bool | false |
On some AVRs (eg. VSX-S510), setting the volume level is not supported natively by the API. This option emulates setting the volume level using volume up and down commands. |
ignore_volume_check |
bool | false |
Don't check volume when determining whether a zone exists on the AVR. Useful for AVRs with an HDZone that passes through audio. |
zone_1_sources |
list | [] |
(>0.4) Customises the available sources for use with Zone 1. Defaults to all available sources. |
zone_2_sources |
list | see source | Customises the available sources for use with Zone 2 (some AVRs do not support all sources). |
zone_3_sources |
list | see source | Customises the available sources for use with Zone 3 (some AVRs do not support all sources). |
hdzone_sources |
list | see source` | Customises the available sources for use with HDZone (some AVRs do not support all sources). |
hdzone_volume_requirements |
list | ["13", "15", "05", "25"] |
A list of sources that HDZone must be set to for volume control, some AVRs do not support HDZone volume at all (see ignore_volume_check above) and some only allow control of certain sources. |
amp_speaker_system_modes |
dict | .... |
Customises the names of speaker system modes. Different generations of AVR will name zones slighty differently. For example, the SC-LX57 names speaker system mode 15 as 5.1ch Bi-Amp + ZONE2 however this can also be called 5.2ch Bi-Amp + HDZONE on newer AVRs. |
extra_amp_listening_modes |
dict | see source | (>0.5) Additional listening modes that are added to the list of all possible listening modes for the AVR. This list is used to decode the listening mode ID returned by the AVR. See the source for the format for listening mode definition. |
enabled_amp_listening_modes |
list | [] |
(>0.5) A list of listening mode IDs to be made available for selection. If specified, then no listening mode IDs will be included by default. All enabled source names must be unique, and duplicated names are ignored. The additional listening modes must be actually supported by the AVR, and will return an error (usually E02 ) when an unsupported listening mode is selected. This list is predefined for some AVRs, and specifying this parameter manually will override the model specific default disable list. |
disabled_amp_listening_modes |
list | [] |
A list of listening mode IDs to be disabled. Listening mode IDs that are also specified in enabled_amp_listening_modes will be disabled. This list is predefined for some AVRs, and specifying this parameter manually will override the model specific default disable list. |
video_resolution_modes |
list | ['0', '1', '3', '4', '5', '6', '7', '8', '9'] |
Sets the available video resolutions. Not all AVRs support the same resolution settings. This defaults to all of the latest resolutions from FY16. |
mhl_source |
string | null |
Sets the MHL source ID. This is used for media controls. This information cannot be queried automatically |
enabled_functions |
list | ["amp", "dsp", "tuner", "tone", "channels", "video", "system", "audio"] |
Change the functions that are enabled by the API, adding more functions will increase the amount of time it takes to complete a full init and update. |
disable_auto_query |
bool | false |
Setting to true will disable auto queries on init for all functions apart from basic functionality (power, source, volume and mute). If you only need those functions, you can set this to true |
am_frequency_step |
int | null |
Optional setting to configure the AM frequency step. If this is set to null , a function is queued to detect this information by stepping up and down the frequency when the tuner is first used while set to AM. |
debug_listener |
bool | false |
Enables additional debug logging for the listener task. |
debug_responder |
bool | false |
Enables additional debug logging for the responder task. |
debug_updater |
bool | false |
Enables additional debug logging for the updater task. |
debug_command |
bool | false |
Enables additional debug logging for commands sent and responses received. |
If your model of AVR always needs specific parameters to be set for the library to function properly, then please create a PR to add a custom profile for the AVR model.
The library exposes a Python API through the PioneerAVR class. The class methods are listed below:
PioneerAVR.__init__(
host, port = DEFAULT_PORT, timeout: float = DEFAULT_TIMEOUT, _scaninterval: int = DEFAULT_SCAN_INTERVAL, params: dict[str, str] = None )
Constructor for the PioneerAVR class. The connection parameters are used when PioneerAVR.connect
is called. After connection is established, the AVR will be polled every _scaninterval seconds. Optional user parameters are provided via params.
awaitable PioneerAVR.connect(
reconnect: bool = True)
Establish a connection to the AVR. Set reconnect to True to attempt to re-establish the connection on disconnect.
awaitable PioneerAVR.disconnect()
Disconnect from the AVR. Attempt to re-establish the connection if enabled.
awaitable PioneerAVR.shutdown()
Permanently disconnect from the AVR. Does not attempt reconnection.
awaitable PioneerAVR.set_timeout(
timeout: float)
Set command timeout. Used also to set the socket keepalive timeout.
awaitable PioneerAVR.update(
full: bool = False, wait: bool = True)
Request an update of the AVR, and wait for the update to complete if wait is True.
If full is True, then a full update is performed irrespective of when the previous update was performed. Otherwise, an update is performed if the scan interval has elapsed.
If a scan interval is set, then an update is scheduled in the updater task. Otherwise the update is performed synchronously (wait cannot be set to False in this case).
awaitable PioneerAVR.set_scan_interval(
_scaninterval: int)
Set the scan interval to _scaninterval and restart the updater task.
awaitable PioneerAVR.update_zones()
Update zones from ignored_zones
parameter and re-query zones from the AVR.
awaitable PioneerAVR.turn_on(
zone: Zones = Zones.Z1)
:
Turn on the Pioneer AVR zone.
awaitable PioneerAVR.turn_off(
zone: Zones = Zones.Z1)
:
Turn off the Pioneer AVR zone.
awaitable PioneerAVR.query_device_info()
Query the AVR for device information. Updates the model parameters if device model is changed.
awaitable PioneerAVR.query_zones(
_forceupdate: bool = True)
Query the AVR for available zones by querying the power status for each zone and checking if the AVR responds.
Ignores zones listed in the ignored_zones
parameter.
If the ignore_volume_check
parameter is not set, then additionally query the zone volume as well.
awaitable PioneerAVR.set_panel_lock(
_panellock: str)
:
Set the panel lock.
awaitable PioneerAVR.set_remote_lock(
_remotelock: bool)
:
Set the remote lock.
awaitable PioneerAVR.set_dimmer(
dimmer: str, zone: Zones = Zones.Z1)
:
Set the display dimmer.
awaitable PioneerAVR.select_source(
source: str = None, _sourceid: str = None, zone: Zones = Zones.Z1)
:
Set the input source for zone to name _sourcename or ID _sourceid (requires one argument.)
awaitable PioneerAVR.build_source_dict()
Query the available sources names from the AVR.
Parameter max_source_id
determines the highest source ID that is queried.
PioneerAVR.set_source_dict(
sources: dict[str, str])
Manually set the available sources to the dict sources, where the keys are source IDs (padded to 2 chars) and the values are the corresponding source names.
PioneerAVR.get_source_list(
zone: Zones = Zones.Z1)
-> list[str]
Return the set of currently available source names for zone. The source names can be used with the select_source
method.
PioneerAVR.get_source_dict(
zone: Zones = None)
-> dict[str, str]
Return a dict of currently available source names to source ID mappings for zone.
If zone is None, then return the dict of all available source names to source ID mappings.
PioneerAVR.get_source_name(
_sourceid: str)
-> str
Return the source name for _sourceid.
awaitable PioneerAVR.set_source_name(
_sourceid: str, _sourcename: str = "", default: bool = False)
-> bool
Renames _sourceid to _sourcename on the AVR.
If default is True, reset _sourceid to the default source name.
PioneerAVR.clear_source_id(
_sourceid: str)
Clear the name mapping for _sourceid.
awaitable PioneerAVR.send_command(
command: str, zone: Zones = Zones.Z1, prefix: str = "", suffix: str = "", _ignore_erro* = None, _ratelimit: bool = True)
-> bool | None
Send command command for zone zone to the AVR, prefixed with prefix and/or suffixed with suffix if specified.
If command does not generate a response, then returns True if the command was successfully sent.
Otherwise, returns the response received from the AVR, None if timed out, or False if an error response was received.
If _ignoreerror is None (default), then raise an exception on error. If _ignoreerror is True, then log the error as level debug, otherwise log the error as level error.
Raises AVRResponseTimeoutError
on timeout, and AVRCommandError
if the request returned an error.
If _ratelimit is True, then rate limit the commands sent to the AVR in accordance with the command_delay
parameter.
PioneerAVR.queue_command(
command: str, _skip_ifqueued: bool = True, _insertat: int = -1)
-> None
Add command to the command queue, to to be sent in the background to the AVR when method command_queue_schedule
is invoked.
Insert the command at queue position _insertat if specified (inserts at end of the queue by default).
awaitable PioneerAVR.send_raw_command(
command: str, _ratelimit: bool = True)
Send a raw command command to the AVR.
If _ratelimit is True, then rate limit the commands sent to the AVR in accordance with the command_delay
parameter.
awaitable PioneerAVR.send_raw_request(
command: str, _responseprefix: str, _ratelimit: bool = True)
-> str | bool | None
Send a raw command command to the AVR and wait for a response with prefix _responseprefix.
Returns the response received from the AVR.
Raises AVRResponseTimeoutError
on timeout, and AVRCommandError
if the request returned an error.
If _ratelimit is True, then rate limit the commands sent to the AVR in accordance with the command_delay
parameter.
awaitable PioneerAVR.select_tuner_band(
band: TunerBand = TunerBand.FM)
-> bool
Set the tuner band to band.
awaitable PioneerAVR.set_tuner_frequency(
band: TunerBand, frequency: float = None)
-> bool
Set the tuner band to band and tuner frequency to frequency. Step the frequency up or down if it cannot be set directly.
awaitable PioneerAVR.select_tuner_preset(
_tunerclass: str, preset: int)
-> bool:
Select the tuner preset preset in class _tunerclass.
awaitable PioneerAVR.tuner_previous_preset()
Select the previous tuner preset.
awaitable PioneerAVR.tuner_next_preset()
Select the next tuner preset.
awaitable PioneerAVR.select_listening_mode(
_modename: str = None, _modeid: str = None)
-> bool
Set the listening mode to name _modename, or ID _modeid (requires one argument.)
Must be a listening mode valid for the current sound input as returned by get_listening_modes
.
PioneerAVR.get_listening_modes()
-> dict[str, str] | None
Return dict of valid listening mode mapping to names for the AVR.
awaitable PioneerAVR.set_volume_level(
_targetvolume: int, zone: Zones = Zones.Z1)
Set the volume level for zone zone to _targetvolume. _targetvolume must be between 0 and 185 inclusive for Zone 1, and between 0 and 81 inclusive for all other zones.
awaitable PioneerAVR.mute_on(
zone: Zones = Zones.Z1)
-> bool
Turn mute on for zone zone.
awaitable PioneerAVR.mute_off(
zone: Zones = Zones.Z1)
-> bool
Turn mute off for zone zone.
awaitable PioneerAVR.set_tone_settings(
tone: str = None, treble: int = None, bass: int = None, zone: Zones = Zones.Z1 )
*
Set the tone settings for zone zone to tone. When tone is set to On
, treble specifies the treble and bass specifies the bass.
awaitable PioneerAVR.set_amp_settings(
_speakerconfig: str = None, _hdmiout: str = None, _hdmi_audiooutput: bool = None, pqls: bool = None, amp: str = None, zone: Zones = Zones.Z1)
-> bool
Set amplifier function settings for zone zone.
PioneerAVR.get_ipod_control_commands()
-> list[str]
Return a list of all valid iPod control modes.
PioneerAVR.get_tuner_control_commands()
-> list[str]
Return a list of all valid tuner control commands.
PioneerAVR.get_supported_media_controls(
zone: Zones)
-> list[str]
Return a list of all valid media control actions for zone zone. Return None if the provided zone source is not currently compatible with media controls.
awaitable PioneerAVR.set_channel_levels(
channel: str, level: float, zone: Zones = Zones.Z1)
-> bool
Set the level (gain) for amplifier channel in zone zone.
awaitable PioneerAVR.set_video_settings(
zone: Zones, arguments)
-> bool**
Set video settings for zone zone.
awaitable PioneerAVR.set_dsp_settings(
zone: Zones, arguments)
-> bool**
Set the DSP settings for the amplifier for zone zone.
awaitable PioneerAVR.media_control(
action: str, zone: Zones = Zones.Z1)
-> bool
Perform media control activities such as play, pause, stop, fast forward or rewind.
PioneerAVR.set_zone_callback(
zone: Zones, callback: Callable[..., None])
Register callback callback for zone zone.
PioneerAVR.clear_zone_callbacks()
Clear callbacks for all zones.
PioneerAVR.set_user_params(
params: dict[str, Any] = None)
-> None
Set user parameters and update current parameters.
PioneerAVR.get_param(
_paramname: str)
-> Any
Get the value of the specified parameter.
PioneerAVR.get_params()
-> dict[str, Any]
Get a copy of all current parameters.
PioneerAVR.get_user_params()
-> dict[str, Any]
Get a copy of user parameters.
PioneerAVR.get_default_params()
-> dict[str, Any]
Get a copy of current default parameters.
Listed below are the public attributes of a PioneerAVR
object. Use a Zones enum to access zone specific attributes for those that are indexed by zone.
Attribute | Type | Description |
---|---|---|
scan_interval |
int | Number of seconds between polls for AVR full updates |
model |
str | None | Model number returned by the AVR |
software_version |
str | None | Software version returned by the AVR |
mac_addr |
str | None | System MAC address returned by the AVR |
available |
bool | Whether integration is connected to the AVR |
initial_update |
bool | None | Set to False if the initial update has been deferred due to the AVR main zone being powered off when initially connected, and True when the update has been completed |
zones |
list[Zones] | List of all zones detected on the AVR |
power |
dict[Zones, bool] | Power status for each detected zone |
volume |
dict[Zones, int] | Volume status for each detected zone |
max_volume |
dict[Zones, int] | Maximum valid volume for each detected zone |
mute |
dict[Zones, bool] | Mute status for each detected zone |
source |
dict[Zones, str] | Active source for each detected zone |
listening_mode |
str | Name of the currently active listening mode |
listening_mode_raw |
str | ID of the currently active listening mode |
media_control_mode |
dict[Zones, str] | Media control mode for each detected zone |
tone |
Tone attributes for each detected zone | |
amp |
Current AVR amp attributes | |
tuner |
Current AVR tuner attributes | |
channel_levels |
dict[str, Any] | Current AVR channel levels, indexed by channel name |
dsp |
Current AVR DSP attributes | |
video |
Current AVR video parameters | |
audio |
Current AVR audio parameters | |
system |
AVR system attributes |
A very simple command line interface aiopioneer
is available to connect to the AVR, send commands and receive responses. It can be used to test the capabilities of the library against your specific AVR.
On Home Assistant, you can run the CLI when the pioneer_async
Home Assistant integration has been installed. On Home Assistant Supervised or Container, start the CLI from within the HA container: docker exec -it homeassistant aiopioneer
.
Invoke the CLI with the following arguments:
Argument | Default | Description |
---|---|---|
hostname | required | hostname for AVR connection |
-p --port |
8102 | port for AVR connection |
+Q --no-query-device-info |
None | skip AVR device info query |
+Z --no-query-zones |
None | skip AVR zone query |
The CLI accepts all API commands, as well as the following: | Command | Argument | Description |
---|---|---|---|
exit or quit |
Exit the CLI. | ||
zone |
zone | Change current zone to zone. | |
log_level |
_loglevel | Change debug level to _loglevel. Valid log levels are: debug , info , warning , error , critical . |
|
update |
Request update of AVR. An update is scheduled in the updater task if a scan interval is set, if it is not set then the update is performed synchronously. | ||
update_full |
Request a full update of AVR irrespective of when the previous update was performed. An update is scheduled in the updater task if a scan interval is set, if it is not set then the update is performed synchronously. | ||
query_device_info |
Query the AVR for device information. | ||
query_zones |
Query the AVR for available zones. Ignore zones specified in parameter ignored_zones (list). |
||
build_source_dict |
Query the sources from the AVR. | ||
set_source_dict |
sources (JSON) | Manually set the sources to sources. | |
get_source_list |
Return the current set of available source names that can be used with the select_source command. |
||
get_zone_listening_modes |
(>0.5) Return the current set of available listening modes. | ||
get_params |
Return the currently active set of parameters. | ||
get_user_params |
Return the currently active set of user parameters. | ||
set_user_params |
params (JSON) | Set the user parameters to params. | |
get_tone |
Returns the current AVR tone attributes. | ||
get_amp |
Returns the current AVR amp attributes. | ||
get_tuner |
Returns the current AVR tuner attributes. | ||
get_channel_levels |
Returns the current AVR channel levels. | ||
get_dsp |
Returns the current AVR DSP attributes. | ||
get_video |
Returns the current AVR video parameters. | ||
get_audio |
Returns the current AVR audio parameters. | ||
get_system |
Returns the AVR system attributes. | ||
debug_listener |
state (bool) | Enable/disable the debug_listener parameter. |
|
debug_responder |
state (bool) | Enable/disable the debug_responder parameter. |
|
debug_updater |
state (bool) | Enable/disable the debug_updater parameter. |
|
debug_command |
state (bool) | Enable/disable the debug_command parameter. |
|
set_scan_interval |
_scaninterval (float) | Set the scan interval to _scaninterval. | |
get_scan_interval |
Return the current scan interval. | ||
set_volume_level |
_volumelevel (int) | Set the volume level for the current zone. | |
select_source |
_sourcename | Set the input source for the current zone. | |
select_listening_mode |
_listeningmode | (>0.5) Set the listening mode to the specified mode. | |
set_tuner_frequency |
band frequency | Set the tuner band and (optionally) frequency. | |
tuner_previous_preset |
Select the previous] tuner preset | ||
tuner_next_preset |
Select the next tuner preset | ||
send_raw_command or > |
_rawcommand | Send the raw command _rawcommand to the AVR. |
NOTE: The CLI interface may change in the future, and should not be used in scripts. Use the Python API instead.
The list below shows the source ID that corresponds to each AVR source:
ID | Default Name |
---|---|
25 | BD |
04 | DVD |
06 | SAT/CBL |
15 | DVR/BDR |
19 | HDMI 1 |
20 | HDMI 2 |
21 | HDMI 3 |
22 | HDMI 4 |
23 | HDMI 5 |
24 | HDMI 6 |
34 | HDMI 7 |
26 | NETWORK (cyclic) |
38 | INTERNET RADIO |
53 | Spotify |
41 | PANDORA |
44 | MEDIA SERVER |
45 | FAVORITES |
17 | iPod/USB |
05 | TV |
01 | CD |
13 | USB-DAC |
02 | TUNER |
00 | PHONO |
12 | MULTI CH IN |
33 | BT AUDIO |
31 | HDMI (cyclic) |
46 | AirPlay (Information only) |
47 | DMR (Information only) |
PioneerError
when an error is encountered, rather than returning false
, None
or similar error value. Some instances that currently raise ValueError
or SystemError
will also raise PioneerError
subclasses in the near futuresend_raw_request
no longer accepts an argument ignore_error
and will always raise exceptions on error. Use ignore_error
with send_command
to have exceptions handled for youStrEnum
Zones
enum now used on all methods accepting zone arguments (except in params)TunerBand
enum now used to specify a tuner bandupdate
now waits for the update to finish by defaultset_tuner_preset
has been renamed to select_tuner_preset
get_zone_listening_modes
has been renamed to get_listening_modes
set_listening_mode
has been renamed to select_listening_mode
tuner_*
, get_zone_listening_modes
, set_panel_lock
, set_remote_lock
and set_dimmer
methods no longer accept a zone argumentsuffix
argument of the send_command
method has been reordered after the prefix
argument---
now return Noneget_sound_modes
was renamed to get_zone_listening_modes
to reflect Pioneer AVR terminologydisable_autoquery
was renamed disable_auto_query
to better match the underlying variable nameamplifier_speaker_system_modes
and disabled_amplifier_listening_modes
were shortened to amp_speaker_system_modes
and disabled_amp_listening_modes
respectivelyzone_z_sources
was renamed hdzone_sources
for even more consistencyzone_h_sources
was renamed zone_z_sources
for consistencyvolume_step_delta
has been removed entirelydisable_autoquery
to true
_PioneerAVR.__init__()
no longer accepts command_delay
, volume_workaround
and volume_steps
arguments. Configure these parameters using the equivalent PARAM_*
keys in the params
dict, passed in via the constructure or set via set_user_params()