Configuration and control for HEOS speakers
Project description
About
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
Using SHOE
Install
To install: Use PIP -
python3 -m pip install shoe
Or from git, clone from -
https://github.com/mkarasoff/shoe
##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:
http://<Speaker IP>/settings/index.html
To update the speaker or disable automatic firmware updates without the HEOS App:
http://<Speaker IP>/settings/upgrade.html
Running
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
or
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>
The <Bond Name> will appear in your DLNA/uPNP client as a renderer.
CLI
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).
Extended Commands
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 -t option:
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>
For Example:
$ 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.
Security considerations
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
v(0.1.5)
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.
v(0.1.7)
- Fixed some issues with alternate xml url (-x option).
- Added versioning option.
- Better response if no host is given.
- Fixed bug with shoeBond.
v(0.1.9)
- Set python minimum version for PIP install to >=3.6
- Added extended commands to README.md
- Typo fixes to README.md
Future Possibilities
Possible future features:
- Discovery
- Network configuration
- Bluetooth configuration
- LED intensity
- Rendering w/ streaming services
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
