Lutron Athena/Vive (LEAP API) - Version 2.2.0.BETA2#

Module Summary

Integrates with Lutron Athena, Vive, using Lutron Extensible Application Protocol (LEAP).

Note: Due to the security requirements of LEAP, the controller must be associated with the Lutron Ethernet bridge before use.
Please refer to the Associate action documentation below.

Module Status

Note: Please be aware that this is a beta version of this IO Module which has not yet been fully tested. We recommend testing before use.

If you encounter any issues with this module, or have any feedback regarding its operation, please contact our support team.

Module Scope

Release Notes

Version 2.2 (Beta 2)

Clears local cache on Lutron Ethernet bridge project change
Improved logging

Support for buttons

Added triggers:

Button: New
Button: Updated
Button: Status

Added Actions:

Button: Set state

Version 2.1

Support for Vive hubs
Updated triggers:
- Area: Status
  - New property and return variableOccupied.
- Zone: Status
  - Switched Level renamed to Non-dimmed level to support reporting CCO and Receptacle control types.
  - Added Vibrancy and Spectrum variables
New actions:
- Zone: Goto level (CCO)
- Zone: Goto level (Receptacle)
- Zone: Goto level (Spectrum Tuning - HSV)
- Zone: Goto level (Spectrum Tuning - CCT)
- Zone: Goto level (Spectrum Tuning - xy)
- Zone: Goto level (White Tuning)
Added support for Unicode
Improved support for large LEAP responses

Version 2.0

Initial release.

Minor point releases (eg. 1.1.x) will be for small fixes and may not be listed here.

Operation

Instance Properties

Checking the Auto reconnect checkbox will instruct the module to automatically reconnect to the Ethernet bridge in the event of an unexpected disconnection.

Checking the Extended Logging checkbox will provide more detailed log messages.\

This is intended for diagnostics and problem solving and should ideally be disabled during normal operation.

Ethernet bridge serial is used by the trigger Discovered.

Status Variables

The IO Modules tab of the web interface provides status variables to shows information about the module and monitor its state.

Connection status	Current bridge connection status. 'Access Denied' 'Associating' 'Connected' 'Connecting' 'Disconnected'
Project name	Name of the currently loaded project on the ethernet bridge
Project type	Type project currently loaded project on the ethernet bridge
Project modified	Timestamp of the last modification to the currently loaded project on the ethernet bridge
Bridge IP address	IP Address of the currently connected/last connected LEAP bridge
Last socket error	Full details on the last communication error, if any

Triggers

Access denied

Fires when the Controller is denied access to the LEAP Ethernet bridge.
This can occur if the Controller hasn't yet been associated with the current LEAP Ethernet bridge.

Connected

Fires when the Controller connects to the LEAP Ethernet bridge.

Disconnected

Fires when the Controller disconnects from the LEAP Ethernet bridge.

Discovered

Fires when the Controller discovers a LEAP Ethernet bridge.

Matching instance properties:

Ethernet bridge serial Matching bridge serial number, or any if empty.

Trigger variables:

Name (string).
IP Address (IP Address).
Serial Number (string).

Area: Updated root

Fires when the root area is updated.

Trigger variables:

Area number (integer).
Name (string).

Area: New

Fires when an area is discovered.

Matching properties:

Number Matching area number, or 'any'.
Name Matching area name, or any if empty.

Trigger variables:

Area number (integer).
Name (string).
Parent or -1 if no parent (integer).

Area: Updated

Fires when an area is updated.

Matching properties:

Number Matching area number, or 'any'.
Name Matching area name, or any if empty.

Trigger variables:

Area number (integer).
Name (string).
Parent or -1 if no parent (integer).

Area: Status

Fires when an area changes status.

Matching properties:

Number: Matching area number, or 'any'.
Name: Matching area name, or any if empty.

Athena only

Scene: Matching scene number, or 'any'.

Scene name: Matching scene, or 'any'.

Occupied: Matching occupancy state name, or 'any'.

Vive only

Power is: Power matching condition operator.

Power: Matching area power, or 'any'.

Trigger variables:

Area number (integer).
Name (string).

Athena only

Current scene number or -1 if no scene (integer).

Current scene name (string).

Current occupancy state (boolean).

Vive only

Current occupancy state (boolean).

Total power, in Watts, used by all the devices in the area (integer).

Button: New (Athena only)

Fires when a button is discovered.

Matching properties:

Number Matching button number, or 'any'.
Name Matching button name, or any if empty.

Trigger variables:

Button number (integer).
Name (string).

Button: Updates (Athena only)

Fires when a button is updated.

Matching properties:

Number Matching button number, or 'any'.
Name Matching button name, or any if empty.

Trigger variables:

Button number (integer).
Name (string).
Engraving text (string).

Button: Status (Athena only)

Fires when a button changes status.

Matching properties:

Number Matching button number, or 'any'.
Name Matching button name, or any if empty.
Event Matching button event, or 'any'.

Trigger variables:

Button number (integer).
Name (string).
Event, one of Press, Release, MultiTap, or LongHold (string).

Event: New

Fires when an event is discovered.

Matching properties:

Number Matching event number, or 'any'.
Name Matching event name, or any if empty.

Trigger variables:

Event number (integer).
Name (string).
Parent or -1 if no parent (integer).

Event: Updated

Fires when an event is updated.

Matching properties:

Number Matching event number, or 'any'.
Name Matching event name, or any if empty.

Trigger variables:

Event number (integer).
Event Name (string).
Parent Timeclock number (integer).
Parent Timeclock name (string).
The Hour at which the event will occur, 0-23. If it is an astronomical event, this is calculated based on controller location (integer).
The Minute at which the event will occur, 0-59 (integer).
The schedule type of the event, either ByDate for events that occur on a specific date, or DayOfWeek for events that occur based on day of week (string).
The timeclock type of the event, either FixedTime for events occurring at a fixed time or Astromomic for astronomic events (string).
For DayOfWeek events, a table of days (Sunday through Saturday) with boolean values for each day. For ByDate events, a date in YYYY/MM/DD format when the events occur - comma separated for multiple dates (string).
Is the event is enabled (boolean).
Sunrise or Sunset for astronomic events - empty for non-astronomic events (string).
The offset from Sunrise/Sunset for an astronomic event - a floating point number of hours the event is offset from sunrise/sunset; or 0 for non-Astronomic events (number).

Event: Status

Fires when an event changes status.

Matching properties:

Number Matching event number, or 'any'.
Name Matching event name, or any if empty.
Enabled Enabled status, or 'any'.

Trigger variables:

Event number (integer).
Name (string).
Enabled status (boolean).

Scene: New (Athena only)

Fires when a scene is discovered.

Matching properties:

Number Matching scene number, or 'any'.
Name Matching area name, or any if empty.
Area Matching area number, or 'any'.
Preset Matching preset number, or 'any'.

Trigger variables:

Scene number (integer).
Name (string).
Area (integer).
Preset (integer).

Scene: Updated (Athena only)

Fires when a scene is updated.

Matching properties:

Number Matching scene number, or 'any'.
Name Matching area name, or any if empty.
Area Matching area number, or 'any'.
Preset Matching preset number, or 'any'.

Trigger variables:

Scene number (integer).
Name (string).
Area (integer).
Preset (integer).

Timeclock: New

Fires when an timeclock is discovered.

Matching properties:

Number Matching timeclock number, or 'any'.

Name Matching timeclock name, or any if empty.

Trigger variables:

Timeclock number (integer).
Name (string).

Timeclock: Updated

Fires when an timeclock is updated.

Matching properties:

Number Matching timeclock number, or 'any'.
Name Matching timeclock name, or any if empty.

Trigger variables:

Timeclock number (integer).
Name (string).

Timeclock: Status

Fires when an Timeclock changes status.

Matching properties:

Number Matching timeclock number, or 'any'.
Name Matching timeclock name, or any if empty.
Enabled Enabled status, or 'any'.

Trigger variables:

timeclock number (integer).
Name (string).
Enabled status (boolean).

Zone: New

Fires when an zone is discovered.

Matching properties:

Number Matching zone number, or 'any'.
Name Matching zone name, or any if empty.
Type Matching zone type, or 'any'.
Area Matching area number, or 'any'.

Trigger variables:

Zone number (integer).
Name (string).
Type (string).
Area or -1 if no area (integer).

Zone: Updated

Fires when an zone is updated.

Matching properties:

Number Matching zone number, or 'any'.
Name Matching zone name, or any if empty.
Type Matching zone type, or 'any'.
Area Matching area number, or 'any'.

Trigger variables:

Zone number (integer).
Name (string).
Type (string).
Area or -1 if no area (integer).

Zone: Status

Fires when an zone changes status.

Matching properties:

Number Matching zone number, or 'any'.
Name Matching zone name, or any if empty.
Type Matching zone type, or 'any'.
Area Matching area number, or 'any'.
Level is Level matching condition operator.
Level Matching level, or 'any'.
Non-dimmed level Matching non-dimmed level, or 'any'.

Trigger variables:

Zone number (integer).
Name (string).
Type (string).
Area or -1 if no area (integer).
Level (percent) or -1 if no level (integer).
Non-dimmed level ('On', 'Off', 'Open, or 'Closed') or '' if no Non-dimmed level (string).

Athena only

Vibrancy (percent) or -1 if no vibrancy (integer).

Hue (degrees) or -1 if no hue (number).

Saturation (percent) or -1 if no saturation (integer).

CCT (kelvin) or -1 if no CCT (number).

CIE x (0-1) or -1 if no vibrancy (number).

CIE y (0-1) or -1 if no vibrancy (number).

Conditions

Connected

Matches if the controller is currently connected to a bridge.

Area: Scene (Athena only)

Matches if the active scene (stored in variable Scene (Variable #)) number in the area (stored in variable Number (Variable #)) matches. If both Number (Variable #) and Scene (Variable #) are 'any', then a Lua table of active scenes is returned.

Condition properties:

Number (Variable #) Variable number containing matching area number, or 'any'.
Scene (Variable #) Variable number containing matching scene number, or 'any'.

Condition variables:

Area number (integer).
Scene number or -1 if no scene (integer).
OR

Table of active scenes, indexed by area number (string).

--- Example table usage
local areaScenes = load("return " .. get_trigger_variable(1).string)()
for area, scene in pairs(areaScenes) do
    log(table.concat({'Area', area, 'scene is', tostring(scene)}, ' '))
end

Event: Enabled

Matches if the event (stored in variable Number (Variable #)) matches the Enabled property. If Number (Variable #) is 'any', then a Lua table of matching event state is returned.

Condition properties:

Number (Variable #) Variable number containing matching event number, or 'any'.
Enabled Matching enabled state, or 'any'.

Condition variables:

Event number (integer).
Enabled status (boolean).
OR

Table of event states, indexed by event number (string).

--- Example table usage
local eventStates = load("return " .. get_trigger_variable(1).string)()
for event, state in pairs(eventStates) do
    log(table.concat({'Event', event, 'is', tostring(state)}, ' '))
end

Event: Scheduled

Matches if the event (stored in variable Number (Variable #)) schedule matches the Year (stored in variable Year (Variable #)), Month (stored in variable Month (Variable #)), and Day (stored in variable Day (Variable #)) properties. If Number (Variable #) is 'any', then a Lua table of matching events is returned. If Year (Variable #), or Month (Variable #), or Day (Variable #) are 'now' then the current Year, and/or Month, and/or Day; are utilised.

Condition properties:

Number(Variable #) Variable number containing matching event number, or 'any'.
Year (Variable #) Variable number containing matching schedule year, or 'now'.
Month (Variable #) Variable number containing matching schedule year, or 'now'.
Day (Variable #) Variable number containing matching schedule year, or 'now'.

Condition variables:

Event number (integer).
Scheduled hour (integer).
Scheduled minute (integer).
OR

Table of event times, indexed by event number (string).

--- Example table usage
local eventTimes = load("return " .. get_trigger_variable(1).string)()
for event, time in pairs(eventTimes) do
    log(table.concat({'Event', event, 'scheduled at', time.hour .. ':' .. time.minute}, ' '))
end

Timeclock: Enabled

Matches if the timeclock (stored in variable Number (Variable #)) matches the Enabled property. If Number (Variable #) is 'any', then a Lua table of matching timeclock state is returned.

Condition properties:

Number (Variable #) Variable number containing matching timeclock number, or 'any'.
Enabled Matching enabled state, or 'any'.

Condition variables:

Timeclock number (integer).
Enabled status (boolean).
OR

Table of timeclock states, indexed by event number (string).

--- Example table usage
local timeclockStates = load("return " .. get_trigger_variable(1).string)()
for timeclock, state in pairs(timeclockStates) do
    log(table.concat({'Timeclock', timeclock, 'is', tostring(state)}, ' '))
end

Zone: Level

Matches if the zone (stored in variable Number (Variable #)) matches the zone's level using the Level is and Level properties. If both (stored in variable Number (Variable #)) is 'any', then a Lua table of current matching levels is returned.

Condition properties:

Number (Variable #) Variable number containing matching zone number, or 'any'.
Level is Level matching condition operator.
Level Matching level, or 'any'.

Condition variables:

Zone number (integer).
Level (percent) or -1 if no level (integer).
OR

Table of zone levels, indexed by zone number (string).

--- Example table usage
local zoneLevels = load("return " .. get_trigger_variable(1).string)()
for zone, level in pairs(zoneLevels) do
    log(table.concat({'Zone', zone, 'is at', tostring(level)}, ' '))
end

Actions

Associate

This process needs to be performed at least once during the initial commissioning process.

Start an association process with ethernet bridge at IP Address.

Athena - After firing this action you will need to tap the button on the ethernet bridge.

Vive - The, time limited, one-time password generated Lutron Vive app should be entered in *Password*.

Please refer to the controllers logs for results of the association.

n.b. The association objects are stored on the controllers local SD card, they are not stored in the project file. If the SD card or ethernet bridge is replaced, the association will need to be re-undertaken

Connect

Start connection to ethernet bridge at IP Address.

Disconnect

Disconnect from any connected (or connecting) ethernet bridge.

Discover

Run bridge discovery on the network, each discovered bridges will be reported by the trigger Discovered ethernet bridge.

Note: The controller must have a default gateway set to a value other than 0.0.0.0.
If network is 'flat', and has no requirement for a default gateway/router, then the default gateway should be set to the controller's own IP.*

Area: Goto scene (Athena only)

Sets an Area to a Scene. The scene must exist in the area

Properties:

Area Area number.
Scene Scene number.

Button: Set state (Athena only)

Sets a Button pressed event state.

Properties:

Button Button number.
Event Press/release event.

Event: Set state

Sets an Event state to either enabled or disabled.

Properties:

Event Event number.
Enabled Enabled yes/no.

Zone: Goto level (Dimmed)

Set a zone with the type 'Dimmed' to Level over Fade seconds after waiting Delay seconds.

Properties:

Zone Zone number.
Level Level (percent).
Fade Fade time (seconds).
Delay Delay time (seconds).

Zone: Goto level (Switched)

Set a zone with the type 'Switched' to Level after waiting Delay seconds.

Properties:

Zone Zone number.
Level Level (On/Off).
Delay Delay time (seconds).

Zone: Goto level (CCO)

Set a zone with the type 'CCO' to Level after waiting Delay seconds.

Properties:

Zone Zone number.
Level Level (Open/Closed).
Delay Delay time (seconds).

Zone: Goto level (Receptacle)

Set a zone with the type 'Receptacle' to Level after waiting Delay seconds.

Properties:

Zone Zone number.
Level Level (On/Off).
Delay Delay time (seconds).

Zone: Goto level (Spectrum Tuning - HSV) (Athena only)

Set a zone with the type 'SpectrumTuning' to Level, with a spectrum of Hue and Saturation, over Fade seconds after waiting Delay seconds.

Properties:

Zone: Zone number.
Level: Level (percent).
Vibrancy: Ratio of white LED vs RGB LEDs (percent).
Hue: Spectrum hue (degrees).
Saturation: Spectrum saturation (percent).
Fade: Fade time (seconds).
Delay: Delay time (seconds).

Zone: Goto level (Spectrum Tuning - CCT) (Athena only)

Set a zone with the type 'SpectrumTuning' to Level, with a spectrum of CCT, over Fade seconds after waiting Delay seconds.

Properties:

Zone: Zone number.
Level: Level (percent).
Vibrancy: Ratio of white LED vs RGB LEDs (percent).
CCT: Colour temperature (1000 k - 25000 k).
Fade: Fade time (seconds).
Delay: Delay time (seconds).

Zone: Goto level (Spectrum Tuning - xy) (Athena only)

Set a zone with the type 'SpectrumTuning' to Level, with a spectrum of x/y, over Fade seconds after waiting Delay seconds.

Properties:

Zone: Zone number.
Level: Level (percent).
Vibrancy: Ratio of white LED vs RGB LEDs (percent).
x: CIE 1931 x colour point (0-1).
y: CIE 1931 y colour point (0-1).
Fade: Fade time (seconds).
Delay: Delay time (seconds).

Zone: Goto level (White Tuning) (Athena only)

Set a zone with the type 'WhiteTuning' to Level, with a spectrum of CCT, over Fade seconds after waiting Delay seconds.

Properties:

Zone: Zone number.
Level: Level (percent).
CCT: Colour temperature (1000 k - 25000 k).
Fade: Fade time (seconds).
Delay: Delay time (seconds).

Support

If you encounter any issues with this module, please contact our support team.

Licences

This module uses the following third party code/modules:

dkjson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.