Package io.github.zeroone3010.yahueapi

Class Hue

java.lang.Object
io.github.zeroone3010.yahueapi.Hue
public final class Hue
extends Object
The main class. This class creates and holds the connection with the Bridge. This class also holds all the methods with which one can get all the lights, sensors, rooms, etc. to interact with them.

  • Constructor Details

    • Hue

      public Hue​(String bridgeIp, String apiKey)
      The basic constructor for initializing the Hue Bridge connection for this library. Sets up an encrypted but unverified HTTPS connection -- see HueBridgeProtocol.UNVERIFIED_HTTPS. Use the hueBridgeConnectionBuilder(String) method instead if you do not have an API key yet.
      Parameters:
      bridgeIp - The IP address of the Hue Bridge.
      apiKey - The API key of your application.
      Since:
      1.0.0

    • Hue

      public Hue​(HueBridgeProtocol protocol, String bridgeIp, String apiKey)
      A basic constructor for initializing the Hue Bridge connection for this library. Use the hueBridgeConnectionBuilder(String) method if you do not have an API key yet.
      Parameters:
      protocol - The desired protocol for the Bridge connection. Older Bridges require HTTP or UNVERIFIED_HTTPS, as the certificate that the Bridge uses cannot be verified. Defaults to UNVERIFIED_HTTPS since version 2.4.0 when using the other constructor (used to default to HTTP before that), for Philips will eventually deprecate the plain HTTP connection altogether.
      bridgeIp - The IP address of the Hue Bridge.
      apiKey - The API key of your application.
      Since:
      1.0.0

  • Method Details

    • setCaching

      public void setCaching​(boolean enabled)

      Controls whether cached states of objects, such as lights, should be used. Off (false) by default. If set on (true), querying light states will NOT actually relay the query to the Bridge. Instead, it uses the state that was valid when this method was called, or the state that was valid when subsequent calls to the refresh() method were made.

      One should use caching when performing multiple queries in a quick succession, such as when querying the states of all the individual lights in a Hue setup.

      If caching is already on and you try to enable it again, this method does nothing. Similarly nothing happens if caching is already disabled and one tries to disable it again.

      Parameters:
      enabled - Set to true to have the lights cache their results from the Bridge. Remember to call refresh() first when you need to retrieve the absolutely current states.
      Since:
      1.2.0

    • isCaching

      public boolean isCaching()
      Tells whether this instance caches the states of objects, such as lights.
      Returns:
      true if cached results are returned, false if all queries are directed to the Bridge.
      Since:
      1.2.0

    • refresh

      public void refresh()
      Refreshes the room, lamp, etc. data from the Hue Bridge, in case it has been updated since the application was started.

      This method is particularly useful if caching is enabled with the setCaching(boolean) method. Calls to refresh() will, in that case, refresh the states of the lights.

      Since:
      1.0.0

    • getGroupsOfType

      public Collection<Room> getGroupsOfType​(GroupType... groupTypes)
      Returns all groups of lights that match any of the specified group types.
      Parameters:
      groupTypes - Type or types of groups to get.
      Returns:
      A Collection of groups matching the requested types.
      Since:
      1.3.0

    • getRooms

      @Deprecated public Collection<Room> getRooms()
      Deprecated.
      Use Hue.getRooms() instead.
      Returns all the rooms configured into the Bridge. Acts as a shorthand version of calling getGroupsOfType(GroupType...) with value GroupType.ROOM.
      Returns:
      A Collection of rooms.
      Since:
      1.0.0

    • getZones

      @Deprecated public Collection<Room> getZones()
      Deprecated.
      Use Hue.getZones() instead.
      Returns all the zones configured into the Bridge. Acts as a shorthand version of calling getGroupsOfType(GroupType...) with value GroupType.ZONE.
      Returns:
      A Collection of zones as Room objects.
      Since:
      1.1.0

    • getRoomByName

      @Deprecated public Optional<Room> getRoomByName​(String roomName)
      Deprecated.
      Use Hue.getRoomByName(String) instead.
      Returns a specific room by its name.
      Parameters:
      roomName - The name of a room
      Returns:
      A room or Optional.empty() if a room with the given name does not exist.
      Since:
      1.0.0

    • getZoneByName

      @Deprecated public Optional<Room> getZoneByName​(String zoneName)
      Deprecated.
      Use Hue.getZoneByName(String) instead.
      Returns a specific zone by its name.
      Parameters:
      zoneName - The name of a zone
      Returns:
      A zone or Optional.empty() if a zone with the given name does not exist.
      Since:
      1.1.0

    • getRaw

      public Root getRaw()
      Returns the raw root node information of the REST API. Not required for anything but querying the most technical details of the Bridge setup. Note that it is not possible to change the state of the Bridge or the lights by using any values returned by this method: the results are read-only.

      The results of this method are also always cached, so a call to this method never triggers a query to the Bridge (unless no other queries have been made to the Bridge since this instance of Hue was constructed). To refresh the cache call the refresh() method.

      Returns:
      A Root element, as received from the Bridge REST API. Always returns a cached version of the data.
      Since:
      1.0.0

    • getUnknownSensors

      public Collection<Sensor> getUnknownSensors()
      Returns all the sensors configured into the Bridge.
      Returns:
      A Collection of sensors.
      Since:
      1.0.0

    • getTemperatureSensors

      public Collection<TemperatureSensor> getTemperatureSensors()
      Deprecated.
      Returns all the temperature sensors configured into the Bridge.
      Returns:
      A Collection of temperature sensors.
      Since:
      1.0.0
      See Also:
      Hue.getTemperatureSensors()

    • getSwitches

      public Collection<Switch> getSwitches()
      Deprecated.
      Returns all the switches configured into the Bridge. Different kinds of switches include, for example, the Philips Hue dimmer switch and the Philips Hue Tap switch.
      Returns:
      A Collection of switches.
      Since:
      2.0.0
      See Also:
      Hue.getSwitches()

    • getPresenceSensors

      public Collection<PresenceSensor> getPresenceSensors()
      Returns all the presence sensors configured into the Bridge.
      Returns:
      A Collection of presence sensors.
      Since:
      2.0.0

    • getDaylightSensors

      public Collection<DaylightSensor> getDaylightSensors()
      Returns all the daylight sensors configured into the Bridge.
      Returns:
      A Collection of daylight sensors.
      Since:
      1.0.0

    • getAmbientLightSensors

      public Collection<AmbientLightSensor> getAmbientLightSensors()
      Returns all the ambient light sensors configured into the Bridge.
      Returns:
      A Collection of ambient light sensors.
      Since:
      2.0.0

    • getTemperatureSensorByName

      public Optional<TemperatureSensor> getTemperatureSensorByName​(String sensorName)
      Returns a specific temperature sensor by its name.
      Parameters:
      sensorName - The name of a sensor
      Returns:
      A sensor or Optional.empty() if a sensor with the given name does not exist.
      Since:
      1.0.0

    • getPresenceSensorByName

      public Optional<PresenceSensor> getPresenceSensorByName​(String sensorName)
      Returns a specific presence sensor by its name.
      Parameters:
      sensorName - The name of a sensor
      Returns:
      A sensor or Optional.empty() if a sensor with the given name does not exist.
      Since:
      2.0.0

    • getAmbientSensorByName

      public Optional<AmbientLightSensor> getAmbientSensorByName​(String sensorName)
      Returns a specific ambient sensor by its name.
      Parameters:
      sensorName - The name of a sensor
      Returns:
      A sensor or Optional.empty() if a sensor with the given name does not exist.
      Since:
      2.0.0

    • getSwitchByName

      public Optional<Switch> getSwitchByName​(String switchName)
      Returns a specific switch by its name.
      Parameters:
      switchName - The name of a switch
      Returns:
      A switch or Optional.empty() if a switch with the given name does not exist.
      Since:
      2.0.0

    • getUnassignedLights

      public Collection<Light> getUnassignedLights()
      Returns all lights that do not belong to any group or zone.
      Returns:
      A collection of lights.
      Since:
      1.4.0

    • getUnassignedLightByName

      public Optional<Light> getUnassignedLightByName​(String lightName)
      Returns a specific unassigned light by its name.
      Parameters:
      lightName - The name of a light
      Returns:
      A light or Optional.empty() if an unassigned light with the given name does not exist.
      Since:
      2.0.0

    • getAllLights

      public Room getAllLights()

      Returns all lights known by the Bridge. This is a convenience method provided by the API, making it easy to, for example, turn on or off all lights at once.

      Note that due to the special nature of this group, caching has no effect on this method. Every time this method is called or the state of this group is queried, a call is made directly into the Bridge.

      Returns:
      A Room object containing all the lights known by the Bridge.
      Since:
      2.4.0

    • searchForNewLights

      public Future<Collection<Light>> searchForNewLights()
      Orders the Bridge to search for new lights. The operation takes some 40-60 seconds -- longer, if there are many new lights found. Returns a Future that is resolved with a collection of new lights found, if any.
      Returns:
      A Future that is resolved in some 40-60 seconds with the new lights that have been found, if any.
      Since:
      2.6.0

    • getNewLightsSearchStatus

      public NewLightsResult getNewLightsSearchStatus()
      Returns the status of new lights search -- see searchForNewLights(). Note that you do not need to call this method manually when you are using the searchForNewLights() method: internally it checks whether the search is finished by calling this exact method. This method is provided as public for convenience in case you need to return to the results later or need to find out about searches performed by some other means than this library.
      Returns:
      Status of the last search for new lights, and the new lights, if any.
      Since:
      2.6.0
      See Also:
      searchForNewLights()

    • bridgeSupportsApiV2

      public boolean bridgeSupportsApiV2()
      Tells whether the Bridge supports the CLIP API v2, introduced in November 2021.
      Returns:
      true if there is a support for API v2, false if not.
      Since:
      3.0.0

    • hueBridgeConnectionBuilder

      public static HueBridgeConnectionBuilder hueBridgeConnectionBuilder​(String bridgeIp)
      Deprecated.
      Use Hue.hueBridgeConnectionBuilder(String) instead.
      The method to be used if you do not have an API key for your application yet. Returns a HueBridgeConnectionBuilder that initializes the process of adding a new application to the Bridge. You can test if you are connecting to a Hue Bridge endpoint before initializing the connection.
      Parameters:
      bridgeIp - The IP address of the Bridge.
      Returns:
      A connection builder that initializes the application for the Bridge.
      Since:
      1.0.0