Node manipulation and state

## Enumerations

enum | lightify_node_type { LIGHTIFY_ONOFF_PLUG, LIGHTIFY_DIMABLE_LIGHT, LIGHTIFY_COLOUR_LIGHT, LIGHTIFY_EXT_COLOUR_LIGHT, LIGHTIFY_CCT_LIGHT, LIGHTIFY_UNKNOWNTYPE = 0xFF00 }
enum | lightify_node_online_state { LIGHTIFY_OFFLINE = 0, LIGHTIFY_ONLINE = 2 }

## Functions

int | lightify_node_request_scan (struct lightify_ctx *ctx)
struct lightify_node * | lightify_node_get_from_mac (struct lightify_ctx *ctx, uint64_t mac)
struct lightify_node * | lightify_node_get_next (struct lightify_ctx *ctx, struct lightify_node *node)
struct lightify_node * | lightify_node_get_previous (struct lightify_ctx *ctx, struct lightify_node *node)
const char * | lightify_node_get_name (struct lightify_node *node)
uint64_t | lightify_node_get_nodeadr (struct lightify_node *node)
uint16_t | lightify_node_get_zoneadr (struct lightify_node *node)
uint16_t | lightify_node_get_grpadr (struct lightify_node *node)
enum lightify_node_type | lightify_node_get_lamptype (struct lightify_node *node)
int | lightify_node_get_red (struct lightify_node *node)
int | lightify_node_get_green (struct lightify_node *node)
int | lightify_node_get_blue (struct lightify_node *node)
int | lightify_node_get_white (struct lightify_node *node)
int | lightify_node_get_cct (struct lightify_node *node)
int | lightify_node_get_brightness (struct lightify_node *node)
int | lightify_node_is_on (struct lightify_node *node)
int | lightify_node_is_stale (struct lightify_node *node)
int | lightify_node_get_onlinestate (struct lightify_node *node)
int | lightify_node_request_onoff (struct lightify_ctx *ctx, struct lightify_node *node, int onoff)
int | lightify_node_request_cct (struct lightify_ctx *ctx, struct lightify_node *node, unsigned int cct, unsigned int fadetime)
int | lightify_node_request_rgbw (struct lightify_ctx *ctx, struct lightify_node *node, unsigned int r, unsigned int g, unsigned int b, unsigned int w, unsigned int fadetime)
int | lightify_node_request_brightness (struct lightify_ctx *ctx, struct lightify_node *node, unsigned int level, unsigned int fadetime)
int | lightify_node_request_update (struct lightify_ctx *ctx, struct lightify_node *node)

## Detailed Description

## Enumeration Type Documentation

enum lightify_node_online_state

Node online / offline information provided from the gateway

Enumerator
LIGHTIFY_OFFLINE | offline
LIGHTIFY_ONLINE | online

Definition at line 118 of file liblightify.h.

enum lightify_node_type

Known lamp types and what they can do.

Enumerator
LIGHTIFY_ONOFF_PLUG | Only On/off capable lamp/device
LIGHTIFY_DIMABLE_LIGHT | Can only control brightness
LIGHTIFY_COLOUR_LIGHT | RGBW
LIGHTIFY_EXT_COLOUR_LIGHT | Tuneable White and RGBW
LIGHTIFY_CCT_LIGHT | Tuneable White
LIGHTIFY_UNKNOWNTYPE | if you encounter this, please encourage people to provide details. The lamp type is in the lower bits.

Definition at line 105 of file liblightify.h.

## Function Documentation

int lightify_node_get_blue | ( | struct lightify_node * | node | ) |

Get the color component of the node: BLUE

Parameters

  node | lamp

Returns
  the value normalized from 0 to 255. negative numbers means: information not available.

Note
  this function returns cached data. Be sure to refresh the data before when required.

Definition at line 230 of file node.c.

int lightify_node_get_brightness | ( | struct lightify_node * | node | ) |

Get a brightness value

Parameters

  node | lamp to be queried

Returns
  the value. negative numbers means: information not available.

Note
  this function returns cached data. Be sure to refresh the data before when required.

Definition at line 274 of file node.c.

int lightify_node_get_cct | ( | struct lightify_node * | node | ) |

Get the Correlated Color Temperature

Parameters

  node | lamp

Returns
  the value. Negative numbers means: information not available.

Note
  this function returns cached data. Be sure to refresh the data before when required.

Definition at line 263 of file node.c.

struct lightify_node* lightify_node_get_from_mac | ( | struct lightify_ctx * | ctx,
|  | uint64_t | mac
| ) |  |

Search node via its MAC address.

Search node via its unique ZLL MAC Address.

Parameters

  ctx | Library context
  mac | MAC Adress of node (64 bit value, guaranteed to be unique)

Returns
  NULL if not found, otherwise pointer to node.

Find node via mac address (from cache)

Parameters

  ctx | context
  mac | 64bit mac adress

Returns
  pointer to node or NULL.

Definition at line 297 of file context.c.

int lightify_node_get_green | ( | struct lightify_node * | node | ) |

Get the color component of the node: GREEN

Parameters

  node | lamp

Returns
  the value normalized from 0 to 255. negative numbers means: information not available.

Note
  this function returns cached data. Be sure to refresh the data before when required.

Definition at line 241 of file node.c.

uint16_t lightify_node_get_grpadr | ( | struct lightify_node * | node | ) |

Get the node's group address

Note
  The group adress is a bitmask, every bit correspondending to a group. The Bit set equals to the Group's ID.

Parameters

  node |

Returns
  node address

Definition at line 197 of file node.c.

enum lightify_node_type lightify_node_get_lamptype | ( | struct lightify_node * | node | ) |

Get node's ZLL lamp type

Parameters

  node |

Returns
  lamp type

See also
  lightify_node_type

Definition at line 208 of file node.c.

const char* lightify_node_get_name | ( | struct lightify_node * | node | ) |

Retrieve the node's name

Parameters

  node |

Returns
  pointer to name or NULL

Definition at line 164 of file node.c.

struct lightify_node* lightify_node_get_next | ( | struct lightify_ctx * | ctx,
|  | struct lightify_node * | node
| ) |  |

Returns the next node in the linked list

Parameters

  ctx | library context
  node | get the next from this node; if NULL, returns the first node

Returns
  NULL or pointer to the node

Warning
  it is not checked if node is actually belonging to this ctx, but this might change in the future

Definition at line 385 of file context.c.

uint64_t lightify_node_get_nodeadr | ( | struct lightify_node * | node | ) |

Get the node's address (MAC address)

Parameters

  node |

Returns
  node address

Definition at line 175 of file node.c.

int lightify_node_get_onlinestate | ( | struct lightify_node * | node | ) |

Get the online status

Parameters

  node | lamp

Returns
  negative on error, otherwise see enum lightify_node_online_state

Definition at line 297 of file node.c.

struct lightify_node* lightify_node_get_previous | ( | struct lightify_ctx * | ctx,
|  | struct lightify_node * | node
| ) |  |

Returns the next node in the linked list

Parameters

  ctx | library context
  node | get the previous from this node

Returns
  NULL or pointer to the node

Warning
  it is not checked if node is actually belonging to this ctx, but that might change in the future.

Definition at line 393 of file context.c.

int lightify_node_get_red | ( | struct lightify_node * | node | ) |

Get the color components of the node: RED

Parameters

  node | lamp

Returns
  the value normalized from 0 to 255. negative numbers means: information not available.

Definition at line 219 of file node.c.

int lightify_node_get_white | ( | struct lightify_node * | node | ) |

Get the color component of the node: WHITE

Parameters

  node | lamp

Returns
  the value normalized from 0 to 255. negative numbers means: information not available.

Note
  this function returns cached data. Be sure to refresh the data before when required.

Definition at line 252 of file node.c.

uint16_t lightify_node_get_zoneadr | ( | struct lightify_node * | node | ) |

Get the zone address (short ZLL address)

Parameters

  node |

Returns
  node address

Definition at line 186 of file node.c.

int lightify_node_is_on | ( | struct lightify_node * | node | ) |

Return the node status

Parameters

  node | lamp

Returns
  0 = off, 1 = 0n, -1=unknown

Note
  this function returns cached data. Be sure to refresh the data before when required.

Definition at line 286 of file node.c.

int lightify_node_is_stale | ( | struct lightify_node * | node | ) |

Check if we think that the cache is actual with lamp state.

A lamp can become stale if a command manipulating its state failed.

Staleness is reset after scanning for nodes or updating a node.

Parameters

  node | lamp

Returns
  negative on error, 0 if not stale, 1 otherwise

Definition at line 302 of file node.c.

int lightify_node_request_brightness | ( | struct lightify_ctx * | ctx,
|  | struct lightify_node * | node,
|  | unsigned int | level,
|  | unsigned int | fadetime
| ) |  |

Set brightness

Parameters

  ctx | context
  node | to be manuipulated
  level | 0..100
  fadetime | in 1/10 seconds

Returns
  negative on error, >=0 on success

Definition at line 905 of file context.c.

int lightify_node_request_cct | ( | struct lightify_ctx * | ctx,
|  | struct lightify_node * | node,
|  | unsigned int | cct,
|  | unsigned int | fadetime
| ) |  |

Set CCT on lamp with configurable time.

Parameters

  ctx |
  node |
  cct | color temperature. (note: not filtered, but usually between 2700 and 6500)
  fadetime | in 1/10 seconds. 0 is instant.

Returns
  negative on error, >=0 on success

Definition at line 877 of file context.c.

int lightify_node_request_onoff | ( | struct lightify_ctx * | ctx,
|  | struct lightify_node * | node,
|  | int | onoff
| ) |  |

Turn lamp on or off

Parameters

  ctx | library context
  node | node to address. If NULL, broadcast.
  onoff | 1 to turn on, 0 do turn off

Returns
  negative on error, >=0 on success

Definition at line 852 of file context.c.

int lightify_node_request_rgbw | ( | struct lightify_ctx * | ctx,
|  | struct lightify_node * | node,
|  | unsigned int | r,
|  | unsigned int | g,
|  | unsigned int | b,
|  | unsigned int | w,
|  | unsigned int | fadetime
| ) |  |

Set RGBW values

Note
  the color values are from 0...255

Parameters

  ctx | context
  node | node to be manipulated
  r | red value
  g | green value
  b | blue value
  w | white value
  fadetime | time in 1/10 seconds to reach final values.

Returns
  negative on error, >=0 on success

Definition at line 889 of file context.c.

int lightify_node_request_scan | ( | struct lightify_ctx * | ctx | ) |

Ask the gateway to provide informations about attached nodes

The library will query the gateway to submit all known nodes.

Disappeared nodes (and ones with stale information that cannot be updated) will be removed from the list.

Parameters

  ctx | context

Returns
  the number of nodes detected (>=0) on success, negative on errors.

Note
  All previous supplied node pointers become invalid after this call.
  on errors it might be that already a few nodes have been successfully parsed. This can be checked via the API to retrieve node pointers. If there are some. the call partially succeeded.

Definition at line 486 of file context.c.

int lightify_node_request_update | ( | struct lightify_ctx * | ctx,
|  | struct lightify_node * | node
| ) |  |

Update node information cache

This function queries the gateway about current node information and the data stored in the node's struct will be updated with the information from it. This will also reset stale status, if it was previously set and the command executed successfully.

Parameters

  ctx | context
  node | node

Returns
  negative on error, >=0 on success

Definition at line 919 of file context.c.