pyControl4.light API documentation
Description: Controls Control4 Light devices.

# Module `pyControl4.light`

Controls Control4 Light devices.

## Classes

`class C4Light (C4Director, item_id)`
  Expand source code

      class C4Light(C4Entity):
          async def getLevel(self):
              """Returns the level of a dimming-capable light as an int 0-100.
              Will cause an error if called on a non-dimmer switch. Use `getState()` instead.
              """
              value = await self.director.getItemVariableValue(self.item_id, "LIGHT_LEVEL")
              return int(value)

          async def getState(self):
              """Returns the power state of a dimmer or switch as a boolean (True=on, False=off)."""
              value = await self.director.getItemVariableValue(self.item_id, "LIGHT_STATE")
              return bool(value)

          async def setLevel(self, level):
              """Sets the light level of a dimmer or turns on/off a switch.
              Any `level > 0` will turn on a switch, and `level = 0` will turn off a switch.

              Parameters:
                  `level` - (int) 0-100
              """
              await self.director.sendPostRequest(
                  "/api/v1/items/{}/commands".format(self.item_id),
                  "SET_LEVEL",
                  {"LEVEL": level},
              )

          async def rampToLevel(self, level, time):
              """Ramps the light level of a dimmer over time.
              Any `level > 0` will turn on a switch, and `level = 0` will turn off a switch.

              Parameters:
                  `level` - (int) 0-100

                  `time` - (int) Duration in milliseconds
              """
              await self.director.sendPostRequest(
                  "/api/v1/items/{}/commands".format(self.item_id),
                  "RAMP_TO_LEVEL",
                  {"LEVEL": level, "TIME": time},
              )

          async def setColorXY(self, x: float, y: float, *, rate: int | None = None):
              """Sends SET_COLOR_TARGET with xy"""
              params = {
                  "LIGHT_COLOR_TARGET_X": float(x),
                  "LIGHT_COLOR_TARGET_Y": float(y),
                  "LIGHT_COLOR_TARGET_MODE": 0,
              }
              if rate is not None:
                  params["RATE"] = int(rate)

              await self.director.sendPostRequest(
                  f"/api/v1/items/{self.item_id}/commands",
                  "SET_COLOR_TARGET",
                  params,
              )

          async def setColorTemperature(self, kelvin: int, *, rate: int | None = None):
              params = {
                  "LIGHT_COLOR_TARGET_COLOR_CORRELATED_TEMPERATURE": int(kelvin),
                  "LIGHT_COLOR_TARGET_MODE": 1,
              }
              if rate is not None:
                  params["RATE"] = int(rate)

              await self.director.sendPostRequest(
                  f"/api/v1/items/{self.item_id}/commands",
                  "SET_COLOR_TARGET",
                  params,
              )

  Creates a Control4 object.

  ## Parameters

  `C4Director` - A `C4Director` object that corresponds to the Control4 Director that the device is connected to.

  `item_id` - The Control4 item ID.

  ### Ancestors

  - C4Entity

  ### Methods

  `async def getLevel(self)`
    Expand source code

        async def getLevel(self):
            """Returns the level of a dimming-capable light as an int 0-100.
            Will cause an error if called on a non-dimmer switch. Use `getState()` instead.
            """
            value = await self.director.getItemVariableValue(self.item_id, "LIGHT_LEVEL")
            return int(value)

    Returns the level of a dimming-capable light as an int 0-100. Will cause an error if called on a non-dimmer switch. Use `getState()` instead.

  `async def getState(self)`
    Expand source code

        async def getState(self):
            """Returns the power state of a dimmer or switch as a boolean (True=on, False=off)."""
            value = await self.director.getItemVariableValue(self.item_id, "LIGHT_STATE")
            return bool(value)

    Returns the power state of a dimmer or switch as a boolean (True=on, False=off).

  `async def rampToLevel(self, level, time)`
    Expand source code

        async def rampToLevel(self, level, time):
            """Ramps the light level of a dimmer over time.
            Any `level > 0` will turn on a switch, and `level = 0` will turn off a switch.

            Parameters:
                `level` - (int) 0-100

                `time` - (int) Duration in milliseconds
            """
            await self.director.sendPostRequest(
                "/api/v1/items/{}/commands".format(self.item_id),
                "RAMP_TO_LEVEL",
                {"LEVEL": level, "TIME": time},
            )

    Ramps the light level of a dimmer over time. Any `level > 0` will turn on a switch, and `level = 0` will turn off a switch.

    ## Parameters

    `level` - (int) 0-100

    `time` - (int) Duration in milliseconds

  `async def setColorTemperature(self, kelvin: int, *, rate: int | None = None)`
    Expand source code

        async def setColorTemperature(self, kelvin: int, *, rate: int | None = None):
            params = {
                "LIGHT_COLOR_TARGET_COLOR_CORRELATED_TEMPERATURE": int(kelvin),
                "LIGHT_COLOR_TARGET_MODE": 1,
            }
            if rate is not None:
                params["RATE"] = int(rate)

            await self.director.sendPostRequest(
                f"/api/v1/items/{self.item_id}/commands",
                "SET_COLOR_TARGET",
                params,
            )

  `async def setColorXY(self, x: float, y: float, *, rate: int | None = None)`
    Expand source code

        async def setColorXY(self, x: float, y: float, *, rate: int | None = None):
            """Sends SET_COLOR_TARGET with xy"""
            params = {
                "LIGHT_COLOR_TARGET_X": float(x),
                "LIGHT_COLOR_TARGET_Y": float(y),
                "LIGHT_COLOR_TARGET_MODE": 0,
            }
            if rate is not None:
                params["RATE"] = int(rate)

            await self.director.sendPostRequest(
                f"/api/v1/items/{self.item_id}/commands",
                "SET_COLOR_TARGET",
                params,
            )

    Sends SET_COLOR_TARGET with xy

  `async def setLevel(self, level)`
    Expand source code

        async def setLevel(self, level):
            """Sets the light level of a dimmer or turns on/off a switch.
            Any `level > 0` will turn on a switch, and `level = 0` will turn off a switch.

            Parameters:
                `level` - (int) 0-100
            """
            await self.director.sendPostRequest(
                "/api/v1/items/{}/commands".format(self.item_id),
                "SET_LEVEL",
                {"LEVEL": level},
            )

    Sets the light level of a dimmer or turns on/off a switch. Any `level > 0` will turn on a switch, and `level = 0` will turn off a switch.

    ## Parameters

    `level` - (int) 0-100