Package org.openhab.core.thing.binding

Class BaseLightThingHandler

java.lang.Object
org.openhab.core.thing.binding.BaseThingHandler
org.openhab.core.thing.binding.BaseLightThingHandler
All Implemented Interfaces:
ThingHandler
@NonNullByDefault public abstract class BaseLightThingHandler extends BaseThingHandler
BaseLightThingHandler provides an abstract base implementation for a ThingHandler for a light.
Author:
Andrew Fiddian-Green - Initial contribution

  • Field Details

    • model

      protected final LightModel model
      Light state machine model to manage light capabilities, configuration, and runtime state

  • Constructor Details

    • BaseLightThingHandler

      public BaseLightThingHandler(Thing thing)

  • Method Details

    • handleCommand

      public abstract void handleCommand(ChannelUID channelUID, Command command)
      Override this method to handle commands from OH core.

      Example: (implementation will depend on the specific binding and device). 

       

 // update the model state based on the command from OpenHAB
 model.handleCommand(command);

 // or if it is a color temperature command
 model.handleColorTemperatureCommand(command);

 // and transmit the appropriate command to the remote light device based on the model state
 doTransmitBindingSpecificRemoteLightData(model);
      Parameters:
      channelUID - the ChannelUID of the channel to which the command was sent
      command - the Command

    • initialize

      public abstract void initialize()
      Override this method to provide initialization of the light state machine capabilities and configuration parameters.

      Example: (implementation will depend on the specific binding and device). 

       

  // STEP 1: Set up the light state machine capabilities.
  model.configSetLightCapabilities(LightCapabilities.COLOR_WITH_COLOR_TEMPERATURE);

  // STEP 2: optionally set up the light state machine configuration parameters.
  // These would typically be read from the thing configuration or read from the remote device.
  model.configSetRgbDataType(RgbDataType.RGB_NO_BRIGHTNESS); // RGB data type
  model.configSetMinimumOnBrightness(2); // minimum brightness level in % when on
  model.configSetIncreaseDecreaseStep(10); // step size for increase/decrease commands
  model.configSetMirekControlCoolest(153); // color temperature control range coolest
  model.configSetMirekControlWarmest(500); // color temperature control range warmest

  // STEP 3: optionally if the light has warm and cool white LEDS then set up their LED color temperatures.
  // These would typically be read from the thing configuration or read from the remote device.
  model.configSetMirekCoolWhiteLED(153);
  model.configSetMirekWarmWhiteLED(500);

  // STEP 4: now set the status to UNKNOWN to indicate that we are initialized
  updateStatus(ThingStatus.UNKNOWN);

  // STEP 5: finally provide further initialization, e.g. connecting to the remote device
  ...

    • doTransmitBindingSpecificRemoteLightData

      protected abstract void doTransmitBindingSpecificRemoteLightData(LightModel model)
      Transmit the appropriate command to the remote light device based on the model state. This method must be overridden in the concrete implementation to transmit the appropriate command(s) to the remote light device based on the model state.

      Example: (implementation will depend on the specific binding and device). 

       

  if (model.getOnOff() == OnOffType.ON) {
      transmit command to turn on the light
  } else {
      transmit command to turn off the light
  }

  if (model.getBrightness() != null) {
      transmit command to set brightness to model.getBrightness()
  }

  if (model.getColor() != null) {
      transmit command to set color to model.getColor()
  }

  if (model.getColorTemperature() != null) {
      transmit command to set color temperature to model.getColorTemperature()
  }

  if (model.getColorTemperaturePercent() != null) {
      transmit command to set color temperature percent to model.getColorTemperaturePercent()
  }

  if (model.getRGBx().length == 3) {
      transmit command to set RGB value to model.getRGBx()
  }

  if the light supports XY color coordinates:
      transmit command to set XY value to model.getXY()
  
 }
      Parameters:
      model - the light model containing the current state

    • onReceiveBindingSpecificRemoteLightData

      protected abstract void onReceiveBindingSpecificRemoteLightData(Object... remoteData)
      Receive data from the remote light device and update the model state accordingly. This method must be overridden in the concrete implementation to 1) receive data from the remote light device 2) update the model state accordingly, and 3) update the openHAB channels.

      Example: (implementation will depend on the specific binding and device). 

       

  STEP 1: Parse the remoteData to extract the relevant information. Depends on specific binding / device

  OnOffType onOff = ...; // extract on/off state from remoteData
  Integer brightness = ...; // extract brightness from remoteData
  HSBType color = ...; // extract color from remoteData
  Integer colorTemperature = ...; // extract color temperature from remoteData
  Integer colorTemperaturePercent = ...; // extract color temperature percent from remoteData
  RGBType rgb = ...; // extract RGB value from remoteData
  XYType xy = ...; // extract XY value from remoteData

  STEP 2: Update the model state based on the received data

  if (onOff != null) {
      model.setOnOff(onOff.booleanValue());
  }

  if (brightness != null) {
      model.setBrightness(brightness);
  }

  if (color != null) {
      model.setColor(color);
  }

  if (rgb != null) {
      model.setRGBx(rgb);
  }

  if (xy != null) {
      model.setXY(xy);
  }
  
  Handle color temperature reports from the device
  Option A: device reports color temperature directly in Mirek (micro reciprocal Kelvin)
  if (colorTemperatureMirek != null) {
      model.setMirek(colorTemperatureMirek);
  }

  Option B: device reports color temperature in Kelvin
  if (colorTemperatureKelvin != null) {
      // Convert Kelvin to Mirek: mirek = 1_000_000 / kelvin
      double mirek = 1_000_000d / colorTemperatureKelvin;
      model.setMirek(mirek);
  }

  Option C: device reports color temperature as a 0–100% value
  if (colorTemperaturePercent != null) {
      // Map the percent value to your device's supported Mirek range (mirekMin..mirekMax)
      // before updating the model. Example:
      double mirek = mirekMin + (mirekMax - mirekMin) * colorTemperaturePercent / 100.0;
      model.setMirek(mirek);
  }

  STEP 3: After updating the model, update the channel states in OpenHAB
  Note: Ensure that the channel IDs used in updateState() match those defined in the thing type.

  if (model.configGetLightCapabilities().supportsColor()) {
      updateState(CHANNEL_COLOR, model.getColor());
  } else if (model.configGetLightCapabilities().supportsBrightness()) {
      updateState(CHANNEL_BRIGHTNESS, model.getBrightness());
  } else {
      updateState(CHANNEL_ON_OFF, model.getOnOff());
  }

  if (model.configGetLightCapabilities().supportsColorTemperature()) {
      updateState(CHANNEL_COLOR_TEMPERATURE_ABS, model.getColorTemperature());
      updateState(CHANNEL_COLOR_TEMPERATURE_PERCENT, model.getColorTemperaturePercent());
  }
      Parameters:
      remoteData - the data received from the remote light device