The Light Controller Class. More...

#include <light_controller.h>

Public Types
enum	Mode { }

typedef std::function< void(bool state, double level, bool control, bool notify)>	T_CONTROL
	Hardware Control Function. More...

Public Member Functions
	LightController ()

void	begin (T_CONTROL controller, bool initialState=false)

void	loop ()

bool	commandParser (String command, String args)

void	set (bool state)

void	brightness (double level)

void	setMode (Mode mode, unsigned int interval_ms=1000, double phase_unit=0.0, String pattern="")

void	setMinMaxWaveBrightness (double minBrightness, double maxBrightness)

void	forceState (bool state, double brightlevel)

Detailed Description

The Light Controller Class.

This class is useful to implement mupplets for things that behave like a light. It supports switching the unit on and off and setting the light intensity. Addionally automatic light effects are supported (see Mode and setMode)

Member Typedef Documentation

◆ T_CONTROL

typedef std::function<void(bool state, double level, bool control, bool notify)> ustd::LightController::T_CONTROL

Hardware Control Function.

The hardware control function is called every time when the state of the light shall change or when the state shall be notified.

state: The logical state of the light: true if the light is on, false if the light is off. level: The brightness level of the light. The value ranges between 0.0 and 1.0 control: If true the hardware shall be set to the supplied values. notify: If true the current state and brightness level shall be notified to whom it may concern.

Member Enumeration Documentation

◆ Mode

enum ustd::LightController::Mode

The light operation mode

Enumerator
Blink	Light is controlled by API or external events, used for on/off and brightness modes. No automatic state changes
Wave	Blink the light with a given frequency. The light is automatically controlled by the mupplet until a manual state override is given.
Pulse	This modulates the light with a soft pulsing wave effect, automatic mode.
Pattern	One-time pulse for a given length, automatic mode while pulse is active. Plays an (optionally) repeating pattern, e.g. to signal a system state.

Constructor & Destructor Documentation

◆ LightController()

ustd::LightController::LightController ( )

inline

Instantiates a LightController instance

No hardware interaction is performed, until begin() is called.

Member Function Documentation

◆ begin()

void ustd::LightController::begin	(	T_CONTROL	controller,
		bool	initialState = `false`
	)

inline

Initiate operation

Parameters

controller	The controller function that controls the hardware and publishes state messages.
initialState	Initial logical state of the light.

◆ brightness()

void ustd::LightController::brightness ( double level )

inline

Set light brighness level

Parameters

level Brightness level [0.0 (off) - 1.0 (on)]

◆ commandParser()

bool ustd::LightController::commandParser	(	String	command,
		String	args
	)

inline

A command parser method for the light

This function acceps commands and their optional arguments. Usually commands in mupplets are sent be publishing messages to specific topics containing the command as the last part of the topic. The most efficient method for processing commands from message subscriptions would be:

pSched->subscribe(tID, name + "/light/#", [this](String topic, String msg, String orig) {
    this->light.commandParser(topic.substring(name.length() + 7), msg);
});

If the topic <muppletname>/light/ shoudl support additonal commands, a typical implementation would be like:

pSched->subscribe(tID, name + "/light/#", [this](String topic, String msg, String orig) {
    topic = topic.substring(name.length() + 7);
 
    if (this->light.commandParser(topic, msg)) {
        // command was processed in light controller
        return;
    }
 
    if (topic == "mycommand") {
        // do my stuff...
    } else if (topic == "myothercommand") {
        // do my other stuff
    }
});

The following commands are supported:

set - set the light on/off or to a specific intensity mode/set - change the mode - see setMode for details unitbrightness/get - notify the current status

Parameters

command	The command to parse
args	The arguments to the command

◆ forceState()

void ustd::LightController::forceState	(	bool	state,
		double	brightlevel
	)

inline

Force the internal state and brightness to a specific value. Useful to fix the internal state in case the hardware is not able to display the requested state. This can usually happen if the brightness is so low that the hardware switches off. e.g.: if a led is moduled via a PWM with only 256 steps, it may happen that a very low brightness will result in the PWM value 0 -> the led is switched off. The implementation will than force the state to false, 0.0:

...
} else if (state && level > 0.0) {
    // led is dimmed
    uint16_t bri = (uint16_t)(level * (double)pwmrange);
    if (bri) {
        if (!activeLogic)
            bri = pwmrange - bri;
        ledcWrite(channel, bri);
    } else {
        light.forceState(false, 0.0);
        onLightControl(false, 0.0, control, notify);
    }
} else {
...

Parameters

state	Logical state of the light: true=on, false=off.
brightlevel	Brightness level of the light [0.0 (off) - 1.0 (on)]

◆ loop()

void ustd::LightController::loop ( )

inline

The loop method This function must be called in the loop method of the mupplet. In order to get smoth effects, this function should be called every 50ms.

◆ set()

void ustd::LightController::set ( bool state )

inline

Set light to a given logical state. A light mupplet usually sends the following messages on state change:

topic	message body	comment
`<prefix>/unitbrightness`	normalized brightness [0.0-1.0]	`0.34`: Float value encoded as string. Not send on automatic changes (e.g. pulse mode)
`<prefix>/state`	`on` or `off`	Current light state (`on` is not sent on brightness intermediate values)

Parameters

state true=on, false=off.

◆ setMinMaxWaveBrightness()

void ustd::LightController::setMinMaxWaveBrightness	(	double	minBrightness,
		double	maxBrightness
	)

inline

Set minimum and maximum brightness in wave Mode Useful to compensate, if a light stays at similar brightness for a range of input values.

Parameters

minBrightness	Minimum brightness 0-1.0
maxBrightness	Maximum brightness 0-1.0

◆ setMode()

void ustd::LightController::setMode	(	Mode	mode,
		unsigned int	interval_ms = `1000`,
		double	phase_unit = `0.0`,
		String	pattern = `""`
	)

inline

Set light mode to given Mode

Parameters

mode	Light Mode
interval_ms	Duration of blink in Mode::Blink or pulse duration.
phase_unit	Phase difference used to synchronize different lights in Wave or blink mode. A phase_unit of 0 synchronizes the given lights. phase-difference is in [0.0-1.0]. A phase difference of 0.5 (180 degrees) between two leds would let leds blink reversed.
pattern	Only in Mode::Pattern: a pattern string consisting of the characters '+' (on), '-' (off), '0'-'9' (brightness 0%-100%), or at the end of the string 'r' for endless repeat. Intervall_ms is the time for each pattern step. Example "++-r" with intervall_ms=100 lights the led for 200ms on, 100ms off and repeats. "1---------r" makes a faint 100ms flash every second. "0135797531r" simulates a wave.

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

src/helper/light_controller.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ T_CONTROL

Member Enumeration Documentation

◆ Mode

Constructor & Destructor Documentation

◆ LightController()

Member Function Documentation

◆ begin()

◆ brightness()

◆ commandParser()

◆ forceState()

◆ loop()

◆ set()

◆ setMinMaxWaveBrightness()

◆ setMode()