nl.q42.jue

Class HueBridge

Object

HueBridge

public class HueBridge
extends Object

Representation of a connection with a Hue bridge.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	HueBridge.ScheduleCallback Callback to specify a schedule command.

Constructor Summary

Constructors

Constructor and Description
HueBridge(String ip) Connect with a bridge as a new user.
HueBridge(String ip, String username) Connect with a bridge as an existing user.

Method Summary

Methods

Modifier and Type	Method and Description
void	authenticate(String username) Authenticate on the bridge as the specified user.
Group	createGroup(List<Light> lights) Creates a new group and returns it.
Group	createGroup(String name, List<Light> lights) Creates a new group and returns it.
void	createSchedule(Date time, HueBridge.ScheduleCallback callback) Schedules a new command to be run at the specified time.
void	createSchedule(String name, Date time, HueBridge.ScheduleCallback callback) Schedules a new command to be run at the specified time.
void	createSchedule(String name, String description, Date time, HueBridge.ScheduleCallback callback) Schedules a new command to be run at the specified time.
void	deleteGroup(Group group) Delete a group.
void	deleteSchedule(Schedule schedule) Delete a schedule.
Group	getAllGroup() Returns a group object representing all lights.
Config	getConfig() Returns bridge configuration.
FullConfig	getFullConfig() Returns the entire bridge configuration.
FullGroup	getGroup(Group group) Returns detailed information for the given group.
List<Group>	getGroups() Returns the list of groups, including the unmodifiable all lights group.
String	getIPAddress() Returns the IP address of the bridge.
Date	getLastSearch() Returns the last time a search for new lights was started.
FullLight	getLight(Light light) Returns detailed information for the given light.
List<Light>	getLights() Returns a list of lights known to the bridge.
FullSchedule	getSchedule(Schedule schedule) Returns detailed information for the given schedule.
List<Schedule>	getSchedules() Returns a list of schedules on the bridge.
String	getUsername() Returns the username currently authenticated with or null if there isn't one.
boolean	isAuthenticated() Returns if authentication was successful on the bridge.
String	link(String devicetype) Link with bridge using the specified device type.
void	link(String username, String devicetype) Link with bridge using the specified username and device type.
void	setConfig(ConfigUpdate update) Change the configuration of the bridge.
String	setGroupAttributes(Group group, String name, List<Light> lights) Changes the name and the lights of a group and returns the new name.
void	setGroupLights(Group group, List<Light> lights) Changes the lights in the group.
String	setGroupName(Group group, String name) Changes the name of the group and returns the new name.
void	setGroupState(Group group, StateUpdate update) Changes the state of a group.
String	setLightName(Light light, String name) Changes the name of the light and returns the new name.
void	setLightState(Light light, StateUpdate update) Changes the state of a light.
void	setSchedule(Schedule schedule, ScheduleUpdate update) Changes a schedule.
void	setScheduleCommand(Schedule schedule, HueBridge.ScheduleCallback callback) Changes the command of a schedule.
void	setTimeout(int timeout) Set the connect and read timeout for HTTP requests.
void	startSearch() Start searching for new lights for 1 minute.
void	unlink() Unlink the current user from the bridge.

Methods inherited from class Object

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

Constructor Detail

HueBridge

public HueBridge(String ip)

Connect with a bridge as a new user.

Parameters:

ip - ip address of bridge

HueBridge

public HueBridge(String ip,
         String username)
          throws IOException,
                 ApiException

Connect with a bridge as an existing user. The username is verified by requesting the list of lights. Use the ip only constructor and authenticate() function if you don't want to connect right now.

Parameters:

ip - ip address of bridge

username - username to authenticate with

Throws:

IOException

ApiException

Method Detail

setTimeout

public void setTimeout(int timeout)

Set the connect and read timeout for HTTP requests.

Parameters:

timeout - timeout in milliseconds or 0 for indefinitely

getIPAddress

public String getIPAddress()

Returns the IP address of the bridge.

Returns:

ip address of bridge

getUsername

public String getUsername()

Returns the username currently authenticated with or null if there isn't one.

Returns:

username or null

isAuthenticated

public boolean isAuthenticated()

Returns if authentication was successful on the bridge.

Returns:

true if authenticated on the bridge, false otherwise

getLights

public List<Light> getLights()
                      throws IOException,
                             ApiException

Returns a list of lights known to the bridge.

Returns:

list of known lights

Throws:

UnauthorizedException - thrown if the user no longer exists

IOException

ApiException

getLastSearch

public Date getLastSearch()
                   throws IOException,
                          ApiException

Returns the last time a search for new lights was started. If a search is currently running, the current time will be returned or null if a search has never been started.

Returns:

last search time

Throws:

UnauthorizedException - thrown if the user no longer exists

IOException

ApiException

startSearch

public void startSearch()
                 throws IOException,
                        ApiException

Start searching for new lights for 1 minute. A maximum amount of 15 new lights will be added.

Throws:

UnauthorizedException - thrown if the user no longer exists

IOException

ApiException

getLight

public FullLight getLight(Light light)
                   throws IOException,
                          ApiException

Returns detailed information for the given light.

Parameters:

light - light

Returns:

detailed light information

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if a light with the given id doesn't exist

IOException

ApiException

setLightName

public String setLightName(Light light,
                  String name)
                    throws IOException,
                           ApiException

Changes the name of the light and returns the new name. A number will be appended to duplicate names, which may result in a new name exceeding 32 characters.

Parameters:

light - light

name - new name [0..32]

Returns:

new name

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if the specified light no longer exists

IOException

ApiException

setLightState

public void setLightState(Light light,
                 StateUpdate update)
                   throws IOException,
                          ApiException

Changes the state of a light.

Parameters:

light - light

update - changes to the state

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if the specified light no longer exists

DeviceOffException - thrown if the specified light is turned off

IOException

ApiException

getAllGroup

public Group getAllGroup()

Returns a group object representing all lights.

Returns:

all lights pseudo group

getGroups

public List<Group> getGroups()
                      throws IOException,
                             ApiException

Returns the list of groups, including the unmodifiable all lights group.

Returns:

list of groups

Throws:

UnauthorizedException - thrown if the user no longer exists

IOException

ApiException

createGroup

public Group createGroup(List<Light> lights)
                  throws IOException,
                         ApiException

Creates a new group and returns it. Due to API limitations, the name of the returned object will simply be "Group". The bridge will append a number to this name if it's a duplicate. To get the final name, call getGroup with the returned object.

Parameters:

lights - lights in group

Returns:

object representing new group

Throws:

UnauthorizedException - thrown if the user no longer exists

GroupTableFullException - thrown if the group limit has been reached

IOException

ApiException

createGroup

public Group createGroup(String name,
                List<Light> lights)
                  throws IOException,
                         ApiException

Creates a new group and returns it. Due to API limitations, the name of the returned object will simply be the same as the name parameter. The bridge will append a number to the name if it's a duplicate. To get the final name, call getGroup with the returned object.

Parameters:

name - new group name

lights - lights in group

Returns:

object representing new group

Throws:

UnauthorizedException - thrown if the user no longer exists

GroupTableFullException - thrown if the group limit has been reached

IOException

ApiException

getGroup

public FullGroup getGroup(Group group)
                   throws IOException,
                          ApiException

Returns detailed information for the given group.

Parameters:

group - group

Returns:

detailed group information

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if a group with the given id doesn't exist

IOException

ApiException

setGroupName

public String setGroupName(Group group,
                  String name)
                    throws IOException,
                           ApiException

Changes the name of the group and returns the new name. A number will be appended to duplicate names, which may result in a new name exceeding 32 characters.

Parameters:

group - group

name - new name [0..32]

Returns:

new name

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if the specified group no longer exists

IOException

ApiException

setGroupLights

public void setGroupLights(Group group,
                  List<Light> lights)
                    throws IOException,
                           ApiException

Changes the lights in the group.

Parameters:

group - group

lights - new lights [1..16]

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if the specified group no longer exists

IOException

ApiException

setGroupAttributes

public String setGroupAttributes(Group group,
                        String name,
                        List<Light> lights)
                          throws IOException,
                                 ApiException

Changes the name and the lights of a group and returns the new name.

Parameters:

group - group

name - new name [0..32]

lights - [1..16]

Returns:

new name

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if the specified group no longer exists

IOException

ApiException

setGroupState

public void setGroupState(Group group,
                 StateUpdate update)
                   throws IOException,
                          ApiException

Changes the state of a group.

Parameters:

group - group

update - changes to the state

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if the specified group no longer exists

IOException

ApiException

deleteGroup

public void deleteGroup(Group group)
                 throws IOException,
                        ApiException

Delete a group.

Parameters:

group - group

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if the specified group no longer exists

IOException

ApiException

getSchedules

public List<Schedule> getSchedules()
                            throws IOException,
                                   ApiException

Returns a list of schedules on the bridge.

Returns:

schedules

Throws:

UnauthorizedException - thrown if the user no longer exists

IOException

ApiException

createSchedule

public void createSchedule(Date time,
                  HueBridge.ScheduleCallback callback)
                    throws IOException,
                           ApiException

Schedules a new command to be run at the specified time. To select the command for the new schedule, simply run it as you normally would in the callback. Instead of it running immediately, it will be scheduled to run at the specified time. It will automatically fail with an IOException, because there will be no response. Note that GET methods cannot be scheduled, so those will still run and return results immediately.

Parameters:

time - time to run command

callback - callback in which the command is specified

Throws:

UnauthorizedException - thrown if the user no longer exists

InvalidCommandException - thrown if the scheduled command is larger than 90 bytes or otherwise invalid

IOException

ApiException

createSchedule

public void createSchedule(String name,
                  Date time,
                  HueBridge.ScheduleCallback callback)
                    throws IOException,
                           ApiException

Schedules a new command to be run at the specified time. To select the command for the new schedule, simply run it as you normally would in the callback. Instead of it running immediately, it will be scheduled to run at the specified time. It will automatically fail with an IOException, because there will be no response. Note that GET methods cannot be scheduled, so those will still run and return results immediately.

Parameters:

name - name [0..32]

time - time to run command

callback - callback in which the command is specified

Throws:

UnauthorizedException - thrown if the user no longer exists

InvalidCommandException - thrown if the scheduled command is larger than 90 bytes or otherwise invalid

IOException

ApiException

createSchedule

public void createSchedule(String name,
                  String description,
                  Date time,
                  HueBridge.ScheduleCallback callback)
                    throws IOException,
                           ApiException

Schedules a new command to be run at the specified time. To select the command for the new schedule, simply run it as you normally would in the callback. Instead of it running immediately, it will be scheduled to run at the specified time. It will automatically fail with an IOException, because there will be no response. Note that GET methods cannot be scheduled, so those will still run and return results immediately.

Parameters:

name - name [0..32]

description - description [0..64]

time - time to run command

callback - callback in which the command is specified

Throws:

UnauthorizedException - thrown if the user no longer exists

InvalidCommandException - thrown if the scheduled command is larger than 90 bytes or otherwise invalid

IOException

ApiException

getSchedule

public FullSchedule getSchedule(Schedule schedule)
                         throws IOException,
                                ApiException

Returns detailed information for the given schedule.

Parameters:

schedule - schedule

Returns:

detailed schedule information

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if the specified schedule no longer exists

IOException

ApiException

setSchedule

public void setSchedule(Schedule schedule,
               ScheduleUpdate update)
                 throws IOException,
                        ApiException

Changes a schedule.

Parameters:

schedule - schedule

update - changes

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if the specified schedule no longer exists

IOException

ApiException

setScheduleCommand

public void setScheduleCommand(Schedule schedule,
                      HueBridge.ScheduleCallback callback)
                        throws IOException,
                               ApiException

Changes the command of a schedule.

Parameters:

schedule - schedule

callback - callback for new command

Throws:

UnauthorizedException - thrown if the user no longer exists

InvalidCommandException - thrown if the scheduled command is larger than 90 bytes or otherwise invalid

IOException

ApiException

See Also:

createSchedule

deleteSchedule

public void deleteSchedule(Schedule schedule)
                    throws IOException,
                           ApiException

Delete a schedule.

Parameters:

schedule - schedule

Throws:

UnauthorizedException - thrown if the user no longer exists

EntityNotAvailableException - thrown if the schedule no longer exists

IOException

ApiException

authenticate

public void authenticate(String username)
                  throws IOException,
                         ApiException

Authenticate on the bridge as the specified user. This function verifies that the specified username is valid and will use it for subsequent requests if it is, otherwise an UnauthorizedException is thrown and the internal username is not changed.

Parameters:

username - username to authenticate

Throws:

UnauthorizedException - thrown if authentication failed

IOException

ApiException

link

public void link(String username,
        String devicetype)
          throws IOException,
                 ApiException

Link with bridge using the specified username and device type.

Parameters:

username - username for new user [10..40]

devicetype - identifier of application [0..40]

Throws:

LinkButtonException - thrown if the bridge button has not been pressed

IOException

ApiException

link

public String link(String devicetype)
            throws IOException,
                   ApiException

Link with bridge using the specified device type. A random valid username will be generated by the bridge and returned.

Parameters:

devicetype - identifier of application [0..40]

Returns:

new random username generated by bridge

Throws:

LinkButtonException - thrown if the bridge button has not been pressed

IOException

ApiException

getConfig

public Config getConfig()
                 throws IOException,
                        ApiException

Returns bridge configuration.

Returns:

bridge configuration

Throws:

UnauthorizedException - thrown if the user no longer exists

IOException

ApiException

See Also:

Config

setConfig

public void setConfig(ConfigUpdate update)
               throws IOException,
                      ApiException

Change the configuration of the bridge.

Parameters:

update - changes to the configuration

Throws:

UnauthorizedException - thrown if the user no longer exists

IOException

ApiException

unlink

public void unlink()
            throws IOException,
                   ApiException

Unlink the current user from the bridge.

Throws:

UnauthorizedException - thrown if the user no longer exists

IOException

ApiException

getFullConfig

public FullConfig getFullConfig()
                         throws IOException,
                                ApiException

Returns the entire bridge configuration. This request is rather resource intensive for the bridge, don't use it more often than necessary. Prefer using requests for specific information your app needs.

Returns:

full bridge configuration

Throws:

UnauthorizedException - thrown if the user no longer exists

IOException

ApiException