somanet_procedures.h

Go to the documentation of this file.

#pragma once
 
#include <array>
#include <chrono>
#include <cstdint>
#include <expected>
#include <filesystem>
#include <nlohmann/json_fwd.hpp>
#include <optional>
#include <stop_token>
#include <string>
#include <string_view>
#include <vector>
 
#include "comm/fieldbus_driver.h"
#include "node/device.h"
#include "node/device_manager.h"
#include "node/firmware_package.h"
#include "node/kuebler_registers.h"
#include "node/procedure.h"
#include "node/procedure_manager.h"
#include "node/somanet_drive.h"
 
namespace mm::node {
 
 
inline constexpr std::string_view kOsCommandProcedure = "os-command";
 
inline constexpr std::string_view kOsCommandStep = "command";
 
struct OsCommandRequest {
  std::vector<uint8_t> command;                
  std::chrono::milliseconds timeout{1000};     
  std::chrono::milliseconds pollInterval{10};  
  OsCommandFsBuffer fsBuffer;
};
 
std::expected<OsCommandRequest, std::string> parseOsCommandRequest(const nlohmann::json& body);
 
std::vector<ProcedureParameter> osCommandParameters();
 
struct OsCommandResult {
  uint8_t status = 0;                
  std::vector<uint8_t> data;         
  std::optional<uint8_t> errorCode;  
  std::vector<uint8_t> fsBuffer;
};
void to_json(nlohmann::json& j, const OsCommandResult& result);
 
std::vector<ProgressStep> osCommandSteps();
 
std::expected<void, std::string> runOsCommandProcedure(Device& device, ProgressReporter& reporter,
                                                       std::stop_token stop,
                                                       const OsCommandRequest& request);
 
inline constexpr std::string_view kEncoderRegisterProcedure = "encoder-register-communication";
 
inline constexpr std::string_view kEncoderRegisterStep = "register-access";
 
struct EncoderRegisterRequest {
  somanet::EncoderOrdinal encoder{somanet::EncoderOrdinal::kEncoder1};  
  bool write = false;           
  uint8_t registerAddress = 0;  
  uint8_t value = 0;            
};
 
std::expected<EncoderRegisterRequest, std::string> parseEncoderRegisterRequest(
    const nlohmann::json& body);
 
std::vector<ProcedureParameter> encoderRegisterParameters();
 
std::vector<ProgressStep> encoderRegisterSteps();
 
std::expected<void, std::string> runEncoderRegisterProcedure(Device& device,
                                                             ProgressReporter& reporter,
                                                             std::stop_token stop,
                                                             const EncoderRegisterRequest& request);
 
inline constexpr std::string_view kIcMuCalibrationModeProcedure = "ic-mu-calibration-mode";
 
inline constexpr std::string_view kIcMuCalibrationModeStep = "set-mode";
 
struct IcMuCalibrationModeRequest {
  somanet::EncoderOrdinal encoder{somanet::EncoderOrdinal::kEncoder1};  
 
  somanet::IcMuCalibrationMode mode{somanet::IcMuCalibrationMode::kStandard};
};
 
std::expected<IcMuCalibrationModeRequest, std::string> parseIcMuCalibrationModeRequest(
    const nlohmann::json& body);
 
std::vector<ProcedureParameter> icMuCalibrationModeParameters();
 
std::vector<ProgressStep> icMuCalibrationModeSteps();
 
std::expected<void, std::string> runIcMuCalibrationModeProcedure(
    Device& device, ProgressReporter& reporter, std::stop_token stop,
    const IcMuCalibrationModeRequest& request);
 
inline constexpr std::string_view kHrdStreamingProcedure = "hrd-streaming";
 
inline constexpr std::string_view kHrdConfigureStep = "configure-stream";
 
inline constexpr std::string_view kHrdRecordStep = "record";
 
struct HrdStreamingRequest {
  somanet::HrdData data{somanet::HrdData::kEncoderRawData};
 
  std::chrono::milliseconds duration{};
};
 
std::expected<HrdStreamingRequest, std::string> parseHrdStreamingRequest(
    const nlohmann::json& body);
 
std::vector<ProcedureParameter> hrdStreamingParameters();
 
std::vector<ProgressStep> hrdStreamingSteps();
 
std::expected<void, std::string> runHrdStreamingProcedure(Device& device,
                                                          ProgressReporter& reporter,
                                                          std::stop_token stop,
                                                          const HrdStreamingRequest& request);
 
inline constexpr std::string_view kKueblerRegisterProcedure = "kuebler-register-communication";
 
inline constexpr std::string_view kKueblerRegisterStep = "register-access";
 
struct KueblerRegisterRequest {
  uint8_t address = 0;  
  uint8_t length = 1;   
  bool write = false;   
  uint32_t value = 0;   
};
 
std::expected<KueblerRegisterRequest, std::string> parseKueblerRegisterRequest(
    const nlohmann::json& body);
 
std::vector<ProcedureParameter> kueblerRegisterParameters();
 
std::vector<ProgressStep> kueblerRegisterSteps();
 
std::expected<void, std::string> runKueblerRegisterProcedure(Device& device,
                                                             ProgressReporter& reporter,
                                                             std::stop_token stop,
                                                             const KueblerRegisterRequest& request);
 
inline constexpr std::string_view kVelocitySourceProcedure = "velocity-source";
 
inline constexpr std::string_view kVelocitySourceStep = "set-source";
 
struct VelocitySourceRequest {
  somanet::VelocitySource source{somanet::VelocitySource::kFirmware};
};
 
std::expected<VelocitySourceRequest, std::string> parseVelocitySourceRequest(
    const nlohmann::json& body);
 
std::vector<ProcedureParameter> velocitySourceParameters();
 
std::vector<ProgressStep> velocitySourceSteps();
 
std::expected<void, std::string> runVelocitySourceProcedure(Device& device,
                                                            ProgressReporter& reporter,
                                                            std::stop_token stop,
                                                            const VelocitySourceRequest& request);
 
inline constexpr std::string_view kFirmwareLatencyProcedure = "firmware-latency-measurement";
 
inline constexpr std::string_view kFirmwareLatencyStartStep = "start-measurement";
 
inline constexpr std::string_view kFirmwareLatencyObserveStep = "observe";
 
inline constexpr std::string_view kFirmwareLatencyReadStep = "read-maximum";
 
inline constexpr std::string_view kFirmwareLatencyStopStep = "stop-measurements";
 
enum class FirmwareLatencyAction : uint8_t {
  kMeasure,
  kStart,
  kReadMaximum,
  kStop,
};
 
constexpr std::string_view toString(FirmwareLatencyAction action) {
  switch (action) {
    case FirmwareLatencyAction::kMeasure:
      return "measure";
    case FirmwareLatencyAction::kStart:
      return "start";
    case FirmwareLatencyAction::kReadMaximum:
      return "read-maximum";
    case FirmwareLatencyAction::kStop:
      return "stop";
  }
  return "unknown";
}
 
std::optional<FirmwareLatencyAction> parseFirmwareLatencyAction(std::string_view token);
 
struct FirmwareLatencyRequest {
  FirmwareLatencyAction action{FirmwareLatencyAction::kMeasure};
 
  somanet::FirmwareLatency latency{somanet::FirmwareLatency::kSetpoint};
 
  std::chrono::milliseconds duration{2000};
};
 
std::expected<FirmwareLatencyRequest, std::string> parseFirmwareLatencyRequest(
    const nlohmann::json& body);
 
std::vector<ProcedureParameter> firmwareLatencyParameters();
 
std::vector<ProgressStep> firmwareLatencySteps();
 
std::expected<void, std::string> runFirmwareLatencyProcedure(Device& device,
                                                             ProgressReporter& reporter,
                                                             std::stop_token stop,
                                                             const FirmwareLatencyRequest& request);
 
inline constexpr std::string_view kTriggerErrorProcedure = "trigger-error";
 
inline constexpr std::string_view kTriggerErrorStep = "trigger";
 
struct TriggerErrorRequest {
  somanet::FirmwareService service{somanet::FirmwareService::kDriveControl};
 
  somanet::FirmwareErrorType errorType{somanet::FirmwareErrorType::kResettableFirmwareError};
};
 
std::expected<TriggerErrorRequest, std::string> parseTriggerErrorRequest(
    const nlohmann::json& body);
 
std::vector<ProcedureParameter> triggerErrorParameters();
 
std::vector<ProgressStep> triggerErrorSteps();
 
std::expected<void, std::string> runTriggerErrorProcedure(Device& device,
                                                          ProgressReporter& reporter,
                                                          std::stop_token stop,
                                                          const TriggerErrorRequest& request);
 
inline constexpr std::string_view kSystemIdentificationProcedure = "system-identification";
 
inline constexpr std::string_view kSystemIdConfigureStep = "configure-chirp";
 
inline constexpr std::string_view kSystemIdArmStep = "arm";
 
struct SystemIdentificationRequest {
  uint32_t startFrequencyMilliHz = 0;   
  uint32_t targetFrequencyMilliHz = 0;  
  uint32_t targetAmplitudePermil = 0;   
  uint32_t transitionTimeMs = 0;        
  somanet::ChirpSignalType signalType{somanet::ChirpSignalType::kLogarithmic};  
 
  somanet::SystemIdentificationStart start{somanet::SystemIdentificationStart::kNone};
};
 
std::expected<SystemIdentificationRequest, std::string> parseSystemIdentificationRequest(
    const nlohmann::json& body);
 
std::vector<ProcedureParameter> systemIdentificationParameters();
 
std::vector<ProgressStep> systemIdentificationSteps();
 
std::expected<void, std::string> runSystemIdentificationProcedure(
    Device& device, ProgressReporter& reporter, std::stop_token stop,
    const SystemIdentificationRequest& request);
 
inline constexpr std::string_view kIgnoreBissStatusBitsProcedure = "ignore-biss-status-bits";
 
inline constexpr std::string_view kIgnoreBissStatusBitsStep = "set-ignore";
 
struct IgnoreBissStatusBitsRequest {
  somanet::EncoderOrdinal encoder{somanet::EncoderOrdinal::kEncoder1};  
 
  bool ignore = false;
};
 
std::expected<IgnoreBissStatusBitsRequest, std::string> parseIgnoreBissStatusBitsRequest(
    const nlohmann::json& body);
 
std::vector<ProcedureParameter> ignoreBissStatusBitsParameters();
 
std::vector<ProgressStep> ignoreBissStatusBitsSteps();
 
std::expected<void, std::string> runIgnoreBissStatusBitsProcedure(
    Device& device, ProgressReporter& reporter, std::stop_token stop,
    const IgnoreBissStatusBitsRequest& request);
 
inline constexpr std::string_view kSkippedCyclesProcedure = "skipped-cycles-counter";
 
inline constexpr std::string_view kSkippedCyclesStep = "read-counter";
 
struct SkippedCyclesRequest {
  somanet::FirmwareService service{somanet::FirmwareService::kDriveControl};
};
 
std::expected<SkippedCyclesRequest, std::string> parseSkippedCyclesRequest(
    const nlohmann::json& body);
 
std::vector<ProcedureParameter> skippedCyclesParameters();
 
std::vector<ProgressStep> skippedCyclesSteps();
 
std::expected<void, std::string> runSkippedCyclesProcedure(Device& device,
                                                           ProgressReporter& reporter,
                                                           std::stop_token stop,
                                                           const SkippedCyclesRequest& request);
 
inline constexpr std::string_view kReadObjectDictionaryProcedure = "read-object-dictionary";
 
inline constexpr std::string_view kReadObjectDictionaryStep = "read-dictionary";
 
std::vector<ProgressStep> readObjectDictionarySteps();
 
std::expected<void, std::string> runReadObjectDictionaryProcedure(Device& device,
                                                                  ProgressReporter& reporter,
                                                                  std::stop_token stop);
 
inline constexpr std::string_view kPrepareStep = "prepare";
inline constexpr std::string_view kReleaseBrakeStep = "release-brake";
inline constexpr std::string_view kRestoreStep = "restore";
 
inline constexpr std::string_view kOpenPhaseDetectionProcedure = "open-phase-detection";
 
inline constexpr std::string_view kOpenPhaseDetectionStep = "open-phase-detection";
 
std::vector<ProgressStep> openPhaseDetectionSteps();
 
std::expected<void, std::string> runOpenPhaseDetectionProcedure(Device& device,
                                                                ProgressReporter& reporter,
                                                                std::stop_token stop);
 
inline constexpr std::string_view kPolePairDetectionProcedure = "pole-pair-detection";
 
inline constexpr std::string_view kPolePairDetectionStep = "pole-pair-detection";
 
std::vector<ProgressStep> polePairDetectionSteps();
 
std::expected<void, std::string> runPolePairDetectionProcedure(Device& device,
                                                               ProgressReporter& reporter,
                                                               std::stop_token stop);
 
inline constexpr std::string_view kMotorPhaseOrderDetectionProcedure =
    "motor-phase-order-detection";
 
inline constexpr std::string_view kMotorPhaseOrderDetectionStep = "motor-phase-order-detection";
 
std::vector<ProgressStep> motorPhaseOrderDetectionSteps();
 
std::expected<void, std::string> runMotorPhaseOrderDetectionProcedure(Device& device,
                                                                      ProgressReporter& reporter,
                                                                      std::stop_token stop);
 
inline constexpr std::string_view kOffsetDetectionProcedure = "offset-detection";
 
std::vector<ProgressStep> offsetDetectionSteps();
 
std::expected<void, std::string> runOffsetDetectionProcedure(Device& device,
                                                             ProgressReporter& reporter,
                                                             std::stop_token stop);
 
inline constexpr std::string_view kCommutationOffsetMeasurementProcedure =
    "commutation-offset-measurement";
 
inline constexpr std::string_view kCommutationOffsetMeasurementStep =
    "commutation-offset-measurement";
 
inline constexpr std::string_view kSetBrakeStep = "set-brake";
 
std::vector<ProgressStep> commutationOffsetMeasurementSteps();
 
std::expected<void, std::string> runCommutationOffsetMeasurementProcedure(
    Device& device, ProgressReporter& reporter, std::stop_token stop);
 
inline constexpr std::string_view kPhaseResistanceMeasurementProcedure =
    "phase-resistance-measurement";
 
inline constexpr std::string_view kPhaseResistanceMeasurementStep = "phase-resistance-measurement";
 
std::vector<ProgressStep> phaseResistanceMeasurementSteps();
 
std::expected<void, std::string> runPhaseResistanceMeasurementProcedure(Device& device,
                                                                        ProgressReporter& reporter,
                                                                        std::stop_token stop);
 
inline constexpr std::string_view kPhaseInductanceMeasurementProcedure =
    "phase-inductance-measurement";
 
inline constexpr std::string_view kPhaseInductanceMeasurementStep = "phase-inductance-measurement";
 
std::vector<ProgressStep> phaseInductanceMeasurementSteps();
 
std::expected<void, std::string> runPhaseInductanceMeasurementProcedure(Device& device,
                                                                        ProgressReporter& reporter,
                                                                        std::stop_token stop);
 
inline constexpr std::string_view kTorqueConstantMeasurementProcedure =
    "torque-constant-measurement";
 
inline constexpr std::string_view kTorqueConstantMeasurementStep = "torque-constant-measurement";
 
std::vector<ProgressStep> torqueConstantMeasurementSteps();
 
std::expected<void, std::string> runTorqueConstantMeasurementProcedure(Device& device,
                                                                       ProgressReporter& reporter,
                                                                       std::stop_token stop);
 
// ── Firmware installation ──────────────────────────────────────────────────────────────────────
//
// The one procedure here that changes AL state. Installing firmware *is* a sequence of transitions
// (BOOT, write the files, back), so it takes the manager and the position rather than one device.
 
 
inline constexpr std::string_view kFirmwareInstallationProcedure = "firmware-installation";
 
 
struct FirmwareInstallationRequest {
  std::vector<uint8_t> package;  
  std::string filename;          
  std::optional<FirmwarePackageName> name;
  std::vector<std::string> skipFiles;  
  bool cachePackage = true;            
  mm::comm::EtherCatState finalState = mm::comm::EtherCatState::PreOp;
 
  std::chrono::milliseconds bootWarmUp{2000};
};
 
std::filesystem::path firmwareCacheDir();
 
std::vector<ProcedureParameter> firmwareInstallationParameters();
 
std::vector<ProgressStep> firmwareInstallationSteps();
 
std::expected<FirmwareInstallationRequest, std::string> parseFirmwareInstallationRequest(
    const nlohmann::json& body);
 
std::expected<void, std::string> runFirmwareInstallationProcedure(
    DeviceManager& deviceManager, uint16_t devicePosition, ProgressReporter& reporter,
    std::stop_token stop, const FirmwareInstallationRequest& request);
 
}  // namespace mm::node