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

# Module `pyControl4.fan`

Controls Control4 Fan devices.

## Classes

`class C4Fan (director: C4Director, item_id: int)`
  Expand source code

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

          async def get_state(self) -> bool | None:
              """
              Returns the current power state of the fan.

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

          async def get_speed(self) -> int | None:
              """
              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 `get_state()` instead.

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

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

          async def set_speed(self, speed: int) -> None:
              """
              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.send_post_request(
                  f"/api/v1/items/{self.item_id}/commands",
                  "SET_SPEED",
                  {"SPEED": speed},
              )

          async def set_preset(self, preset: int) -> None:
              """
              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.send_post_request(
                  f"/api/v1/items/{self.item_id}/commands",
                  "DESIGNATE_PRESET",
                  {"PRESET": preset},
              )

  Creates a Control4 object.

  ## Parameters

  `director` - 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 get_speed(self) ‑> int | None`
    Expand source code

        async def get_speed(self) -> int | None:
            """
            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 `get_state()` instead.

            Returns:
                int: Current fan speed (0–4).
            """
            value = await self.director.get_item_variable_value(
                self.item_id, "CURRENT_SPEED"
            )
            if value is None:
                return None
            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 `get_state()` instead.

    ## Returns

    `int`
      Current fan speed (0–4).
  `async def get_state(self) ‑> bool | None`
    Expand source code

        async def get_state(self) -> bool | None:
            """
            Returns the current power state of the fan.

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

    Returns the current power state of the fan.

    ## Returns

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

        async def set_preset(self, preset: int) -> None:
            """
            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.send_post_request(
                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 set_speed(self, speed: int) ‑> None`
    Expand source code

        async def set_speed(self, speed: int) -> None:
            """
            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.send_post_request(
                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