libraries commonLib - kkossev/Hubitat GitHub Wiki

commonLib.groovy

importUrl: 'https://raw.githubusercontent.com/kkossev/Hubitat/refs/heads/development/Libraries/commonLib.groovy'

Every custom driver must obligatorily include the commonLib. It defines resources used by all devices, handles the standard ZCL messages, and performs basic Tuya 0xEF00 cluster processing.

Including the 'commonLib.groovy' file in the beginning of your driver will automatically add the following capabilities, attributes, commands and preferences:

• Capabilities :

  • 'Configuration'
  • 'Refresh'
  • 'Health Check'
  • 'Power Source'.

• Attributes :

  • 'healthStatus'
  • 'rtt'
  • 'Status'

• Commands :

  • 'Configure'
  • 'Refresh'
  • 'Ping'

• Preferences :

  • 'advancedOptions'
  • 'healthCheckMethod'
  • 'healthCheckInterval'
  • 'traceEnable' Note, that the 'txtEnable' and 'logEnable' preferences must be copied and pasted into the driver Preferences section. This is done to ensure that these two most-frequently used options are always at the top position of the custom driver.

commonLib public methods:

• parse()

  • checkDriverVersion()
  • unscheduleCommandTimeoutCheck()
  • setHealthStatusOnline()
  • processes 'zone status' and 'zone report' messages, calling customParseIasMessage() or standardParseIasMessage() or parseIasMessage() if defined in the custom driver
  • responds to 'enroll request' messages
  • isTuyaE00xCluster() and otherTuyaOddities() - custom parsing and processing of Tuya 0xE000 and 0xE001 clusters that often generate exceptions.
  • isSpammyDeviceReport(descMap) - skips chatty Tuya devices processing
  • parseZdoClusters(descMap) - 0x0000 ZDO cluster processing
  • parseGeneralCommandResponse() - parses Zigbee general commands 0x01, 0x04, 0x07, 0x09, 0x0B
  • standardAndCustomParseCluster() - finally, calls the standard clusters processors:
    • "customParse${clusterName}Cluster" is called first, if defined in the custom driver code
    • "standardParse${clusterName}Cluster" is called otherwise - expected to be defined in the included library files in the custom driver.

• isChattyDeviceReport()

  • do not generate Debug log messages if the chatty DP is defined in the spammyDPsToNotTrace element of the active Device Profile

• isSpammyDeviceReport()

  • do not process this message if the spammy DP is defined in the spammyDPsToIgnore element of the active Device Profile

• isSpammyTuyaRadar()

  • do not trace/debug this message if the device profile 'device' section has a key 'isSpammy':true

• intTo16bitUnsignedHex()

• intTo8bitUnsignedHex()

• standardParseTuyaCluster()

  • called from the main parse method when the cluster is 0xEF00 and no custom handler is defined
  • processes syncTuyaDateTime()
  • processes multiple Tuya commands '01', '02', '05', '06' sent in one Zigbee message in standardProcessTuyaDP() :
  • if customProcessTuyaDp() is defined in the main driver code, then the custom parser is used!. Otherwise :
  • calls processTuyaDPfromDeviceProfile() from the deviceProfile.lib for further processing... Note, that for simple drivers that do not use Device Profiles, a customProcessTuyaDp() must be defined in the simple driver code.

getTuyaCommand()

sendTuyaCommand()

tuyaTest()

tuyaBlackMagic()

aqaraBlackMagic()

initializeDevice()

If there is a customInitializeDevice() method defined in the custom driver, it returns the list of the specific device initialization Zigbee commands.

configureDevice()

If there is a customConfigureDevice() method defined in the custom driver, it returns the list of the specific device configuration Zigbee commands.

refresh()

If there is a customRefresh() method defined, it executes the Zigbee commands returned from the custom driver. Otherwise, calls all known refresh methods from the libraries, if included - onOffRefresh, groupsRefresh, batteryRefresh, levelRefresh, temperatureRefresh, humidityRefresh, illuminanceRefresh. TODO - check all libraries!

clearInfoEvent()

sendInfoEvent()

ping()

sendRttEvent()

scheduleCommandTimeoutCheck() - TODO

updated()

Invoked by Hubitat when the driver configuration is updated. Checks the driver version; unschedules all periodic jobs; reschedules logsOff and traceOff; schedules the DeviceHealthCheck; at the end, invokes customUpdated().

configure(String command)

Invokes one of the ConfigureOpts functions (TODO)

configure()

Invokes tuyaBlackMagic() or aqaraBlackMagic() commands; calls initializeDevice(); calls configureDevice()

loadAllDefaults()

installed()

Invoked when the device is installed with this driver automatically selected. Sends 'unknown' values for healthStatus and powerSource attributes, then schedules calling 'updated' and 'queryPowerSource'.

initialize()

Invoked from 'LoadAllDefaults'. Initializes all common variables and updates Tuya/Aqara versions.

safeToInt(), safeToDouble(), safeToBigDecimal()

sendZigbeeCommands()

TODO!

back to https://github.com/kkossev/Hubitat/wiki/