pyControl4.fan API documentation
Description: Controls Control4 Fan devices.

# Module `pyControl4.fan`

Controls Control4 Fan devices.

## Classes

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

      class C4Fan(C4Entity):
          # ------------------------
          # Fan State Getters
          # ------------------------

          async def getState(self):
              """
              Returns the current power state of the fan.

              Returns:
                  bool: True if the fan is on, False otherwise.
              """
              value = await self.director.getItemVariableValue(self.item_id, "IS_ON")
              return bool(value)

          async def getSpeed(self):
              """
              Returns the current speed of the fan controller.

              Valid speed values:
                  0 - Off
                  1 - Low
                  2 - Medium
                  3 - Medium High
                  4 - High

              Note:
                  Only valid for fan controllers. On non-dimmer switches,
                  use `getState()` instead.

              Returns:
                  int: Current fan speed (0–4).
              """
              value = await self.director.getItemVariableValue(self.item_id, "CURRENT_SPEED")
              return int(value)

          # ------------------------
          # Fan Control Setters
          # ------------------------

          async def setSpeed(self, speed: int):
              """
              Sets the fan speed or turns it off.

              Parameters:
                  speed (int): Fan speed level:
                      0 - Off
                      1 - Low
                      2 - Medium
                      3 - Medium High
                      4 - High
              """
              await self.director.sendPostRequest(
                  f"/api/v1/items/{self.item_id}/commands",
                  "SET_SPEED",
                  {"SPEED": speed},
              )

          async def setPreset(self, preset: int):
              """
              Sets the fan's preset speed — the speed used when the fan is
              turned on without specifying speed.

              Parameters:
                  preset (int): Preset fan speed level:
                      0 - Off
                      1 - Low
                      2 - Medium
                      3 - Medium High
                      4 - High
              """
              await self.director.sendPostRequest(
                  f"/api/v1/items/{self.item_id}/commands",
                  "DESIGNATE_PRESET",
                  {"PRESET": preset},
              )

  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 getSpeed(self)`
    Expand source code

        async def getSpeed(self):
            """
            Returns the current speed of the fan controller.

            Valid speed values:
                0 - Off
                1 - Low
                2 - Medium
                3 - Medium High
                4 - High

            Note:
                Only valid for fan controllers. On non-dimmer switches,
                use `getState()` instead.

            Returns:
                int: Current fan speed (0–4).
            """
            value = await self.director.getItemVariableValue(self.item_id, "CURRENT_SPEED")
            return int(value)

    Returns the current speed of the fan controller.

    Valid speed values: 0 - Off 1 - Low 2 - Medium 3 - Medium High 4 - High

    ## Note

    Only valid for fan controllers. On non-dimmer switches, use `getState()` instead.

    ## Returns

    `int`
      Current fan speed (0–4).
  `async def getState(self)`
    Expand source code

        async def getState(self):
            """
            Returns the current power state of the fan.

            Returns:
                bool: True if the fan is on, False otherwise.
            """
            value = await self.director.getItemVariableValue(self.item_id, "IS_ON")
            return bool(value)

    Returns the current power state of the fan.

    ## Returns

    `bool`
      True if the fan is on, False otherwise.
  `async def setPreset(self, preset: int)`
    Expand source code

        async def setPreset(self, preset: int):
            """
            Sets the fan's preset speed — the speed used when the fan is
            turned on without specifying speed.

            Parameters:
                preset (int): Preset fan speed level:
                    0 - Off
                    1 - Low
                    2 - Medium
                    3 - Medium High
                    4 - High
            """
            await self.director.sendPostRequest(
                f"/api/v1/items/{self.item_id}/commands",
                "DESIGNATE_PRESET",
                {"PRESET": preset},
            )

    Sets the fan's preset speed — the speed used when the fan is turned on without specifying speed.

    ## Parameters

    preset (int): Preset fan speed level: 0 - Off 1 - Low 2 - Medium 3 - Medium High 4 - High

  `async def setSpeed(self, speed: int)`
    Expand source code

        async def setSpeed(self, speed: int):
            """
            Sets the fan speed or turns it off.

            Parameters:
                speed (int): Fan speed level:
                    0 - Off
                    1 - Low
                    2 - Medium
                    3 - Medium High
                    4 - High
            """
            await self.director.sendPostRequest(
                f"/api/v1/items/{self.item_id}/commands",
                "SET_SPEED",
                {"SPEED": speed},
            )

    Sets the fan speed or turns it off.

    ## Parameters

    speed (int): Fan speed level: 0 - Off 1 - Low 2 - Medium 3 - Medium High 4 - High