lampda::modes::BasicMode Struct Reference

Parent object for all custom user modes. More...

#include <mode_type.hpp>

Inheritance diagram for lampda::modes::BasicMode:

Classes
struct	StateTy
	Mode custom static state, made available through context (optional) More...

Static Public Member Functions
static void	loop (auto &ctx)
	Custom user mode loop function (default)
static void	on_enter_mode (auto &ctx)
	Custom callback when mode gains focus (optional)
static void	on_exit_mode (auto &ctx)
	Custom callback when mode goes outside of focus (optional)
static void	sunset_update (auto &ctx, float progress)
	Custom callback when sunset mode is updated (optional)
static void	brightness_update (auto &ctx, brightness_t brightness)
	Custom callback when brightness changes (optional)
static void	custom_ramp_update (auto &ctx, uint8_t rampValue)
	Custom callback when system sets user ramp (optional)
static bool	custom_click (auto &ctx, uint8_t nbClick)
	Custom "usermode" button UI for "click" action (optional)
static bool	custom_hold (auto &ctx, uint8_t nbClickAndHold, bool isEndOfHoldEvent, uint32_t holdDuration)
	Custom "usermode" button UI for "click+hold" action (optional)
static void	power_on_sequence (auto &ctx)
	Custom callback when the system powers on (optional)
static void	power_off_sequence (auto &ctx)
	Custom callback when the system powers off (optional)
static void	read_parameters (auto &ctx)
	Custom callback to read parameters from filesystem (optional)
static void	write_parameters (auto &ctx)
	Custom callback to write parameters to filesystem (optional)
static void	user_thread (auto &ctx)
	Custom secondary loop, executed in another thread (optional)

Static Public Attributes
static constexpr bool	isGroupManager = false
static constexpr bool	hasSunsetAnimation = false
	Toggles the use of custom BasicMode::sunset_update() callback.
static constexpr bool	hasBrightCallback = false
	Toggles the use of custom BasicMode::brightness_update() callback.
static constexpr bool	hasCustomRamp = false
	Toggles the use of custom ramps & BasicMode::custom_ramp_update()
static constexpr bool	hasButtonCustomUI = false
	Toggles "usermode" button UI custom_click() and custom_hold()
static constexpr bool	hasSystemCallbacks = false
	Toggles advanced system callbacks, see list here .
static constexpr bool	requireUserThread = false
	Toggles the use of custom BasicMode::user_thread() callback.
static constexpr uint32_t	storeId = 0
	Store identifier for persistent storage (optional)

Detailed Description

Parent object for all custom user modes.

Implement a custom user mode as follow:

// user mode definition
struct MyCustomMode : public modes::BasicMode {
  static void loop(auto& ctx) {
    ctx.lamp.setBrightness(200);
 
    // ... other things using lamp
  }
};

Once defined, you can enable the mode by adding it to indexable_functions.cpp :

using ManagerTy = modes::ManagerFor<
  modes::GroupFor<ModeA,
                  ModeB,
                  ...>,
  modes::GroupFor<Mode1,
                  MyCustomMode, // mode available between Mode1 & Mode2
                  Mode2>
>;

You can start from the mode template below where you will need to remove the unused callbacks:

#ifndef MY_CUSTOM_MODE_H
#define MY_CUSTOM_MODE_H
 
struct MyCustomMode : public lampda::modes::BasicMode
{
  static void loop(auto& ctx) {}
  static void on_enter_mode(auto& ctx) {}
  static void on_exit_mode(auto& ctx) {}
 
  // only if hasSunsetAnimation
  static void sunset_update(auto& ctx, float progress) {}
 
  // only if hasBrightCallback
  static void brightness_update(auto& ctx, brightness_t brightness) {}
 
  // only if hasCustomRamp
  static void custom_ramp_update(auto& ctx, uint8_t rampValue) {}
 
  // only if hasButtonCustomUI
  static bool custom_click(auto& ctx, uint8_t nbClick) { return false; }
 
  static bool custom_hold(auto& ctx, uint8_t nbClickAndHold, bool isEndOfHoldEvent, uint32_t holdDuration)
  {
    return false;
  }
 
  // only if hasSystemCallbacks
  static void power_on_sequence(auto& ctx) {}
  static void power_off_sequence(auto& ctx) {}
  static void read_parameters(auto& ctx) {}
  static void write_parameters(auto& ctx) {}
 
  // only if requireUserThread
  static void user_thread(auto& ctx) {}
 
  // keep only if customized
  struct StateTy
  {
  };
 
  // keep only the ones you need (= true)
  static constexpr bool hasBrightCallback = false;
  static constexpr bool hasCustomRamp = false;
  static constexpr bool hasButtonCustomUI = false;
  static constexpr bool hasSystemCallbacks = false;
  static constexpr bool requireUserThread = false;
};
 
#endif

Further examples of modes are available in src/modes/default

Remarks

BasicMode and all derived user modes should never be constructed, use custom StateTy to implement stateful modes

Member Function Documentation

brightness_update()

static void lampda::modes::BasicMode::brightness_update ( auto &  ctx, brightness_t  brightness  )

inlinestatic

Custom callback when brightness changes (optional)

Callback active only if BasicMode::hasBrightCallback is True

Parameters

[in]	ctx	The current context
[in]	brightness	The brightness value set by the system

Remarks

Use update_brightness() to change brightness in order for this callback to be correctly handled at runtime

custom_click()

static bool lampda::modes::BasicMode::custom_click ( auto &  ctx, uint8_t  nbClick  )

inlinestatic

Custom "usermode" button UI for "click" action (optional)

Callback active only if BasicMode::hasButtonCustomUI is True

Parameters

[in]	ctx	The current context
[in]	nbClick	The number of clicks made by the user

Returns

Returns True if default UI action should be prevented

custom_hold()

static bool lampda::modes::BasicMode::custom_hold ( auto &  ctx, uint8_t  nbClickAndHold, bool  isEndOfHoldEvent, uint32_t  holdDuration  )

inlinestatic

Custom "usermode" button UI for "click+hold" action (optional)

Callback active only if BasicMode::hasButtonCustomUI is True

Parameters

[in]	ctx	The current context
[in]	nbClickAndHold	The number of clicks made by the user
[in]	isEndOfHoldEvent	True if the user just released the button
[in]	holdDuration	The duration of the on-going hold event

Returns

Returns True if default action must be prevented

Remarks

When isEndOfHoldEvent is True, then holdDuration is zero

custom_ramp_update()

static void lampda::modes::BasicMode::custom_ramp_update ( auto &  ctx, uint8_t  rampValue  )

inlinestatic

Custom callback when system sets user ramp (optional)

This can be used to make a mode configurable through the 3H click+hold user action, which will cycle through the 0-255 values in a ~2s ramp

Parameters

[in]	ctx	The current context
[in]	rampValue	The custom value set by the user

Remarks

This behavior is in user::button_hold_default() and may be prevented if custom "usermode UI" via custom_hold() is enabled

loop()

static void lampda::modes::BasicMode::loop ( auto &  ctx )

inlinestatic

Custom user mode loop function (default)

Loop function each tick called whenever the mode is set as the currently active mode by the user

Parameters

[in]

ctx

The current context, providing a interface to the local state, the mode manager, as well as the hardware through its lamp object

on_enter_mode()

static void lampda::modes::BasicMode::on_enter_mode ( auto &  ctx )

inlinestatic

Custom callback when mode gains focus (optional)

Parameters

[in]

ctx

The current context

on_exit_mode()

static void lampda::modes::BasicMode::on_exit_mode ( auto &  ctx )

inlinestatic

Custom callback when mode goes outside of focus (optional)

Parameters

[in]

ctx

The current context

power_off_sequence()

static void lampda::modes::BasicMode::power_off_sequence ( auto &  ctx )

inlinestatic

Custom callback when the system powers off (optional)

Callback active only if BasicMode::hasSystemCallbacks is True

Parameters

[in]

ctx

The current context

Remarks

This must be a non-blocking function

power_on_sequence()

static void lampda::modes::BasicMode::power_on_sequence ( auto &  ctx )

inlinestatic

Custom callback when the system powers on (optional)

Callback active only if BasicMode::hasSystemCallbacks is True

Parameters

[in]

ctx

The current context

Remarks

This must be a non-blocking function

read_parameters()

static void lampda::modes::BasicMode::read_parameters ( auto &  ctx )

inlinestatic

Custom callback to read parameters from filesystem (optional)

Callback active only if BasicMode::hasSystemCallbacks is True

Parameters

[in]

ctx

The current context

sunset_update()

static void lampda::modes::BasicMode::sunset_update ( auto &  ctx, float  progress  )

inlinestatic

Custom callback when sunset mode is updated (optional)

Callback active only if BasicMode::hasSunsetAnimation is True

Parameters

[in]	ctx	The current context
[in]	progress	Between 0 and 1, progress of the sunset. At 1, the system turns off

user_thread()

static void lampda::modes::BasicMode::user_thread ( auto &  ctx )

inlinestatic

Custom secondary loop, executed in another thread (optional)

Called only if BasicMode::requireUserThread is True

Parameters

[in]

ctx

The current context

Remarks

This is executed as prologue of user::user_thread() and hence must complete quickly in order to keep the lamp responsive

write_parameters()

static void lampda::modes::BasicMode::write_parameters ( auto &  ctx )

inlinestatic

Custom callback to write parameters to filesystem (optional)

Callback active only if BasicMode::hasSystemCallbacks is True

Parameters

[in]

ctx

The current context

Member Data Documentation

hasCustomRamp

constexpr bool lampda::modes::BasicMode::hasCustomRamp = false

staticconstexpr

Toggles the use of custom ramps & BasicMode::custom_ramp_update()

Remarks

Without this set to True, manager will NOT save custom ramp value!

hasSystemCallbacks

constexpr bool lampda::modes::BasicMode::hasSystemCallbacks = false

staticconstexpr

Toggles advanced system callbacks, see list here .

Required to use any of the following:

• BasicMode::power_on_sequence(),
• BasicMode::power_off_sequence()
• BasicMode::read_parameters()
• BasicMode::write_parameters()

Remarks

By default, these callbacks are called for all modes (not only the active one) and thus should be kept minimal

requireUserThread

constexpr bool lampda::modes::BasicMode::requireUserThread = false

staticconstexpr

Toggles the use of custom BasicMode::user_thread() callback.

Remarks

When this is enabled, default is to call hardware::LampTy's show() in user::user_thread() after the BasicMode::user_thread() callback

storeId

constexpr uint32_t lampda::modes::BasicMode::storeId = 0

staticconstexpr

Store identifier for persistent storage (optional)

By default, all modes are reset upon a shutdown, providing no persistence of their state across several on/off cycles. To expose to the user a way to configure your mode in a persistent fashion, you can use:

static void loop(auto& ctx) {
  uint8_t rampValue = ctx.get_active_custom_ramp();
  // ... (use rampValue to pick a color or something) ...
}
 
static constexpr bool hasCustomRamp = true; // required

This value is configurable through user interaction with the button. If you need a persistent value, private to your mode, you can use:

static void loop(auto& ctx) {
  uint8_t indexValue = ctx.get_active_custom_index();
  // ... (use indexValue to change how something works) ...
 
  // at some point, indexValue is modified:
  indexValue += 1;
  ctx.set_active_custom_index(indexValue);
 
  // next time mode is enabled, or saved as favorite, both custom
  // values (rampValue, indexValue) are remembered by default
}
 
static constexpr bool hasCustomRamp = true; // also required

These are the two always-available persistent state that a mode can configure by default. However, for more advanced modes (like games, with a list of high-scores, for example) more flexibility can be required.

If you need such extended storage, see ContextTy::KeyProxy for usage.

If you don't need these capabilities, just ignore this identifier :)

---

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

• src/modes/include/mode_type.hpp