ustd::IlluminanceTSL2561 Class Reference

mupplet-sensor luminance with TSL2561 More...

#include <mup_illuminance_tsl2561.h>

Public Member Functions
	IlluminanceTSL2561 (String name, FilterMode filterMode=FilterMode::FAST, IntegrationMode integrationMode=IntegrationMode::LONGTERM402ms, GainMode gainMode=GainMode::LOW1x, uint8_t i2cAddress=0x39)
double	getIlluminance ()
double	getUnitIlluminance ()
double	getUnitIlluminanceSensitivity ()
void	setUnitIlluminanceSensitivity (double sensitivity)

Detailed Description

mupplet-sensor luminance with TSL2561

The mup_illuminance_tsl2561 mupplet measures illuminance using the TSL2561 sensor.

Precision and range can be modified using the following parameters:

• FilterMode modifies the software filter for FAST (no software averages), MEDIUM, or LONGTERM (more software averages)
• IntegrationMode modifies the sensor's internal integration time from FAST (13ms), MEDIUM (101ms) to LONGTERM (402ms).
• GainMode selects the sensor hardware gain amplification between LOW (1x) and HIGH (16x)
• unitilluminancesensitivity is a software amplification factor that shifts the range of calculated unitilluminance values using a model that is perceived by humans as linear. (The value for illuminance is in lux, which is not perceived as linear.)

This mupplet is a fully asynchronous state-machine with no delay()s, so it never blocks.

Messages sent by illuminance_tsl2561 mupplet:

messages are prefixed by omu/<hostname>:

topic	message body	comment
<mupplet-name>/sensor/illuminance	illumance in lux	Float value encoded as string, sent periodically as available
<mupplet-name>/sensor/unitilluminance	normalized illumance 0.0(dark)..1.0(max light)	Float value encoded as string, sent periodically as available
<mupplet-name>/sensor/lightch0	raw sensor value photo diode ch0 visible light	Float value encoded as string, sent periodically as available
<mupplet-name>/sensor/irch1	raw sensor value photo diode ch1 IR light	Float value encoded as string, sent periodically as available
<mupplet-name>/sensor/mode	FAST, MEDIUM, or LONGTERM	Software filter values, external, additional software integration, in addition to hardware integration on sensor
<mupplet-name>/sensor/integration	FAST, MEDIUM, or LONGTERM	Integration on sensor hardware: FAST: 13.7 ms, MEDIUM: 101ms, LONG: 402ms (default)

| <mupplet-name>/sensor/gain / LOW or HIGH | Low is 1x gain, high is 16x gain | | <mupplet-name>/sensor/unitilluminancesensitivity | <sensitivity> | Sensitivity-factor for unitilluminance, default 0.2. |

Messages received by illuminance_tsl2561 mupplet:

Need to be prefixed by <hostname>/:

topic	message body	comment
<mupplet-name>/sensor/illuminance/get	-	Causes current value to be sent.
<mupplet-name>/sensor/unitilluminance/get	-	Causes current value to be sent.
<mupplet-name>/sensor/lightch0/get	-	Causes current value to be sent.
<mupplet-name>/sensor/irch1/get	-	Causes current value to be sent.
<mupplet-name>/sensor/mode/get	-	Returns software filterMode: FAST, MEDIUM, or LONGTERM
<mupplet-name>/sensor/integration/get	-	Returns hardware integration: FAST (13.7ms), MEDIUM (101ms), or LONGTERM (402ms)
<mupplet-name>/sensor/mode/set	FAST, MEDIUM, or LONGTERM	Set softwaare filter values, a 2nd stage filter, additional to hardware integration on sensor
<mupplet-name>/sensor/integration/set	FAST, MEDIUM, or LONGTERM	Set hardware integration values values, default is LONGTERM, 402ms
<mupplet-name>/sensor/gain/set	LOW or HIGH	Set 1x (low, default) or 16x (high) gain
<mupplet-name>/sensor/gain/get	-	Causes gain message to be sent.
<mupplet-name>/sensor/unitilluminancesensitivity/set	<sensitivity>	Default 0.2. If decreased, lower values for unitilluminance are generated, and vice versa. Uses logarithmic model in order to match human perception.
<mupplet-name>/sensor/unitilluminancesensitivity/get	-	Get current value

Sample code

For a complete examples see the muwerk/examples project.

#include "ustd_platform.h"
#include "scheduler.h"
#include "net.h"
#include "mqtt.h"
 
#include "mup_illuminance_tsl2561.h"
 
void appLoop();
 
ustd::Scheduler sched(10, 16, 32);
ustd::Net net(LED_BUILTIN);
ustd::Mqtt mqtt;
 
ustd::IlluminanceTSL2561101 TSL("myTSL2561");
 
void sensorUpdates(String topic, String msg, String originator) {
    // data is in topic, msg
}
 
void setup() {
#ifdef USE_SERIAL_DBG
    Serial.begin(115200);
#endif  // USE_SERIAL_DBG
    net.begin(&sched);
    mqtt.begin(&sched);
    ota.begin(&sched);
    int tID = sched.add(appLoop, "main", 1000000);
 
    // sensors start measuring pressure and temperature
    TSL.begin(&sched);
 
    sched.subscribe(tID, "myTSL2561/sensor/illuminance", sensorUpdates);
}
 
void appLoop() {
}
 
// Never add code to this loop, use appLoop() instead.
void loop() {
    sched.loop();
}

Constructor & Destructor Documentation

IlluminanceTSL2561()

ustd::IlluminanceTSL2561::IlluminanceTSL2561 ( String  name, FilterMode  filterMode = FilterMode::FAST, IntegrationMode  integrationMode = IntegrationMode::LONGTERM402ms, GainMode  gainMode = GainMode::LOW1x, uint8_t  i2cAddress = 0x39  )

inline

Instantiate an TSL sensor mupplet

Parameters

name	Name used for pub/sub messages
filterMode	FAST, MEDIUM or LONGTERM filtering of sensor values
i2cAddress	Should be 0x29, 0x39, 0x49, for TSL2561, depending address selector (three state) config.

Member Function Documentation

getIlluminance()

double ustd::IlluminanceTSL2561::getIlluminance ( )

inline

Get Illuminance

Returns

illuminance (lux)

getUnitIlluminance()

double ustd::IlluminanceTSL2561::getUnitIlluminance ( )

inline

Get normalized Illuminance

Returns

illuminance [0(dark)..1(full light)]

getUnitIlluminanceSensitivity()

double ustd::IlluminanceTSL2561::getUnitIlluminanceSensitivity ( )

inline

Get normalized Illuminance sensitivity

Lower values (<0.2) generate low unitilluminance values, higher values amplify.

Returns

illuminance sensitivity

setUnitIlluminanceSensitivity()

void ustd::IlluminanceTSL2561::setUnitIlluminanceSensitivity ( double  sensitivity )

inline

Set normalized Illuminance sensitivity

This can be used to modify the range use by unitilluminance, which is always [0..1]. The sensitivity reduces (lower sensitivity) or amplifies (higher sensitivity) the values generated for unitilluminance. A logarithmic model is used to match human perception.

Default is 0.2 on startup.

Parameters

sensitivity

illuminance sensitivity [0.001(no sensitivity)..0.2(default)..(higher sensitivity)]

---

The documentation for this class was generated from the following file:

• src/mup_illuminance_tsl2561.h