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.
Some of the functions take a priority argument:
typedef enum thsq_lighting_prio {
THSQ_LIGHTING_PRIO_0 = 0, /* lowest prio */
THSQ_LIGHTING_PRIO_1 = 1,
THSQ_LIGHTING_PRIO_2 = 2,
THSQ_LIGHTING_PRIO_3 = 3,
THSQ_LIGHTING_PRIO_4 = 4, /* max prio */
} thsq_lighting_prio_t;
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_set_lamp(void): Define this device as a lamp
Description
This sets the device to be a lamp. Must be called directly after thsq_lighting_init(); to allow lighting functionality if this is a lamp. Internally, this initializes schedules and other functionality to work with the lighting module. Ie this is not necessary on non-lamp devices, such as PIR devices.
Example usage
// Init lighting and set as lamp
thsq_lighting_init();
thsq_lighting_set_lamp();
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 structf: Callback function
Callback parameters, light_callback
rgb: Array containing dimming valueslen:rgbarray lengthreason: String identifier of lighting event such asscheduleorpir
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-255green: Dimming value green channel, 0-255blue: Dimming value blue channel, 0-255
Example usage
thsq_lighting_trigger_switch(100, 100, 100);
void thsq_lighting_set_default_pir(thsq_lighting_prio_t 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-255green: PIR trigger green channel, 0-255blue: 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(thsq_lighting_prio_t 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(thsq_lighting_prio_t 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(thsq_lighting_prio_t 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);