manager_type.hpp

Go to the documentation of this file.

#ifndef MANAGER_TYPE_H
#define MANAGER_TYPE_H
 
#include <cstdint>
#include <utility>
#include <tuple>
#include <array>
 
#include <src/system/logic/alerts.h>
#include <src/system/logic/sunset_timer.h>
 
#include <src/system/utils/assert.h>
 
#include "src/modes/include/draw/overlay.hpp"
 
#include "src/modes/include/tools.hpp"
#include "src/modes/include/context_type.hpp"
#include "src/modes/include/default_config.hpp"
#include "src/modes/include/hardware/keystore.hpp"
#include "src/modes/include/hardware/lamp_type.hpp"
 
namespace lampda::modes {
 
union ActiveIndexTy
{
  struct
  {
    uint8_t groupIndex; // group id (as ordered in the manager)
    uint8_t modeIndex;  // mode id (as ordered in its group)
 
    uint8_t rampIndex;   // ramp value (as set by the user)
    uint8_t customIndex; // custom (as set by the mode)
  };
 
  uint32_t rawIndex;
 
  // static constructors
  //
  static constexpr auto from(const uint8_t* arr)
  {
    ActiveIndexTy index = {arr[0], arr[1], arr[2], arr[3]};
    return index;
  }
  static constexpr auto from(const std::array<uint8_t, 4>& arr) { return ActiveIndexTy::from(arr.data()); }
};
 
template<typename Config> struct RampHandlerTy
{
  using ConfigTy = Config;
  static constexpr uint32_t startPeriod = Config::rampStartPeriodMs;
 
  // \in stepSpeed how long to wait before incrementing (ms)
  // \in rampSaturates does the ramp saturates, or else wrap around?
  RampHandlerTy(uint32_t stepSpeed, bool rampSaturates = Config::defaultRampSaturates) :
    stepSpeed {stepSpeed},
    rampSaturates {rampSaturates},
    lastTimeMeasured {1000},
    isForward {true},
    animEffect {Config::defaultCustomRampAnimEffect},
    animChoice {Config::defaultCustomRampAnimChoice}
  {
  }
 
  void LMBD_INLINE reset()
  {
    isForward = true;
    stepSpeed = Config::defaultCustomRampStepSpeedMs;
    rampSaturates = Config::defaultRampSaturates;
    animEffect = Config::defaultCustomRampAnimEffect;
    animChoice = Config::defaultCustomRampAnimChoice;
  }
 
  void LMBD_INLINE update_ramp(uint8_t rampValue, uint32_t holdTime, auto callback)
  {
    // restart the rampage
    if (holdTime < lastTimeMeasured)
    {
      lastTimeMeasured = holdTime;
 
      if (holdTime < startPeriod)
      {
        // toggle forward / backward direction
        isForward = !isForward;
        if (rampSaturates)
        {
          if (rampValue == 0)
            isForward = true;
          if (rampValue == 255)
            isForward = false;
        }
      }
      return;
    }
 
    // count how many step we advanced
    uint32_t lastCounter = lastTimeMeasured / stepSpeed;
    uint32_t nextCounter = holdTime / stepSpeed;
    if (nextCounter <= lastCounter)
      return;
 
    // apply steps
    for (uint32_t I = 0; I < nextCounter - lastCounter; ++I)
    {
      // increment iff possible
      if (isForward && (!rampSaturates || rampValue < 255))
        rampValue += 1;
 
      // decrement iff possible
      if (!isForward && (!rampSaturates || rampValue > 0))
        rampValue -= 1;
 
      // forward value to callback
      callback(rampValue);
    }
 
    lastTimeMeasured = holdTime;
  }
 
  uint32_t stepSpeed;
  bool rampSaturates;
  bool animEffect;
  bool animChoice;
  uint32_t lastTimeMeasured;
  bool isForward;
};
 
template<typename Config, typename AllGroups, uint8_t hiddenGroupsCount> struct ModeManagerTy
{
  using SelfTy = ModeManagerTy<Config, AllGroups, hiddenGroupsCount>;
  using ConfigTy = Config;
  using AllGroupsTy = AllGroups;
  using AllStatesTy = details::StateTyFrom<AllGroups>;
 
  static constexpr uint8_t nbGroupsTotal {std::tuple_size_v<AllGroupsTy>};
  static constexpr uint8_t hiddenGroupCount = hiddenGroupsCount;
 
  static_assert(nbGroupsTotal >= hiddenGroupsCount, "Manager cannot operate without accessible groups");
 
  static constexpr uint8_t nbAccessibleGroups = nbGroupsTotal - hiddenGroupsCount;
 
  // last group index must not collide with modes::store::noGroupIndex
  static_assert(nbGroupsTotal <= 15, "Maximum of 15 groups has been exceeded.");
 
  template<uint8_t Idx> using GroupAt = std::tuple_element_t<Idx, AllGroupsTy>;
 
  // required to support manager-level context
  using HasAnyGroup = details::anyOf<AllGroupsTy>;
  static constexpr bool hasSunsetAnimation = HasAnyGroup::hasSunsetAnimation;
  static constexpr bool hasBrightCallback = HasAnyGroup::hasBrightCallback;
  static constexpr bool requireUserThread = HasAnyGroup::requireUserThread;
  static constexpr bool hasCustomRamp = HasAnyGroup::hasCustomRamp;
  static constexpr bool hasSystemCallbacks = hasCustomRamp || HasAnyGroup::hasSystemCallbacks;
  static constexpr bool hasButtonCustomUI = HasAnyGroup::hasButtonCustomUI;
 
  // useful for runtime tests of mode properties
  using EveryModeBool = details::asTableFor<AllGroupsTy>;
  static constexpr auto everySunsetCallback = EveryModeBool::everySunsetCallback;
  static constexpr auto everyBrightCallback = EveryModeBool::everyBrightCallback;
  static constexpr auto everyRequireUserThread = EveryModeBool::everyRequireUserThread;
  static constexpr auto everyCustomRamp = EveryModeBool::everyCustomRamp;
  static constexpr auto everySystemCallbacks = EveryModeBool::everySystemCallbacks;
  static constexpr auto everyButtonCustomUI = EveryModeBool::everyButtonCustomUI;
 
  // constructors
  ModeManagerTy(hardware::LampTy& lamp) : activeIndex {ActiveIndexTy::from(Config::initialActiveIndex)}, lamp {lamp} {}
 
  ModeManagerTy() = delete;
  ModeManagerTy(const ModeManagerTy&) = delete;
  ModeManagerTy& operator=(const ModeManagerTy&) = delete;
 
  auto get_context() { return ContextTy<SelfTy, SelfTy>(*this); }
 
  template<typename CallBack> static void LMBD_INLINE dispatch_group(auto& ctx, CallBack&& cb)
  {
    uint8_t groupId = ctx.get_active_group(nbGroupsTotal);
 
    details::unroll<nbGroupsTotal>([&](auto Idx) LMBD_INLINE {
      if (Idx == groupId)
      {
        cb(context_as<GroupAt<Idx>>(ctx));
      }
    });
  }
 
  template<bool systemCallbacksOnly, typename CallBack> static void LMBD_INLINE foreach_group(auto& ctx, CallBack&& cb)
  {
    if constexpr (systemCallbacksOnly)
    {
      details::unroll<nbGroupsTotal>([&](auto Idx) LMBD_INLINE {
        using GroupHere = GroupAt<Idx>;
        constexpr bool hasCallbacks = GroupHere::hasSystemCallbacks;
 
        if constexpr (hasCallbacks)
        {
          cb(context_as<GroupAt<Idx>>(ctx));
        }
      });
    }
    else
    {
      details::unroll<nbGroupsTotal>([&](auto Idx) LMBD_INLINE {
        cb(context_as<GroupAt<Idx>>(ctx));
      });
    }
  }
 
  //
  // store
  //
 
  // persistent values
  enum class Store : uint16_t
  {
    lastActive,
    modeMemory,
    usedFavoriteCount,
    favoriteModes,
    lastUsedFavorite,
    isInFavoriteGroup
  };
 
  static constexpr uint32_t storeId = modes::store::derivateStoreId<modes::store::hash("ManagerStoreId"), AllGroupsTy>;
 
  //
  // state
  //
 
  struct StateTy
  {
    AllStatesTy groupStates;
 
    std::array<uint8_t, nbGroupsTotal> lastModeMemory = {};
 
    static constexpr uint8_t maxFavoriteCount = 8;
    std::array<ActiveIndexTy, maxFavoriteCount> favorites = {};
    uint8_t usedFavoriteCount = 0; 
 
    static constexpr uint8_t defaultFavoriteCount_indexable = 6;
    static constexpr std::array<ActiveIndexTy, maxFavoriteCount> defaultFavorites_indexable = {
            ActiveIndexTy::from({0, 2, 80, 0}),
            ActiveIndexTy::from({0, 2, 165, 0}),
            ActiveIndexTy::from({0, 2, 0, 0}),
            ActiveIndexTy::from({0, 0, 0, 0}),
            ActiveIndexTy::from({0, 0, 128, 0}),
            ActiveIndexTy::from({0, 0, 255, 0}),
    };
 
    static constexpr uint8_t defaultFavoriteCount_simple = 0;
    static constexpr std::array<ActiveIndexTy, maxFavoriteCount> defaultFavorites_simple = {};
 
    static_assert(maxFavoriteCount < 16, "Maximum of 15 favorite as been exceeded");
 
    // (variables for pending favorite state machine)
    uint8_t isFavoritePending = 0;           
    uint8_t whichFavoritePending = 0;        
    bool isInDeleteFavorite = false;         
    uint8_t isFavoriteDeletePending = 0;     
    uint8_t lastFavoriteStep = 0;            
    bool isInFavoriteMockGroup = false;      
    ActiveIndexTy beforeFavoriteActiveIndex; 
    uint8_t isSunsetTimingPending = 0;       
 
    bool isLastScrollAGroupChange = false; 
    uint32_t lastScrollStopped = 0;        
 
    RampHandlerTy<Config> rampHandler = {Config::defaultCustomRampStepSpeedMs};
    RampHandlerTy<Config> scrollHandler = {Config::scrollRampStepSpeedMs};
    bool clearStripOnModeChange = Config::defaultClearStripOnModeChange;
 
    // special effects
    uint8_t skipNextFrameEffect = 0; 
 
    void reset()
    {
      lastModeMemory = {};
 
      favorites = {};
      usedFavoriteCount = 0;
 
      isFavoritePending = 0;
      whichFavoritePending = 0;
      isInDeleteFavorite = false;
      isFavoriteDeletePending = 0;
      lastFavoriteStep = 0;
      isInFavoriteMockGroup = false;
      beforeFavoriteActiveIndex = ActiveIndexTy();
      isSunsetTimingPending = 0;
 
      isLastScrollAGroupChange = false;
      lastScrollStopped = 0;
 
      skipNextFrameEffect = 0;
    }
 
    // inside lamp.config
    //  - skipFirstLedsForEffect = 0; // should the loop skip some lower LEDs?
    //  - skipFirstLedsForAmount = 0; // how many pixels to shave from the top?
 
    static void LMBD_INLINE before_enter_mode(auto& ctx)
    {
      auto& self = ctx.state;
      self.rampHandler.reset();
      self.clearStripOnModeChange = Config::defaultClearStripOnModeChange;
    }
 
    static void LMBD_INLINE after_enter_mode(auto& ctx)
    {
      auto& self = ctx.state;
      if (self.clearStripOnModeChange)
      {
        ctx.lamp.clear();
      }
    }
  };
 
  template<typename Group> StateTyOf<Group>* LMBD_INLINE getStateGroupOf()
  {
    using StateTy = StateTyOf<Group>;
    using OptionalTy = std::optional<StateTy>;
 
    StateTy* substate = nullptr;
    details::unroll<nbGroupsTotal>([&](auto Idx) LMBD_INLINE {
      using GroupHere = GroupAt<Idx>;
      constexpr bool IsHere = std::is_same_v<GroupHere, Group>;
 
      if constexpr (IsHere)
      {
        OptionalTy& opt = std::get<OptionalTy>(state.groupStates);
        if (!opt.has_value())
        {
          opt.emplace();
        }
 
        StateTy& stateHere = *opt;
        substate = &stateHere;
      }
    });
    assert(substate != nullptr && "this should not have compiled at all!");
 
    static_assert(details::ModeBelongsTo<Group, AllGroups>);
    return substate;
  }
 
  template<typename Mode> StateTyOf<Mode>& LMBD_INLINE getStateOf()
  {
    using TargetStateTy = StateTyOf<Mode>;
 
    // Mode is unknown / as no state, return placeholder
    if constexpr (std::is_same_v<TargetStateTy, NoState>)
    {
      return placeholder;
 
      // Mode is ManagerTy, return our own state
    }
    else if constexpr (std::is_same_v<TargetStateTy, StateTy>)
    {
      return state;
 
      // Mode is GroupTy, return the state of the group
    }
    else if constexpr (details::GroupBelongsTo<Mode, AllGroups>)
    {
      TargetStateTy* substate = getStateGroupOf<Mode>();
 
      if (substate == nullptr)
      {
        substate = (TargetStateTy*)&placeholder;
        assert(false && "this code should be unreachable, but is it?");
      }
 
      return *substate;
    }
    else
    {
      static_assert(details::ModeExists<Mode, AllGroups>);
 
      // Mode is somewhere in a group, search for it, return its state
      TargetStateTy* substate = nullptr;
 
      details::unroll<nbGroupsTotal>([&](auto Idx) LMBD_INLINE {
        using Group = GroupAt<Idx>;
        using AllModes = typename Group::AllModesTy;
        if constexpr (details::ModeBelongsTo<Mode, AllModes>)
        {
          substate = Group::template getStateOf<Mode>(*this);
        }
      });
      assert(substate != nullptr && "this should not have compiled at all!");
 
      if (substate == nullptr)
      {
        substate = (TargetStateTy*)&placeholder;
        assert(false && "this code should be unreachable, but is it?");
      }
 
      return *substate;
    }
  }
 
  //
  // navigation
  //
 
  static constexpr bool isGroupManager = true; 
  static constexpr bool isModeManager = true;  
 
  static void next_group(auto& ctx)
  {
    // change current group: Limited to accessible groups
    uint8_t groupIdBefore = ctx.get_active_group(nbAccessibleGroups);
    ctx.set_active_group(groupIdBefore + 1, nbAccessibleGroups);
  }
 
  static void next_mode(auto& ctx)
  {
    dispatch_group(ctx, [](auto group) {
      group.next_mode();
    });
  }
 
  static void jump_to_new_active_index(auto& ctx, const ActiveIndexTy& newActiveIndex)
  {
    // not limited to accessible groups
    ctx.set_active_group(newActiveIndex.groupIndex, nbGroupsTotal);
    ctx.set_active_mode(newActiveIndex.modeIndex);
    // just copy the other values
    ctx.modeManager.activeIndex.customIndex = newActiveIndex.customIndex;
    ctx.modeManager.activeIndex.rampIndex = newActiveIndex.rampIndex;
 
    // if ramps loaded in enter_mode != ones saved as favorite, emulate update
    if (ctx.modeManager.activeIndex.rawIndex != newActiveIndex.rawIndex)
    {
      ctx.modeManager.activeIndex = newActiveIndex;
      custom_ramp_update(ctx, ctx.get_active_custom_ramp());
    }
  }
 
  static bool jump_to_favorite(auto& ctx, uint8_t which_one, bool shouldSaveLastActiveIndex)
  {
    // sanity check
    if (ctx.state.usedFavoriteCount <= 0)
      return false;
 
    // wrap back to max number of favorites
    which_one = (which_one % ctx.state.usedFavoriteCount);
    ctx.state.lastFavoriteStep = which_one;
 
    // store last active index before jump
    if (shouldSaveLastActiveIndex)
    {
      ctx.state.beforeFavoriteActiveIndex = ctx.modeManager.activeIndex;
    }
 
    if (which_one >= ctx.state.maxFavoriteCount)
      return false;
 
    const auto targetFavorite = ctx.state.favorites[which_one];
    // reset once with the right mode
    jump_to_new_active_index(ctx, targetFavorite);
 
    // show which favorite is currently set
    overlay.clear();
    display_favorite_number_ramp(ctx, which_one, ctx.state.usedFavoriteCount, true, 1000);
 
    // indicate favorite mode entry
    ctx.blip(250);
 
    // indicate that we are now in a favorite group
    ctx.state.isInFavoriteMockGroup = true;
 
    return true;
  }
 
  static bool exit_favorite_group(auto& ctx, ActiveIndexTy newActiveIndex)
  {
    if (not ctx.state.isInFavoriteMockGroup)
      return false;
 
#ifdef LMBD_SIMULATION
    fprintf(stderr, "Exit fake favorite group\n");
#endif
    // reset favorite indicator
    ctx.state.isInFavoriteMockGroup = false;
    // return to previous state
    jump_to_new_active_index(ctx, newActiveIndex);
 
    // blip to indicate favorite mode exit
    ctx.blip(250);
 
    return true;
  }
 
  static bool set_favorite_now(auto& ctx, uint8_t which_one = 0)
  {
    // new favorite added
    if (which_one != ctx.state.maxFavoriteCount && which_one == ctx.state.usedFavoriteCount)
    {
      // augment favorite count until we reach the max
      ctx.state.usedFavoriteCount = std::min<uint8_t>(ctx.state.usedFavoriteCount + 1, ctx.state.maxFavoriteCount);
    }
 
    if (which_one < ctx.state.maxFavoriteCount)
    {
      ctx.state.favorites[which_one] = ctx.modeManager.activeIndex;
      return true;
    }
    return false;
  }
 
  static bool delete_favorite_now(auto& ctx)
  {
    // delete current
    const auto which_one = ctx.state.lastFavoriteStep;
    if (ctx.state.usedFavoriteCount > 0 and which_one < ctx.state.maxFavoriteCount)
    {
      ctx.state.usedFavoriteCount -= 1;
 
      for (uint8_t i = which_one; i < ctx.state.maxFavoriteCount - 1; ++i)
      {
        // make them all go down one spot
        ctx.state.favorites[i] = ctx.state.favorites[i + 1];
      }
      // changed favorite index, jump
      if (ctx.state.usedFavoriteCount > 0)
      {
        jump_to_favorite(ctx, which_one, false);
      }
      else
      {
        // no more favorite, restore last used mode
        exit_favorite_group(ctx, ctx.state.beforeFavoriteActiveIndex);
      }
      return true;
    }
    return false;
  }
 
  static void handle_scroll_modes(auto& ctx, uint32_t holdDuration)
  {
    auto& scrollHandler = ctx.state.scrollHandler;
    scrollHandler.isForward = false; // (always scroll modes backward)
 
    static constexpr uint32_t scrollActivationTiming = 750;
    if (holdDuration <= scrollActivationTiming)
    {
      // display the ramp and do nothing else
      overlay_animate_ramp(
              ctx, holdDuration, scrollActivationTiming, colors::PaletteGradient<colors::White, colors::Cyan>);
      return;
    }
 
    scrollHandler.update_ramp(128, holdDuration, [&](uint8_t rampValue) {
      uint8_t modeIndex = ctx.get_active_mode();
      uint8_t groupIndex = ctx.get_active_group();
      uint8_t modeCount = ctx.get_modes_count();
 
      ctx.state.isLastScrollAGroupChange = false;
 
      // we are going backward
      //
      if (rampValue < 128)
      {
        // if modeIndex is not the first, just decrement it
        if (modeIndex > 0)
        {
          ctx.set_active_mode(modeIndex - 1, modeCount);
 
          // or else decrement group, then set mode to last one
        }
        else
        {
          ctx.state.isLastScrollAGroupChange = true;
          // if groupIndex is not the first, just decrement it
          if (groupIndex > 0)
          {
            // can only access visible modes
            ctx.set_active_group(groupIndex - 1, nbAccessibleGroups);
 
            // else wrap to last group
          }
          else
          {
            // can only access visible modes
            ctx.set_active_group(nbAccessibleGroups - 1, nbAccessibleGroups);
          }
 
          // backward scroll: set mode to last one on group change
          modeCount = ctx.get_modes_count();
          ctx.set_active_mode(modeCount - 1, modeCount);
        }
 
        // we are going forward
        //
      }
      else
      {
        // if modeIndex is not the last, just increment it
        if (modeIndex + 1 < modeCount)
        {
          ctx.next_mode();
 
          // or else increment group
        }
        else
        {
          ctx.state.isLastScrollAGroupChange = true;
          // if groupIndex is not the last, just increment it
          if (groupIndex + 1 < nbAccessibleGroups)
          {
            ctx.next_group();
 
            // else wrap to first group
          }
          else
          {
            ctx.set_active_group(0, nbAccessibleGroups);
          }
 
          // forward scroll: set mode to first one on group change
          ctx.set_active_mode(0, modeCount);
        }
      }
    });
  }
 
  static void enter_hidden_group(auto& ctx, uint8_t index)
  {
    assert(index < hiddenGroupsCount);
    ctx.set_active_group(nbAccessibleGroups + index, nbGroupsTotal);
  }
 
  static bool overlay_animate_ramp(
          auto& ctx, float holdDuration, float stepSize, const colors::PaletteTy& palette, const uint32_t timeout = 0)
  {
    // where we are: 0-255 rampColorRing
    const uint32_t stepProgress = floor((holdDuration * 256.0) / stepSize);
    return overlay_animate_ramp(ctx, stepProgress % 256, palette);
  }
  static bool overlay_animate_ramp(auto& ctx,
                                   uint8_t progress,
                                   const colors::PaletteTy& palette,
                                   const uint32_t timeout = 0)
  {
    // only display on indexable
    if constexpr (ctx.lamp.flavor == hardware::LampTypes::indexable)
    {
      // if first display failed, add a new ramp and try again
      if (not overlay.update_type(ctx, draw::overlay::ElementType::RAMP, 0, progress, palette))
      {
        // add new ramp element
        overlay.add_ui_element(ctx, draw::overlay::ElementType::RAMP, palette, 0, 0, progress);
      }
 
      // if timeout is requested, update it
      if (timeout > 0)
        overlay.update_type_timeout(ctx, draw::overlay::ElementType::RAMP, 0, timeout);
    }
    else if constexpr (ctx.lamp.flavor == hardware::LampTypes::simple)
    {
      // blip at the ramp end
      if (progress >= 250)
        ctx.blip(100);
    }
    return (progress >= 250);
  }
 
  static void overlay_animate_dot(auto& ctx,
                                  uint16_t index,
                                  uint16_t positionX,
                                  uint8_t progress,
                                  const auto& palette,
                                  const uint32_t timeout = 0)
  {
    // only display on indexable
    if constexpr (ctx.lamp.flavor == hardware::LampTypes::indexable)
    {
      // if first display failed, add a new ramp and try again
      if (not overlay.update_type(ctx, draw::overlay::ElementType::DOT, index, progress, palette))
      {
        // add new element
        overlay.add_ui_element(ctx, draw::overlay::ElementType::DOT, palette, positionX, 0, progress);
      }
 
      // if timeout is requested, update it
      if (timeout > 0)
        overlay.update_type_timeout(ctx, draw::overlay::ElementType::DOT, index, timeout);
    }
  }
 
  static uint8_t get_modes_count(auto& ctx)
  {
    uint8_t value = 0;
    dispatch_group(ctx, [&](auto group) {
      value = decltype(group)::LocalModeTy::nbModes;
    });
    return value;
  }
 
  static void enter_group(auto& ctx, const uint8_t value)
  {
    // prevent value overflow
    assert(value < nbGroupsTotal);
 
    auto manager = ctx.modeManager.get_context();
 
    // signal that we are quitting the mode
    ctx.modeManager.quit_mode(manager);
 
    // switch group (after quit mode)
    ctx.modeManager.activeIndex.groupIndex = value;
    // switch mode (restore last stored id)
    ctx.modeManager.activeIndex.modeIndex = ctx.state.lastModeMemory[value];
 
    // signal that we entered a new mode
    ctx.modeManager.enter_mode(manager);
  }
 
  static void quit_group(auto& ctx)
  {
    //
    uint8_t modeIdBefore = ctx.get_active_mode();
 
    // changes to lastModeMemory made in this function will be persistent
    auto keyModeMemory = ctx.template storageFor<Store::modeMemory>(ctx.state.lastModeMemory);
 
    // save last mode used in group, before switching
    uint8_t groupIdBefore = ctx.get_active_group(nbGroupsTotal);
    ctx.state.lastModeMemory[groupIdBefore] = modeIdBefore;
  }
 
  static void enter_mode(auto& ctx)
  {
    ctx.state.before_enter_mode(ctx);
 
    // enter mode
    dispatch_group(ctx, [](auto group) {
      group.enter_mode();
    });
 
    ctx.state.after_enter_mode(ctx);
  }
 
  static void quit_mode(auto& ctx)
  {
    dispatch_group(ctx, [](auto group) {
      group.quit_mode();
    });
  }
 
  //
  // all the callbacks
  //
 
  static void loop(auto& ctx)
  {
    // handle pending favorite
    if (ctx.state.isFavoritePending > 0)
    {
      ctx.state.isFavoritePending -= 1;
 
      if (ctx.state.isFavoritePending == 0 && ctx.state.whichFavoritePending <= ctx.state.usedFavoriteCount)
      {
        if (ctx.set_favorite_now(ctx.state.whichFavoritePending))
        {
          logic::alerts::manager.raise(logic::alerts::Type::FAVORITE_SET);
        }
      }
    }
 
    // handle favorite delete
    if (ctx.state.isFavoriteDeletePending > 0)
    {
      ctx.state.isFavoriteDeletePending -= 1;
 
      // delete favorite
      if (ctx.state.isFavoriteDeletePending == 0)
      {
        ctx.delete_favorite_now();
      }
    }
 
    // handle the sunset timer update
    if (ctx.state.isSunsetTimingPending > 0)
    {
      ctx.state.isSunsetTimingPending -= 1;
      if (ctx.state.isSunsetTimingPending == 0)
      {
        // set and update sunset timer
        logic::sunset::add_time_minutes(5);
        // blip AFTER the update
        ctx.blip(50);
      }
    }
 
    if (ctx.lamp.config.skipFirstLedsForEffect > 0)
    {
      ctx.lamp.config.skipFirstLedsForEffect -= 1;
    }
 
    if (ctx.state.skipNextFrameEffect > 0)
    {
      ctx.state.skipNextFrameEffect -= 1;
 
      // reached last skip frame, restore mode
      if (ctx.state.skipNextFrameEffect == 0)
      {
        ctx.lamp.restoreBrightness();
      }
      return;
    }
 
    ctx.lamp.refresh_tick_value();
 
    // udpate modes and groups
    dispatch_group(ctx, [](auto group) {
      group.loop();
    });
 
    // display the overlay after the group update
    overlay.display_update(ctx);
  }
 
  static void sunset_update(auto& ctx, float progress)
  {
    dispatch_group(ctx, [&](auto group) {
      group.sunset_update(progress);
    });
  }
 
  static void brightness_update(auto& ctx, brightness_t brightness)
  {
    dispatch_group(ctx, [&](auto group) {
      group.brightness_update(brightness);
    });
  }
 
  static void power_on_sequence(auto& ctx)
  {
    // start with tick value
    ctx.lamp.refresh_tick_value();
 
    foreach_group<true>(ctx, [](auto group) {
      group.power_on_sequence();
    });
 
    // activate last used favorite, in the favorite group
    if (ctx.state.isInFavoriteMockGroup and jump_to_favorite(ctx, ctx.state.lastFavoriteStep, false))
    {
      // success jump to favorite
    }
    else
    {
      // activate current mode
      uint8_t groupIdBefore = ctx.get_active_group(nbGroupsTotal);
      ctx.set_active_group(groupIdBefore);
    }
  }
 
  static void power_off_sequence(auto& ctx)
  {
    foreach_group<true>(ctx, [](auto group) {
      group.power_off_sequence();
    });
  }
 
  static void write_parameters(auto& ctx)
  {
    // clear the stored parameters, before storing ours.
    store::clear_stored();
 
    // this scope is the only one where parameters will be kept
    ctx.template storageSaveOnly<Store::lastActive>(ctx.modeManager.activeIndex);
 
    // save the maxFavoriteCount possible favorites
    ctx.template storageSaveOnly<Store::usedFavoriteCount>(ctx.modeManager.state.usedFavoriteCount);
    ctx.template storageSaveOnly<Store::favoriteModes>(ctx.modeManager.state.favorites);
    ctx.template storageSaveOnly<Store::lastUsedFavorite>(ctx.modeManager.state.lastFavoriteStep);
    ctx.template storageSaveOnly<Store::isInFavoriteGroup>(ctx.state.isInFavoriteMockGroup);
    ctx.template storageSaveOnly<Store::modeMemory>(ctx.state.lastModeMemory);
 
    foreach_group<not hasCustomRamp>(ctx, [&ctx](auto group) {
      if constexpr (group.hasCustomRamp)
      {
        using StoreHere = typename decltype(group)::StoreEnum;
        group.template storageSaveOnly<StoreHere::rampMemory>(group.state.customRampMemory);
        group.template storageSaveOnly<StoreHere::indexMemory>(group.state.customIndexMemory);
      }
 
      group.write_parameters();
    });
  }
 
  static void read_parameters(auto& ctx)
  {
    // Reset the states before reading the parameters
    ctx.state.reset();
 
    // remove old filesystem data if we detect obsolete "storeId" serial
    using LocalStore = details::LocalStoreOf<decltype(ctx)>;
    LocalStore::template migrateStoreIfNeeded<storeId>();
 
    // load last active mode and active ramp, or default index
    ctx.template storageLoadOnly<Store::lastActive>(ctx.modeManager.activeIndex,
                                                    ActiveIndexTy::from(Config::initialActiveIndex));
 
    if constexpr (ctx.lamp.flavor == hardware::LampTypes::indexable)
    {
      // load the maxFavoriteCount possible favorites, or default favorites, for indexable
      ctx.template storageLoadOnly<Store::usedFavoriteCount>(ctx.modeManager.state.usedFavoriteCount,
                                                             ctx.modeManager.state.defaultFavoriteCount_indexable);
      ctx.template storageLoadOnly<Store::favoriteModes>(ctx.state.favorites,
                                                         ctx.modeManager.state.defaultFavorites_indexable);
    }
    else if constexpr (ctx.lamp.flavor == hardware::LampTypes::simple)
    {
      // load the maxFavoriteCount possible favorites, or default favorites, for simple
      ctx.template storageLoadOnly<Store::usedFavoriteCount>(ctx.modeManager.state.usedFavoriteCount,
                                                             ctx.modeManager.state.defaultFavoriteCount_simple);
      ctx.template storageLoadOnly<Store::favoriteModes>(ctx.state.favorites,
                                                         ctx.modeManager.state.defaultFavorites_simple);
    }
 
    ctx.template storageLoadOnly<Store::lastUsedFavorite>(ctx.modeManager.state.lastFavoriteStep);
    ctx.template storageLoadOnly<Store::isInFavoriteGroup>(ctx.state.isInFavoriteMockGroup);
    ctx.template storageLoadOnly<Store::modeMemory>(ctx.state.lastModeMemory);
 
    // for each group, migrate & handle custom ramp memory
    foreach_group<not hasCustomRamp>(ctx, [&ctx](auto group) {
      using LocalStore = details::LocalStoreOf<decltype(group)>;
      LocalStore::template migrateStoreIfNeeded<storeId>();
 
      if constexpr (group.hasCustomRamp)
      {
        using StoreHere = typename LocalStore::EnumTy;
        // Get saved ramp values, or default values pulled from modes
        group.template storageLoadOnly<StoreHere::rampMemory>(group.state.customRampMemory,
                                                              group.template get_custom_ramp_default_value());
        group.template storageLoadOnly<StoreHere::indexMemory>(group.state.customIndexMemory);
      }
 
      group.read_parameters();
    });
  }
 
  static void user_thread(auto& ctx)
  {
    dispatch_group(ctx, [](auto group) {
      group.user_thread();
    });
  }
 
  static void custom_ramp_update(auto& ctx, uint8_t rampValue, uint32_t timeout = 0)
  {
    uint8_t groupId = ctx.get_active_group();
    uint8_t modeId = ctx.get_active_mode();
 
    if (ctx.everyCustomRamp[groupId][modeId] && ctx.state.rampHandler.animEffect)
    {
      switch (ctx.state.rampHandler.animChoice)
      {
        case 0:
          overlay_animate_ramp(ctx, rampValue, modes::colors::PaletteBlackBodyColors, timeout);
          break;
 
        case 1:
          overlay_animate_ramp(ctx, rampValue, modes::colors::PaletteRainbowColors, timeout);
          break;
      }
    }
 
    dispatch_group(ctx, [&](auto group) {
      group.custom_ramp_update(rampValue);
    });
  }
 
  static bool custom_click(auto& ctx, uint8_t nbClick)
  {
    bool retVal = false;
    dispatch_group(ctx, [&](auto group) {
      retVal = group.custom_click(nbClick);
    });
    return retVal;
  }
 
  static bool custom_hold(auto& ctx, uint8_t nbClickAndHold, bool isEndOfHoldEvent, uint32_t holdDuration)
  {
    bool retVal = false;
    dispatch_group(ctx, [&](auto group) {
      retVal = group.custom_hold(nbClickAndHold, isEndOfHoldEvent, holdDuration);
    });
    return retVal;
  }
 
  //
  // Private action functions
  //
 
  static void display_favorite_number_ramp(auto& ctx,
                                           const uint8_t favoriteIndex,
                                           const uint8_t maxFavoriteIndex,
                                           const bool display = false,
                                           const uint32_t timeout = 0)
  {
    const uint8_t maxPixelDisplay = std::min<uint8_t>(ctx.state.maxFavoriteCount, maxFavoriteIndex);
    for (uint8_t i = 0; i < maxPixelDisplay; ++i)
    {
      const bool shouldDisplay = (display and i <= favoriteIndex);
      overlay_animate_dot(
              ctx, i, i, shouldDisplay ? 255 : 0, colors::PaletteGradient<colors::Black, colors::Cyan>, timeout);
    }
  }
 
  static uint8_t get_number_of_allowed_favorites(auto& ctx)
  {
    // user as a number of favorite set
    // occasional +1 if not all favorite are set (allow a new favorite)
    return ctx.state.usedFavoriteCount + ((ctx.state.usedFavoriteCount < ctx.state.maxFavoriteCount) ? 1 : 0);
  }
 
  template<bool displayFavoriteNumber = true>
  static void set_current_mode_as_favorite(auto& ctx, uint8_t favoriteIndex, uint32_t displayTimeout_s = 0)
  {
    const uint8_t numberOfFavoriteSet = get_number_of_allowed_favorites(ctx);
    if (favoriteIndex >= numberOfFavoriteSet)
    {
      bsp::lampda_print(
              "Cannot set a favorite at index %d, max index must be less than %d", favoriteIndex, numberOfFavoriteSet);
      return;
    }
 
    // extra display on the first pixels (count pixels to know fav no)
    if constexpr (displayFavoriteNumber)
    {
      // display the set favorite ramp
      display_favorite_number_ramp(
              ctx, favoriteIndex, numberOfFavoriteSet, favoriteIndex < numberOfFavoriteSet, displayTimeout_s);
    }
 
    // set this, after a while upon no longer holding button, favorite is set
    ctx.state.isFavoritePending = 10;
    ctx.state.whichFavoritePending = favoriteIndex;
  }
 
  template<bool displayFavoriteNumber = true>
  static void animate_favorite_pick(auto& ctx, float holdDuration, float stepSize)
  {
    const uint8_t numberOfFavoriteSet = get_number_of_allowed_favorites(ctx);
 
    // up to maxFavoriteCount step state: "which_one" is [0, 1, 2, 3, ...] and "do not set" is the max index + 1
    uint32_t stepCount = numberOfFavoriteSet + floor(holdDuration / stepSize);
    stepCount = stepCount % (numberOfFavoriteSet + 1);
 
    // display ramp to show where user is standing
    if (stepCount >= numberOfFavoriteSet)
    {
      // cancel action
      ctx.state.isFavoritePending = 0;
 
      // display ramp for the first time to allow the user to cancel the action
      if (holdDuration <= 2 * stepSize)
      {
        overlay_animate_ramp(ctx, holdDuration, stepSize, colors::PaletteGradient<colors::White, colors::Cyan>);
      }
    }
    else
    {
      // green ramp : favorites
      overlay_animate_ramp(ctx, holdDuration, stepSize, colors::PaletteGradient<colors::Green, colors::White>);
 
      // Set the favorite: this actually do not set it immediatly but waits until the function is not called anymores
      set_current_mode_as_favorite<displayFavoriteNumber>(ctx, stepCount);
    }
  }
 
  template<bool displayFavoriteNumber = true>
  static void animate_favorite_delete(auto& ctx, float holdDuration, float stepSize)
  {
    // no favorite deletion if no favorites
    if (ctx.state.usedFavoriteCount <= 0)
      return;
 
    ctx.state.isInDeleteFavorite = true;
 
    uint32_t stepCount = floor(holdDuration / stepSize);
    stepCount = stepCount % 2;
 
    if (stepCount == 0)
    {
      if (overlay_animate_ramp(ctx, holdDuration, stepSize, colors::PaletteGradient<colors::Orange, colors::Red>))
      {
        // set this on ramp saturation. The favorite will be removed in 2 frames
        ctx.state.isFavoriteDeletePending = 2;
      }
      else
      {
        // no deletion if release on ramp
        ctx.state.isFavoriteDeletePending = 0;
      }
 
      // extra display on the first pixels (count pixels to know fav no)
      if constexpr (displayFavoriteNumber)
      {
        // display ramp
        display_favorite_number_ramp(ctx, ctx.state.lastFavoriteStep, ctx.state.usedFavoriteCount, true);
      }
    }
    // else: do nothing
  }
 
  //
  // members with direct access
  //
 
  ActiveIndexTy activeIndex;
 
  hardware::LampTy& lamp;
 
  inline static draw::overlay::Manager<> overlay;
 
  //
  // private members
  //
 
private:
  NoState placeholder;
  StateTy state;
};
 
template<typename ManagerConfig, typename... Groups> using ManagerForConfig =
        ModeManagerTy<ManagerConfig, std::tuple<Groups...>, 0>;
 
template<typename... Groups> using ManagerFor = ModeManagerTy<DefaultManagerConfig, std::tuple<Groups...>, 0>;
 
template<uint8_t hiddenGroupCnt, typename... Groups> using ManagerForHiddenGroups =
        ModeManagerTy<DefaultManagerConfig, std::tuple<Groups...>, hiddenGroupCnt>;
 
template<uint8_t hiddenGroupCnt, typename ManagerConfig, typename... Groups> using ManagerFoHiddenConfig =
        ModeManagerTy<ManagerConfig, std::tuple<Groups...>, hiddenGroupCnt>;
 
} // namespace lampda::modes
 
#endif