Introduction

The purpose of this guide is to provide a step by step configuration to allow automatic light control within CinemaVision using the SmartThings by Samsung home automation system. This will allow light dimming during the CinemaVision sequence prior to and during the theater event.

Note: This guide makes the following assumptions.

• Kodi is installed and working properly
• CinemaVision is installed and working properly
• Your home is SmartThings equipped, has a control hub and various lighting switches and dimmers

Configuration Examples

Basic Light Control: Lights dim or turn off once during CinemaVision sequence and/or turn back on at the end of the CinemaVision sequence.

• You hit play. The trivia slide show plays to completion. The Sequence initiates trailer playback. Lights turn off or dim to 30% of full brightness. Movie plays to completion, lights turn back up to previous or predetermined level. 

Advanced Light Control: Lights dim in stages throughout the sequence, leading up to the Feature event in the sequence.

• You hit play. The Sequence changes the SmartThings mode from Home to Movie*, disabling the motion activated lights in the hallway and kitchen, and then dims the theater lights down to 65% of full brightness. The trivia slide show starts and it plays to completion. The Sequence initiates a video bumper of your choice (Let's go down to the looooobby...). As the video bumper ends, the Sequence dims the lights again from 65% to 35% of full brightness and shuts off all other lights in the house, and then starts the trailer portion of the Sequence. As the movie begins, the theater lights dim from 35% to 10% of full brightness. *Motion in the hallways is ignored. Motion in the kitchen turns on the Philips Hue under-cabinet multi-colored LEDs, sets them to red and sets the brightness at 25%.

Prerequisites

The list of required items is listed below, with detailed information on each prerequisite beneath the list. 

1. CinemaVision Addon
2. Kodi v14+ CinemaVision will drop support for 14 in the future, so our recommendation is to use version 15 as of the time of this document (01/26/2016)
3. SmartThings application on iDevice/Android and SmartApp(s) listed below

• SmartApp: Kodi/XBMC Callback Endpoint for Light Control 
  • Optional SmartApp: SwitchMania (For creating a Virtual Switch in SmartThings without using the IDE – though for the purposes of this tutorial, we’ll use the IDE)
  • Optional SmartApp for Advanced Control: Switch Changes Mode (Allows a virtual or physical switch to change Modes in SmartThings. This is located in SmartApps official SmartApps)

The Kodi/XBMC Callback Endpoint SmartApp is an OAuth application that allows direct control of lights, outlets and other devices or functions by creating a URL command link that you can easily access from within the Kodi/XBMC SmartApp's control interface in the SmartThings mobile app. The SmartApp runs in the SmartThings cloud and listens for HTTPS requests with the correct authorization token and SmartApp installation ID URL string. An example of what a command URL looks like is listed below.

https://graph.api.smartthings.com:443/api/token/{Auth-Token}/smartapps/installations/{SmartApp-Installation-ID}/play

The example above is the URL associated with the Playback setting within the SmartApp. When this URL is accessed, the SmartApp instance that the Installation ID references will set the lights to the level that is set in the Playback setting within the SmartApp. Changing the variable at the end changes the setting that is addressed when making HTTPS requests with the URL. You can set up to six discreet light levels for each SmartApp instance you install, meaning you can have six light or control events.

Variable options include:

• play
• pause
• resume
• stop
• custom1
• custom2

SwitchMania creates, controls, and uses Virtual Switches from a single application within the SmartThings SmartApp environment. There is no need to log into the SmartThings IDE to create a virtual switch. 

Switch Changes Mode allows a physical or virtual switch to change Modes in SmartThings. Using this can allow you to disable various automated functions (such as motion based lights in the theater room) so that they do not happen during the CinemaVision Sequence. Other lighting automation tasks within SmartThings are set to not activate while in Movie Mode in order to prevent interruptions.

• Example 1: In Home Mode, the hallway, kitchen and foyer lights are all motion activated by their respective motion sensors. When the dogs move around, the lights turn on, and then turn off when the motion stops. By switching to Movie Mode at the start of the CinemaVision Sequence, the motion function becomes disabled, and the lights no longer automatically turn on. 
• Example 2: In the example above, the alternative would be to have the motion sensor in the kitchen activate the under cabinet multi-colored lighting, and turn it red when in Movie Mode, but turn the main kitchen lights on when in Home Mode.

Basic Control Instructions

1. Install the Kodi/XBMC Callback Endpoint for Light Control SmartApp within the SmartThings IDE.

• a. Visit the GitHub repository, located here.    
  • i. The KodiPlaybackControls SmartApp is the Parent application, and needs to be installed within the SmartThings IDE as a new SmartApp. This SmartApp must be saved and published.
  • ii. KodiPlaybackControlsLightGroup SmartApp is the Child application. This SmartApp needs to be installed within the SmartThings IDE as a new SmartApp. Do NOT publish this app.     
• b. Open the SmartThings IDE in a new browser window or tab, and sign in with your SmartThings account.
• c. Click My SmartApps at the top.
• d. On the right side of the IDE, click the green +New SmartApp button
• e. In the New SmartApp window, click From Code at the top, and paste the code from KodiPlaybackControls.groovy into this window.
• f. Click Save at the top, and then click Publish and select For me from the dropdown.
• g. Repeat steps c through f using the KodiPlaybackControlsLightGroup.groovy, but do NOT Publish this SmartApp.
• h. For support and discussion of this SmartApp, you can visit the SmartThings Community page here. 

2.  On your iDevice or Android phone or tablet, open the SmartThings application.

• a. Under the application menu, choose Connect New Device
• b. Select SmartApps from the Marketplace
• c. Scroll down and select + My Apps
• d. Find the KODI Callback Endpoint SmartApp and select it
• e. Set a Label for this Instance
• f.  To make the app only run in a specific mode, you can set the Only run or the Never run functions to limit the function of the app. 
• g. Select New Light Control Group, and on the new page, create a new Label for this Group (example: Theater Room Lamps)
• h. Under Lights to Control, tap on the Which Switches section and select the switches that you want this light group to control. Once you have selected all of the switches you want in this group, click Done.
• i.  In the Level to set Lights to section, set your light levels for the various functions.
  •  i. Please note that the SmartThings system does not easily provide a “Dim down” or “Dim up” to level. Light levels will set instantly on most Z-Wave or Zigbee hardware.
  •  ii. For lights that do not dim, any number lower than 100 will equate to “Off” for the device. Setting the number to 101 will attempt to restore the lights to their last reported level when that SmartApp function URL is called.
• j.  If you have any custom functions within Kodi or CinemaVision that you would like implement for controlling this light group, you can set the level for the Custom Event 1 or 2
• k. Click Done.

3. In the SmartApp that you have installed and set, you can view the URL for each action event (playback, pause, resume, stop, custom) by tapping on the View URLs section at the bottom. To use these URLs within CinemaVision, you will need to copy them from within SmartThings and paste them into .cvaction files in the Actions folder within the CinemaVision directory structure. I find that copying and pasting them into an email to myself is the simplest way to get the URL. 

4. Open your favorite text editor and create a new text file.

• a. Paste the URL into this new text file.
• b. Save the file to your CinemaVision Actions folder with the file extension cvaction and a descriptive name explaining what it does. (Example: lights-dim-on-playback.cvaction)

5. Open Kodi and launch the CinemaVision addon from the Programs menu (The Settings -> Addons menu will work as well, if you do not have a Programs option available)

• a. When the CinemaVision Sequence Editor has opened, use the left or right arrow keys to move to the position you want to dim or turn off the lights, and select Add:Actions from the menu by using the up or down arrow keys and pressing enter on the selection.
• b. Arrow up to the Edit button on your newly created Action item and press enter
• c. Select the Action file path, and browse to your Actions folder.
• d. Find and select the action file you want to embed here. (Example: lights-dim-on-playback.cvaction)
• e. Press the Test button to confirm your URL works (the light group you have programmed into the SmartApp will change to the setting you have specified when you do this), and then hit the backspace key one time to return to the main sequence editor. 
• f. Select the Rename button for the Action item, and set a name (Example: Dim lights before movie)
• g, Repeat Step 5, sections a through f to set the Stop Action item at the end of the CinemaVision Sequence, being sure to select your Stop.cvaction

To set Pause and Resume functions within CinemaVision, go to the Add-ons menu under Settings in Kodi and locate the CinemaVision add-on. Click Configure, and browse to the Actions menu. Configure the file paths to the Pause.cvaction and Resume.cvaction for each respective menu item. You can also configure a specific action for when the Sequence is aborted.

Advanced Control Instructions

Coming soon.

Optional Steps and Features

The following section covers some advanced features, such as changing the Home Mode and setting up virtual switches.