Configuration and control for HEOS speakers
SHOE - An open source HEOS configuration and control project written in python 3.7.
SHOE is designed first as a configuration tool for HEOS devices. It uses XML HTTP commands, like those in the HEOS App, and it is designed to replace and possibly extend the functionality of the app. SHOE has been developed and tested on HEOS1 HS2 speakers, running version 1.520.200 firmware.
The SHOE package is split into two components:
- A library call shoelib that enables access to HEOS speakers via other Python programs. This provides the low level communication interface.
- A CLI client program called shoe that provides a front end to drive shoelib functionality.
Currently, shoe has no special commands to use the speakers as renderers or control the speakers as streaming devices. However, it does expose the renderer device command. This functionality can be achieved using a variety of uPNP software packages.
Note that SHOE is not based on the HEOS CLI interface published by Denon. That interface has limited functionality with regards to configuration. For instance, the CLI spec doesn't address the creations of "Zones" and does not display Groups generated by the app. The CLI may be useful for implementing playback functions, if SHOE ever goes that way, but the XML HTTP appears to expose a far more feature rich set.
Licensing and Stuff
SHOE provided free, "as is", without warranty, under the GPL3 License. Please read "LICENSE" file for details. Use at your own risk. Copyright (C) 2020
To install: Use PIP -
python3 -m pip install shoe
Or from git, clone from -
##Other Requirements## Python 3 python-lxml library
Shoe does not yet implement SSDP discovery, so one must know the IP address.
Speaker Network Setup
To setup a HEOS speaker for the network without the HEOS App:
To update the speaker or disable automatic firmware updates without the HEOS App:
A quick check of operation can tested here:
shoe -H <Speaker IP> -i
This should return something like:
Info for <Speaker IP> ---------------- friendlyName : <SPEAKER NAME> manufacturer : Denon manufacturerURL : http://www.denon.com modelName : HEOS 1 modelNumber : DWS-1000 4.0 serialNumber : ACJG00000000 UDN : uuid:00000000-0000-0000-0000-000000000000 DeviceID : AIOS:0001 firmwareRevision : 147202 firmware_date : Thu 2019-09-12 02:43:50 firmware_version : 1.520.200 lanMac : 00:00:00:00:00:00 locale : en_NA moduleRevision : 4 moduleType : Aios 4.0 productRevision : 3 releaseType : Production wlanMac : 00:00:00:00:00:00
To get additional information:
shoe -H <Speaker IP> -ii
shoe -H <Speaker IP> -iii
To set a name:
shoe -H <Speaker IP> -n <Speaker Name>
To combine speakers into a stereo pair:
shoe -H <Lead Speaker IP> <Other Speaker IP> -b <Bond Name>
<Bond Name> will appear in your DLNA/uPNP client as a renderer.
usage: shoe [-h] [-q] [-v] -H HOSTS [HOSTS ...] [-i] [-t] [-n <Speaker Name>] [-u] [-b <Bond Name>] [-s] [-f] [-D <Device Name>] [-F <Root File Name>] [-S <Service Name>] [-x <Root URL Path>] [-c <Command>] [-a <Name> <Value>] [-p <Command> [<Command> ...]] optional arguments: -h, --help show this help message and exit -q, --quiet make output quiet -v, --verbose Increase output verbosity. '-vv' and '-vvv' will show more. -H HOSTS [HOSTS ...], --Host HOSTS [HOSTS ...] This will set the host for the operation, usually an IP address. At least one host is required. For some operations (e.g. -b) multiple hosts can be given. If only one host is required for the command, then the first host will be used. Port can be specified with ':' as in '<host>:<port>' -i, --info Displays info for devices. '-ii' and '-iii' will show more -t, --tree Displays Command Tree. Defaults to showing commands from AIOS, Group, and Zone services. Add a second t, '-tt' to show commands from all services. -n <Speaker Name>, --name <Speaker Name> This will name a speaker. If multiple hosts are given, multiple names may also be given. Names will be assigned in order ofhosts given by the (-H) command -u, --unBond This will delete the bond -b <Bond Name>, --bond <Bond Name> This will bond all hosts given on command line with the (-H) command, making a multichannel speaker grouping with the name <Bond Name>. The channel assignment will be based on the order of hosts given by the (-H) command: Left, Right, RearL, RearR, Center, Sub. If two speakers are given, the pair will be stereo, and surround speakers will be added for more than two speakers. Speaker channels can be modified with the (-s) command. -s, --swap Swaps left and right speakers -f, --force Send commmand without parameter checks. Requires '-D' and '-S' options to work correctly -D <Device Name>, --device <Device Name> Select a device. -F <Root File Name>, --rootFileName <Root File Name> Use file given by <Root File Name> for the root configuration, rather than URL. -S <Service Name>, --service <Service Name> Select a service. -x <Root URL Path>, --rootUrlPath <Root URL Path> Specifies a URL for the root XML configuration file. By default, this is the config path is "/upnp/desc/aios_device/aios_device.xml", for HEOS1 running firmware version 1.520.200 -c <Command>, --cmnd <Command> Select a command. The command can be followed by (-a) to give arguments for the command. If multiple hosts are given with the (-H) option, the command will be run on all hosts. If device and service are not specified with (-d) and (-s) options, and the command name is duplicated across services, it will be run on all matching services. -a <Name> <Value>, --arg <Name> <Value> Set an argument given to an expert command (-e). Must give two values: <Name> indicates the name of the argument. <Value> indicates the value of the argument. For commands that require multiple arguments, use more (-a). If all required arguments are given, with -e, the command will run. -p <Command> [<Command> ...], --param <Command> [<Command> ...] List command argument parameters. Returns hints for argument parameters for the command given by (-c).
SHOE provides access to extended commands not directly accessible using the HEOS app. In a way, these commands are "hidden". There is no documentation on how they work, nor directly accessible or documented in the HEOS app.
These commands are broken down into a hierarchy of "devices" and "services" that run on the speaker. These commands are organized into a "command tree":
Device | |\_Service | | Device \_Commands | |\_Service | | | \_Commands | \_Service | . \_Commands . . etc.
SHOE will show the device command tree with the
shoe -H <Speaker IP> -t[t]
This would return a list of commands:
$ shoe -H <Speaker IP> -tt Device: ACT-Denon : Service: ACT : ---------------- AddNetworkShare ApplyChanges CancelChanges CancelFirmwareUpgrade CheckForFirmwareUpgrade DeleteNetworkShare GetAccessPointList GetActiveInterface GetAudioConfig GetBluetoothStatus GetConfigurationStatus GetConfigurationToken GetCurrentLanguage GetCurrentState GetDaylightSaving GetFriendlyName GetHEOSNetID GetLEDConfig GetNetworkConfiguration GetNetworkConfigurationList GetNetworkShares GetP2PMode GetSessionId GetSupportedLanguageList GetSurroundSpeakerConfig GetTimeZone GetTranscode GetUpdateAction GetUpdateLevel GetUpgradeProgress GetUpgradeStatus GetVolumeLimit GetWirelessProfile GetWirelessState GetWirelessStatus ReIndexNetworkShare ReMountNetworkShare RegisterUser ReleaseConfigurationToken SetAudioConfig SetBluetoothAction SetConfigurationStatus SetCurrentLanguage SetDaylightSaving SetFriendlyName SetHEOSNetID SetLEDConfig SetNetworkConfiguration SetSessionId SetSurroundSpeakerConfig SetTimeZone SetTranscode SetUpdateAction SetUpdateLevel SetVolumeLimit SetWPSPinSSID SetWirelessProfile StartInvitation StartWifiAp StopInvitation StopWifiAp SubmitDiagnostics UpdateFirmware ---------------- Device: AiosServices : Service: ErrorHandler : ---------------- ClearError DummyAction_ErrorHandler ---------------- Service: ZoneControl : ---------------- AddMemberToZone CreateZone DestroyZone DummyAction_ZoneControl GetCurrentState GetMemberStatus GetZoneConnectedList GetZoneFriendlyName GetZoneMemberList GetZoneMinimise GetZoneMute GetZoneStatus GetZoneUUID GetZoneVolume RemoveMemberFromZone SetZoneFriendlyName SetZoneMinimise SetZoneMute SetZoneVolume TestZoneConnectivity ---------------- Service: GroupControl : ---------------- AddMembersToGroup CreateGroup DestroyGroup DummyAction_GroupControl GetConfigDeviceUUID GetCurrentState GetDeviceFriendlyName GetGroupBalance GetGroupBass GetGroupFriendlyName GetGroupMemberChannel GetGroupMemberList GetGroupMute GetGroupStatus GetGroupTreble GetGroupUUID GetGroupUpdating GetGroupVolume GetMediaServerUUID GetSignalStrength RemoveMembersFromGroup SetDeviceFriendlyName SetGroupBalance SetGroupBass SetGroupFriendlyName SetGroupMemberChannel SetGroupMute SetGroupTreble SetGroupVolume ---------------- ---------------- Device: MediaRenderer : Service: AVTransport : ---------------- GetCurrentState GetCurrentTransportActions GetDeviceCapabilities GetMediaInfo GetMediaInfo_Ext GetPositionInfo GetTransportInfo GetTransportSettings Next Pause Play Previous Seek SetAVTransportURI SetNextAVTransportURI SetPlayMode Stop X_SetShuffle ---------------- Service: ConnectionManager : ---------------- ConnectionComplete GetCurrentConnectionIDs GetCurrentConnectionInfo GetCurrentState GetProtocolInfo PrepareForConnection ---------------- Service: RenderingControl : ---------------- GetCurrentState GetMute GetVolume GetVolumeDB ListPresets SelectPreset SetMute SetVolume SetVolumeDB X_GetBalance X_GetBass X_GetPreset X_GetSubwoofer X_GetTreble X_SetBalance X_SetBass X_SetMute X_SetSubwoofer X_SetTreble X_SetVolume ---------------- Device: MediaServer : Service: ContentDirectory : ---------------- Browse GetSearchCapabilities GetSortCapabilities GetSystemUpdateID Search X_HideItem X_RenameItem X_SetItemInputLevel ---------------- Service: ConnectionManager : ---------------- ConnectionComplete GetCurrentConnectionIDs GetCurrentConnectionInfo GetCurrentState GetProtocolInfo PrepareForConnection ----------------
Argument for any of these commands can be found:
$ shoe -H <Speaker IP> -p <Command Name>
$ shoe -H <Speaker IP> -p GetGroupBalance Cmnd: GetGroupBalance Device: AiosServices Service: GroupControl Parameters : ---------------- name : GroupUUID direction : in state : dataType : string @sendEvents : no ---------------- name : GroupBalance direction : out state : dataType : ui2 defaultValue : 50 allowedValueRange : minimum : 0 maximum : 100 step : 1 @sendEvents : no ----------------
This indicates that GroupUUID is required as an input parameter, and GroupBalance is an output. To get the group balance, one must first get the GroupUUID:
$ shoe -H <Speaker IP> -c GetGroupUUID Cmnd: GetGroupUUIDResponse Service: GroupControl Device: AiosServices GroupUUID : 00000000000000000000000000000000 $ shoe -H <Speaker IP> -c GetGroupBalance -a GroupUUID 00000000000000000000000000000000 Cmnd: GetGroupBalanceResponse Service: GroupControl Device: AiosServices GroupBalance : 50
Other Version of Hardware
Other version of hardware and firmware may work with SHOE. SHOE requires a root XML, served from the HEOS device, to configure itself. The URL can be found in the payload header of SSDP packets, gathered using a packet sniffing tool such as wireshark:
LOCATION: http://<Speaker IP>:<Port>/upnp/desc/aios_device/aios_device.xml
This is the location of the root XML file for the HEOS 1 speaker, version 1.520.200. Other devices may have a different location. The
shoe program allows one to specify URL or a file on the command line.
Just like the HEOS app, all communication between SHOE and Denon HEOS speakers is plaintext, without password protection. From a practical perspective, any sensitive information stored on you speakers, including your WIFI password, may be be gathered through trivial methods. Anyone with network access to your speaker, either via WIFI, or physical access to the Ethernet port, can access and control you speakers with SHOE. Consider this when setting up your speakers on your network.
Version Release Notes
The goal is to remove configuration dependence from the HEOS app. SHOE will provide a minimal CLI interface that address devices via IP and allow for configuration of speakers without the use of the HEOS app. With the limited feature set, the test focus will primarily be on ACT, GroupConfig, and ZoneConfig services.
The following features are implemented:
- Display information from the HEOS device.
- Provide CLI interface to execute individual commands on the HEOS device in an "Expert Mode'
- Script more complex actions for easy configuration:
- Naming a device
- Binding devices into a "Zone" for multichannel speaker operation
- Selecting channels.
- Fixed some issues with alternate xml url (-x option).
- Added versioning option.
- Better response if no host is given.
- Fixed bug with shoeBond.
- Set python minimum version for PIP install to >=3.6
- Added extended commands to README.md
- Typo fixes to README.md
Possible future features:
- Network configuration
- Bluetooth configuration
- LED intensity
- Rendering w/ streaming services
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size shoe-0.1.9-py3-none-any.whl (96.7 kB)||File type Wheel||Python version py3||Upload date||Hashes View|
|Filename, size shoe-0.1.9.tar.gz (60.8 kB)||File type Source||Python version None||Upload date||Hashes View|