Light Lightness models

The Light Lightness models allow remote control and configuration of dimmable lights on a mesh device.

The Light Lightness models can represent light in the following ways:

  • Actual: Lightness is represented on a perceptually uniform lightness scale.

  • Linear: Lightness is represented on a linear scale.

The relationship between the Actual and the Linear representations is the following:

Light (Linear) = (Light (Actual))2

Bindings with other states are always made to the Actual representation.

The Light Lightness models also feature their own common types, listed below. For types common to all models, see Bluetooth mesh models.

The application can select whether to use the Actual or Linear representation. To do so, use the following options in the API at compile time:

Internally, the models will always support both representations, so nodes with different representations can be be used interchangeably.

Common types

This section lists the types common to the Light Lightness mesh models.

Header file: include/bluetooth/mesh/lightness.h
group bt_mesh_lightness

API for the Light Lightness models.



Minimum permitted Lightness level


Maximum permitted Lightness level

struct bt_mesh_lightness_set
#include <lightness.h>

Lightness set message parameters.

Public Members

uint16_t lvl

Lightness level.

const struct bt_mesh_model_transition *transition

Transition time parameters for the state change, or NULL.

When sending, setting the transition to NULL makes the receiver use its default transition time parameters, or 0 if no default transition time is set.

struct bt_mesh_lightness_status
#include <lightness.h>

Lightness status message parameters.

Public Members

uint16_t current

Current Lightness level.

uint16_t target

Target Lightness level.

int32_t remaining_time

Time remaining of the ongoing transition in milliseconds, or SYS_FOREVER_MS. If there’s no ongoing transition, remaining_time is 0.

struct bt_mesh_lightness_range
#include <lightness.h>

Lightness range parameters.

Public Members

uint16_t min

Minimum allowed level.

uint16_t max

Maximum allowed level.

struct bt_mesh_lightness_range_status
#include <lightness.h>

Lightness range message parameters.

Public Members

enum bt_mesh_model_status status

Status of the previous operation.

struct bt_mesh_lightness_range range

Current Lightness range.