Light Hue Server

The Light Hue Server controls the hue of the light color. It should be instantiated in the light fixture node.

The Light Hue Server adds a single model instance to the composition data, in addition to the extended Generic Level Server. Although the Light Hue Server contains range and default states like other lighting models, the states cannot be accessed directly by other nodes without a Light HSL Server.

The Light Hue Server model’s Hue state has certain rules for the wrap-around behavior that need to be considered when writing the application. Unlike the other Lightness models, the Hue state’s change structure bt_mesh_light_hue has an additional field bt_mesh_light_hue.direction. This field tells whether the current Hue state should increase or decrease in order to reach the target value, when the Hue state transition is not instantaneous.

When the Hue state is not limited by the Hue Range state (the minimum value of the hue range is 0 and the maximum value is 65535), the Hue state can wrap around. This, for example, can happen when the target value is lower than the current one, but the Hue state should increment as claimed by the bt_mesh_light_hue.direction field. This is because the bt_mesh_light_hue.direction field points to the shortest path towards the target value.

The Hue state also wraps around when the minimum value of the Hue state is greater than the maximum value. In this case, the state wraps around when the value reaches the end of the type range. This happens because the bt_mesh_light_hue.direction field points to the direction of the allowed range of the Hue state values.

When the application gets a call to the bt_mesh_light_hue_srv_handlers.set callback, the transition always stops at the target value represented by the bt_mesh_light_hue.lvl field. But, if the application gets a call to the bt_mesh_light_hue_srv_handlers.move_set callback, it must start a continuous transition of the Hue state in the direction and rate determined by the bt_mesh_light_hue_move structure. This move transition continues until the Light Hue Server receives a new set or move_set message, or the device reboots.

States

Hue: uint16_t

The Hue controls the light’s angle on the color wheel. The Hue values 0 - 65535 can represent any position on the color spectrum, starting at red, moving through green and blue, before coming back to red at the maximum value. The Hue state should wrap around when it reaches the end of the spectrum, so that a Generic Level Move message to the extended Generic Level Server should start a never-ending cycling through the hue spectrum, unless it is restricted by the Hue Range.

The Hue state power-up behavior is determined by the On Power Up state of the extended Generic Power OnOff Server:

Your application is expected to hold the state memory and provide access to the state through the bt_mesh_light_hue_srv_handlers handler structure.

Note

If the Light Hue Server is part of a Light HSL Server, the application must publish the HSL status using bt_mesh_light_hsl_srv_pub() whenever the Hue state changes. This is not handled automatically by the Light HSL Server.

Hue Range: bt_mesh_light_hsl_range

The Hue Range is a meta state that defines the valid range for the Hue state. The Hue should never go outside the Hue Range. The maximum value can be less than the minimum value.

The memory for the Hue Range state is held by the model, and the application may receive updates on state changes through the bt_mesh_light_hue_handlers.range_update callback.

Default Hue: uint16_t

The Default Hue state is only used when the model is instantiated as part of a Light HSL Server. The Default Hue determines the initial Hue when the node is powered on, and the On Power Up state of the Light HSL Server’s extended Generic Power OnOff Server is ON or OFF.

The memory for the Default Hue state is held by the model, and the application may receive updates on state changes through the bt_mesh_light_hue_handlers.default_update callback.

Extended models

The Light Hue Server extends the following models:

As the state of the extended model is bound to the Hue state, the extended model is not exposed directly to the application.

Persistent storage

The Light Hue Server stores the following information:

  • Any changes to the Default Hue and Hue Range states.

  • The last known Hue level.

This information is used to reestablish the correct Hue level when the device powers up.

If CONFIG_BT_SETTINGS is enabled, the Light Hue Server stores all its states persistently using a configurable storage delay to stagger storing. See CONFIG_BT_MESH_STORE_TIMEOUT.

The Light Hue Server can use the emergency data storage (EMDS) together with persistent storage to:

  • Extend the flash memory life expectancy.

  • Reduce the use of resources by reducing the number of writes to flash memory.

If option CONFIG_EMDS is enabled, the Light Hue Server continues to store the default Hue and Hue range states to the flash memory through the settings library, but the last known Hue level is stored by using the EMDS library. The values stored by EMDS will be lost at first boot when the CONFIG_EMDS is enabled. This split is done so the values that may change often are stored on shutdown only, while the rarely changed values are immediately stored in flash memory.

API documentation

Header file: include/bluetooth/mesh/light_hue_srv.h
Source file: subsys/bluetooth/mesh/light_hue_srv.c
group bt_mesh_light_hue_srv

API for the Light Hue Server model.

Defines

BT_MESH_LIGHT_HUE_SRV_INIT(_handlers)

Initialization parameters for a Light Hue Server model instance.

Parameters:

  • _handlers – [in] HSL Hue Server callbacks.

BT_MESH_MODEL_LIGHT_HUE_SRV(_srv)

HSL Hue Server model composition data entry.

Parameters:

Functions

int bt_mesh_light_hue_srv_pub(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue_status *status)

Publish the current HSL Hue status.

Asynchronously publishes a HSL Hue status message with the configured publish parameters.

Note

This API is only used publishing unprompted status messages. Response messages for get and set messages are handled internally.

Parameters:

  • srv – [in] Server instance to publish on.

  • ctx – [in] Message context to send with, or NULL to send with the default publish parameters.

  • status – [in] Status parameters.

Return values:

  • 0 – Successfully sent the message.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

struct bt_mesh_light_hue_srv_handlers
#include <light_hue_srv.h>

HSL Hue Server state access handlers.

Public Members

void (*const set)(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue *set, struct bt_mesh_light_hue_status *rsp)

Set the Hue state.

When a set message is received, the model publishes a status message, with the response set to rsp. When an acknowledged set message is received, the model also sends a response back to a client. If a state change is non-instantaneous, for example when bt_mesh_model_transition_time returns a nonzero value, the application is responsible for publishing a value of the Hue state at the end of the transition.

When a state change is not-instantaneous, the bt_mesh_light_hue::direction field represents a direction in which the value of the Hue state should change. When the target value of the Hue state is less than the current value and the direction field is positive, or when the target value is greater than the current value and the direction field is negative, the application is responsible for wrapping the value of the Hue state around when the value reaches the end of the type range.

Note

This handler is mandatory.

Param srv:

[in] Server to set the Hue state of.

Param ctx:

[in] Message context.

Param set:

[in] Parameters of the state change.

Param rsp:

[out] Response structure to be filled.

void (*const move_set)(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue_move *move, struct bt_mesh_light_hue_status *rsp)

Move the hue continuously at a certain rate.

The hue state should move move_set::delta units for every move_set::transition::time milliseconds. For instance, if delta is 5 and the transition time is 100ms, the state should move at a rate of 50 per second.

When reaching the border values for the state, the value should wrap around. While the server is executing a move command, it should report its target value as BT_MESH_LIGHT_HSL_MIN or BT_MESH_LIGHT_HSL_MAX, depending on whether it’s moving up or down.

Note

This handler is mandatory.

Param srv:

[in] Server to set the Hue state of.

Param ctx:

[in] Message context.

Param move:

[in] Parameters of the state change.

Param rsp:

[out] Response structure to be filled.

void (*const get)(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_hue_status *rsp)

Get the Hue state.

Note

This handler is mandatory.

Param srv:

[in] Server to get the CTL state of.

Param ctx:

[in] Message context.

Param rsp:

[out] Response structure to be filled.

void (*const default_update)(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, uint16_t old_default, uint16_t new_default)

The default hue has been updated.

Param srv:

[in] Light Hue server.

Param ctx:

[in] Message context, or NULL if the callback was not triggered by a mesh message

Param old_default:

[in] Default value before the update.

Param new_default:

[in] Default value after the update.

void (*const range_update)(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl_range *old_range, const struct bt_mesh_light_hsl_range *new_range)

The valid hue range has been updated.

Param srv:

[in] Light Hue server.

Param ctx:

[in] Message context, or NULL if the callback was not triggered by a mesh message

Param old_range:

[in] Range before the update.

Param new_range:

[in] Range after the update.

struct bt_mesh_light_hue_srv
#include <light_hue_srv.h>

HSL Hue Server instance. Should be initialized with BT_MESH_LIGHT_HUE_SRV_INIT.

Public Members

struct bt_mesh_lvl_srv lvl

Light Level Server instance.

const struct bt_mesh_light_hue_srv_handlers *handlers

Handler function structure.

struct bt_mesh_model *model

Model entry.

const struct bt_mesh_light_hsl_srv *hsl

Pointer to the corresponding HSL server, if it has one. Is set automatically by the HSL server.

struct bt_mesh_model_pub pub

Publish parameters.

struct net_buf_simple buf

Publication buffer

uint8_t pub_data[BT_MESH_MODEL_BUF_LEN(BT_MESH_LIGHT_HUE_OP_STATUS, BT_MESH_LIGHT_HSL_MSG_MAXLEN_HUE_STATUS)]

Publication buffer data

struct bt_mesh_tid_ctx prev_transaction

Transaction ID tracker for the set messages.

struct bt_mesh_light_hsl_range range

Hue range

uint16_t dflt

Default Hue level

uint16_t last

Last known Hue level