somanet_drive.h

Go to the documentation of this file.

#pragma once
 
#include <array>
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <nlohmann/json_fwd.hpp>
#include <optional>
#include <span>
#include <stop_token>
#include <string>
#include <string_view>
#include <variant>
#include <vector>
 
#include "node/cia402_drive.h"
#include "node/firmware_package.h"
 
namespace mm::node {
 
namespace somanet {
 
enum Object : uint16_t {
  kCommutationAngleOffset = 0x2001,  
  kMotorSpecificSettings = 0x2003,   
  kBrakeOptions = 0x2004,            
  kCommutationOffsetDetection = 0x2009,  
  kErrorReport = 0x203F,                 
};
 
enum ErrorReportEntry : uint8_t {
  kErrorReportDescription = 1,  
};
 
enum MotorSetting : uint8_t {
  kMotorPolePairs = 1,  
 
  kMotorTorqueConstant = 2,
  kMotorPhaseResistance = 3,
 
  kMotorPhaseInductance = 4,
  kMotorPhasesInverted = 5,  
};
 
enum CommutationOffsetSetting : uint8_t {
  kCommutationOffsetState = 1,  
 
  kCommutationOffsetAppliedTorquePercent = 2,
 
  kCommutationOffsetMethod = 3,  
  kCommutationOffsetKp = 4,      
  kCommutationOffsetKi = 5,      
  kCommutationOffsetKd = 6,      
};
 
enum class CommutationOffsetMethod : uint8_t {
  kRotating = 0,
 
  kRotatingTuned = 1,
 
  kStationary = 2,
};
 
constexpr std::string_view toString(CommutationOffsetMethod method) {
  switch (method) {
    case CommutationOffsetMethod::kRotating:
      return "rotating";
    case CommutationOffsetMethod::kRotatingTuned:
      return "rotatingTuned";
    case CommutationOffsetMethod::kStationary:
      return "stationary";
  }
  return "unknown";
}
 
constexpr bool requiresBrakeReleased(CommutationOffsetMethod method) {
  return method != CommutationOffsetMethod::kStationary;
}
 
enum class EncoderOrdinal : uint8_t {
  kEncoder1 = 1,  
  kEncoder2 = 2,  
};
 
constexpr std::string_view toString(EncoderOrdinal encoder) {
  switch (encoder) {
    case EncoderOrdinal::kEncoder1:
      return "encoder 1";
    case EncoderOrdinal::kEncoder2:
      return "encoder 2";
  }
  return "unknown encoder";
}
 
enum class IcMuCalibrationMode : uint8_t {
  kConfiguration = 0,
 
  kRaw = 1,
 
  kStandard = 2,
};
 
constexpr std::string_view toString(IcMuCalibrationMode mode) {
  switch (mode) {
    case IcMuCalibrationMode::kConfiguration:
      return "configuration";
    case IcMuCalibrationMode::kRaw:
      return "raw";
    case IcMuCalibrationMode::kStandard:
      return "standard";
  }
  return "unknown";
}
 
std::optional<IcMuCalibrationMode> parseIcMuCalibrationMode(std::string_view token);
 
enum class FirmwareService : uint8_t {
  kDriveControl = 0,   
  kMotionControl = 1,  
};
 
constexpr std::string_view toString(FirmwareService service) {
  switch (service) {
    case FirmwareService::kDriveControl:
      return "drive-control";
    case FirmwareService::kMotionControl:
      return "motion-control";
  }
  return "unknown";
}
 
std::optional<FirmwareService> parseFirmwareService(std::string_view token);
 
enum class KueblerRegisterFault : uint8_t {
  kAsyncInProgress = 0,        
  kInvalidRegisterLength = 1,  
  kEncoderTimeout = 2,         
  kWrongByteCount = 3,  
  kEncoderBusy = 4,
};
 
constexpr std::string_view toString(KueblerRegisterFault fault) {
  switch (fault) {
    case KueblerRegisterFault::kAsyncInProgress:
      return "the encoder's asynchronous channel is busy with another transaction";
    case KueblerRegisterFault::kInvalidRegisterLength:
      return "the register length must be 1 to 4 bytes";
    case KueblerRegisterFault::kEncoderTimeout:
      return "the encoder did not return a value within 10 ms";
    case KueblerRegisterFault::kWrongByteCount:
      return "the encoder answered with a different number of bytes than were asked for";
    case KueblerRegisterFault::kEncoderBusy:
      return "the encoder is accessing its flash memory and cannot service this register";
  }
  return "unknown fault";
}
 
enum class VelocitySource : uint8_t {
  kFirmware = 0,
  kEncoder = 1,
};
 
constexpr std::string_view toString(VelocitySource source) {
  switch (source) {
    case VelocitySource::kFirmware:
      return "firmware";
    case VelocitySource::kEncoder:
      return "encoder";
  }
  return "unknown";
}
 
std::optional<VelocitySource> parseVelocitySource(std::string_view token);
 
enum class FirmwareLatency : uint8_t {
  kSetpoint = 0,
  kFeedback = 1,
};
 
constexpr std::string_view toString(FirmwareLatency latency) {
  switch (latency) {
    case FirmwareLatency::kSetpoint:
      return "setpoint";
    case FirmwareLatency::kFeedback:
      return "feedback";
  }
  return "unknown";
}
 
std::optional<FirmwareLatency> parseFirmwareLatency(std::string_view token);
 
enum class FirmwareErrorType : uint8_t {
  kLinkError = 0,           
  kIllegalPc = 1,           
  kIllegalInstruction = 2,  
  kIllegalResource = 3,     
  kLoadStore = 4,           
  kIllegalPs = 5,           
  kArithmetic = 6,          
  kEcall = 7,               
  kResourceDependency = 8,  
  kKcall = 9,               
  kEndlessLoop = 10,        
  kResettableFirmwareError = 11,
};
 
enum class FirmwareErrorEffect : uint8_t {
  kNotImplemented,
  kStopsService,
  kRaisesResettableError,
};
 
constexpr FirmwareErrorEffect effectOf(FirmwareErrorType type) {
  switch (type) {
    case FirmwareErrorType::kLinkError:
    case FirmwareErrorType::kIllegalPc:
    case FirmwareErrorType::kIllegalInstruction:
    case FirmwareErrorType::kIllegalResource:
    case FirmwareErrorType::kIllegalPs:
    case FirmwareErrorType::kResourceDependency:
    case FirmwareErrorType::kKcall:
      return FirmwareErrorEffect::kNotImplemented;
    case FirmwareErrorType::kLoadStore:
    case FirmwareErrorType::kArithmetic:
    case FirmwareErrorType::kEcall:
    case FirmwareErrorType::kEndlessLoop:
      return FirmwareErrorEffect::kStopsService;
    case FirmwareErrorType::kResettableFirmwareError:
      return FirmwareErrorEffect::kRaisesResettableError;
  }
  return FirmwareErrorEffect::kNotImplemented;
}
 
constexpr std::string_view toString(FirmwareErrorType type) {
  switch (type) {
    case FirmwareErrorType::kLinkError:
      return "link-error";
    case FirmwareErrorType::kIllegalPc:
      return "illegal-pc";
    case FirmwareErrorType::kIllegalInstruction:
      return "illegal-instruction";
    case FirmwareErrorType::kIllegalResource:
      return "illegal-resource";
    case FirmwareErrorType::kLoadStore:
      return "load-store";
    case FirmwareErrorType::kIllegalPs:
      return "illegal-ps";
    case FirmwareErrorType::kArithmetic:
      return "arithmetic";
    case FirmwareErrorType::kEcall:
      return "ecall";
    case FirmwareErrorType::kResourceDependency:
      return "resource-dependency";
    case FirmwareErrorType::kKcall:
      return "kcall";
    case FirmwareErrorType::kEndlessLoop:
      return "endless-loop";
    case FirmwareErrorType::kResettableFirmwareError:
      return "resettable-firmware-error";
  }
  return "unknown";
}
 
std::optional<FirmwareErrorType> parseFirmwareErrorType(std::string_view token);
 
inline constexpr FirmwareErrorType kFirmwareErrorTypes[] = {
    FirmwareErrorType::kLinkError,          FirmwareErrorType::kIllegalPc,
    FirmwareErrorType::kIllegalInstruction, FirmwareErrorType::kIllegalResource,
    FirmwareErrorType::kLoadStore,          FirmwareErrorType::kIllegalPs,
    FirmwareErrorType::kArithmetic,         FirmwareErrorType::kEcall,
    FirmwareErrorType::kResourceDependency, FirmwareErrorType::kKcall,
    FirmwareErrorType::kEndlessLoop,        FirmwareErrorType::kResettableFirmwareError,
};
 
enum class SystemIdentificationParameter : uint8_t {
  kStartFrequency = 0,   
  kTargetFrequency = 1,  
  kTargetAmplitude = 2,  
  kTransitionTime = 3,   
  kSignalType = 4,       
  kStartProcedure = 5,   
};
 
constexpr std::string_view toString(SystemIdentificationParameter parameter) {
  switch (parameter) {
    case SystemIdentificationParameter::kStartFrequency:
      return "start frequency";
    case SystemIdentificationParameter::kTargetFrequency:
      return "target frequency";
    case SystemIdentificationParameter::kTargetAmplitude:
      return "target amplitude";
    case SystemIdentificationParameter::kTransitionTime:
      return "transition time";
    case SystemIdentificationParameter::kSignalType:
      return "signal type";
    case SystemIdentificationParameter::kStartProcedure:
      return "start the procedure";
  }
  return "unknown parameter";
}
 
enum class ChirpSignalType : uint8_t {
  kLogarithmic = 0,
  kLinear = 1,
};
 
constexpr std::string_view toString(ChirpSignalType type) {
  switch (type) {
    case ChirpSignalType::kLogarithmic:
      return "logarithmic";
    case ChirpSignalType::kLinear:
      return "linear";
  }
  return "unknown";
}
 
std::optional<ChirpSignalType> parseChirpSignalType(std::string_view token);
 
enum class SystemIdentificationStart : uint8_t {
  kNone = 0,
  kImmediately = 1,  
  kAfterHrdStreamStart = 2,
};
 
constexpr std::string_view toString(SystemIdentificationStart start) {
  switch (start) {
    case SystemIdentificationStart::kNone:
      return "none";
    case SystemIdentificationStart::kImmediately:
      return "immediately";
    case SystemIdentificationStart::kAfterHrdStreamStart:
      return "after-hrd-stream-start";
  }
  return "unknown";
}
 
std::optional<SystemIdentificationStart> parseSystemIdentificationStart(std::string_view token);
 
inline constexpr uint32_t kMinChirpFrequencyMilliHz = 100;        
inline constexpr uint32_t kMaxChirpFrequencyMilliHz = 1'000'000;  
inline constexpr uint32_t kMinChirpTransitionTimeMs = 1'000;      
inline constexpr uint32_t kMaxChirpTransitionTimeMs = 20'000;     
 
enum class EncoderRegisterFault : uint8_t {
  kInvalidResponse = 0,     
  kRegisterNotAllowed = 1,  
};
 
constexpr std::string_view toString(EncoderRegisterFault fault) {
  switch (fault) {
    case EncoderRegisterFault::kInvalidResponse:
      return "invalid response";
    case EncoderRegisterFault::kRegisterNotAllowed:
      return "register not allowed";
  }
  return "unknown";
}
 
constexpr std::string_view describe(EncoderRegisterFault fault) {
  switch (fault) {
    case EncoderRegisterFault::kInvalidResponse:
      return "the register communication transaction failed internally, which a BiSS clock "
             "frequency set too high can cause";
    case EncoderRegisterFault::kRegisterNotAllowed:
      return "the register cannot be accessed at the moment, which happens when the firmware is "
             "itself using it — an iC-MU I2C register while iC-PVL registers are being monitored, "
             "say";
  }
  return "unknown fault";
}
 
enum class HrdData : uint8_t {
  kEncoderRawData = 0,
 
  kSystemIdentificationData = 1,
};
 
constexpr std::string_view toString(HrdData data) {
  switch (data) {
    case HrdData::kEncoderRawData:
      return "encoder-raw";
    case HrdData::kSystemIdentificationData:
      return "system-identification";
  }
  return "unknown";
}
 
std::optional<HrdData> parseHrdData(std::string_view token);
 
constexpr size_t hrdSampleSize(HrdData data) { return data == HrdData::kEncoderRawData ? 4 : 6; }
 
constexpr std::chrono::milliseconds maxHrdStreamDuration(HrdData data) {
  return data == HrdData::kEncoderRawData ? std::chrono::milliseconds(10000)
                                          : std::chrono::milliseconds(6000);
}
 
enum class HrdStreamFault : uint8_t {
  kInitialization = 0,  
  kStreaming = 1,       
  kDuration = 2,        
  kDataIndex = 3,       
  kAction = 4,          
};
 
constexpr std::string_view toString(HrdStreamFault fault) {
  switch (fault) {
    case HrdStreamFault::kInitialization:
      return "initialization error";
    case HrdStreamFault::kStreaming:
      return "streaming error";
    case HrdStreamFault::kDuration:
      return "duration value";
    case HrdStreamFault::kDataIndex:
      return "data index value";
    case HrdStreamFault::kAction:
      return "action value";
  }
  return "unknown";
}
 
constexpr std::string_view describe(HrdStreamFault fault) {
  switch (fault) {
    case HrdStreamFault::kInitialization:
      return "the drive could not start the recording";
    case HrdStreamFault::kStreaming:
      return "the recording failed part way through, so whatever reached the drive's files is "
             "incomplete";
    case HrdStreamFault::kDuration:
      return "the requested duration is longer than the drive allows for the chosen data, which is "
             "10000 ms for encoder raw data and 6000 ms for system identification data";
    case HrdStreamFault::kDataIndex:
      return "the drive does not know the requested data index, which means its firmware records a "
             "different set of signals than this build expects";
    case HrdStreamFault::kAction:
      return "the drive does not know the requested action, which means its firmware drives HRD "
             "streaming differently than this build expects";
  }
  return "unknown fault";
}
 
enum BrakeOption : uint8_t {
  kBrakePullVoltage = 1,      
  kBrakeHoldVoltage = 2,      
  kBrakePullTime = 3,         
  kBrakeReleaseStrategy = 4,  
  kBrakeControllerDisableDelay = 5,  
  kBrakeDcBusVoltage = 6,            
  kBrakeStatus = 7,  
  kBrakeMinimumDisplacement = 8,  
 
  kBrakePinCurrentPercent = 9,
 
  kBrakeOutputVoltage = 10,        
  kBrakeSwitchingFrequency = 11,   
  kBrakePinInitialDirection = 12,  
};
 
enum class BrakeReleaseStrategy : uint8_t {
  kManualOutputVoltage = 0,  
  kClutch = 1,               
  kPin = 2,                  
};
 
enum class BrakeStatus : uint8_t {
  kNotConfigured = 0,  
  kEngaged = 1,        
  kDisengaged = 2,     
};
 
constexpr std::string_view toString(BrakeStatus status) {
  switch (status) {
    case BrakeStatus::kNotConfigured:
      return "notConfigured";
    case BrakeStatus::kEngaged:
      return "engaged";
    case BrakeStatus::kDisengaged:
      return "disengaged";
  }
  return "unknown";
}
 
constexpr std::string_view toString(BrakeReleaseStrategy strategy) {
  switch (strategy) {
    case BrakeReleaseStrategy::kManualOutputVoltage:
      return "manualOutputVoltage";
    case BrakeReleaseStrategy::kClutch:
      return "clutch";
    case BrakeReleaseStrategy::kPin:
      return "pin";
  }
  return "unknown";
}
 
enum class OsCommandId : uint8_t {
  kEncoderRegisterCommunication = 0,  
  kIcMuCalibrationMode = 1,           
  kHrdStreaming = 3,              
  kMotorPhaseOrderDetection = 4,  
  kCommutationOffsetMeasurement = 5,  
  kOpenPhaseDetection = 6,            
  kPolePairDetection = 7,             
  kPhaseResistanceMeasurement = 8,    
  kPhaseInductanceMeasurement = 9,    
  kTorqueConstantMeasurement = 10,    
  kSkippedCyclesCounter = 13,         
  kIgnoreBissStatusBits = 14,         
  kSystemIdentification = 15,         
  kTriggerError = 16,                 
  kVelocitySource = 18,               
  kKueblerRegisterCommunication = 19,  
  kReadObjectDictionary = 21,          
  kMeasureFirmwareLatency = 22,        
};
 
enum class OpenPhaseFault : uint8_t {
  kOpenTerminalA = 0,  
  kOpenTerminalB = 1,  
  kOpenTerminalC = 2,  
  kOpenFetAHigh = 3,   
  kOpenFetALow = 4,    
  kOpenFetBHigh = 5,   
  kOpenFetBLow = 6,    
  kOpenFetCHigh = 7,   
  kOpenFetCLow = 8,    
};
 
constexpr std::string_view toString(OpenPhaseFault fault) {
  switch (fault) {
    case OpenPhaseFault::kOpenTerminalA:
      return "open terminal A";
    case OpenPhaseFault::kOpenTerminalB:
      return "open terminal B";
    case OpenPhaseFault::kOpenTerminalC:
      return "open terminal C";
    case OpenPhaseFault::kOpenFetAHigh:
      return "open FET A high";
    case OpenPhaseFault::kOpenFetALow:
      return "open FET A low";
    case OpenPhaseFault::kOpenFetBHigh:
      return "open FET B high";
    case OpenPhaseFault::kOpenFetBLow:
      return "open FET B low";
    case OpenPhaseFault::kOpenFetCHigh:
      return "open FET C high";
    case OpenPhaseFault::kOpenFetCLow:
      return "open FET C low";
  }
  return "unknown";
}
 
constexpr std::string_view describe(OpenPhaseFault fault) {
  switch (fault) {
    case OpenPhaseFault::kOpenTerminalA:
      return "terminal A of the drive is not connected";
    case OpenPhaseFault::kOpenTerminalB:
      return "terminal B of the drive is not connected";
    case OpenPhaseFault::kOpenTerminalC:
      return "terminal C of the drive is not connected";
    case OpenPhaseFault::kOpenFetAHigh:
      return "the upper FET in leg A is not conducting (open circuit fault)";
    case OpenPhaseFault::kOpenFetALow:
      return "the lower FET in leg A is not conducting (open circuit fault)";
    case OpenPhaseFault::kOpenFetBHigh:
      return "the upper FET in leg B is not conducting (open circuit fault)";
    case OpenPhaseFault::kOpenFetBLow:
      return "the lower FET in leg B is not conducting (open circuit fault)";
    case OpenPhaseFault::kOpenFetCHigh:
      return "the upper FET in leg C is not conducting (open circuit fault)";
    case OpenPhaseFault::kOpenFetCLow:
      return "the lower FET in leg C is not conducting (open circuit fault)";
  }
  return "unknown fault";
}
 
enum class MotorPhaseOrder : uint8_t {
  kNormal = 0,    
  kInverted = 1,  
};
 
constexpr std::string_view toString(MotorPhaseOrder order) {
  switch (order) {
    case MotorPhaseOrder::kNormal:
      return "normal";
    case MotorPhaseOrder::kInverted:
      return "inverted";
  }
  return "unknown";
}
 
enum class MotorMeasurementFault : uint8_t {
  kCurrentAmplitudeError = 0,  
};
 
constexpr std::string_view toString(MotorMeasurementFault fault) {
  switch (fault) {
    case MotorMeasurementFault::kCurrentAmplitudeError:
      return "current amplitude error";
  }
  return "unknown";
}
 
constexpr std::string_view describe(MotorMeasurementFault fault) {
  switch (fault) {
    case MotorMeasurementFault::kCurrentAmplitudeError:
      return "the drive could not raise the motor phase currents to the amplitude it needed, which "
             "a limited DC-link voltage or a high motor phase impedance can both cause";
  }
  return "unknown fault";
}
 
enum class OperationMode : int8_t {
  kImpedance = -6,             
  kJointTorque = -5,           
  kSystemIdentification = -4,  
  kOpenLoopField = -3,         
  kDiagnostics = -2,           
  kCoggingCompensationRecording = -1,  
};
 
constexpr std::string_view toString(OperationMode mode) {
  switch (mode) {
    case OperationMode::kImpedance:
      return "Impedance";
    case OperationMode::kJointTorque:
      return "JointTorque";
    case OperationMode::kSystemIdentification:
      return "SystemIdentification";
    case OperationMode::kOpenLoopField:
      return "OpenLoopField";
    case OperationMode::kDiagnostics:
      return "Diagnostics";
    case OperationMode::kCoggingCompensationRecording:
      return "CoggingCompensationRecording";
  }
  return "Unknown";
}
 
constexpr std::string_view describe(OperationMode mode) {
  switch (mode) {
    case OperationMode::kImpedance:
      return "Impedance mode";
    case OperationMode::kJointTorque:
      return "Joint torque mode";
    case OperationMode::kSystemIdentification:
      return "System identification mode";
    case OperationMode::kOpenLoopField:
      return "Open loop field mode";
    case OperationMode::kDiagnostics:
      return "Diagnostics mode";
    case OperationMode::kCoggingCompensationRecording:
      return "Cogging compensation recording mode";
  }
  return "Unknown mode";
}
 
inline constexpr OperationMode kOperationModes[] = {
    OperationMode::kImpedance,
    OperationMode::kJointTorque,
    OperationMode::kSystemIdentification,
    OperationMode::kOpenLoopField,
    OperationMode::kDiagnostics,
    OperationMode::kCoggingCompensationRecording,
};
 
constexpr bool isDeprecated(OperationMode mode) {
  return mode == OperationMode::kSystemIdentification;
}
 
}  // namespace somanet
 
inline constexpr size_t kOsCommandSize = 8;
 
enum class OsCommandStatus : uint8_t {
  kCompleted = 0,          
  kCompletedWithData = 1,  
  kFailed = 2,             
  kFailedWithData = 3,     
};
 
enum class OsCommandError : uint8_t {
  kNotAllowed = 251,  
  kAborted = 252,     
  kTimeout = 253,
  kUnsupported = 254,  
  kReserved = 255,     
};
 
std::optional<std::string_view> osCommandErrorName(uint8_t code);
 
struct OsCommandResponse {
  OsCommandStatus status{OsCommandStatus::kCompleted};  
  std::vector<uint8_t> data;                            
  std::optional<uint8_t> errorCode;                     
  std::vector<uint8_t> fsBuffer;
 
  bool failed() const {
    return status == OsCommandStatus::kFailed || status == OsCommandStatus::kFailedWithData;
  }
};
 
inline constexpr std::string_view kFsBufferFilename = "fs-buffer";
 
enum class FsBufferTransfer : uint8_t {
  kNone,   
  kRead,   
  kWrite,  
};
 
constexpr std::string_view toString(FsBufferTransfer transfer) {
  switch (transfer) {
    case FsBufferTransfer::kRead:
      return "read";
    case FsBufferTransfer::kWrite:
      return "write";
    case FsBufferTransfer::kNone:
      break;
  }
  return "none";
}
 
std::optional<FsBufferTransfer> parseFsBufferTransfer(std::string_view token);
 
struct OsCommandFsBuffer {
  FsBufferTransfer transfer{FsBufferTransfer::kNone};  
  std::vector<uint8_t> payload;  
};
 
struct OsCommandConfig {
  std::chrono::milliseconds timeout{1000};  
 
  std::chrono::milliseconds pollInterval{10};  
 
  std::chrono::milliseconds abortTimeout{10000};  
  std::stop_token stop{};  
};
 
inline constexpr std::array<uint32_t, 1> kObjectsOutsideOdValues{
    makeParameterKey(0x10F8, 0x00),  // Timestamp Object, served by the EtherCAT stack.
};
 
struct ObjectDictionaryValue {
  uint16_t index{};    
  uint8_t subindex{};  
  DeviceParameterValue value;
};
void to_json(nlohmann::json& j, const ObjectDictionaryValue& entry);
 
struct ObjectDictionaryValues {
  size_t byteCount{};  
  std::vector<ObjectDictionaryValue> values;
};
void to_json(nlohmann::json& j, const ObjectDictionaryValues& values);
 
std::expected<ObjectDictionaryValues, std::string> decodeObjectDictionaryValues(
    std::span<const uint8_t> data, const std::vector<DeviceParameter>& definitions);
 
struct BrakeState {
  somanet::BrakeStatus status{somanet::BrakeStatus::kNotConfigured};  
  somanet::BrakeReleaseStrategy releaseStrategy{
      somanet::BrakeReleaseStrategy::kManualOutputVoltage};  
  std::chrono::milliseconds pullTime{};                      
  uint32_t pullVoltageMv = 0;                                
  uint32_t holdVoltageMv = 0;                                
 
  bool softwareControllable() const {
    return releaseStrategy != somanet::BrakeReleaseStrategy::kManualOutputVoltage;
  }
 
  bool releaseMovesShaft() const { return releaseStrategy == somanet::BrakeReleaseStrategy::kPin; }
};
void to_json(nlohmann::json& j, const BrakeState& state);
 
struct EncoderRegisterResult {
  somanet::EncoderOrdinal encoder{somanet::EncoderOrdinal::kEncoder1};  
  uint8_t registerAddress = 0;                                          
  bool wrote = false;            
  std::optional<uint8_t> value;  
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const EncoderRegisterResult& result);
 
struct DeviceFile {
  std::string name;                 
  std::optional<size_t> byteCount;  
};
void to_json(nlohmann::json& j, const DeviceFile& file);
 
std::vector<DeviceFile> parseDeviceFileList(std::string_view text);
 
std::expected<void, std::string> removeDeviceFile(Device& device, const std::string& filename);
 
struct HrdEncoderSample {
  uint32_t raw = 0;          
  uint16_t masterCount = 0;  
  uint16_t noniusCount = 0;  
};
 
struct HrdSystemIdentificationSample {
  double velocityRpm = 0.0;
 
  int16_t torquePermil = 0;
};
 
using HrdSamples =
    std::variant<std::vector<HrdEncoderSample>, std::vector<HrdSystemIdentificationSample>>;
 
struct HrdRecording {
  somanet::HrdData data{somanet::HrdData::kEncoderRawData};  
  std::vector<DeviceFile> files;  
  size_t byteCount = 0;           
  size_t trailingBytes = 0;       
  HrdSamples samples;             
 
  size_t sampleCount() const;
};
void to_json(nlohmann::json& j, const HrdRecording& recording);
 
std::string toCsv(const HrdRecording& recording);
 
std::vector<std::string_view> hrdColumns(somanet::HrdData data);
 
HrdSamples decodeHrdSamples(std::span<const uint8_t> bytes, somanet::HrdData data);
 
struct OpenPhaseResult {
  bool phaseOpened = false;  
 
  std::optional<somanet::OpenPhaseFault> fault;
  std::optional<uint8_t> faultCode;  
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const OpenPhaseResult& result);
 
struct MotorPhaseOrderResult {
  somanet::MotorPhaseOrder order{somanet::MotorPhaseOrder::kNormal};  
 
  bool inverted() const { return order == somanet::MotorPhaseOrder::kInverted; }
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const MotorPhaseOrderResult& result);
 
struct CommutationOffsetResult {
  int16_t angleOffset = 0;  
 
  somanet::CommutationOffsetMethod method{somanet::CommutationOffsetMethod::kRotating};
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const CommutationOffsetResult& result);
 
struct PolePairResult {
  uint8_t polePairs = 0;  
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const PolePairResult& result);
 
struct PhaseResistanceResult {
  uint32_t milliohms = 0;  
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const PhaseResistanceResult& result);
 
struct PhaseInductanceResult {
  uint32_t microhenries = 0;  
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const PhaseInductanceResult& result);
 
struct TorqueConstantResult {
  int32_t milliNewtonMetresPerAmpere = 0;  
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const TorqueConstantResult& result);
 
struct SkippedCyclesResult {
  somanet::FirmwareService service{somanet::FirmwareService::kDriveControl};  
  uint32_t skippedCycles = 0;  
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const SkippedCyclesResult& result);
 
struct TriggerErrorResult {
  somanet::FirmwareService service{somanet::FirmwareService::kDriveControl};  
  somanet::FirmwareErrorType type{somanet::FirmwareErrorType::kLinkError};    
  somanet::FirmwareErrorEffect effect{somanet::FirmwareErrorEffect::kNotImplemented};
 
  bool serviceStopped = false;
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const TriggerErrorResult& result);
 
struct KueblerRegisterResult {
  uint8_t address = 0;  
  uint8_t length = 0;   
  bool wrote = false;   
 
  std::vector<uint8_t> bytes;
 
  uint32_t value = 0;
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const KueblerRegisterResult& result);
 
struct FirmwareLatencyResult {
  somanet::FirmwareLatency latency{somanet::FirmwareLatency::kSetpoint};  
 
  uint32_t maximumNanoseconds = 0;
 
  uint32_t configuredNanoseconds = 0;
 
  std::string describe() const;
};
void to_json(nlohmann::json& j, const FirmwareLatencyResult& result);
 
class SomanetDrive : public Cia402Drive {
 public:
  explicit SomanetDrive(Device& device) : Cia402Drive(device) {}
 
  std::expected<OsCommandResponse, std::string> runOsCommand(
      const std::vector<uint8_t>& command, const OsCommandConfig& config = {},
      const OsCommandFsBuffer& fsBuffer = {});
 
  std::expected<ObjectDictionaryValues, std::string> readObjectDictionaryValues(
      const OsCommandConfig& config = {});
 
  std::expected<std::string, std::string> errorReport() const;
 
  // --- Brake (0x2004) --------------------------------------------------------------------------
 
  std::expected<BrakeState, std::string> brakeState() const;
 
  std::expected<somanet::BrakeStatus, std::string> brakeStatus() const;
 
  std::expected<void, std::string> setBrakeStatus(somanet::BrakeStatus status);
 
  std::expected<BrakeState, std::string> releaseBrake(
      std::chrono::milliseconds settle = std::chrono::milliseconds(50));
 
  std::expected<BrakeState, std::string> engageBrake(
      std::chrono::milliseconds settle = std::chrono::milliseconds(50));
 
  // --- Vendor operation modes (0x6060) ---------------------------------------------------------
 
  // Keep the inherited standard-mode setter visible: declaring an overload below would otherwise
  // hide it, since name lookup stops at the first scope that has a match.
  using Cia402Drive::setOperationMode;
 
  std::expected<void, std::string> setOperationMode(somanet::OperationMode mode);
 
  // --- Typed OS commands -----------------------------------------------------------------------
 
  std::expected<EncoderRegisterResult, std::string> readEncoderRegister(
      somanet::EncoderOrdinal encoder, uint8_t registerAddress,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(5),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<EncoderRegisterResult, std::string> writeEncoderRegister(
      somanet::EncoderOrdinal encoder, uint8_t registerAddress, uint8_t value,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(5),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<void, std::string> setIcMuCalibrationMode(
      somanet::EncoderOrdinal encoder, somanet::IcMuCalibrationMode mode,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(5),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<void, std::string> configureHrdStream(
      somanet::HrdData data, std::chrono::milliseconds duration,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(10),
                                       .pollInterval = std::chrono::milliseconds(100)});
 
  std::expected<void, std::string> startHrdStream(const OsCommandConfig& config);
 
  std::expected<HrdRecording, std::string> readHrdRecording(somanet::HrdData data) const;
 
  std::expected<std::vector<DeviceFile>, std::string> readFileList() const;
 
  std::expected<HardwareDescription, std::string> readHardwareDescription() const;
 
  std::expected<std::optional<IntegroVariant>, std::string> readIntegroVariant() const;
 
  std::expected<FullFirmwareDescriptors, std::string> readFullFirmwareDescriptors() const;
 
  std::expected<FirmwareCompatibility, std::string> checkFirmwarePackage(
      std::string_view packageFilename) const;
 
  std::expected<OpenPhaseResult, std::string> runOpenPhaseDetection(
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(10),
                                       .pollInterval = std::chrono::milliseconds(100)});
 
  std::expected<MotorPhaseOrderResult, std::string> runMotorPhaseOrderDetection(
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(60),
                                       .pollInterval = std::chrono::milliseconds(100)});
 
  std::expected<somanet::CommutationOffsetMethod, std::string> commutationOffsetMethod() const;
 
  std::expected<CommutationOffsetResult, std::string> runCommutationOffsetMeasurement(
      somanet::CommutationOffsetMethod method,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(60),
                                       .pollInterval = std::chrono::milliseconds(100)});
 
  std::expected<PolePairResult, std::string> runPolePairDetection(
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(60),
                                       .pollInterval = std::chrono::milliseconds(100)});
 
  std::expected<PhaseResistanceResult, std::string> runPhaseResistanceMeasurement(
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(30),
                                       .pollInterval = std::chrono::milliseconds(100)});
 
  std::expected<PhaseInductanceResult, std::string> runPhaseInductanceMeasurement(
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(30),
                                       .pollInterval = std::chrono::milliseconds(100)});
 
  std::expected<TorqueConstantResult, std::string> runTorqueConstantMeasurement(
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(60),
                                       .pollInterval = std::chrono::milliseconds(100)});
 
  std::expected<TriggerErrorResult, std::string> triggerError(
      somanet::FirmwareService service, somanet::FirmwareErrorType type,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(3),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<KueblerRegisterResult, std::string> accessKueblerRegister(
      uint8_t address, uint8_t length, bool write = false, uint32_t value = 0,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(5),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<void, std::string> setVelocitySource(
      somanet::VelocitySource source,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(5),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<void, std::string> startFirmwareLatencyMeasurement(
      somanet::FirmwareLatency latency,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(5),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<FirmwareLatencyResult, std::string> readMaximumFirmwareLatency(
      somanet::FirmwareLatency latency,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(5),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<void, std::string> stopFirmwareLatencyMeasurements(
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(5),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<SkippedCyclesResult, std::string> readSkippedCycles(
      somanet::FirmwareService service,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(30),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<void, std::string> setIgnoreBissStatusBits(
      somanet::EncoderOrdinal encoder, bool ignore,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(30),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  std::expected<void, std::string> setSystemIdentificationParameter(
      somanet::SystemIdentificationParameter parameter, uint32_t value,
      const OsCommandConfig& config = {.timeout = std::chrono::seconds(5),
                                       .pollInterval = std::chrono::milliseconds(20)});
 
  // SOMANET-specific synchronous object-dictionary accessors are added here as their object
  // indices are confirmed (encoder type/resolution, motor pole pairs, commutation offset, ...).
  // Each is a thin typed read/write over device(); none holds state.
};
 
std::expected<SomanetDrive, std::string> createSomanetDrive(Device& device);
 
}  // namespace mm::node