Package io.github.zeroone3010.yahueapi

Class Hue

java.lang.Object
io.github.zeroone3010.yahueapi.Hue
public final class Hue
extends java.lang.Object

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    static class  Hue.HueBridgeConnectionBuilder  

  • Constructor Summary

    Constructors 
    Constructor Description
    Hue​(HueBridgeProtocol protocol, java.lang.String bridgeIp, java.lang.String apiKey)
    A basic constructor for initializing the Hue Bridge connection for this library.
    Hue​(java.lang.String bridgeIp, java.lang.String apiKey)
    The basic constructor for initializing the Hue Bridge connection for this library.

  • Method Summary

    Modifier and Type Method Description
    java.util.Collection<AmbientLightSensor> getAmbientLightSensors()
    Returns all the ambient light sensors configured into the Bridge.
    java.util.Optional<AmbientLightSensor> getAmbientSensorByName​(java.lang.String sensorName)
    Returns a specific ambient sensor by its name.
    java.util.Collection<DaylightSensor> getDaylightSensors()
    Returns all the daylight sensors configured into the Bridge.
    java.util.Collection<Room> getGroupsOfType​(GroupType... groupTypes)
    Returns all groups of lights that match any of the specified group types.
    java.util.Optional<PresenceSensor> getPresenceSensorByName​(java.lang.String sensorName)
    Returns a specific presence sensor by its name.
    java.util.Collection<PresenceSensor> getPresenceSensors()
    Returns all the presence sensors configured into the Bridge.
    Root getRaw()
    Returns the raw root node information of the REST API.
    java.util.Optional<Room> getRoomByName​(java.lang.String roomName)
    Returns a specific room by its name.
    java.util.Collection<Room> getRooms()
    Returns all the rooms configured into the Bridge.
    java.util.Optional<Switch> getSwitchByName​(java.lang.String switchName)
    Returns a specific switch by its name.
    java.util.Collection<Switch> getSwitches()
    Returns all the switches configured into the Bridge.
    java.util.Optional<TemperatureSensor> getTemperatureSensorByName​(java.lang.String sensorName)
    Returns a specific temperature sensor by its name.
    java.util.Collection<TemperatureSensor> getTemperatureSensors()
    Returns all the temperature sensors configured into the Bridge.
    java.util.Optional<Light> getUnassignedLightByName​(java.lang.String lightName)
    Returns a specific unassigned light by its name.
    java.util.Collection<Light> getUnassignedLights()
    Returns all lights that do not belong to any group or zone.
    java.util.Collection<Sensor> getUnknownSensors()
    Returns all the sensors configured into the Bridge.
    java.util.Optional<Room> getZoneByName​(java.lang.String zoneName)
    Returns a specific zone by its name.
    java.util.Collection<Room> getZones()
    Returns all the zones configured into the Bridge.
    static Hue.HueBridgeConnectionBuilder hueBridgeConnectionBuilder​(java.lang.String bridgeIp)
    The method to be used if you do not have an API key for your application yet.
    boolean isCaching()
    Tells whether this instance caches the states of objects, such as lights.
    void refresh()
    Refreshes the room, lamp, etc.
    void setCaching​(boolean enabled)
    Controls whether cached states of objects, such as lights, should be used.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Hue

      public Hue​(java.lang.String bridgeIp, java.lang.String apiKey)
      The basic constructor for initializing the Hue Bridge connection for this library. Use the hueBridgeConnectionBuilder method 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, java.lang.String bridgeIp, java.lang.String apiKey)
      A basic constructor for initializing the Hue Bridge connection for this library. Use the hueBridgeConnectionBuilder method if you do not have an API key yet.
      Parameters:
      protocol - The desired protocol for the Bridge connection. HTTP or UNVERIFIED_HTTPS, as the certificate that the Bridge uses cannot be verified. Defaults to HTTP when using the other constructor.
      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 java.util.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

      public java.util.Collection<Room> getRooms()
      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

      public java.util.Collection<Room> getZones()
      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

      public java.util.Optional<Room> getRoomByName​(java.lang.String roomName)
      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

      public java.util.Optional<Room> getZoneByName​(java.lang.String zoneName)
      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 java.util.Collection<Sensor> getUnknownSensors()
      Returns all the sensors configured into the Bridge.
      Returns:
      A Collection of sensors.
      Since:
      1.0.0

    • getTemperatureSensors

      public java.util.Collection<TemperatureSensor> getTemperatureSensors()
      Returns all the temperature sensors configured into the Bridge.
      Returns:
      A Collection of temperature sensors.
      Since:
      1.0.0

    • getSwitches

      public java.util.Collection<Switch> getSwitches()
      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

    • getPresenceSensors

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

    • getDaylightSensors

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

    • getAmbientLightSensors

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

    • getTemperatureSensorByName

      public java.util.Optional<TemperatureSensor> getTemperatureSensorByName​(java.lang.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 java.util.Optional<PresenceSensor> getPresenceSensorByName​(java.lang.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 java.util.Optional<AmbientLightSensor> getAmbientSensorByName​(java.lang.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:
      1.5.0

    • getSwitchByName

      public java.util.Optional<Switch> getSwitchByName​(java.lang.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 java.util.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 java.util.Optional<Light> getUnassignedLightByName​(java.lang.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

    • hueBridgeConnectionBuilder

      public static Hue.HueBridgeConnectionBuilder hueBridgeConnectionBuilder​(java.lang.String bridgeIp)
      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.
      Parameters:
      bridgeIp - The IP address of the Bridge.
      Returns:
      A connection builder that initializes the application for the Bridge.
      Since:
      1.0.0