====== Chromecast 4 Lox  ======


++++ Version History...|

**Version 0.2.31 (28.2.2021)**

  * fix for a crash on network error (typically recovery after a power failure, if the network (DHCP) was not up yet**\\
**

**Version 0.2.30**

  * rounding bug fixed (ADJUST_VOLUME over 29 etc.)

**Version 0.2.29**

  * QUIT command fixed

**Version 0.2.28**

  * Better loging (easier to see invalid commands)

**Version 0.2.27**

  * Chromecast connection status reporting

**Version 0.2.25**

  * bug fixes

**Version 0.2.12**

  * private beta test

**Version 0.2**

  * first fully working version\\


**Version 0.1**

  * development, proof of concept, initial version

++++


{{plugins:chromecast_4_lox:1231423417.png}}

----

===== Download =====

Latest version here: http://aleq.eu/chromecast4lox/

===== Installation =====

Requires LoxBerry 1.2.2+ (briefly tested to work with 2.2)

  - Follow the standard installation procedure to install the plugin, just link/upload the ZIP file in/to the LoxBerry Plugin Management.
  - After the installation, head to the plugin pages in the LoxBerry Web UI and enter the Configuration. 
  - Return to Overview once finished to validate the configuration:
    - LoxBerry status should say "server running". If not, check your configuration of UDP Port and restart LoxBerry, if still not OK. Check Log, still not OK
    - Chromecast status should say "Connected". If not, check your configuration of Chromecast IP. Make sure the Chromecast is on the same network (same sub net). See Troubleshooting, tips below
    - "Replies will be sent to:" section shows the configured Loxone target. //Optional.//


===== Plugin function =====

Plugin contains a server, which listens for UDP commands coming from Loxone Miniserver, performs desired actions on Chromecast and replies results back to Loxone via another UDP transmission.

__**Supported Chromecast actions:**__

  * //Query status//
  * //Query volume//
  * //Get notified of volume changes//
  * //Control volume (both absolute and relative)//
  * //Play (cast) a stream//
  * //Pause/Stop current cast//
  * //Quit current application//

===== Configuration =====

Plugin needs to be configured first. You need to set:

  * UDP port (where the plugin accepts UDP commands)
  * Chromecast address (if you don't know it, try Discover tab in the plugin, it scans LAN for Chromecasts and lists their IPs)
  * Loxone Miniserver IP address and UDP port (where to send the replies). This is //optional//. If you don't want to receive result (or to query the volume), you don't need to configure it.
  * Periodic volume change detection. This is //optional//. If defined (as a number of seconds), enabled active polling for volume change compared to last known value. The configured time is the amount of seconds how often or how soon after last command is the volume polled. This polling happens on LoxBerry. If a volume change is detected, then (and only then) the message is sent to Loxone Miniserver (ie. Loxone isn't receiving periodic messages unless there's a change). If you need periodic reporting to Loxone, query the volume (using GET_VOLUME command described below) on your own.

===== Loxone Config =====

To control Chromecast:

  - Create Virtual Output, as address use udp:%%//%%//<loxberry_ip>//://<configured_udp_port>//
  - Under this Virtual Output, create desired Virtual output commands. This is a list of supported functions (to be entered into "Command for ON"):
    - GET_STATUS
    - GET_VOLUME
    - SET_VOLUME <v> (Uncheck Use as digital output and copy paste the command including the angle brackets and "v" (less-than and greater_than signs)!
    - ADJUST_VOLUME 5 (feel free to change 5 to a different number, if you want bigger or smaller volume increase in one step)
    - ADJUST_VOLUME -5 (feel free to change -5 to a different number, if you want bigger or smaller volume decrease in one step)
    - PLAY //stream_url//
    - PAUSE
    - QUIT

To receive replies from plugin **(OPTIONAL, simple version):**

  - Create Virtual UDP Input, pick any port number, put it into "UDP receive port" and also into the Chromecast 4 Lox configuration, field "Loxone UDP Port"
  - Under this Virtual UDP Input, add Virtual UDP input commands:
    - Volume
      - Uncheck Signed values
      - Command recognition: "VOLUME \v;" without quotes
      - Unit: "<v>" without quotes
      - Minimum value: 0
      - Maximum value: 100

You can use the UDP monitor (feature of Loxone Config) to explore the replies

===== UDP communication =====

You can send multiple commands at once, separated by semicolon ( ; ). Replies always start with asterisk ( * ) and end with semicolon ( ; ). There is no escaping at the moment

==== Commands (received and recognized by Chromecast 4 Lox) ====

==== GET_STATUS ====

Checks the Chromecast status. Returns free text returned from builtin Chromecast controlling utility prefixed by "STATUS:\n" and ended by ";"

__Sample response:__

<HTML><blockquote>
<code>
*STATUS:
Connecting to 192.168.1.51:8009...
Connected
[Default Media Receiver] Default Media Receiver
Volume: 0.41
;
</code>
</blockquote></HTML>
\\


==== GET_VOLUME ====

Queries Chromecast volume, which is returned as integer value 0-100, prefixed by "*GET_VOLUME_ACK " (including the space) and ended by ";"

__Possible responses are:__

<HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML>**''%%*GET_VOLUME_ACK%%'' **//number//;   (if succeeded)<HTML></li></HTML>
<HTML><li></HTML>**''%%*GET_VOLUME_NACK;%%''**             (if failed, for instance Chromecast was not reachable, in case of network issues, etc. For details check Log)<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>

__Sample response:__

<HTML><blockquote>
<code>
*GET_VOLUME 41;
</code>
</blockquote></HTML>
==== SET_VOLUME ====

Sets the new volume level. Command format "**''%%SET_VOLUME %%''**//number//" where //number //is the volume level, integer, 0-100.

Possible responses are:

<HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML>**''%%*SET_VOLUME_ACK%%''** //number//**''%%;%%''**   (if succeeded)<HTML></li></HTML>
<HTML><li></HTML>**''%%*SET_VOLUME_NACK;%%''**              (if failed, for instance Chromecast was not reachable, in case of network issues, etc. For details check Log)<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>

==== ADJUST_VOLUME ====

Adjusts the new volume level by defined difference (positive or negative for volume increase or decrease). Command format "**''%%ADJUST_VOLUME %%''**//delta//" where //delta //is the volume difference, integer, -100..100, to be added to the current volume level. The purpose of this function is accommodate volume up and volume down operations.

Possible responses are:

<HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML>**''%%*ADJUST_VOLUME_ACK%%'' **//number//**''%%;%%''**   (if succeeded; //number// represents the resulting (new) absolute volume level)<HTML></li></HTML>
<HTML><li></HTML>**''%%*ADJUST_VOLUME_NACK;%%''**              (if failed, for instance Chromecast was not reachable, in case of network issues, etc. For details check Log)\\
<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>

\\


__Sample command:__

<HTML><blockquote>
<code>
ADJUST_VOLUME -10;
</code>
</blockquote></HTML>
\\


__Sample response (from a Chromecast having a volume level 65 before the command was processed):__

<HTML><blockquote>
<code>
*ADJUST_VOLUME_ACK 55;
</code>
</blockquote></HTML>
==== PLAY <url> ====

Plays (casts) remote stream (defined by URL) on Chromecast. Supported formats rely completely on Chromecast, LoxBerry plugin passes just the URL. Command format "**''%%PLAY %%''**//url//" where //url //is the address of the stream. From the Chromecast Help, Chromecast Audio supports: HE-AAC, LC-AAC, MP3, Vorbis, WAV (LPCM), Opus, FLAC with support for high-resolution streams (24-bit/96KHz).

Possible responses are:

<HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML>**''%%*PLAY_ACK%%'' **//url//**''%%;%%''**   (if succeeded)<HTML></li></HTML>
<HTML><li></HTML>**''%%*PLAY_NACK;%%''**      (if failed, for instance Chromecast was not reachable, in case of network issues, etc. For details check Log)<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>

\\


__Sample command:__

<HTML><blockquote>
<code>
PLAY http://amp.cesnet.cz:8000/cro1-256.ogg;
</code>
</blockquote></HTML>
\\


__Sample response:__

<HTML><blockquote>
<code>
*PLAY_ACK http://amp.cesnet.cz:8000/cro1-256.ogg;
</code>
</blockquote></HTML>
==== PAUSE ====

Pauses Chromecast playback. 

__Possible responses are:__

<HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML>**''%%*PAUSE_ACK%%''**''%%;%%''****     (if succeeded)<HTML></li></HTML>
<HTML><li></HTML>**''%%*PAUSE_NACK; %%''** (if failed, for instance Chromecast was not reachable, in case of network issues, etc. For details check Log)<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>

==== STOP ====

Stops Chromecast playback. 

__Possible responses are:__

<HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML>**''%%*STOP_ACK%%''**''%%;%%''****     (if succeeded)<HTML></li></HTML>
<HTML><li></HTML>**''%%*STOP_NACK; %%''** (if failed, for instance Chromecast was not reachable, in case of network issues, etc. For details check Log)<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>

==== QUIT ====

Closes current app on Chromecast

__Possible responses are:__

<HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML>**''%%*QUIT_ACK%%''**''%%;%%''****     (if succeeded)<HTML></li></HTML>
<HTML><li></HTML>**''%%*QUIT_NACK; %%''** (if failed, for instance Chromecast was not reachable, in case of network issues, etc. For details check Log)<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>

\\


==== Messages sent to Loxone Miniserver (besides replies to commands described above) ====

==== Periodic volume notification ====

Periodic check of volume (if configured) sends "**''%%*VOLUME %%''**//number//**''%%;%%''**" messages to Loxone upon volume change, where //number //is the new volume level, integer, 0-100.

__Sample message sent to Loxone Miniserver:__

<HTML><blockquote>
<code>
*VOLUME 5;
</code>
</blockquote></HTML>
==== Connection status ====

Chromecast connection status is reported (if changes) after each communication with the device. Offline message is repeated after each failed attempt. Periodic repeating of the message can be configured on top of this. It is important to understand the status reporting period is dependent on any action on Chromecast. Without it will not report anything, ie. it is recommended to have Periodic volume notification enabled (and the Period of volume notifications should be less or equal to Connection status reporting period).

__Messages sent to Loxone Miniserver:__

<HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML><HTML><ul></HTML>
<HTML><li></HTML>**''%%*STATUS_ONLINE;%%''**<HTML></li></HTML>
<HTML><li></HTML>**''%%*STATUS_OFFLINE;%%''**<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>
<HTML></li></HTML><HTML></ul></HTML>

**\\
**

__Sample message sent to Loxone Miniserver:__

<HTML><blockquote>
<code>
*STATUS_ONLINE;
</code>
</blockquote></HTML>
=====   =====

===== Road map =====

To be considered:

  * <del>Active monitoring for volume changes</del> **DONE** (polling-based)
  * <del>Volume up/down</del> **DONE.**
  * Support M3U/PLS files as a casting source (medium priority)
  * Google Music All Access integration (no promises, no timelines, just a wish)
  * Active monitoring for volume changes (event-based) (very low priority)
  * **Support multiple Chromecast devices (high priority)**
  * **New Chromecast features (next, prev, seeking, song title, ...)**
  * **TTS**

=====   =====

===== Troubleshooting, tips =====

  * If you don't want to use "slightly less secure" WiFi on the same network as LoxBerry (Chromecast doesn't support WPA Enterprise/802.1x, only WPA2-PSK), consider Chromecast Ethernet Adapter. Even cheap 3rd party product from ebay/Aliexpress has proven to work great. You'll also get a nice bonus on top of the security - absolute connection stability
  * In case of any issue, check the Log
  * If the UDP server crashes, you'll need to restart the LoxBerry to get it up again\\


\\


===== Known issues, limitations =====

  * Some ShoutCast/IceCast streams are not supported by Chromecast (nothing I can do about it, unless a conversion proxy is made, which is not in scope of this small plugin)
  * <del>Plugin won't start if networking is not yet ready (ie. DHCP server not yet up after a power failure for instance) - workaround - restart LoxBerry</del>

\\


===== Questions, bug reports =====

__[[https://www.vodnici.net/community/loxone-a-arduino/chromecast/|Vodnici.net, czech Loxone forum]]__

__[[https://www.loxforum.com/forum/projektforen/loxberry/plugins/174244-chromecast-control-early-access-english|Loxforum.com]]__

E-mail: ales.berka.dev //at// gmail 

\\


\\