fieldbus_driver.h

Go to the documentation of this file.

#pragma once
 
#include <array>
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <functional>
#include <mutex>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <vector>
 
#include "comm/foe_error.h"
 
namespace mm::comm {
 
inline constexpr std::size_t kMaxProcessImageBytes = 32768;
 
inline constexpr std::chrono::milliseconds kFoeReadTimeout{6000};
 
enum class EtherCatState : uint16_t {
  Init = 0x01,    
  PreOp = 0x02,   
  Boot = 0x03,    
  SafeOp = 0x04,  
  Op = 0x08,      
};
 
inline EtherCatState alState(uint16_t alStatus) {
  return static_cast<EtherCatState>(alStatus & 0x000Fu);
}
 
inline bool alHasError(uint16_t alStatus) { return (alStatus & 0x0010u) != 0; }
 
inline std::string_view toString(EtherCatState state) {
  switch (state) {
    case EtherCatState::Init:
      return "INIT";
    case EtherCatState::PreOp:
      return "PRE-OP";
    case EtherCatState::Boot:
      return "BOOT";
    case EtherCatState::SafeOp:
      return "SAFE-OP";
    case EtherCatState::Op:
      return "OP";
  }
  return "UNKNOWN";
}
 
enum class Reachability : uint8_t {
  Answering,     
  AddressLost,   
  NotAnswering,  
};
 
inline std::string_view toString(Reachability reachability) {
  switch (reachability) {
    case Reachability::Answering:
      return "answering";
    case Reachability::AddressLost:
      return "addressLost";
    case Reachability::NotAnswering:
      return "notAnswering";
  }
  return "notAnswering";
}
 
inline int workingCounterContribution(uint16_t alStatus, bool hasOutputs, bool hasInputs) {
  if (alHasError(alStatus)) {
    return 0;
  }
  switch (alState(alStatus)) {
    case EtherCatState::SafeOp:
    case EtherCatState::Op:
      return (hasOutputs ? 2 : 0) + (hasInputs ? 1 : 0);
    default:
      return 0;
  }
}
 
inline bool exchangesProcessData(uint16_t alStatus) {
  const EtherCatState state = alState(alStatus);
  return !alHasError(alStatus) && (state == EtherCatState::SafeOp || state == EtherCatState::Op);
}
 
struct SlaveInfo {
  std::string name;             
  uint32_t vendorId = 0;        
  uint32_t productCode = 0;     
  uint32_t revisionNumber = 0;  
  uint32_t serialNumber = 0;    
  std::optional<uint8_t> escType;
  bool mailboxWriteOnce = false;
};
 
struct OdEntry {
  uint16_t index = 0;            
  uint8_t subindex = 0;          
  uint16_t objectCode = 0;       
  uint16_t dataType = 0;         
  uint16_t bitLength = 0;        
  uint16_t access = 0;           
  std::string name;              
  std::optional<uint32_t> unit;  
  std::optional<std::vector<uint8_t>> defaultValue;  
  std::optional<std::vector<uint8_t>> minValue;      
  std::optional<std::vector<uint8_t>> maxValue;      
};
 
struct OdRead {
  std::vector<OdEntry> entries;  
  int missingEntries = 0;  
};
 
struct SlaveIo {
  uint16_t slavePosition = 0;  
  uint32_t outputOffset = 0;   
  uint32_t outputBytes = 0;    
  uint32_t inputOffset = 0;    
  uint32_t inputBytes = 0;     
};
 
struct PdoLayout {
  uint32_t outputBytes = 0;     
  uint32_t inputBytes = 0;      
  std::vector<SlaveIo> slaves;  
  int expectedWkc = 0;  
};
 
struct SyncManagerConfig {
  uint8_t index = 0;           
  uint16_t physicalStart = 0;  
  uint16_t length = 0;         
  uint32_t flags = 0;  
  uint8_t type = 0;    
};
 
struct FmmuConfig {
  uint8_t index = 0;             
  uint32_t logicalStart = 0;     
  uint16_t length = 0;           
  uint8_t logicalStartBit = 0;   
  uint8_t logicalEndBit = 0;     
  uint16_t physicalStart = 0;    
  uint8_t physicalStartBit = 0;  
  uint8_t type = 0;              
  uint8_t active = 0;            
};
 
struct MailboxConfig {
  static constexpr uint16_t kProtocolCoe = 0x04;
 
  uint16_t writeLength = 0;  
  uint16_t writeOffset = 0;  
  uint16_t readLength = 0;   
  uint16_t readOffset = 0;   
  uint16_t protocols = 0;    
  // Per-protocol capability detail bytes as advertised in EEPROM (ECT_*DETAILS), refining the
  // supported-protocol bits above. Raw bytes — the meaning of each bit is decoded by the client
  // (CoE has a rich flag set; FoE/EoE are essentially an enable bit; SoE is a channel count). An
  // advertisement, not a guarantee (see the CoE Complete-Access note in the parameter path).
  uint8_t coeDetails = 0;  
  uint8_t foeDetails = 0;  
  uint8_t eoeDetails = 0;  
  uint8_t soeDetails = 0;  
};
 
constexpr uint16_t kSyncManagerRegisterBase = 0x0800;  
constexpr uint16_t kSyncManagerRegisterBytes = 8;      
constexpr uint16_t kFmmuRegisterBase = 0x0600;         
constexpr uint16_t kFmmuRegisterBytes = 16;            
 
std::array<uint8_t, kSyncManagerRegisterBytes> encodeSyncManager(const SyncManagerConfig& config);
 
std::optional<SyncManagerConfig> decodeSyncManager(uint8_t index, std::span<const uint8_t> bytes);
 
std::array<uint8_t, kFmmuRegisterBytes> encodeFmmu(const FmmuConfig& config);
 
std::optional<FmmuConfig> decodeFmmu(uint8_t index, std::span<const uint8_t> bytes);
 
struct DcConfig {
  bool capable = false;          
  bool active = false;           
  int32_t propagationDelay = 0;  
  int32_t cycleTime = 0;         
  int32_t shift = 0;             
};
 
struct SlaveConfig {
  uint16_t slavePosition = 0;      
  uint16_t configuredAddress = 0;  
  uint16_t aliasAddress = 0;       
  uint16_t outputBits = 0;         
  uint16_t inputBits = 0;          
  MailboxConfig mailbox;           
  DcConfig dc;                     
  std::vector<SyncManagerConfig> syncManagers;  
  std::vector<FmmuConfig> fmmus;                
};
 
struct PortDiagnostics {
  bool linkUp = false;      
  bool loopClosed = false;  
  bool communication = false;  
  uint8_t invalidFrame = 0;  
  uint8_t rxError = 0;       
  uint8_t forwardedError = 0;  
  uint8_t lostLink = 0;        
};
 
struct SlaveDiagnostics {
  uint16_t slavePosition = 0;            
  std::array<PortDiagnostics, 4> ports;  
  uint8_t processingUnitError = 0;       
  uint8_t pdiError = 0;             
  uint8_t processDataWatchdog = 0;  
  uint8_t pdiWatchdog = 0;          
};
 
struct DcSyncDiagnostics {
  uint16_t slavePosition = 0;    
  bool dcCapable = false;        
  bool referenceClock = false;   
  int32_t propagationDelay = 0;  
  int32_t systemTimeDifference =
      0;  
};
 
struct ProcessDataWatchdogConfig {
  bool enabled = false;                 
  bool running = false;                 
  std::chrono::nanoseconds timeout{0};  
  uint16_t divider = 0;                 
  uint16_t ticks = 0;                   
};
 
class FieldbusDriver {
 public:
  virtual ~FieldbusDriver() = default;
 
  virtual std::expected<void, std::string> init() = 0;
 
  virtual std::expected<int, std::string> scan() = 0;
 
  virtual SlaveInfo slaveInfo(uint16_t position) const = 0;
 
  virtual uint16_t slaveState(uint16_t position) const = 0;
 
  virtual uint16_t mailboxProtocols(uint16_t /*position*/) const { return 0; }
 
  virtual std::expected<void, std::string> configureProcessData() = 0;
 
  virtual PdoLayout processDataLayout() = 0;
 
  virtual std::vector<SlaveConfig> busConfig() const { return {}; }
 
  virtual int exchangeProcessData(std::span<const uint8_t> outputs, std::span<uint8_t> inputs) = 0;
 
  virtual void stop() = 0;
 
  struct SlaveStateRaw {
    uint16_t alStatus = 0;      
    uint16_t alStatusCode = 0;  
    Reachability reachability = Reachability::Answering;  
  };
 
  virtual std::expected<std::vector<SlaveStateRaw>, std::string> readStates(
      const std::vector<uint16_t>& positions) = 0;
 
  virtual std::optional<int> readDevicesOnWire() { return std::nullopt; }
 
  virtual std::expected<std::vector<SlaveDiagnostics>, std::string> readDiagnostics(
      const std::vector<uint16_t>& /*positions*/) {
    return std::unexpected("diagnostics not supported by this transport");
  }
 
  virtual std::expected<std::vector<DcSyncDiagnostics>, std::string> readDcSync(
      const std::vector<uint16_t>& /*positions*/) {
    return std::unexpected("distributed-clock diagnostics not supported by this transport");
  }
 
  virtual std::expected<std::vector<uint8_t>, std::string> readSdo(uint16_t slavePosition,
                                                                   uint16_t index,
                                                                   uint8_t subindex) = 0;
 
  virtual std::expected<std::vector<uint8_t>, std::string> readSdoComplete(
      uint16_t /*slavePosition*/, uint16_t /*index*/) {
    return std::unexpected("complete access not supported by this driver");
  }
 
  virtual std::expected<void, std::string> writeSdo(uint16_t slavePosition, uint16_t index,
                                                    uint8_t subindex,
                                                    std::span<const uint8_t> data) = 0;
 
  virtual std::expected<OdRead, std::string> readObjectDictionary(uint16_t slavePosition) = 0;
 
  virtual std::expected<std::vector<uint8_t>, std::string> readSii(uint16_t /*slavePosition*/) {
    return std::unexpected("SII (EEPROM) read not supported by this transport");
  }
 
  virtual std::expected<void, std::string> writeSii(uint16_t /*slavePosition*/,
                                                    std::span<const uint8_t> /*data*/) {
    return std::unexpected("SII (EEPROM) write not supported by this transport");
  }
 
  virtual std::expected<std::vector<uint8_t>, FoeError> readFile(
      uint16_t slavePosition, const std::string& filename, std::chrono::milliseconds timeout) = 0;
 
  virtual std::expected<void, FoeError> writeFile(uint16_t slavePosition,
                                                  const std::string& filename,
                                                  std::span<const uint8_t> data) = 0;
 
  virtual std::expected<void, std::string> readRegister(uint16_t slavePosition, uint16_t address,
                                                        std::span<uint8_t> data) = 0;
 
  virtual std::expected<void, std::string> writeRegister(uint16_t slavePosition, uint16_t address,
                                                         std::span<const uint8_t> data) = 0;
 
  virtual std::expected<ProcessDataWatchdogConfig, std::string> processDataWatchdog(
      uint16_t /*slavePosition*/) {
    return std::unexpected("process-data watchdog not supported by this transport");
  }
 
  virtual std::expected<ProcessDataWatchdogConfig, std::string> setProcessDataWatchdog(
      uint16_t /*slavePosition*/, std::chrono::nanoseconds /*timeout*/) {
    return std::unexpected("process-data watchdog not supported by this transport");
  }
 
  virtual void transitionToState(
      const std::vector<uint16_t>& positions, std::optional<EtherCatState> requiredState,
      EtherCatState targetState, std::chrono::steady_clock::duration timeout,
      std::chrono::steady_clock::duration resendInterval = std::chrono::seconds(2),
      std::function<void()> tick = nullptr, std::function<bool()> shouldAbort = nullptr) = 0;
 
  virtual bool supportsEsc() const { return true; }
 
  virtual std::string adapter() const { return {}; }
 
  virtual uint64_t droppedInputFrames() const { return 0; }
 
  virtual bool supportsLocate() const { return false; }
 
  virtual std::expected<void, std::string> locate(uint16_t /*slavePosition*/, bool /*on*/) {
    return std::unexpected("device locate not supported by this transport");
  }
 
  enum class FirmwareActivation : uint8_t {
    kOnBootExit,
    kRestarted,
  };
 
  virtual std::expected<FirmwareActivation, std::string> activateFirmware(
      uint16_t /*slavePosition*/, std::chrono::steady_clock::duration /*timeout*/) {
    return FirmwareActivation::kOnBootExit;
  }
 
  virtual std::optional<std::string> stateChangeRefusal() const { return std::nullopt; }
};
 
}  // namespace mm::comm