plugin.hpp

Go to the documentation of this file.

#ifndef _PAINLESS_MESH_PLUGIN_HPP_
#define _PAINLESS_MESH_PLUGIN_HPP_
 
#include "Arduino.h"
#include "painlessmesh/configuration.hpp"
 
#include "painlessmesh/router.hpp"
#include <utility>
#include <vector>
 
namespace painlessmesh {
 
namespace plugin {
 
class SinglePackage : public protocol::PackageInterface {
 public:
  // `from` and `dest` are the application's to fill; a package built by
  // the type constructor and sent before they are set addresses node 0,
  // not whatever the stack held.
  uint32_t from = 0;
  uint32_t dest = 0;
  router::Type routing = router::SINGLE;
  int type = 0;
  int noJsonFields = 4;
 
  SinglePackage(int type) : routing(router::SINGLE), type(type) {}
 
  SinglePackage(JsonObject jsonObj) {
    from = jsonObj["from"];
    dest = jsonObj["dest"];
    type = jsonObj["type"];
    routing = static_cast<router::Type>(jsonObj["routing"].as<int>());
  }
 
  JsonObject addTo(JsonObject&& jsonObj) const {
    jsonObj["from"] = from;
    jsonObj["dest"] = dest;
    jsonObj["routing"] = static_cast<int>(routing);
    jsonObj["type"] = type;
    return jsonObj;
  }
};
 
class BroadcastPackage : public protocol::PackageInterface {
 public:
  uint32_t from = 0;
  router::Type routing = router::BROADCAST;
  int type = 0;
  int noJsonFields = 3;
 
  BroadcastPackage(int type) : routing(router::BROADCAST), type(type) {}
 
  BroadcastPackage(JsonObject jsonObj) {
    from = jsonObj["from"];
    type = jsonObj["type"];
    routing = static_cast<router::Type>(jsonObj["routing"].as<int>());
  }
 
  JsonObject addTo(JsonObject&& jsonObj) const {
    jsonObj["from"] = from;
    jsonObj["routing"] = static_cast<int>(routing);
    jsonObj["type"] = type;
    return jsonObj;
  }
};
 
class NeighbourPackage : public plugin::SinglePackage {
 public:
  NeighbourPackage(int type) : SinglePackage(type) {
    routing = router::NEIGHBOUR;
  }
 
  NeighbourPackage(JsonObject jsonObj) : SinglePackage(jsonObj) {}
};
 
class BridgeCoordinationPackage : public plugin::BroadcastPackage {
 public:
  uint8_t priority = 5;           // Bridge priority (10=highest, 1=lowest)
  TSTRING role = "secondary";     // Role: "primary", "secondary", "standby"
  std::vector<uint32_t> peerBridges;  // List of known bridge node IDs
  uint8_t load = 0;               // Current load percentage (0-100)
  uint32_t timestamp = 0;         // Coordination timestamp
  int noJsonFields = 8;           // Base fields (3) + new fields (5)
 
  BridgeCoordinationPackage() : BroadcastPackage(613) {}
 
  BridgeCoordinationPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
    priority = jsonObj["priority"] | 5;
    role = jsonObj["role"].as<TSTRING>();
    load = jsonObj["load"] | 0;
    timestamp = jsonObj["timestamp"] | 0;
    
    // Parse peer bridge array
    if (jsonObj["peerBridges"].is<JsonArray>()) {
      JsonArray peers = jsonObj["peerBridges"];
      for (JsonVariant peer : peers) {
        peerBridges.push_back(peer.as<uint32_t>());
      }
    }
  }
 
  JsonObject addTo(JsonObject&& jsonObj) const {
    jsonObj = BroadcastPackage::addTo(std::move(jsonObj));
    jsonObj["priority"] = priority;
    jsonObj["role"] = role;
    jsonObj["load"] = load;
    jsonObj["timestamp"] = timestamp;
    
    // Add peer bridge array
    JsonArray peers = jsonObj["peerBridges"].to<JsonArray>();
    for (uint32_t peerId : peerBridges) {
      peers.add(peerId);
    }
    
    return jsonObj;
  }
 
#if ARDUINOJSON_VERSION_MAJOR < 7
  size_t jsonObjectSize() const {
    // Base fields + string length + array overhead
    size_t peerArraySize = JSON_ARRAY_SIZE(peerBridges.size()) + 
                          (peerBridges.size() * sizeof(uint32_t));
    return JSON_OBJECT_SIZE(noJsonFields) + role.length() + peerArraySize;
  }
#endif
};
 
template <typename T>
class PackageHandler : public layout::Layout<T> {
 public:
  // NOTE: scheduler is optional (defaults to nullptr) for backward
  // compatibility with existing call sites; without it we can't detect
  // the "current" task and behaviour falls back to the original one.
  // Passing the scheduler (mesh.hpp already has it as mScheduler) avoids
  // the use-after-free described below.
  void stop(Scheduler* scheduler = nullptr) {
    // If stop() is called from within the callback of one of the tasks in
    // taskList (e.g. promoteToBridge()), that task is
    // "scheduler->getCurrentTask()" at this exact moment. Disabling it,
    // clearing its callback, or letting its shared_ptr refcount drop to
    // zero here would destroy its closure - which is still on the stack,
    // in the middle of its own execution - causing a use-after-free crash
    // (same bug family as upstream issue #373, but triggered by the
    // shared_ptr refcount instead of a raw delete in onDisable).
    // Move it out of the reusable list while retaining ownership for the
    // handler's lifetime. This also protects a stop()/init() sequence inside
    // the callback: a new scheduler must receive a new task rather than
    // mutating the task that is still executing on the old scheduler.
    Task* current = scheduler ? scheduler->getCurrentTask() : nullptr;
    for (auto it = taskList.begin(); it != taskList.end();) {
      if (current != nullptr && it->get() == current) {
        // Keep the executing task alive, but remove it from the reusable
        // pool. A callback may stop() and immediately init() with a new
        // scheduler; reusing this still-running task would rewrite its
        // closure and would not attach it to that new scheduler.
        quarantinedTasks.push_back({scheduler, *it});
        it = taskList.erase(it);
        continue;
      }
      (*it)->disable();
      (*it)->setCallback(NULL);
      it = taskList.erase(it);
    }
    callbackList.clear();
  }
 
  ~PackageHandler() {
    if (taskList.size() > 0)
      Log(logger::ERROR,
          "~PackageHandler(): Always call PackageHandler::stop(scheduler) "
          "before calling this destructor");
  }
 
  bool sendPackage(const protocol::PackageInterface* pkg) {
    auto variant = protocol::Variant(pkg);
    // if single or neighbour with direction
    if (variant.routing() == router::SINGLE ||
        (variant.routing() == router::NEIGHBOUR && variant.dest() != 0)) {
      return router::send(variant, (*this));
    }
 
    // if broadcast or neighbour without direction
    if (variant.routing() == router::BROADCAST ||
        (variant.routing() == router::NEIGHBOUR && variant.dest() == 0)) {
      auto i = router::broadcast(variant, (*this), 0);
      if (i > 0) return true;
      return false;
    }
    return false;
  }
 
  void onPackage(int type, std::function<bool(protocol::Variant&)> function) {
    auto func = [function](protocol::Variant& var, std::shared_ptr<T>,
                           uint32_t) { return function(var); };
    this->callbackList.onPackage(type, func);
  }
 
  std::shared_ptr<Task> addTask(Scheduler& scheduler, unsigned long aInterval,
                                long aIterations,
                                std::function<void()> aCallback) {
    using namespace painlessmesh::logger;
    reclaimQuarantinedTasks();
    for (auto&& task : taskList) {
      if (task.use_count() == 1 && !task->isEnabled()) {
        task->set(aInterval, aIterations, aCallback, NULL, NULL);
        // Use enableDelayed() for delayed one-shot tasks to prevent immediate execution
        // This ensures tasks with intervals execute after the delay, not immediately
        if (aInterval > 0 && aIterations == TASK_ONCE) {
          task->enableDelayed();
        } else {
          task->enable();
        }
        return task;
      }
    }
 
    std::shared_ptr<Task> task =
        std::make_shared<Task>(aInterval, aIterations, aCallback);
    scheduler.addTask((*task));
    // Use enableDelayed() for delayed one-shot tasks to prevent immediate execution
    // This ensures tasks with intervals execute after the delay, not immediately
    if (aInterval > 0 && aIterations == TASK_ONCE) {
      task->enableDelayed();
    } else {
      task->enable();
    }
    taskList.push_front(task);
    return task;
  }
 
  std::shared_ptr<Task> addTask(Scheduler& scheduler,
                                std::function<void()> aCallback) {
    return this->addTask(scheduler, 0, TASK_ONCE, aCallback);
  }
 
 protected:
  void reclaimQuarantinedTasks() {
    for (auto it = quarantinedTasks.begin(); it != quarantinedTasks.end();) {
      if (it->first != nullptr &&
          it->first->getCurrentTask() == it->second.get()) {
        ++it;
        continue;
      }
      it->second->disable();
      it->second->setCallback(NULL);
      it = quarantinedTasks.erase(it);
    }
  }
 
  callback::MeshPackageCallbackList<T> callbackList;
  std::list<std::shared_ptr<Task> > taskList = {};
  // Tasks detached while their own callback is executing, paired with the
  // scheduler whose stack still references them. They become reclaimable
  // after that scheduler no longer reports the task as current.
  std::list<std::pair<Scheduler*, std::shared_ptr<Task> > > quarantinedTasks =
      {};
};
 
}  // namespace plugin
}  // namespace painlessmesh
#endif