spoe_fieldbus_driver.h

Go to the documentation of this file.

#pragma once
 
// The fieldbus driver for SPoE: one TCP connection to the netX of each drive.
//
// Where the SPoE specification and the firmware disagree, this driver follows the firmware. The
// differences are listed in issue #36.
//
// A position is the place of an address in the configured list, and it never changes. A drive that
// does not answer keeps its position with no state known, so the positions after it stay where
// they are.
//
// There is no ESC, so SII, ESC registers, DC and the ESC diagnostics answer "not supported".
 
#include <chrono>
#include <cstdint>
#include <expected>
#include <functional>
#include <memory>
#include <optional>
#include <span>
#include <stop_token>
#include <string>
#include <vector>
 
#include "comm/control_plane_locks.h"
#include "comm/fieldbus_driver.h"
#include "comm/spoe_frame.h"
 
namespace mm::comm::spoe {
 
enum class PdoMode : uint8_t {
  kNone = 0x00,
  kMonitor = 0x01,
  kControl = 0x02,
};
 
enum class SpoeMode : uint8_t {
  kMonitor,
  kControl,
};
 
struct SpoeFieldbusDriverConfig {
  std::vector<std::string> hosts;
  uint16_t port = 8080;
  SpoeMode mode = SpoeMode::kMonitor;
  uint32_t watchdogMs = 75;
  std::chrono::milliseconds requestTimeout{1000};
  std::chrono::milliseconds connectTimeout{1000};
  std::chrono::milliseconds fileTimeout{30000};
  std::chrono::microseconds exchangePeriod{1000};
};
 
constexpr std::size_t kInputQueueLimit = 30;
 
constexpr uint16_t kProtocolVersion100 = 0x0100;
constexpr uint16_t kProtocolVersion102 = 0x0102;
 
constexpr std::size_t kParameterEntrySize = 68;
 
struct ParameterEntry {
  OdEntry entry;
  uint32_t subindexCount = 0;
};
 
std::vector<ParameterEntry> decodeParameterEntries(std::span<const uint8_t> bytes);
 
std::string sdoStatusName(uint16_t status);
 
class SpoeFieldbusDriver : public FieldbusDriver {
 public:
  explicit SpoeFieldbusDriver(SpoeFieldbusDriverConfig config);
  ~SpoeFieldbusDriver() override;
 
  SpoeFieldbusDriver(const SpoeFieldbusDriver&) = delete;
  SpoeFieldbusDriver& operator=(const SpoeFieldbusDriver&) = delete;
 
  std::expected<void, std::string> init() override;
  std::expected<int, std::string> scan() override;
  SlaveInfo slaveInfo(uint16_t position) const override;
  uint16_t slaveState(uint16_t position) const override;
  uint16_t mailboxProtocols(uint16_t position) const override;
 
  std::expected<void, std::string> configureProcessData() override;
  PdoLayout processDataLayout() override;
  int exchangeProcessData(std::span<const uint8_t> outputs, std::span<uint8_t> inputs) override;
  void stop() override;
 
  std::expected<std::vector<SlaveStateRaw>, std::string> readStates(
      const std::vector<uint16_t>& positions) override;
 
  std::expected<std::vector<uint8_t>, std::string> readSdo(uint16_t slavePosition, uint16_t index,
                                                           uint8_t subindex) override;
  std::expected<void, std::string> writeSdo(uint16_t slavePosition, uint16_t index,
                                            uint8_t subindex,
                                            std::span<const uint8_t> data) override;
  std::expected<OdRead, std::string> readObjectDictionary(uint16_t slavePosition) override;
 
  std::expected<std::vector<uint8_t>, FoeError> readFile(
      uint16_t slavePosition, const std::string& filename,
      std::chrono::milliseconds timeout) override;
  std::expected<void, FoeError> writeFile(uint16_t slavePosition, const std::string& filename,
                                          std::span<const uint8_t> data) override;
 
  std::expected<void, std::string> readRegister(uint16_t slavePosition, uint16_t address,
                                                std::span<uint8_t> data) override;
  std::expected<void, std::string> writeRegister(uint16_t slavePosition, uint16_t address,
                                                 std::span<const uint8_t> data) override;
 
  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::function<void()> tick, std::function<bool()> shouldAbort) override;
 
  std::optional<std::string> stateChangeRefusal() const override;
 
  bool supportsEsc() const override { return false; }
  uint64_t droppedInputFrames() const override;
  bool supportsLocate() const override { return true; }
  std::expected<void, std::string> locate(uint16_t slavePosition, bool on) override;
  std::expected<FirmwareActivation, std::string> activateFirmware(
      uint16_t slavePosition, std::chrono::steady_clock::duration timeout) override;
 
 private:
  struct Drive;
 
  Drive* driveAt(uint16_t position) const;
  void closeAll();
  void releaseDrives();
  void stopExchanges();
  void runExchange(Drive& drive, const std::stop_token& stopToken);
  std::expected<uint32_t, std::string> assignedBits(Drive& drive, uint16_t assignIndex);
  // request, readSdoFrom and connectAndIdentify take no lock. The caller holds bus_, shared or
  // exclusive. filePacket takes bus_ shared itself, for one packet.
  std::expected<Frame, std::string> request(Drive& drive, MessageType type,
                                            std::span<const uint8_t> data, uint16_t status = 0);
  std::expected<std::vector<uint8_t>, std::string> readSdoFrom(Drive& drive, uint16_t index,
                                                               uint8_t subindex);
  void connectAndIdentify(Drive& drive);
  std::expected<Frame, FoeError> filePacket(Drive& drive, MessageType type, uint8_t packetState,
                                            std::span<const uint8_t> data,
                                            std::chrono::milliseconds timeout);
  std::expected<std::vector<uint8_t>, FoeError> readFileFrom(Drive& drive,
                                                             const std::string& filename,
                                                             std::chrono::milliseconds timeout);
 
  SpoeFieldbusDriverConfig config_;
  // Held exclusive by scan, configureProcessData and stop, which rebuild the connections, the drive
  // information and the layout. Every other request holds it shared for that one request, so a scan
  // waits for the requests in flight and never for a whole transfer. A transfer that a scan
  // interrupts fails on its next packet. The order is a drive's sequenceMutex, then this lock, then
  // the connection's mutex. mutable so the const accessors can lock.
  mutable BusLock bus_;
  // Sized once in the constructor and never resized, so a position indexes it without a lock.
  std::vector<std::unique_ptr<Drive>> drives_;
  // Written by configureProcessData while no exchange runs, read by processDataLayout.
  PdoLayout layout_;
};
 
}  // namespace mm::comm::spoe