Lighting Module Firmware API Reference

Firmware functions

Below is a list of firmware functions used to configure and adapt the lighting behavior on lamps and other in-network devices.


void thsq_lighting_init(void): Initialize Lighting Module

Description

Initializes the lighting module. Must be called by all lighting devices.

Example usage

// Init lighting
thsq_lighting_init();

void thsq_lighting_add_callback(struct thsq_lighting_callback *c, thsq_lighting_callback_fn f): add lighting changed callback

Description

Register to receive callbacks when lighting dimming levels change.

Parameters

  • c: Pointer to opaque thsq_lighting_callback struct
  • f: Callback function

Callback parameters, light_callback

  • rgb: Array containing dimming values
  • len: rgb array length
  • reason: String identifier of lighting event such as schedule or pir

Example usage

static void
light_callback(const uint8_t *rgb, int len, const char *reason)
{
  if(len < 3) {
    return;
  }
  printf("light_callback: red %u, green %u, blue %u\n", rgb[0], rgb[1], rgb[2]);
}

static struct thsq_lighting_callback cb;
thsq_lighting_add_callback(&cb, light_callback);

void thsq_lighting_apply_last(void): apply lighting dimming levels from before last reboot, if available

Description

Lighting devices opportunistically store dimming levels to survive device reboots. This function applies any such dimming levels if they are available.

Note that these dimming levels are not stored permanently, but only survive soft reboots when the device is still powered but the MCU is reset, such as after a firmware update. This function hence allows lighting devices to quickly restore lighting settings even before the device has found and synchronized with the mesh network.

Example usage

  thsq_lighting_init();

  thsq_lighting_apply_last();

void thsq_lighting_set_ontime_limits(uint8_t *ls): re-configure on-time logging

Description

Lamps automatically store dimming-level durations. The on-times are stored in 10 different buckets, where each bucket logs an dimming interval. This function configures the size of the buckets using to store dimming durations.

Parameters

  • ls: sorted 10-byte array containing buckets' upper limits.

Example usage

uint8_t arr[10] = { 0, 25, 50, 75, 100, 125, 150, 175, 200, 255 };
thsq_lighting_set_ontime_limits(arr);
// duration of dim-level 0 is now stored in bucket[0]
// duration of dim-levels 1-25 is now stored in bucket[1]
// duration of dim-levels 26-50 is now stored in bucket[2]
// ...

void thsq_lighting_trigger_pir(void): trigger PIR event in network

Description

Called by a low-power PIR device to signal to the mesh network that a PIR event occured. If the PIR device has a zone configured, the event will be sent to all same-zone devices. If no zone is configured, the event will be sent to all lighting devices.

Example usage

  thsq_lighting_trigger_pir();

void thsq_lighting_trigger_switch(int red, int green, int blue): trigger switch event in network

Description

Called by a low-power switch device to signal to the mesh network that a switch event occured. If the switch device has a zone configured, the event will be sent to all same-zone devices. If no zone is configured, the event will be sent to all lighting devices.

Parameters

  • red: Dimming value red channel, 0-255
  • green: Dimming value green channel, 0-255
  • blue: Dimming value blue channel, 0-255

Example usage

  thsq_lighting_trigger_switch(100, 100, 100);

void thsq_lighting_set_default_pir(int prio, uint32_t duration, int red, int green, int blue): re-configure PIR events

Description

Re-configure how PIR events are handled.

Parameters

  • prio: priority from 0 (lowest) to 4 (highest)
  • duration: event duration (seconds)
  • red: PIR trigger red channel, 0-255
  • green: PIR trigger green channel, 0-255
  • blue: PIR trigger blue channel, 0-255

Example usage

// Configure PIR events to use priority 1, to last for 1 hour,
// and to turn on all three lighting channels
thsq_lighting_set_default_pir(1, 3600, 100, 100, 100);

void thsq_lighting_set_default_switch(int prio, uint32_t duration): re-configure switch events

Description

Re-configure how switch events are handled.

Parameters

  • prio: priority from 0 (lowest) to 4 (highest)
  • duration: event duration (seconds)

Example usage

// Configure switch events to use priority 2 and to last for 1 hour.
// Note that dimming levels are contained in the switch event
thsq_lighting_set_default_switch(2, 3600);

void thsq_lighting_set_default_zone_control(int prio, uint32_t duration): re-configure zone control events

Description

Re-configure how zone control events are handled, such as events sent from a nearby smart phone or via the server API.

Parameters

  • prio: priority from 0 (lowest) to 4 (highest)
  • duration: event duration (seconds)

Example usage

// Configure zone control events to use priority 4 and to last for 30 minutes.
thsq_lighting_set_default_lc(4, 1800);

void thsq_lighting_set_default_schedule(int prio): re-configure schedule events

Description

Re-configure the priority of schedule events.

Parameters

  • prio: priority from 0 (lowest) to 4 (highest)

Example usage

// Configure schedule events to use priority 1.
// A low schedule priority enables higher priority events,
// for example PIR events, to override a currently applied schedule
thsq_lighting_set_default_schedule(1);