Loading...
Searching...
No Matches
hueplusplus::Group Class Reference

Class for Groups of lights. More...

`#include <hueplusplus/Group.h>`

Collaboration diagram for hueplusplus::Group:
[legend]

## Public Member Functions

| Group (int id, const std::shared_ptr< APICache > &baseCache)
| Creates group with shared cache.
| Group (int id, const HueCommandAPI &commands, std::chrono::steady_clock::duration refreshDuration, const nlohmann::json &currentState)
| Creates group with id.
void | refresh (bool force=false)
| Refreshes internal cached state.
void | setRefreshDuration (std::chrono::steady_clock::duration refreshDuration)
| Sets custom refresh interval for this group.
General information
int | getId () const
| Get the group id.
std::string | getName () const
| Get the group name.
std::string | getType () const
| Get the group type.
std::vector< int > | getLightIds () const
| Get lights in the group.
void | setName (const std::string &name)
| Set group name.
void | setLights (const std::vector< int > &ids)
| Set group lights.
std::string | getRoomType () const
| Get room type, only for type room.
void | setRoomType (const std::string &type)
| Set room type, only for type room.
std::string | getModelId () const
| Get luminaire model id, only for type luminaire.
std::string | getUniqueId () const
| Get luminaire model id, only for type luminaire or lightsource.
bool | getAllOn ()
| Get whether all lights are on.
bool | getAllOn () const
| Get whether all lights are on.
bool | getAnyOn ()
| Get whether any light is on.
bool | getAnyOn () const
| Get whether any light is on.
Query Action
The action is the state of one light in the group. It can be accessed using these methods.
bool | getActionOn ()
| Get on state of one light in the group.
bool | getActionOn () const
| Get on state of one light in the group.
std::pair< uint16_t, uint8_t > | getActionHueSaturation ()
| Get hue and saturation of one light in the group.
std::pair< uint16_t, uint8_t > | getActionHueSaturation () const
| Get hue and saturation of one light in the group.
unsigned int | getActionBrightness ()
| Get brightness of one light in the group.
unsigned int | getActionBrightness () const
| Get brightness of one light in the group.
unsigned int | getActionColorTemperature ()
| Get color temperature of one light in the group.
unsigned int | getActionColorTemperature () const
| Get color temperature of one light in the group.
std::pair< float, float > | getActionColorXY ()
| Get color coordinates of one light in the group.
std::pair< float, float > | getActionColorXY () const
| Get color coordinates of one light in the group.
std::string | getActionColorMode ()
| Get color mode of one light in the group.
std::string | getActionColorMode () const
| Get color mode of one light in the group.
Change lights
StateTransaction | transaction ()
| Create a transaction for this group.
void | setOn (bool on, uint8_t transition=4)
| Convenience function to turn lights on.
void | setBrightness (uint8_t brightness, uint8_t transition=4)
| Convenience function to set brightness.
void | setColor (const HueSaturation &hueSat, uint8_t transition=4)
| Convenience function to set hue and saturation.
void | setColor (const XYBrightness &xy, uint8_t transition=4)
| Convenience function to set color xy.
void | setColorTemperature (unsigned int mired, uint8_t transition=4)
| Convenience function to set color temperature.
void | setColorLoop (bool on, uint8_t transition=4)
| Convenience function to set color loop.
void | setScene (const std::string &scene)
| Recall scene for the group.
Action | createSceneAction (const std::string &scene) const
| Get Action to set scene.

## Protected Member Functions

nlohmann::json | sendPutRequest (const std::string &subPath, const nlohmann::json &request, FileInfo fileInfo)
| Utility function to send a put request to the group.

## Protected Attributes

int | id
APICache | state

## Detailed Description

Class for Groups of lights.

Provides methods to control groups.

## Constructor & Destructor Documentation

## Group() [1/2]

hueplusplus::Group::Group | ( | int | id,
|  | const std::shared_ptr< APICache > & | baseCache )

Creates group with shared cache.

Parameters

  id | Group id in the bridge
  baseCache | Cache of the group list.

## Group() [2/2]

hueplusplus::Group::Group | ( | int | id,
|  | const HueCommandAPI & | commands,
|  | std::chrono::steady_clock::duration | refreshDuration,
|  | const nlohmann::json & | currentState )

Creates group with id.

Parameters

  id | Group id in the bridge
  commands | HueCommandAPI for requests
  refreshDuration | Time between refreshing the cached state.
  currentState | The current state, may be null.

## Member Function Documentation

## createSceneAction()

Action hueplusplus::Group::createSceneAction | ( | const std::string & | scene | ) | const

Get Action to set scene.

Parameters

  scene | Scene name

Returns
  A Action that can be used to set the scene on a Schedule

To set other light properties in a scene, use transaction().

## getActionBrightness() [1/2]

unsigned int hueplusplus::Group::getActionBrightness | ( |  | ) |

Get brightness of one light in the group.

Returns
  Brightness (0-254).

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## getActionBrightness() [2/2]

unsigned int hueplusplus::Group::getActionBrightness | ( |  | ) | const

Get brightness of one light in the group.

Returns
  Brightness (0-254).

Note
  Does not refresh the state.

## getActionColorMode() [1/2]

std::string hueplusplus::Group::getActionColorMode | ( |  | ) |

Get color mode of one light in the group.

The color mode is the currently used way to specify the color (hs,ct or xy).

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## getActionColorMode() [2/2]

std::string hueplusplus::Group::getActionColorMode | ( |  | ) | const

Get color mode of one light in the group.

The color mode is the currently used way to specify the color (hs,ct or xy).

Note
  Does not refresh the state.

## getActionColorTemperature() [1/2]

unsigned int hueplusplus::Group::getActionColorTemperature | ( |  | ) |

Get color temperature of one light in the group.

Returns
  Color temperature in mired.

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## getActionColorTemperature() [2/2]

unsigned int hueplusplus::Group::getActionColorTemperature | ( |  | ) | const

Get color temperature of one light in the group.

Returns
  Color temperature in mired.

Note
  Does not refresh the state.

## getActionColorXY() [1/2]

std::pair< float, float > hueplusplus::Group::getActionColorXY | ( |  | ) |

Get color coordinates of one light in the group.

Returns
  Pair of x and y color coordinates.

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## getActionColorXY() [2/2]

std::pair< float, float > hueplusplus::Group::getActionColorXY | ( |  | ) | const

Get color coordinates of one light in the group.

Returns
  Pair of x and y color coordinates.

Note
  Does not refresh the state.

## getActionHueSaturation() [1/2]

std::pair< uint16_t, uint8_t > hueplusplus::Group::getActionHueSaturation | ( |  | ) |

Get hue and saturation of one light in the group.

Returns
  Pair of hue, saturation.

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## getActionHueSaturation() [2/2]

std::pair< uint16_t, uint8_t > hueplusplus::Group::getActionHueSaturation | ( |  | ) | const

Get hue and saturation of one light in the group.

Returns
  Pair of hue, saturation.

Note
  Does not refresh the state.

## getActionOn() [1/2]

bool hueplusplus::Group::getActionOn | ( |  | ) |

Get on state of one light in the group.

Returns
  True if the light is on.

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## getActionOn() [2/2]

bool hueplusplus::Group::getActionOn | ( |  | ) | const

Get on state of one light in the group.

Returns
  True if the light is on.

Note
  Does not refresh the state.

## getAllOn() [1/2]

bool hueplusplus::Group::getAllOn | ( |  | ) |

Get whether all lights are on.

Returns
  true when all lights are on.

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## getAllOn() [2/2]

bool hueplusplus::Group::getAllOn | ( |  | ) | const

Get whether all lights are on.

Returns
  true when all lights are on.

Note
  Does not refresh the state.

## getAnyOn() [1/2]

bool hueplusplus::Group::getAnyOn | ( |  | ) |

Get whether any light is on.

Returns
  true when any light is on.

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## getAnyOn() [2/2]

bool hueplusplus::Group::getAnyOn | ( |  | ) | const

Get whether any light is on.

Returns
  true when any light is on.

Note
  Does not refresh the state.

## getId()

int hueplusplus::Group::getId | ( |  | ) | const

Get the group id.

## getLightIds()

std::vector< int > hueplusplus::Group::getLightIds | ( |  | ) | const

Get lights in the group.

Returns
  Ids of the lights in the group.

## getModelId()

std::string hueplusplus::Group::getModelId | ( |  | ) | const

Get luminaire model id, only for type luminaire.

Returns
  Unique id for the hardware model.

## getName()

std::string hueplusplus::Group::getName | ( |  | ) | const

Get the group name.

## getRoomType()

std::string hueplusplus::Group::getRoomType | ( |  | ) | const

Get room type, only for type room.

Returns
  Room type/class of the group.

## getType()

std::string hueplusplus::Group::getType | ( |  | ) | const

Get the group type.

The type is specified on creation and cannot be changed.

Possible types:

- `0`: Special group containing all lights, cannot be modified.
- `Luminaire`, `Lightsource`: Automatically created groups for multisource luminaires.
- `LightGroup`: Standard, user created group, not empty.
- `Room`: User created room, has room type.
- `Entertainment`: User created entertainment setup.
- `Zone`: User created Zone.

## getUniqueId()

std::string hueplusplus::Group::getUniqueId | ( |  | ) | const

Get luminaire model id, only for type luminaire or lightsource.

Returns
  Unique id in `AA:BB:CC:DD` format for luminaire groups or `AA:BB:CC:DD-XX` for Lightsource groups.

## refresh()

void hueplusplus::Group::refresh | ( | bool | force = false | ) |

Refreshes internal cached state.

Parameters

  force | `true` forces a refresh, regardless of how long the last refresh was ago. `false` to only refresh when enough time has passed (needed e.g. when calling only const methods).

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## sendPutRequest()

nlohmann::json hueplusplus::Group::sendPutRequest | ( | const std::string & | subPath,
|  | const nlohmann::json & | request,
|  | FileInfo | fileInfo )

protected

Utility function to send a put request to the group.

Parameters

  request | The request to send
  subPath | A path that is appended to the uri, note it should always start with a slash ("/")
  fileInfo | FileInfo from calling function for exception details.

Returns
  The parsed reply

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## setBrightness()

void hueplusplus::Group::setBrightness | ( | uint8_t | brightness,
|  | uint8_t | transition = 4 )

Convenience function to set brightness.

See also
  StateTransaction::setBrightness

## setColor() [1/2]

void hueplusplus::Group::setColor | ( | const HueSaturation & | hueSat,
|  | uint8_t | transition = 4 )

Convenience function to set hue and saturation.

See also
  StateTransaction::setColor(const HueSaturation&)

## setColor() [2/2]

void hueplusplus::Group::setColor | ( | const XYBrightness & | xy,
|  | uint8_t | transition = 4 )

Convenience function to set color xy.

See also
  StateTransaction::setColor(const XYBrightness&)

## setColorLoop()

void hueplusplus::Group::setColorLoop | ( | bool | on,
|  | uint8_t | transition = 4 )

Convenience function to set color loop.

See also
  StateTransaction::setColorLoop

## setColorTemperature()

void hueplusplus::Group::setColorTemperature | ( | unsigned int | mired,
|  | uint8_t | transition = 4 )

Convenience function to set color temperature.

See also
  StateTransaction::setColorTemperature

## setLights()

void hueplusplus::Group::setLights | ( | const std::vector< int > & | ids | ) |

Set group lights.

Parameters

  ids | New light ids. May or may not be empty depending on type.

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## setName()

void hueplusplus::Group::setName | ( | const std::string & | name | ) |

Set group name.

Parameters

  name | New name for the group. Must be unique for all groups, otherwise a number is added.

## setOn()

void hueplusplus::Group::setOn | ( | bool | on,
|  | uint8_t | transition = 4 )

Convenience function to turn lights on.

See also
  StateTransaction::setOn

## setRefreshDuration()

void hueplusplus::Group::setRefreshDuration | ( | std::chrono::steady_clock::duration | refreshDuration | ) |

Sets custom refresh interval for this group.

Parameters

  refreshDuration | The new minimum duration between refreshes. May be 0 or c_refreshNever.

## setRoomType()

void hueplusplus::Group::setRoomType | ( | const std::string & | type | ) |

Set room type, only for type room.

Parameters

  type | New room class, case sensitive. Only specific values are allowed.

Exceptions

  std::system_error | when system or socket operations fail
  HueException | when response contained no body
  HueAPIResponseException | when response contains an error
  nlohmann::json::parse_error | when response could not be parsed

## setScene()

void hueplusplus::Group::setScene | ( | const std::string & | scene | ) |

Recall scene for the group.

Scenes are saved configurations for the lights in a group.

Parameters

  scene | Scene name.

## transaction()

StateTransaction hueplusplus::Group::transaction | ( |  | ) |

Create a transaction for this group.

The transaction can be used to change more than one value in one request.

Example usage:

group.transaction().setBrightness(240).setColorHue(5000).commit();

## Member Data Documentation

## id

int hueplusplus::Group::id

protected

## state

APICache hueplusplus::Group::state

protected

The documentation for this class was generated from the following files:

- include/hueplusplus/Group.h
- src/Group.cpp