Marantz AV8805 HEOS CLI PROTOCOL Specification - Page 4

1026 1027 1028 HEOS History HEOS aux inputs HEOS Favorites Yes No Yes No 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 un-register 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 Changes made to HEOS user account, through HEOS app will not reflect through CLI until the controller is restarted. Ex: Adding or removing music services to HEOS user account, through HEOS app will not reflect in get_music_sources command response until the controller is restarted. Solution: Controller needs to re sign-in to HEOS account to reflect changes made through HEOS app, with out restarting the controller. So, in addition to performing HEOS account sign-in as part of driver initialization process, it is highly recommended to provide sign-out and sign-in option through end users UI screen. End user need to re-signIn when he adds/removes music service through HEOS app.