device.h

Go to the documentation of this file.

#pragma once
 
#include <chrono>
#include <cstdint>
#include <cstring>
#include <deque>
#include <expected>
#include <format>
#include <map>
#include <memory>
#include <mutex>
#include <nlohmann/json_fwd.hpp>
#include <optional>
#include <span>
#include <string>
#include <type_traits>
#include <unordered_map>
#include <utility>
#include <variant>
#include <vector>
 
#include "comm/fieldbus_driver.h"
#include "node/device_parameter.h"
#include "node/pdo_mapping.h"
 
namespace mm::node {
 
struct ProcessData;
 
class ParameterCache;
 
enum class CompleteAccessSupport : uint8_t { kUnknown, kSupported, kUnsupported };
 
enum class DeclaredSubindexReads : uint8_t { kUnknown, kServed, kRefused };
 
struct ObjectValues {
  uint16_t index = 0;                              
  std::map<uint8_t, DeviceParameterValue> values;  
 
  template <typename T>
  std::expected<T, std::string> get(uint8_t subindex) const {
    auto it = values.find(subindex);
    if (it == values.end()) {
      return std::unexpected(
          std::format("object 0x{:04X} has no readable subindex {:02X}", index, subindex));
    }
    if (const auto* p = std::get_if<T>(&it->second)) {
      return *p;
    }
    return std::unexpected(
        std::format("parameter 0x{:04X}:{:02X} holds a different type", index, subindex));
  }
};
 
class Device {
 public:
  Device(uint16_t slavePosition, mm::comm::FieldbusDriver& driver,
         ProcessData* processData = nullptr, const ParameterCache* parameterCache = nullptr);
 
  uint16_t slavePosition() const;
 
  const std::string& name() const;
 
  std::string productName() const;
 
  uint32_t vendorId() const;
 
  uint32_t productCode() const;
 
  uint32_t revisionNumber() const;
 
  uint32_t serialNumber() const;
 
  bool isCia402() const;
 
  bool mailboxActive() const;
 
  bool supportsCoe() const;
 
  bool supportsEsc() const;
 
  bool supportsLocate() const;
 
  std::optional<uint8_t> escType() const;
 
  bool mailboxWriteOnce() const;
 
  std::expected<void, std::string> locate(bool on) const;
 
  std::expected<mm::comm::FieldbusDriver::FirmwareActivation, std::string> activateFirmware(
      std::chrono::steady_clock::duration timeout) const;
 
  bool exchangesProcessData() const;
 
  std::expected<std::vector<uint8_t>, std::string> readSdo(uint16_t index, uint8_t subindex) const;
 
  std::expected<void, std::string> writeSdo(uint16_t index, uint8_t subindex,
                                            std::span<const uint8_t> data) const;
 
  std::expected<std::vector<uint8_t>, mm::comm::FoeError> readFile(
      const std::string& filename,
      std::chrono::milliseconds timeout = mm::comm::kFoeReadTimeout) const;
 
  std::expected<void, mm::comm::FoeError> writeFile(const std::string& filename,
                                                    std::span<const uint8_t> data) const;
 
  std::expected<void, std::string> readRegister(uint16_t address, std::span<uint8_t> data) const;
 
  std::expected<void, std::string> writeRegister(uint16_t address,
                                                 std::span<const uint8_t> data) const;
 
  std::expected<std::vector<uint8_t>, std::string> readSii() const;
 
  std::expected<void, std::string> writeSii(std::span<const uint8_t> data) const;
 
  std::expected<void, std::string> initializeParameters(bool readValues = false,
                                                        bool useCompleteAccess = true);
 
  std::expected<void, std::string> readFlatPdoMapping();
 
  const FlatPdoMapping& flatPdoMapping() const;
 
  std::expected<PdoMapping, std::string> readPdoMapping();
 
  std::expected<void, std::string> writePdoMapping(const PdoMapping& mapping);
 
  std::expected<DeviceParameterValue, std::string> setValueFromBytes(
      uint16_t index, uint8_t subindex, std::span<const uint8_t> bytes);
 
  bool hasParameters() const;
 
  bool parametersUnavailable() const;
 
  std::vector<DeviceParameter> parametersOrdered() const;
 
  std::optional<DeviceParameter> parameter(uint16_t index, uint8_t subindex) const;
 
  std::optional<DeviceParameterValue> parameterValue(uint16_t index, uint8_t subindex) const;
 
  std::optional<uint16_t> dataType(uint16_t index, uint8_t subindex) const;
 
  std::expected<DeviceParameterValue, std::string> readParameter(uint16_t index, uint8_t subindex);
 
  std::expected<void, std::string> readAllParameters(bool useCompleteAccess = true);
 
  std::expected<ObjectValues, std::string> readObject(uint16_t index,
                                                      bool useCompleteAccess = true);
 
  std::expected<void, std::string> writeParameter(uint16_t index, uint8_t subindex,
                                                  const DeviceParameterValue& newValue);
 
  template <typename T>
  std::expected<void, std::string> writeValue(uint16_t index, uint8_t subindex, T newValue) {
    return writeParameter(index, subindex, DeviceParameterValue{newValue});
  }
 
  template <typename T>
  std::expected<T, std::string> readValue(uint16_t index, uint8_t subindex) {
    auto v = readParameter(index, subindex);
    if (!v) {
      return std::unexpected(v.error());
    }
    if (const auto* p = std::get_if<T>(&*v)) {
      return *p;
    }
    return std::unexpected(
        std::format("parameter 0x{:04X}:{:02X} holds a different type", index, subindex));
  }
 
  template <typename T>
  std::expected<T, std::string> readValue(ObjectAddress<T> address) {
    return readValue<T>(address.index, address.subindex);
  }
 
  template <typename T>
  std::expected<void, std::string> writeValue(ObjectAddress<T> address, T newValue) {
    return writeValue<T>(address.index, address.subindex, std::move(newValue));
  }
 
  template <typename T>
  std::expected<T, std::string> readCachedValue(uint16_t index, uint8_t subindex) {
    {
      std::lock_guard<std::mutex> lock(*parametersMutex_);
      if (const DeviceParameter* p = findParameter(index, subindex);
          p && p->syncState == SyncState::Synced) {
        return p->getValue<T>();
      }
    }
    return readValue<T>(index, subindex);  // never read: fetch once — readValue marks it Synced.
  }
 
  DeviceParameter* findParameter(uint16_t index, uint8_t subindex);
 
  const DeviceParameter* findParameter(uint16_t index, uint8_t subindex) const;
 
  template <typename T>
  std::optional<T> value(uint16_t index, uint8_t subindex) const {
    const DeviceParameter* p = findParameter(index, subindex);
    if (p == nullptr) {
      return std::nullopt;
    }
    return p->scalar<T>();
  }
 
  template <typename T>
  bool setValue(uint16_t index, uint8_t subindex, T newValue) {
    static_assert(std::is_arithmetic_v<T>, "the cell holds arithmetic types only");
    static_assert(sizeof(T) <= sizeof(uint64_t), "the cell holds at most eight bytes");
    const DeviceParameter* p = findParameter(index, subindex);
    if (p == nullptr || !std::holds_alternative<T>(defaultValueForDataType(p->dataType))) {
      return false;
    }
    uint64_t bits = 0;
    std::memcpy(&bits, &newValue, sizeof(T));
    p->storeBits(bits);
    return true;
  }
 
  template <typename T>
  std::optional<T> value(ObjectAddress<T> address) const {
    return value<T>(address.index, address.subindex);
  }
 
  template <typename T>
  bool setValue(ObjectAddress<T> address, T newValue) {
    return setValue<T>(address.index, address.subindex, newValue);
  }
 
 private:
  void publishParameters(std::unordered_map<uint32_t, DeviceParameter>&& built);
 
  void readParameterValues(std::vector<DeviceParameter>& defs, bool useCompleteAccess);
 
  void markReadFailed(uint16_t index, uint8_t subindex, uint16_t declaredType);
 
  bool recordDeclaredSubindexRead(bool ok);
 
  bool declaredSubindexReadsWorthTrying() const;
 
  bool readObjectComplete(uint16_t index, std::span<const uint8_t> subindices,
                          bool useCompleteAccess);
 
  std::expected<std::vector<PdoMappingObject>, std::string> readPdoAssignment(
      uint16_t assignmentIndex);
 
  std::expected<FlatPdoMapping, std::string> readSiiPdoMapping();
 
  std::expected<std::vector<DeviceParameter>, std::string> buildSiiParameterDefinitions();
 
  uint16_t slavePosition_;
  mm::comm::FieldbusDriver& driver_;
  // Live process-data runtime, or nullptr for SDO-only operation. Injected by DeviceManager so
  // read/writeParameter can prefer PDO over SDO while exchanging. Non-owning; the owner
  // (DeviceManager) outlives every Device it created. A raw pointer keeps Device
  // move-constructible.
  ProcessData* processData_ = nullptr;
  // On-disk parameter-definition cache, or nullptr to always enumerate live. Non-owning; owned by
  // DeviceManager, which outlives every Device. Consulted only by initializeParameters.
  const ParameterCache* parameterCache_ = nullptr;
  std::string name_;
  uint32_t vendorId_;
  uint32_t productCode_;
  uint32_t revisionNumber_;
  uint32_t serialNumber_;
  // EEPROM mailbox-protocol bits, copied at construction. Immutable like the identity fields above,
  // and cached for the same reason the constructor explains: reading it from the driver on demand
  // would take the control-plane mutex and so block behind whatever bus operation holds it.
  uint16_t mailboxProtocols_ = 0;
  // Transport capabilities, copied at construction for the reason given above.
  bool supportsEsc_ = true;
  bool supportsLocate_ = false;
  std::optional<uint8_t> escType_;
  bool mailboxWriteOnce_ = false;
  // Guards parameters_ (and caSupport_) against the off-RT monitoring threads (the refresher
  // refreshes cached values, the sampler reads them) racing the control-plane thread.
  //
  // **Never held across bus I/O.** Every method that reads or writes the bus — readParameter,
  // writeParameter, readObjectComplete, readAllParameters, initializeParameters — takes it, decides
  // what to transfer, releases it for the transfer, and re-takes it to commit. That is not a
  // micro-optimisation: a mailbox transfer queues behind the driver's control-plane mutex, which an
  // FoE file transfer holds for its whole multi-second duration, so a lock held across "one mailbox
  // round-trip" is in fact held for as long as any unrelated bus traffic takes. With a background
  // parameter refresh and a user on the FoE page — the ordinary configuration, not a rare one —
  // that stalled every cached read of the device.
  //
  // The rule this imposes on callers: a DeviceParameter* must never be carried across the release,
  // because initializeParameters replaces the whole map. Re-find after the transfer, and treat a
  // miss (or a changed dataType) as "re-enumerated mid-transfer" rather than assuming it cannot
  // happen.
  //
  // Held by unique_ptr because std::mutex is neither movable nor copyable, and Device is moved
  // into DeviceManager's std::vector<Device> (which relocates on growth). The indirection keeps
  // Device move-constructible (the pointer moves); a Device is never copied, only moved.
  std::unique_ptr<std::mutex> parametersMutex_;
 
  std::expected<void, std::string> readParameterDefinitions(bool readValues,
                                                            bool useCompleteAccess);
 
  bool parametersUnavailable_ = false;
  // The cells themselves, and they are never destroyed while this Device lives. A re-enumeration
  // rebuilds the *map* above, reuses every cell whose declaration is unchanged, and appends a cell
  // for anything new; it never erases one. So a DeviceParameter* held by a published process image
  // stays valid across a re-enumeration — which is the point, because buildProcessImage resolves
  // that pointer once and the RT decode dereferences it every cycle without re-checking anything.
  // A cyclic task's own lookups are valid for the body of one cycle, not across cycles: the Device
  // dies with its DeviceSet once the last holder releases it.
  //
  // A deque because the standard says an insertion at either end invalidates iterators but leaves
  // *references* to existing elements valid ([deque.modifiers]) — and pointers into it are exactly
  // what everything above holds. It allocates in blocks, so a cell costs no allocation of its own.
  //
  // std::vector is not an option and reserve() does not rescue it: the count is unknown until the
  // dictionary is read, a later enumeration can add objects a firmware update introduced, and the
  // one growth past capacity would dangle every pointer at once, silently and far from the cause.
  // std::list and vector<unique_ptr<DeviceParameter>> are address-stable too, at one allocation per
  // cell and an extra indirection, for nothing gained: nothing indexes this container, and no code
  // on the RT path iterates it (the decode walks the image's entries instead).
  //
  // Behind a unique_ptr so that moving a Device — DeviceManager builds its vector<Device> by
  // emplacing — never moves the deque object itself, and the question of whether a moved deque
  // preserves element addresses never has to be asked.
  std::unique_ptr<std::deque<DeviceParameter>> cells_;
  // (index, subindex) -> the cell that holds that object's value. Replaced wholesale by
  // publishParameters; the cells it points at outlive every replacement.
  std::unordered_map<uint32_t, DeviceParameter*> parameters_;
  // Maps kept alive because the RT cycle did not drain before they were replaced. A cyclic task may
  // still be walking one, and freeing it then is a use-after-free. They are only ever added
  // to, which is bounded by how many times a drain fails — an emergency that is logged each time.
  std::vector<std::unordered_map<uint32_t, DeviceParameter*>> retiredMaps_;
  FlatPdoMapping flatPdoMapping_;
  // Discovered Complete Access support (the probe outcome), shared by every grouped read for the
  // device's lifetime. Read and written only under parametersMutex_.
  CompleteAccessSupport caSupport_ = CompleteAccessSupport::kUnknown;
  // Whether this device serves a subindex above its object's stated count -- see
  // DeclaredSubindexReads. Learned by the read sweeps and kept for the device's lifetime. Read and
  // written only under parametersMutex_.
  DeclaredSubindexReads declaredSubindexReads_ = DeclaredSubindexReads::kUnknown;
};
 
void to_json(nlohmann::json& j, const Device& d);
 
std::expected<int, std::string> reconcileDetectedModules(const Device& device);
 
}  // namespace mm::node