device_manager.h

Go to the documentation of this file.

#pragma once
 
#include <atomic>
#include <chrono>
#include <cstdint>
#include <expected>
#include <iosfwd>
#include <memory>
#include <nlohmann/json_fwd.hpp>
#include <optional>
#include <shared_mutex>
#include <span>
#include <string>
#include <vector>
 
#include "comm/fieldbus_driver.h"
#include "node/device.h"
#include "node/parameter_cache.h"
#include "node/process_data_ring.h"
#include "node/process_image.h"
 
namespace mm::node {
 
struct ProcessData;
 
struct DeviceStateInfo {
  uint16_t slavePosition;  
  uint16_t alStatus;       
  uint16_t alState;  
  bool error;        
  uint16_t alStatusCode;  
};
 
void to_json(nlohmann::json& j, const DeviceStateInfo& info);
 
struct ProcessImageObjectInfo {
  uint16_t slavePosition = 0;  
  uint16_t index = 0;          
  uint8_t subindex = 0;        
  std::string name;            
  uint32_t bitOffset = 0;      
  uint16_t bitLength = 0;      
};
 
struct ProcessImageInfo {
  bool configured = false;      
  uint32_t outputBytes = 0;     
  uint32_t inputBytes = 0;      
  int expectedWkc = 0;          
  int lastWkc = 0;              
  bool healthy = false;         
  std::size_t generations = 0;  
  std::vector<ProcessImageObjectInfo> outputs;  
  std::vector<ProcessImageObjectInfo> inputs;   
};
 
void to_json(nlohmann::json& j, const ProcessImageObjectInfo& obj);
 
void to_json(nlohmann::json& j, const ProcessImageInfo& info);
 
struct OutputStageRequest {
  uint16_t slavePosition = 0;  
  uint16_t index = 0;          
  uint8_t subindex = 0;        
  DeviceParameterValue value;  
};
 
struct OutputStageResult {
  uint16_t slavePosition = 0;  
  uint16_t index = 0;          
  uint8_t subindex = 0;        
  bool staged = false;         
  std::string error;           
};
 
void to_json(nlohmann::json& j, const OutputStageResult& result);
 
struct SlaveConfigInfo {
  mm::comm::SlaveConfig config;  
  std::string deviceName;        
  // Immutable identity, denormalised from the Device for this slave position (like deviceName) so
  // the Configuration page can show it without a second endpoint. Zero when the slave is unknown.
  uint32_t vendorId = 0;        
  uint32_t productCode = 0;     
  uint32_t revisionNumber = 0;  
  uint32_t serialNumber = 0;    
};
 
void to_json(nlohmann::json& j, const SlaveConfigInfo& info);
 
struct DeviceDiagnosticsInfo {
  mm::comm::SlaveDiagnostics diagnostics;  
  std::string deviceName;  
};
 
void to_json(nlohmann::json& j, const DeviceDiagnosticsInfo& info);
 
struct DcSyncInfo {
  mm::comm::DcSyncDiagnostics dcSync;  
  std::string deviceName;              
};
 
void to_json(nlohmann::json& j, const DcSyncInfo& info);
 
struct DeviceManagerConfig {
  bool readObjectDictionaryOnPreop = true;
  bool useCompleteAccess = true;
  std::string recorderDumpDir;
  uint32_t recorderCapacity = 300000;
};
 
class DeviceManager {
 public:
  DeviceManager();
 
  ~DeviceManager();
 
  std::expected<void, std::string> init(std::unique_ptr<mm::comm::FieldbusDriver> driver,
                                        const DeviceManagerConfig& config = {});
 
  void configureParameterCache(const ParameterCacheConfig& config);
 
  const ParameterCache& parameterCache() const;
 
  std::expected<int, std::string> scan();
 
  void reset();
 
  bool initialised() const { return driver_ != nullptr; }
 
  const std::vector<Device>& devices() const;
 
  const Device* findDevice(uint16_t slavePosition) const;
 
  Device* findDevice(uint16_t slavePosition);
 
  uint64_t topologyGeneration() const;
 
  std::expected<void, std::string> configureProcessData();
 
  void exchangeProcessData();
 
  bool processDataConfigured() const;
 
  uint64_t processImageGeneration() const;
 
  int lastWorkingCounter() const;
 
  int expectedWorkingCounter() const;
 
  bool processDataHealthy() const;
 
  ProcessImageInfo processImageInfo() const;
 
  std::expected<std::string, std::string> dumpProcessData();
 
  std::expected<std::string, std::string> dumpProcessDataBuffer();
 
  std::vector<SlaveConfigInfo> busConfig() const;
 
  std::expected<std::vector<DeviceStateInfo>, std::string> transitionToState(
      const std::vector<uint16_t>& positions, mm::comm::EtherCatState targetState,
      std::chrono::steady_clock::duration timeout);
 
  std::expected<std::vector<DeviceStateInfo>, std::string> getDeviceStates(
      const std::vector<uint16_t>& positions);
 
  std::expected<std::vector<DeviceDiagnosticsInfo>, std::string> getDeviceDiagnostics(
      const std::vector<uint16_t>& positions);
 
  std::expected<std::vector<DcSyncInfo>, std::string> getDcSync(
      const std::vector<uint16_t>& positions);
 
  std::expected<mm::comm::ProcessDataWatchdogConfig, std::string> getProcessDataWatchdog(
      uint16_t slavePosition);
 
  std::expected<mm::comm::ProcessDataWatchdogConfig, std::string> setProcessDataWatchdog(
      uint16_t slavePosition, std::chrono::nanoseconds timeout);
 
  std::expected<void, std::string> initializeDeviceParameters(uint16_t slavePosition,
                                                              bool readValues);
 
  std::expected<void, std::string> readAllDeviceParameters(uint16_t slavePosition);
 
  std::expected<DeviceParameterValue, std::string> readDeviceParameter(uint16_t slavePosition,
                                                                       uint16_t index,
                                                                       uint8_t subindex);
 
  std::expected<DeviceParameter, std::string> deviceParameterView(uint16_t slavePosition,
                                                                  uint16_t index, uint8_t subindex,
                                                                  bool refreshFromBus);
 
  std::expected<void, std::string> writeDeviceParameter(uint16_t slavePosition, uint16_t index,
                                                        uint8_t subindex,
                                                        DeviceParameterValue newValue);
 
  std::expected<void, std::string> writeDevicePdoMapping(uint16_t slavePosition,
                                                         const PdoMapping& mapping);
 
  std::expected<PdoMapping, std::string> readDevicePdoMapping(uint16_t slavePosition);
 
  std::vector<OutputStageResult> stageProcessDataOutputs(
      std::span<const OutputStageRequest> requests);
 
  // --- Off-thread sampling read surface (for monitoring) ---
  //
  // These let the monitoring sampler read live values from its own thread without ever blocking
  // on the bus: SDO objects from the (refresher-fed) cache via value(); PDO objects decoded by
  // the caller from recorder-ring records (recorderHead()/recorderOldestSeq()/readRecord()) using
  // the layout pdoSampleSpec() captures. Thread-safe; they hand back copies, never device pointers.
 
  std::optional<DeviceParameterValue> value(uint16_t slavePosition, uint16_t index,
                                            uint8_t subindex) const;
 
  struct PdoSampleSpec {
    bool isOutput;       
    uint32_t bitOffset;  
    uint16_t bitLength;  
    uint16_t dataType;   
  };
 
  std::optional<PdoSampleSpec> pdoSampleSpec(uint16_t slavePosition, uint16_t index,
                                             uint8_t subindex) const;
 
  uint64_t recorderHead() const;
 
  uint64_t recorderOldestSeq() const;
 
  bool readRecord(uint64_t seq, ProcessDataRing::Record& out) const;
 
  bool deviceExchangesProcessData(uint16_t slavePosition) const;
 
 private:
  struct DumpSpan {
    uint64_t rows = 0;
    uint64_t startSeq = 0;
    uint64_t endSeq = 0;
  };
 
  std::expected<DumpSpan, std::string> serializeDump(std::ostream& out);
 
  std::expected<void, std::string> remapProcessImage();
 
  std::expected<std::vector<uint16_t>, std::string> resolveTargets(
      const std::vector<uint16_t>& positions) const;
 
  void updateExpectedWkc();
 
  void stopExchange();
 
  // Guards the non-RT mutable state — driver_, devices_, and the retained image generations —
  // against the off-RT monitoring threads. Control-plane mutators (init/scan/reset/
  // configureProcessData/transitionToState) take it exclusively; the position-based value
  // reads called from other threads (readDeviceParameter/writeDeviceParameter) take it shared.
  // The RT exchangeProcessData() never takes it (it is gated by the atomic image pointer
  // instead), so the lock never touches the real-time path. Lock order, where both are taken:
  // busMutex_ (here) before any Device-level parametersMutex_.
  mutable std::shared_mutex busMutex_;
  // Bumped under the exclusive lock on every scan()/reset(); see topologyGeneration().
  std::atomic<uint64_t> topologyGeneration_{0};
  // Bumped every time remapProcessImage() publishes a new image; see processImageGeneration().
  std::atomic<uint64_t> processImageGeneration_{0};
  std::unique_ptr<mm::comm::FieldbusDriver> driver_;
  std::vector<Device> devices_;
  std::unique_ptr<ProcessData> pd_;
  // On-disk parameter-definition cache, shared by every Device (handed to each by pointer at
  // scan()). Outlives the device set, which is rebuilt on every scan/reset. Configured at init().
  ParameterCache parameterCache_;
  // Runtime tuning captured at init(); drives recorder-ring sizing at configureProcessData.
  DeviceManagerConfig config_;
};
 
void to_json(nlohmann::json& j, const DeviceManager& dm);
 
}  // namespace mm::node