iris_alertme_repeator_zwave.groovy

/**
 *  Iris v1 Z-Wave Repeater plug
    https://github.com/tmastersmart/hubitat-code/blob/main/iris_alertme_repeator_zwave.groovy

    v1.2 05/8/21  

 REP901 has updates to zwave
 REP800 has zwave problems. This is the version I have that drops off. I cant do anymore without a REP901
 it looks like REP800 was a recalled version and zwave cant be used.

  Forked from:

  URL: https://raw.githubusercontent.com/shackrat/Hubitat/master/Drivers/Iris-ZWave-Repeater.src
 *
 *  Advanced (Iris) Z-Wave Repeater Driver for Hubitat
 *  Copyright 2017-2020 Steve White
 *
 *  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 *  in compliance with the License. You may obtain a copy of the License at:
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed
 *  on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License
 *  for the specific language governing permissions and limitations under the License.
 *
 */
def getDriverVersion() {[platform: "Hubitat", major: 2, minor: 0, build: 0]}

metadata
{
	
	definition (name: "Iris AlertMe Repeator Z-Wave", namespace: "tmastersmart", author: "tmaster", importUrl: "https://github.com/tmastersmart/hubitat-code/raw/main/iris_alertme_repeator_zwave.groovy") {

		capability "Polling"
		capability "Refresh"
		capability "Sensor"
		capability "Configuration"

		command "testCommunication"
		command "interrogateDevice"

		attribute "status", "string"
		attribute "lastRefresh", "string"
		attribute "deviceMSR", "string"
		attribute "deviceVersion", "string"
		attribute "deviceZWaveLibType", "string"
		attribute "deviceZWaveVersion", "string"
		attribute "lastRefresh", "string"
		attribute "lastMsgRcvd", "string"

		fingerprint mfr: "0246", prod: "0001", model: "0001", cc: "85,59,5A,72,73,86,5E",  deviceJoinName: "Iris Z-Wave Repeater"
        fingerprint mfr: "0126", prod: "0002", model: "0001", inClusters: "0x72",  deviceJoinName: "Iris v1 Z-Wave Repeater plug"
	}
//fingerprint  mfr:"0126", prod:"0002", deviceId:"0001", inClusters:"0x72" 
//MANUFACTURER SPECIFIC V2: Manufacturer ID: 0126, Manufacturer Name: Alertme, Product Type ID: 0002, Product ID: 0001       MSR: 0126-0002-0001 
	preferences
	{
		section("Device Health")
		{
			//paragraph "SmartThings is unable to reliably check the health of these devices using device health check.  Instead, the device can be checked every 30 minutes to ensure that it's online and healthy."
			input "enablePing", "bool", title: "Enable device online check?", description: "Periodically check in with device to ensure it's online and healthy.", defaultValue: true, required: true, multiple: false
		}

		section("Device Logging")
		{
			//paragraph "By default, only device status is reported.  If you are experiencing an issue with the SmartPlug, you can enable additional output in the IDE."
			input "enableTrace", "bool", title: "Enable trace logging?", description: "Indicates high-level activities during the operation of the device.", defaultValue: false, required: true, multiple: false
			input "enableDebug", "bool", title: "Enable debug logging?", description: "Shows detailed responses to Z-Wave commands.", defaultValue: false, required: true, multiple: false
		}
	}
}


/*
	installed

	Doesn't do much other than call configure().
*/
def installed()
{
    configure()
}


/*
	updated

	Doesn't do much other than call configure().
*/
def updated()
{
    configure()
}


/*
	configure

	Configures the Z-Wave repeater associations and establishes periodic device check.
*/
def configure()
{
	unschedule()

	// Three failed pings and the device is considered offline
	state.failedPings = 0
	state.testRefreshCount = 0

	logTrace("Sending configuration commands to Iris Smart Plug...")

	// Associate Group 1 (Lifeline) with the Hub.
	sendCommand(zwave.associationV2.associationSet(groupingIdentifier:1, nodeId: zwaveHubNodeId))

	// Check every 30 minutes to see if the device is responding.
	if (enablePing)
	{
		logInfo("Periodic health check is enabled but bypassed in the code.")
		runEvery30Minutes(refreshDevice)
	}
	else logInfo("Periodic health check is disabled.")
}


/*
	parse

	Processes messages from the Z-Wave side of the Iris Smart Plug.
*/
def parse(String description)
{
	logDebug("Parsing ${description}")

	def result = []
	if (description.startsWith("Err"))
	{
		result = createEvent(descriptionText:description, isStateChange:true)
	}
	else
	{
		def cmd = zwave.parse(description)
		if (cmd)
		{
			result += zwaveEvent(cmd)
		}
	}
	return result
}




/*
	POWER LEVEL REPORT RESPONSE
*/
def zwaveEvent(hubitat.zwave.commands.powerlevelv1.PowerlevelReport cmd)
{
	def pwrLevel = (cmd.powerLevel > 0) ? "${cmd.powerLevel}dBm." : "NOMINAL"
	logDebug("POWER LEVEL REPORT V1: Transmit power for ${device.displayName} is ${pwrLevel}.")

	def dateTime = new Date()
	sendEvent(name: "powerLevel", value: pwrLevel, displayed: false)
	sendEvent(name: "lastMsgRcvd", value: dateTime.format("yyyy-MM-dd HH:mm:ss", location.timeZone) + ": POWER LEVEL REPORT V1", displayed: false)
	updateStatus()

	if (state.interrogationPhase == 1)
	{
		state.interrogationPhase = 2
		state.interrogationRetries = 0
	}
}


/*
	VERSION REPORT RESPONSE
*/
def zwaveEvent(hubitat.zwave.commands.versionv1.VersionReport cmd)
{
	def fwVersion = "${cmd.firmware0Version}.${cmd.firmware0SubVersion}"
	def zwVersion = "${cmd.zWaveProtocolVersion}.${cmd.zWaveProtocolSubVersion}"

	logDebug("VERSION REPORT V1: ${device.displayName} is running firmware version: ${fwVersion}, Z-Wave version: ${zwVersion}, Library type: ${cmd.zWaveLibraryType}")

	sendEvent(name: "deviceVersion", value: fwVersion, displayed: false)
	sendEvent(name: "deviceZWaveVersion", value: zwVersion, displayed: false)
	sendEvent(name: "deviceZWaveLibType", value: cmd.zWaveLibraryType, displayed: false)

	def dateTime = new Date()
	sendEvent(name: "lastMsgRcvd", value: dateTime.format("yyyy-MM-dd HH:mm:ss", location.timeZone) + ": VERSION REPORT V1", displayed: false)
	updateStatus()

	if (state.interrogationPhase == 2)
	{
		state.interrogationPhase = 3
		state.interrogationRetries = 0
	}
}


/*
	FIRMWARE REPORT RESPONSE

	Note: Not currently used
*/
def zwaveEvent(hubitat.zwave.commands.firmwareupdatemdv2.FirmwareMdReport cmd)
{
	// Credit to Z-Wave Tweaker!!
	def firmwareIdDisp = String.format("%04X",cmd.firmwareId)
	def checksumDisp = String.format("%04X",cmd.checksum)

	def dateTime = new Date()
	logDebug("FIRMWARE METADATA REPORT V1: ${device.displayName} is running firmware ID: ${firmwareIdDisp} with checksum: ${checksumDisp}")
	sendEvent(name: "lastMsgRcvd", value: dateTime.format("yyyy-MM-dd HH:mm:ss", location.timeZone) + ": FIRMWARE METADATA REPORT V1", displayed: false)
	updateStatus()

	if (state.interrogationPhase == 3)
	{
		state.interrogationPhase = 4
		state.interrogationRetries = 0
	}
}


/*
	MANUFACTURER SPECIFIC RESPONSE

	Note: Used for device up/down checks.
*/
def zwaveEvent(hubitat.zwave.commands.manufacturerspecificv2.ManufacturerSpecificReport cmd)
{
	// Credit to Z-Wave Tweaker!!
	def manufacturerIdDisp = String.format("%04X",cmd.manufacturerId)
	def productIdDisp = String.format("%04X",cmd.productId)
	def productTypeIdDisp = String.format("%04X",cmd.productTypeId)

	def msr = String.format("%04X-%04X-%04X", cmd.manufacturerId, cmd.productTypeId, cmd.productId)
	updateDataValue("MSR", msr)
	updateDataValue("manufacturer", cmd.manufacturerName)

	def dateTime = new Date()
	logDebug("Manufacturer ID: ${manufacturerIdDisp}, Manufacturer Name: ${cmd.manufacturerName}, Product Type ID: ${productTypeIdDisp}, Product ID: ${productIdDisp}")
	sendEvent(name: "lastMsgRcvd", value: dateTime.format("yyyy-MM-dd HH:mm:ss", location.timeZone) + ": MANUFACTURER", displayed: false)

	sendEvent(name: "deviceMSR", value: msr, displayed: false)
	updateStatus()


	if (state.manualRefresh == 1)
	{
		state.manualRefresh = 0
		unschedule(refresh)
	}
	if (state.interrogationPhase != 4) sendEvent(name: "lastTest", value: "Device is responding!", displayed: false)


	if (state.interrogationPhase == 4)
	{
		state.interrogationPhase = 5
		state.interrogationRetries = 0
	}
}


/*
	ASSOCIATION GROUP NAME RESPONSE

	Note: Not currently used
*/
def zwaveEvent(hubitat.zwave.commands.associationgrpinfov1.AssociationGroupNameReport cmd)
{
	logTrace "Received: ${cmd}"
	state.assocGrpName = cmd.name ? new String(cmd.name as byte[]) : ""

	def dateTime = new Date()
	logDebug("ASSOCIATION GROUP NAME REPORT V1: ${device.displayName} belongs to group ${state.assocGrpName}")
	sendEvent(name: "lastMsgRcvd", value: dateTime.format("yyyy-MM-dd HH:mm:ss", location.timeZone) + ": ASSOCIATION GROUP NAME REPORT V1", displayed: false)
	updateStatus()

	if (state.interrogationPhase == 5)
	{
		state.interrogationPhase = 6
		state.interrogationRetries = 0
	}
}


/*
	ASSOCIATION GROUP INFO RESPONSE

	Note: Not currently used
*/
def zwaveEvent(hubitat.zwave.commands.associationv2.AssociationReport cmd)
{
	def assocNodes
	def dateTime = new Date()
	logDebug("ASSOCIATION GROUP REPORT V2: ${device.displayName} in Group #${cmd.groupingIdentifier} with nodes: ${cmd.nodeId}")
	sendEvent(name: "lastMsgRcvd", value: dateTime.format("yyyy-MM-dd HH:mm:ss", location.timeZone) + ": ASSOCIATION GROUP REPORT V2", displayed: false)

	updateStatus()

	if (cmd.nodeId.any { it == zwaveHubNodeId })
	{
		assocNodes = "hub"
		sendEvent(name: "assocGroup", value: "${state.assocGrpName} (#${cmd.groupingIdentifier}) with ${assocNodes}.", displayed: false)
	}
	else
	{
		sendEvent(name: "assocGroup", value: "FAIL: Group 1 not found, configure device!", displayed: false)
	}

	if (state.interrogationPhase == 6)
	{
		state.interrogationPhase = 7
		state.interrogationRetries = 0
	}
}


/*
	POWER LEVEL TEST REPORT RESPONSE

	Status Codes:
	STATUS_OF_OPERATION_ZW_TEST_FAILED	= 0
	STATUS_OF_OPERATION_ZW_TEST_SUCCES	= 1
	STATUS_OF_OPERATION_ZW_TEST_INPROGRESS	= 2
*/
def zwaveEvent(hubitat.zwave.commands.powerlevelv1.PowerlevelTestNodeReport cmd)
{
	logDebug("statusOfOperation: ${cmd.statusOfOperation}")

	def testResults = ""
	switch (cmd.statusOfOperation)
	{
		case 0:
			testResults = "FAILED\n${cmd.testFrameCount} of 30 frames received."
			unschedule(getCommunicationTestResults)
			break;
		case 1:
			testResults = "SUCCESS\n${cmd.testFrameCount} of 30 frames received."
			unschedule(getCommunicationTestResults)
			break;
		case 2:
			testResults = "IN PROGRESS\n${cmd.testFrameCount} of 30 frames received."
			break;
	}
	if (state.testRefreshCount > 3)
	{
		testResults = "FAILED due to TIMEOUT."
		unschedule(getCommunicationTestResults)
	}
	sendEvent(name: "lastTest", value: testResults, displayed: false)

	def dateTime = new Date()
	logDebug(testResults)
	sendEvent(name: "lastMsgRcvd", value: dateTime.format("yyyy-MM-dd HH:mm:ss", location.timeZone) + ": POWER LEVEL NODE TEST REPORT V1", displayed: false)
	updateStatus()
}


/*
	updateStatus

	Sets the device state to online, but only if previously offline.
*/
def updateStatus()
{
	Map deviceState =
	[
		name: "status",
		isStateChange: (device.currentValue('status') != 'online' ? true : false),
		displayed: (device.currentValue('status') != 'online' ? true : false),
		value: 'online',
		descriptionText: "$device.displayName is online"
	]

	state.failedPings = 0
	logInfo("Device is online")
	sendEvent(deviceState)
}


/*
	testCommunication

	Executes a Z-Wave powerlevel test with 10 transmission frames.

	Note: Useful for testing Z-Wave signal reliability
*/
def testCommunication()
{
	runIn(10, getCommunicationTestResults)
	state.testRefreshCount = 0

	sendEvent(name: "lastMsgRcvd", value: "", displayed: false)
	logTrace("Sending 30 test frames to device...")
	sendEvent(name: "lastTest", value: "Sending 30 test frames to device...", displayed: false)


	// Test 30 frames at nominal power
	sendHubCommand(new hubitat.device.HubAction(zwave.powerlevelV1.powerlevelTestNodeSet(powerLevel: 0, testFrameCount: 30, testNodeid: 1).format(), hubitat.device.Protocol.ZWAVE))
}


/*
	getCommunicationTestResults

	Requests results from device of test initiated by testCommunication()

	Note: Attempts to retreive results at 10 second intervals, up to 3 times before timing out.
*/
def getCommunicationTestResults()
{
	sendHubCommand(new hubitat.device.HubAction(zwave.powerlevelV1.powerlevelTestNodeGet().format(), hubitat.device.Protocol.ZWAVE))
	state.testRefreshCount = state.testRefreshCount + 1

	logTrace("Requesting test results from device ${state.testRefreshCount} of 3...")
	sendEvent(name: "lastTest", value: "Asking device for results (${state.testRefreshCount}/3)...", displayed: false)

	if (state.testRefreshCount <= 3) runIn(6, getCommunicationTestResults)
	else
	{
		unschedule(getCommunicationTestResults)
		sendEvent(name: "lastTest", value: "FAILED - Device unreachable.", displayed: false)
	}
}


/*
	interrogateDevice

	Schedules request for power level, device version, and other details from device.

	Note: Iris SmartPlugs can be slow to respond to Z-Wave commands; it's not unusual for one not be handled by the device.
*/
def interrogateDevice()
{
	logTrace("Interrogating device...")
	sendEvent(name: "lastMsgRcvd", value: "", displayed: false)
	sendEvent(name: "powerLevel", value: "--", displayed: false)
	sendEvent(name: "deviceVersion", value: "--", displayed: false)
	sendEvent(name: "deviceMSR", value: "--", displayed: false)
	sendEvent(name: "assocGroup", value: "--", displayed: false)

    if (state.failedPings >= 3)
    {
		if (device.currentValue('status') != 'offline')
		{
			sendEvent([
				name: "status",
				isStateChange: true,
				displayed: true,
				value: 'offline',
				descriptionText: "${device.displayName} is offline"
			])
		}
		logInfo("Device is offline")
	}
	state.failedPings = state.failedPings + 1

	state.interrogationPhase = 1
	state.interrogationRetries = 0
	doDeviceInterrogation()
}


/*
	doDeviceInterrogation

	Manages requests power level, device version, and other details from device.

	Note: Since delayBetween is currently broken, we'll use runIn and space the commands out by a few seconds.
*/
def doDeviceInterrogation()
{
	state.interrogationRetries = state.interrogationRetries + 1
	if (state.interrogationRetries > 3)
	{
		sendEvent(name: "lastTest", value: "FAILED - Device unreachable.", displayed: false)
		unschedule(doDeviceInterrogation)
		return
	}

	def result
	switch (state.interrogationPhase)
	{
		case 1:		// Power Level
			result = sendCommand(zwave.powerlevelV1.powerlevelGet())
			sendEvent(name: "lastTest", value: "Phase ${state.interrogationPhase} of 6\nAsking for Power Level (${state.interrogationRetries}/3)...", displayed: false)
			break;
		case 2:		// Version
			result = sendCommand(zwave.versionV1.versionGet())
			sendEvent(name: "lastTest", value: "Phase ${state.interrogationPhase} of 6\nAsking for Version (${state.interrogationRetries}/3)...", displayed: false)
			break;
		case 3:		// Firmware
			result = sendCommand(zwave.firmwareUpdateMdV2.firmwareMdGet())
			sendEvent(name: "lastTest", value: "Phase ${state.interrogationPhase} of 6\nAsking for Firmware (${state.interrogationRetries}/3)...", displayed: false)
			break;
		case 4:		// Manufacturer-Specific
			result = sendCommand(zwave.manufacturerSpecificV2.manufacturerSpecificGet())
			sendEvent(name: "lastTest", value: "Phase ${state.interrogationPhase} of 6\nAsking for Mfr Data (${state.interrogationRetries}/3)...", displayed: false)
			break;
		case 5:		// Association Group #1 Name
			result = sendCommand(zwave.associationGrpInfoV1.associationGroupNameGet(groupingIdentifier: 1))
			sendEvent(name: "lastTest", value: "Phase ${state.interrogationPhase} of 6\nAsking for Grp #1 Name (${state.interrogationRetries}/3)...", displayed: false)
			break;
		case 6:		// Association Group #1 Nodes
			result = sendCommand(zwave.associationV2.associationGet(groupingIdentifier: 1))
			sendEvent(name: "lastTest", value: "Phase ${state.interrogationPhase} of 6\nAsking for Grp #1 Nodes (${state.interrogationRetries}/3)...", displayed: false)
			break;
		case 7:		// Complete
			result = sendEvent(name: "lastTest", value: "Interrogation complete!", displayed: false)
			state.interrogationPhase = 0
			break;
	}

	if (state.interrogationPhase > 0 ) runIn(5, doDeviceInterrogation)
	logTrace("Device Interrogation: Phase ${state.interrogationPhase} of 6; Attempt ${state.interrogationRetries} of 3...")

	result
}


/*
	refresh

	Refreshes the device by requesting manufacturer-specific information.

	Note: This is called from the refresh capbility
*/
def refresh()
{
	if (state.manualRefresh == 1)
	{
		sendEvent(name: "lastTest", value: "FAILED due to TIMEOUT.", displayed: false)
		state.manualRefresh = 0
		return
	}

	state.manualRefresh = 1
	logTrace("Checking to see if device is online...")
	sendEvent(name: "lastTest", value: "Attempting to contact device...", displayed: false)

	runIn(15, refresh)
	refreshDevice()
}


/*
	refreshDevice

	Refreshes the device by requesting manufacturer-specific information.

	Note: Three missed communication attempts will cause the device to be declared offline.
*/
def refreshDevice()
{
	def dateTime = new Date()
	sendEvent(name: "lastMsgRcvd", value: "", displayed: false)
	sendEvent(name: "lastRefresh", value: dateTime.format("yyyy-MM-dd HH:mm:ss", location.timeZone), displayed: false)

    if (state.failedPings >= 3)
    {
		if (device.currentValue('status') != 'offline')
		{
			sendEvent([
				name: "status",
				isStateChange: true,
				displayed: true,
				value: 'offline',
				descriptionText: "${device.displayName} is offline"
			])
		}
		logInfo("Device is offline")
	}

	// Update device status with comm failures for automated refresh
	if (state.manualRefresh == 0)
	{
		sendEvent(name: "lastTest", value: "Contacting device...  Errors: ${state.failedPings}", displayed: false)
	}
	state.failedPings = state.failedPings + 1


	logDebug("Querying device for manufacturerSpecificV2 information...")
	sendCommand(zwave.manufacturerSpecificV2.manufacturerSpecificGet())
}


/*
	poll

	Sets the device state to online, but only if previously offline.

	Note: This has *NEVER* been called by the hub in testing, but is included for use with 3rd party SmartApps
*/
def poll()
{
	logDebug("Poll called, checking to see if device is online......")

	state.manualRefresh = 0
	refreshDevice()
}


/**
 * PING is used by Device-Watch in attempt to reach the Device
 * */
def ping()
{
	logDebug("Ping called, checking to see if device is online......")

	state.manualRefresh = 0
	refreshDevice()
}


/*
	zwaveEvent

	Helper function, nothing to see here.
*/
def zwaveEvent(hubitat.zwave.Command cmd)
{
	createEvent(descriptionText: "Log: $device.displayName: $cmd", isStateChange: true)
}


/*
	sendCommand

	Helper function, nothing to see here.
*/
private sendCommand(hubitat.zwave.Command cmd)
{
	logTrace "Sending command... " + cmd
    if (getDataValue("zwaveSecurePairingComplete") == "true") {
		return zwave.securityV1.securityMessageEncapsulation().encapsulate(cmd).format()
    } else {
		return cmd.format()
    }
}


/*
	logDebug

	Displays debug output to IDE logs based on user preference.
*/
private logDebug(msgOut)
{
	if (settings.enableDebug)
	{
		log.debug msgOut
	}
}


/*
	logTrace

	Displays trace output to IDE logs based on user preference.
*/
private logTrace(msgOut)
{
	if (settings.enableTrace)
	{
		log.trace msgOut
	}
}


/*
	logInfo

	Displays informational output to IDE logs.
*/
private logInfo(msgOut)
{
	log.info msgOut
}