Marantz SR5015 HEOS CLI ProtocolSpecification Version - Page 5

Following table list out other supported music sources through CLI. Source ID (sid) Source name Browse supported Search supported 1024 Local USB Media/ Local DLNA servers Yes Yes 1025 HEOS Playlists Yes No 1026 HEOS History Yes No 1027 HEOS aux inputs Yes No 1028 HEOS Favorites Yes No 2. Connection The HEOS products can be discovered using the UPnP SSDP protocol. Through discovery, the IP address of the HEOS products can be retrieved. Once the IP address is retrieved, a telnet connection to port 1255 can be opened to access the HEOS CLI and control the HEOS system. The HEOS product IP address can also be set statically and manually programmed into the control system. Search target name (ST) in M-SEARCH discovery request is 'urn:schemas-denon-com:device:ACT-Denon:1'. The control system should use various Get commands to determine the players and groups currently in the HEOS system. Controller software can control all HEOS speakers in the network by establishing socket connection with just one HEOS speaker. It is recommended not to establish socket connection to each HEOS speaker. This is to decrease network traffic caused by establishing socket connection to each HEOS speaker. Controller software can open multiple socket connections to the single HEOS speaker. Typically controllers will use one connection to listen for change events and one to handle user actions. 2.1 Controller Design Guidelines 2.1.1 Driver Initialization In order to reduce number of UPnP devices running on the network, HEOS Speaker runs CLI module in a dormant mode. HEOS speaker spawns CLI core modules when the controller establishes the first socket connection to the speaker. What it all means for controller? Inability of CLI module to process player commands. This is because, by nature of UPnP, CLI module need some time to discover all players before they can be identified by their unique Id (pid) Spew of events when controller initially connects to the speaker. In order to avoid excessive event handling in a event driven controller system, the following initialization sequence is suggested: 1. Un-register for change events. By default speaker doesn't send unsolicited events but still it is a good idea to send unregister command.This is done through 'register_for_change_events' command. 2. If user credentials are available, sign-in to HEOS user account. This is done through 'sign_in' command. 3. Retrieve current HEOS ecosystem status. This is done through commands like 'get_players', 'get_sources', 'get_groups', 'get_queue', 'get_now_playing_media', 'get_volume', 'get_play_state' etc. 4. Register for change events. This is done through 'register_for_change_events' command. If controller design involves disconnect and reconnect to HEOS speakers through CLI, it is recommended to keep a idle connection to HEOS Speaker thus avoiding CLI module to set back to dormant mode. 2.1.2 Caveats 2.1.2.1 Compatibility Please take a look at the following suggestions to avoid breaking controller code due to future enhancements The 'message' field part of HEOS response is a string. The attribute value pair in this message string is delimited by '&'. Further the attribute name and value is separated by '=' sign. Please note that new arguments can be added in the future. New JSON objects may be added to the 'payload' as part of future enhancements. 2.1.2.2 Issues & Solutions