KNX Driver for CasaTunes

The KNX driver for CasaTunes allows control and monitoring of a CasaTunes multi room audio system using KNX. The KNX driver for CasaTunes works with all CasaTunes systems (including both software and hardware matrix systems) and 3rd party audio distribution systems compatible with CasaTunes.

Overview

The CasaTunes multi room audio system is implemented as a virtual device. The CasaTunes driver sends, listens and responds to Group Address Read/Write requests.

INSTALLATION NOTICE: It is recommended you install all your other hardware before installing the keypads.
SAFETY NOTICES

CasaTunes hardware is designed for professional installation only. Follow all NEC (National Electrical Code)/national wiring rules, as well as local codes. The Cat5 cables connecting between the USB6 Keypad Hub and the Keypads should not be routed outside the home (to prevent risk of lightning damage and shock) and are not meant to be connected to any other equipment, such as Ethernet switches.

The Keypads and the USB6 Keypad Hub are low-voltage devices. If you mount them in an electrical box, for safety’s sake do not bring any high voltage wiring into the same box.

Please leave the keypads and the USB6 Keypad Hub in their protective bags until you are ready to install them in the electrical box. When handling these devices, try to keep yourself grounded as much as possible to minimize the possibility of damage due to electrostatic discharge.

Please note there is a power inlet covered by a vinyl sheet, just below the USB connector on the USB6 Keypad Hub. It is not used in our current products. If it is used in the future, we will be supplying a DC power supply. The following safety notices are required by UL regarding this connector and any future CasaTunes supplied power supply.

The DC inlet on the USB6 Keypad Hub (just below the USB connector on the front of the wall plate) must only be used with an optional CasaTunes 5VDC power supply with positive center conductor.

Keypads are not designed for outdoor use.

Prerequisites

The KNX driver for CasaTunes uses the Falcon SDK (v5.7.322 for dot net framework 4.62) to interface with your KNX system (and runs as a daemon process on the CasaTunes music server)

Group Address Organization

To support the large number of rooms that CasaTunes supports, CasaTunes implements a Group Addressing scheme that uses the Main and Middle Groups of a 3-level style Group Addressing scheme, to uniquely identify each room (or zone).

Use the CasaSetup utility to assign a CasaTunes room to a KNX Group Address. CasaTunes supports up to 64 zones or rooms. You can also assign AirPlay rooms and Room Groups.

For more control over the Group Addresses assigned for CasaTunes zones, you can specify a starting offset for the Main Group value. For example, if you configured a starting offset of 5 for the Main Group, then the new Group Address for KNX Zone ID 1 (Office below) would be 5/1/X

Rather than assume you want to control every zone via KNX (which could result in a more complex setup and potentially unnecessary KNX bus activity), you must add each zone you wish to control. If you want to configure all your zones, then CasaSetup make this easy as well. Selecting the Add KNX Zone button in CasaSetup automatically assigns the next CasaTunes zone.

When the keypad is off, if the keypad does not display the time of day, then the keypad is not setup correctly. Check the keypad is plugged into the USB6 Keypad Hub, and verify the USB6 Keypad Hub is connected to your music server. Next, unplug the keypad and plug it back in to the Hub, and if that does not work, try unplugging and plugging back in the USB6 Keypad Hub. If you still do not see the time of day, please contact CasaTunes Support.

CasaTunes Functions

The Subgroup of the 3-level style Group Addressing scheme is used to select a CasaTunes Function.

The following CasaTunes Functions are available:

Function x/x/
1

Set Power

R/W:
DPT Type:
Read/Write
1 Bit Switch (DPT 1.001)

Select to power a room or room group on/off. Value = 1 to power on, 0 to power off.

Function x/x/
2

Toggle Power

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to toggle power for a room or room group. Value is ignored. Can be 0 or 1.

Function x/x/
3

Set Volume

R/W:
DPT Type:
Read/Write
8-Bit Unsigned (DPT 5.010)

Select to set the volume for a room or room group. Value is 0 to 100.

Function x/x/
4

Increase Volume

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to increase volume for a room or room group. Value is ignored. Can be 0 or 1.

Function x/x/
5

Decrease Volume

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to decrease the volume in a room or room group. Value is ignored.  Can be 0 or 1.

Function x/x/
6

Set Mute

R/W:
DPT Type:
Read/Write
1 Bit Switch (DPT 1.001)

Select to mute a room or room group on/off. Value = 1 will mute room, 0 = unmute.

Function x/x/
7

Toggle Mute

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to toggle mute for a room or room group. Value is ignored. Can be 0 or 1.

Function x/x/
8

Set Source

R/W:
DPT Type:
Read/Write
8-Bit Unsigned (DPT 5.010)

Select a specific source for a room. Value can be 0 .. Maximum Sources - 1.

Function x/x/
9

Select Next Source

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select this option to select the next available source for a room or room group. If this is the last source for a room, then Select Next Source will move to the first source. Value is ignored. Can be 0 or 1.

Function x/x/
10

Select Previous Source

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select this option to select the previous available source for a room or room group. If this is the first source for a room, then Select Next Source will move to the last source for a room. Value is ignored. Can be 0 or 1.

Function x/x/
11

Set Balance

R/W:
DPT Type:
Read/Write
8-Bit Signed (DPT 6.010)

Select to set the Balance for a room. Support for Balance may not be available on all matrix systems (and is not available on AirPlay rooms or room groups). The value is usually -X to X, where X is specific to the hardware. You can determine the value of X by viewing the available Balance Settings in the Apps.  For example, on a Russound CAV 6.6 matrix,  value can be -10 to 10, where -10 is Left Speaker only and 10 is Right Speaker only.

Function x/x/
12

Move Balance Left

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to move the sound more to the Left Speaker. Value is ignored. Can be 0 or 1.

Function x/x/
13

Move Balance Right

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to move the sound more to the Right Speaker. Value is ignored. Can be 0 or 1.

Function x/x/
14

Set Bass Level

R/W:
DPT Type:
Read/Write
8-Bit Signed (DPT 6.010)

Select to set the Bass level for a room. Support for Bass may not be available on all matrix systems (and is not available on AirPlay rooms or room groups). The value is usually -X to X, where X is specific to the hardware. You can determine the value of X by viewing the available Bass Settings in the Apps.  For example, on a Russound CAV 6.6 matrix, the value can be set between -10 to 10.

Function x/x/
15

Increase Bass Level

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to increase the Bass level for a room. Value is ignored. Can be 0 or 1.

Function x/x/
16

Decrease Bass Level

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to decrease the Bass level for a room. Value is ignored. Can be 0 or 1.

Function x/x/
17

Set Treble Level

R/W:
DPT Type:
Read/Write
8-Bit Signed (DPT 6.010)

Select to set the Treble level for a room. Support for Bass may not be available on all matrix systems (and is not available on AirPlay rooms or room groups). The value is usually -X to X, where X is specific to the hardware. You can determine the value of X by viewing the available Treble Settings in the Apps.  For example, on a Russound CAV 6.6 matrix, the value can be set between -10 to 10.

Function x/x/
18

Increase Treble Level

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to increase the Treble level for a room. Value is ignored. Can be 0 or 1.

Function x/x/
19

Decrease Treble Level

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to decrease the Treble level for a room. Value is ignored. Can be 0 or 1.

Function x/x/
20

Set Loudness

R/W:
DPT Type:
Read/Write
1 Bit Switch (DPT 1.001)

Select to turn Loudness Compensation on/off for a room. Support for Loudness Compensation may not be available on all matrix systems (and is not available on AirPlay rooms or room groups). Value can be 0 or 1. To enable Loudness Compensation the value = 1, to disable the value = 0.

Function x/x/
21

Toggle Loudness

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to toggle Loudness Compensation on/off for a room. Loudness Compensation is not supported on all matrices.

Function x/x/
22

Play/Pause Music

R/W:
DPT Type:
Read/Write
1 Bit Switch (DPT 1.001)

Select to play or pause music. Set value to 1 to play music. Set value to 0 to pause music.

Function x/x/
23

Toggle Play/Pause Music

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Toggles between playing and pausing the music in the current room or room group. Value is ignored. Can be 0 or 1.

Function x/x/
24

Stop Music

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to Stop music playback. It is recommended to Pause music instead of Stop music. Value is ignored. Can be 0 or 1.

Function x/x/
25

Select Previous Song

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select this option to restart the current song or to move to the previous song. If you are more than 10 seconds into playing the current song, this will move playback to the beginning of the song. If you are less than 10 seconds into the song, then this option moves playback to the previous song. Value is ignored. Can be 0 or 1.

Function x/x/
26

Select Next Song

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select to move to the next song. Value is ignored. Can be 0 or 1.

Function x/x/
27

Play Playlist

R/W:
DPT Type:
Write Only
8-Bit Unsigned (DPT 5.010)

Select to play a specific playlist in this room or room group. Value can be 0 to maximum number of playlists - 1. You can view the playlists and their index in CasaSetup.

Function x/x/
28

Select Previous Playlist

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select this to play the next playlist in the list (in CasaSetup). If you are at the end of the available playlists, the first playlist is played. Value is ignored. Can be 0 or 1.

Function x/x/
29

Select Next Playlist

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Select this to play the previous playlist in the list (in CasaSetup). If you are at the first of the available playlists, then the last available playlist is played. Value is ignored. Can be 0 or 1.

Function x/x/
30

Play Chime

R/W:
DPT Type:
Write Only
8-Bit Unsigned (DPT 5.010)

Select to play a specific chime from the list of available Chimes in CasaSetup. Use this to play specific sound files. Value can be 0 to maximum number of chimes - 1.

Function x/x/
31

Set Metadata Line 1

R/W:
DPT Type:
Read/Write
14 8859_1 Characters (DPT 16.001)

Select this option to read/write Line 1 of CasaTunes metadata. Typically this is the name of the song that is playing.

Function x/x/
32

Set Metadata Line 2

R/W:
DPT Type:
Read/Write
14 8859_1 Characters (DPT 16.001)

Select this option to read/write Line 2 of CasaTunes metadata. Typically this is the name of the artist for the song that is playing.

Function x/x/
33

Set Metadata Line 3

R/W:
DPT Type:
Read/Write
14 8859_1 Characters (DPT 16.001)

Select this option to read/write Line 3 of CasaTunes metadata. Typically this is the album name of the song that is playing, playlist name, or station name.

Function x/x/
34

Set Power For All Zones

R/W:
DPT Type:
Read/Write
1 Bit Switch (DPT 1.001)

Select to power all rooms on or off. Value = 1 to power all rooms on, 0 to power all rooms off.

Function x/x/
35

Toggle Power For All Zones

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

If one or more rooms are powered on, it will power all rooms off. If all rooms are powered off, then it powers all rooms on. Value is ignored. Can be 0 or 1.

Function x/x/
40

Select Scene 1

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Executes all the commands configured for Scene 1 in CasaSetup. Can include CasaTunes and other commands. Value is ignored. Can be 0 or 1.

Function x/x/
41

Select Scene 2

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Executes all the commands configured for Scene 2 in CasaSetup. Can include CasaTunes and other commands. Value is ignored. Can be 0 or 1.

Function x/x/
42

Select Scene 3

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Executes all the commands configured for Scene 3 in CasaSetup. Can include CasaTunes and other commands. Value is ignored. Can be 0 or 1.

Function x/x/
43

Select Scene 4

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Executes all the commands configured for Scene 4in CasaSetup. Can include CasaTunes and other commands. Value is ignored. Can be 0 or 1.

Function x/x/
44

Select Scene 5

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Executes all the commands configured for Scene 5 in CasaSetup. Can include CasaTunes and other commands. Value is ignored. Can be 0 or 1.

Function x/x/
45

Select Scene 6

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Executes all the commands configured for Scene 6 in CasaSetup. Can include CasaTunes and other commands. Value is ignored. Can be 0 or 1.

Function x/x/
46

Select Scene 7

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Executes all the commands configured for Scene 7 in CasaSetup. Can include CasaTunes and other commands. Value is ignored. Can be 0 or 1.

Function x/x/
47

Select Scene 8

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Executes all the commands configured for Scene 8 in CasaSetup. Can include CasaTunes and other commands. Value is ignored. Can be 0 or 1.

Function x/x/
48

Select Scene 9

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Executes all the commands configured for Scene 9 in CasaSetup. Can include CasaTunes and other commands. Value is ignored. Can be 0 or 1.

Function x/x/
49

Select Scene 10

R/W:
DPT Type:
Write Only
1 Bit Switch (DPT 1.001)

Executes all the commands configured for Scene 10 in CasaSetup. Can include CasaTunes and other commands. Value is ignored. Can be 0 or 1.

Using CasaSetup

To configure the KNX Driver for CasaTunes you use the CasaSetup administration utility. To start CasaSetup for KNX enter the following in your browser:

PC: http://casaserver/casasetup/knx.aspx
MAC: http://casaserver.local/casasetup/knx.aspx

You should see a screen similar to:

Step 1: Enable the KNX Driver for CasaTunes. After a few seconds, you will see a screen similar to:

Step 2: Next, add the CasaTunes rooms or room groups you want to control from KNX. Select the Zones option from the list on the left hand side, and select Add KNX Zone for each CasaTunes room you want to add. Click on the X to delete a KNX zone. You can specify an offset to use for the Main Group in the Group Address, for example in the screen shot below, we selected 5/X/X.

CasaTunes uses the Main and Middle Groups of a 3-tier Group Address to specify the KNX Zone ID, and the Subgroup to specify the CasaTunes function.

A KNX Zone ID is mapped to a Group Address as follows:

KNX Zone ID = (Main Group value * 8) + Middle Group value

So, for example, KNX Zone ID 20 would be mapped to the Group Address 2/4/x

Or, KNX Zone ID = (2 * 8) + 4 = 20

Step 3: If you want to select playlists from KNX, then configure your playlists. If you are planning to select specific playlists, for example, setting up a button on a KNX panel to select a specific playlist, or adding a command to play a specific playlist as part of a scene, you should select "Select Custom Playlists" from the Select Playlists Type drop down. If you plan to simply have one or two buttons to scroll through your playlists (Select Next or Previous Playlist), you should select "All CasaTunes Playlists" from the Select Playlists Type drop down.

If you select custom playlists, then add all the playlists you want to include in your list, by clicking on the Add KNX Playlist button. To delete a playlist from the list, click on the X button.

The KNX Value specifies the value to use in the Play Playlist Function.

Step 4: If you want to play specific chimes from KNX, then configure your Chimes. Add all the chimes you want to include in your list, by clicking on the Add KNX Chime button. To delete a chime from the list, click on the X button.

The KNX Value specifies the value to use in the Play Chime Function.

Step 5: Select the Feedback menu item to provide fine grain control over enabling or disabling feedback for a CasaTunes function. You can select which functions send out a telegram when the value changes.

For example, if you check Enable Power Feedback, then anytime the power changes for a room, even if the power for the room was changed using an external control system, like the CasaTunes App, the KNX driver will write to the Group Address for the room and power function with the updated state value. This is important if your KNX keypad that displays state information (for example, using LEDs). Enabling feedback ensures the LED is properly updated to reflect the power state of a room. On the other hand if your KNX Keypad or device does not display state information then you can disable feedback, and minimize KNX bus traffic.

Step 6: The KNX Driver for CasaTunes includes support for up to 10 scenes. A scene is simply a sequence of commands (Group Addresses + Values) that are executed in sequence. They can be used to configure multiple rooms or multiple functions and you can assign these to a single button. You can even add functionality for non-CasaTunes devices.

Select the scene you want to create or edit from the Select Scene drop down.

Next, enter the Group Address, select the DPT type from the drop down list, and enter the Value to write to the Group Address. To add the command, click on the + button. Commands are always appended to a scene.

To delete a command from a scene, select the scene, then click on the X to remove the command from the scene.

In the example below, we have configured a scene that powers on a room, sets the volume in the room to 15, changes the source to the first source, and then plays the playlist with a KNX Value of 2.

Next Steps

Now that you have configured the KNX Driver for CasaTunes, the next step is to use the ETS5 tool (or equivalent), to configure your Group Addresses for the CasaTunes functions you want to use, and for each CasaTunes room or room group you want to control, and then assign these Group Addresses to the KNX panels and devices you are planning to use.

Using ETS 5, you can define the CasaTunes Functions to use for one room, then copy and paste these into another room, greatly simplifying and speeding up the configuration process.

For more information on how to use ETS5 and configure your KNX network, please refer to the KNX site.