somanet_procedures.h File Reference

SOMANET procedure bodies — the work a ProcedureManager run performs. More...

#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"

Include dependency graph for somanet_procedures.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	mm::node::OsCommandRequest
	What one raw OS command run was asked to do. More...
struct	mm::node::OsCommandResult
	What one raw OS command run produced — the step's value. More...
struct	mm::node::EncoderRegisterRequest
	What one encoder register access was asked to do. More...
struct	mm::node::IcMuCalibrationModeRequest
	What one iC-MU calibration mode change was asked to do. More...
struct	mm::node::HrdStreamingRequest
	What one high resolution data recording was asked to capture. More...
struct	mm::node::KueblerRegisterRequest
	What one Kübler register access was asked to do. More...
struct	mm::node::VelocitySourceRequest
	Which velocity the control loop should use. More...
struct	mm::node::FirmwareLatencyRequest
	What one firmware latency run was asked to do. More...
struct	mm::node::TriggerErrorRequest
	Which service to break, and how. More...
struct	mm::node::SystemIdentificationRequest
	One system identification run, as a client describes it. More...
struct	mm::node::IgnoreBissStatusBitsRequest
	Which encoder's status bits to act on, and which way. More...
struct	mm::node::SkippedCyclesRequest
	Which control loop's counter to read. More...
struct	mm::node::FirmwareInstallationRequest
	Where an install leaves the device, as an AL state. More...

Namespaces
namespace	mm
namespace	mm::node

Enumerations
enum class	mm::node::FirmwareLatencyAction : uint8_t { mm::node::kMeasure , mm::node::kStart , mm::node::kReadMaximum , mm::node::kStop }
	What one firmware latency run should do. More...

Functions
std::expected< OsCommandRequest, std::string >	mm::node::parseOsCommandRequest (const nlohmann::json &body)
	Parses and validates a client's OS command request body.
std::vector< ProcedureParameter >	mm::node::osCommandParameters ()
	What the OS command procedure accepts, as its descriptor advertises it.
void	mm::node::to_json (nlohmann::json &j, const OsCommandResult &result)
std::vector< ProgressStep >	mm::node::osCommandSteps ()
	The OS command procedure's step template — one step, all idle.
std::expected< void, std::string >	mm::node::runOsCommandProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const OsCommandRequest &request)
	Runs one raw OS command as a procedure body.
std::expected< EncoderRegisterRequest, std::string >	mm::node::parseEncoderRegisterRequest (const nlohmann::json &body)
	Parses and validates a client's encoder register request body.
std::vector< ProcedureParameter >	mm::node::encoderRegisterParameters ()
	What encoder register communication accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::encoderRegisterSteps ()
	Encoder register communication's step template — one step, idle.
std::expected< void, std::string >	mm::node::runEncoderRegisterProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const EncoderRegisterRequest &request)
	Runs one encoder register access as a procedure body.
std::expected< IcMuCalibrationModeRequest, std::string >	mm::node::parseIcMuCalibrationModeRequest (const nlohmann::json &body)
	Parses and validates a client's iC-MU calibration mode request body.
std::vector< ProcedureParameter >	mm::node::icMuCalibrationModeParameters ()
	What setting an iC-MU calibration mode accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::icMuCalibrationModeSteps ()
	The iC-MU calibration mode procedure's step template — one step, idle.
std::expected< void, std::string >	mm::node::runIcMuCalibrationModeProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const IcMuCalibrationModeRequest &request)
	Sets an iC-MU encoder's calibration mode as a procedure body.
std::expected< HrdStreamingRequest, std::string >	mm::node::parseHrdStreamingRequest (const nlohmann::json &body)
	Parses and validates a client's HRD streaming request body.
std::vector< ProcedureParameter >	mm::node::hrdStreamingParameters ()
	What HRD streaming accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::hrdStreamingSteps ()
	The HRD streaming procedure's step template — configure, then record.
std::expected< void, std::string >	mm::node::runHrdStreamingProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const HrdStreamingRequest &request)
	Records one high resolution data stream as a procedure body.
std::expected< KueblerRegisterRequest, std::string >	mm::node::parseKueblerRegisterRequest (const nlohmann::json &body)
	Parses and validates a client's Kübler register request body.
std::vector< ProcedureParameter >	mm::node::kueblerRegisterParameters ()
	What a Kübler register access accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::kueblerRegisterSteps ()
	The Kübler register procedure's step template — one step, idle.
std::expected< void, std::string >	mm::node::runKueblerRegisterProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const KueblerRegisterRequest &request)
	Reads or writes one Integro internal-encoder register as a procedure body.
std::expected< VelocitySourceRequest, std::string >	mm::node::parseVelocitySourceRequest (const nlohmann::json &body)
	Parses and validates a client's velocity source request body.
std::vector< ProcedureParameter >	mm::node::velocitySourceParameters ()
	What choosing the velocity source accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::velocitySourceSteps ()
	The velocity-source procedure's step template — one step, idle.
std::expected< void, std::string >	mm::node::runVelocitySourceProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const VelocitySourceRequest &request)
	Chooses the velocity loop's feedback source as a procedure body.
constexpr std::string_view	mm::node::toString (FirmwareLatencyAction action)
	Name of a firmware latency action (for JSON). Never returns nullptr.
std::optional< FirmwareLatencyAction >	mm::node::parseFirmwareLatencyAction (std::string_view token)
	Parses a firmware latency action token. std::nullopt if it names none of them.
std::expected< FirmwareLatencyRequest, std::string >	mm::node::parseFirmwareLatencyRequest (const nlohmann::json &body)
	Parses and validates a client's firmware latency request body.
std::vector< ProcedureParameter >	mm::node::firmwareLatencyParameters ()
	What measuring a firmware latency accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::firmwareLatencySteps ()
	The firmware latency procedure's step template — start, observe, read, stop.
std::expected< void, std::string >	mm::node::runFirmwareLatencyProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const FirmwareLatencyRequest &request)
	Measures one internal firmware latency as a procedure body.
std::expected< TriggerErrorRequest, std::string >	mm::node::parseTriggerErrorRequest (const nlohmann::json &body)
	Parses and validates a client's trigger-error request body.
std::vector< ProcedureParameter >	mm::node::triggerErrorParameters ()
	What provoking a firmware error accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::triggerErrorSteps ()
	The trigger-error procedure's step template — one step, idle.
std::expected< void, std::string >	mm::node::runTriggerErrorProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const TriggerErrorRequest &request)
	Provokes a firmware error in a control service as a procedure body.
std::expected< SystemIdentificationRequest, std::string >	mm::node::parseSystemIdentificationRequest (const nlohmann::json &body)
	Parses and validates a client's system identification request body.
std::vector< ProcedureParameter >	mm::node::systemIdentificationParameters ()
	What system identification accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::systemIdentificationSteps ()
	The system identification procedure's step template — configure, then arm.
std::expected< void, std::string >	mm::node::runSystemIdentificationProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const SystemIdentificationRequest &request)
	Configures and optionally arms a system identification run as a procedure body.
std::expected< IgnoreBissStatusBitsRequest, std::string >	mm::node::parseIgnoreBissStatusBitsRequest (const nlohmann::json &body)
	Parses and validates a client's ignore-BiSS-status-bits request body.
std::vector< ProcedureParameter >	mm::node::ignoreBissStatusBitsParameters ()
	What ignoring BiSS status bits accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::ignoreBissStatusBitsSteps ()
	The ignore-BiSS-status-bits procedure's step template — one step, idle.
std::expected< void, std::string >	mm::node::runIgnoreBissStatusBitsProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const IgnoreBissStatusBitsRequest &request)
	Starts or stops ignoring a BiSS encoder's status bits as a procedure body.
std::expected< SkippedCyclesRequest, std::string >	mm::node::parseSkippedCyclesRequest (const nlohmann::json &body)
	Parses and validates a client's skipped cycles request body.
std::vector< ProcedureParameter >	mm::node::skippedCyclesParameters ()
	What reading a skipped cycles counter accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::skippedCyclesSteps ()
	The skipped cycles procedure's step template — one step, idle.
std::expected< void, std::string >	mm::node::runSkippedCyclesProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop, const SkippedCyclesRequest &request)
	Reads one control loop's skipped-cycle counter as a procedure body.
std::vector< ProgressStep >	mm::node::readObjectDictionarySteps ()
	The read-object-dictionary procedure's step template — one step, idle.
std::expected< void, std::string >	mm::node::runReadObjectDictionaryProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop)
	Reads every object dictionary value in one transfer, as a procedure body.
std::vector< ProgressStep >	mm::node::openPhaseDetectionSteps ()
	Open phase detection's step template — prepare, check, restore, all idle.
std::expected< void, std::string >	mm::node::runOpenPhaseDetectionProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop)
	Runs open phase detection as a procedure body.
std::vector< ProgressStep >	mm::node::polePairDetectionSteps ()
	Pole pair detection's step template — prepare, release the brake, detect, restore.
std::expected< void, std::string >	mm::node::runPolePairDetectionProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop)
	Runs pole pair detection as a procedure body.
std::vector< ProgressStep >	mm::node::motorPhaseOrderDetectionSteps ()
	Motor phase order detection's step template — prepare, release the brake, detect, restore.
std::expected< void, std::string >	mm::node::runMotorPhaseOrderDetectionProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop)
	Runs motor phase order detection as a procedure body.
std::vector< ProgressStep >	mm::node::offsetDetectionSteps ()
	The commissioning sequence's step template — every command in the order it runs, plus the shared prepare, brake and restore steps.
std::expected< void, std::string >	mm::node::runOffsetDetectionProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop)
	Runs the whole commissioning sequence as one procedure body.
std::vector< ProgressStep >	mm::node::commutationOffsetMeasurementSteps ()
	Commutation offset measurement's step template — prepare, release the brake, measure, restore.
std::expected< void, std::string >	mm::node::runCommutationOffsetMeasurementProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop)
	Runs commutation offset measurement as a procedure body — OS command 5 and nothing else.
std::vector< ProgressStep >	mm::node::phaseResistanceMeasurementSteps ()
	Phase resistance measurement's step template — prepare, measure, restore, all idle.
std::expected< void, std::string >	mm::node::runPhaseResistanceMeasurementProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop)
	Runs phase resistance measurement as a procedure body.
std::vector< ProgressStep >	mm::node::phaseInductanceMeasurementSteps ()
	Phase inductance measurement's step template — prepare, measure, restore, all idle.
std::expected< void, std::string >	mm::node::runPhaseInductanceMeasurementProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop)
	Runs phase inductance measurement as a procedure body.
std::vector< ProgressStep >	mm::node::torqueConstantMeasurementSteps ()
	Torque constant measurement's step template — prepare, release the brake, measure, restore.
std::expected< void, std::string >	mm::node::runTorqueConstantMeasurementProcedure (Device &device, ProgressReporter &reporter, std::stop_token stop)
	Runs torque constant measurement as a procedure body.
std::filesystem::path	mm::node::firmwareCacheDir ()
	Where installed packages are kept: a firmwares subdirectory of the per-user cache.
std::vector< ProcedureParameter >	mm::node::firmwareInstallationParameters ()
	What the procedure accepts, as its descriptor advertises it.
std::vector< ProgressStep >	mm::node::firmwareInstallationSteps ()
	The procedure's step template, in order.
std::expected< FirmwareInstallationRequest, std::string >	mm::node::parseFirmwareInstallationRequest (const nlohmann::json &body)
	Parses and validates a client's installation request.
std::expected< void, std::string >	mm::node::runFirmwareInstallationProcedure (DeviceManager &deviceManager, uint16_t devicePosition, ProgressReporter &reporter, std::stop_token stop, const FirmwareInstallationRequest &request)
	Installs request's package on the device at devicePosition.

Variables
constexpr std::string_view	mm::node::kOsCommandProcedure = "os-command"
	Procedure name for the raw OS command, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kOsCommandStep = "command"
	The single step the OS command procedure reports against.
constexpr std::string_view	mm::node::kEncoderRegisterProcedure = "encoder-register-communication"
	Procedure name for encoder register communication, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kEncoderRegisterStep = "register-access"
	The single step encoder register communication reports against.
constexpr std::string_view	mm::node::kIcMuCalibrationModeProcedure = "ic-mu-calibration-mode"
	Procedure name for setting an iC-MU calibration mode, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kIcMuCalibrationModeStep = "set-mode"
	The single step setting an iC-MU calibration mode reports against.
constexpr std::string_view	mm::node::kHrdStreamingProcedure = "hrd-streaming"
	Procedure name for recording a high resolution data stream, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kHrdConfigureStep = "configure-stream"
	The step that arms the recording — chooses the signal and the duration, and clears the files the last recording left behind.
constexpr std::string_view	mm::node::kHrdRecordStep = "record"
	The step that records. Occupies the whole configured duration.
constexpr std::string_view	mm::node::kKueblerRegisterProcedure = "kuebler-register-communication"
	Procedure name for a Kübler encoder register access, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kKueblerRegisterStep = "register-access"
	The single step a Kübler register access reports against.
constexpr std::string_view	mm::node::kVelocitySourceProcedure = "velocity-source"
	Procedure name for choosing the velocity feedback source, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kVelocitySourceStep = "set-source"
	The single step choosing the velocity source reports against.
constexpr std::string_view	mm::node::kFirmwareLatencyProcedure = "firmware-latency-measurement"
	Procedure name for measuring a firmware latency, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kFirmwareLatencyStartStep = "start-measurement"
	The step that starts a measurement, and clears whatever the latency recorded.
constexpr std::string_view	mm::node::kFirmwareLatencyObserveStep = "observe"
	The step that lets the drive run while the measurement collects. Occupies the whole requested duration, and only FirmwareLatencyAction::kMeasure performs it.
constexpr std::string_view	mm::node::kFirmwareLatencyReadStep = "read-maximum"
	The step that reads and clears the recorded maximum.
constexpr std::string_view	mm::node::kFirmwareLatencyStopStep = "stop-measurements"
	The step that stops both measurements.
constexpr std::string_view	mm::node::kTriggerErrorProcedure = "trigger-error"
	Procedure name for provoking a firmware error, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kTriggerErrorStep = "trigger"
	The single step provoking a firmware error reports against.
constexpr std::string_view	mm::node::kSystemIdentificationProcedure = "system-identification"
	Procedure name for configuring a system identification run, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kSystemIdConfigureStep = "configure-chirp"
	The step that writes the chirp's five settings.
constexpr std::string_view	mm::node::kSystemIdArmStep = "arm"
	The step that arms the run — or disarms it.
constexpr std::string_view	mm::node::kIgnoreBissStatusBitsProcedure = "ignore-biss-status-bits"
	Procedure name for ignoring a BiSS encoder's status bits, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kIgnoreBissStatusBitsStep = "set-ignore"
	The single step ignoring BiSS status bits reports against.
constexpr std::string_view	mm::node::kSkippedCyclesProcedure = "skipped-cycles-counter"
	Procedure name for reading a skipped cycles counter, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kSkippedCyclesStep = "read-counter"
	The single step reading a skipped cycles counter reports against.
constexpr std::string_view	mm::node::kReadObjectDictionaryProcedure = "read-object-dictionary"
	Procedure name for reading the whole object dictionary, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kReadObjectDictionaryStep = "read-dictionary"
	The single step reading the whole object dictionary reports against.
constexpr std::string_view	mm::node::kPrepareStep = "prepare"
	The step ids shared by every procedure that prepares a drive, measures, and puts it back.
constexpr std::string_view	mm::node::kReleaseBrakeStep = "release-brake"
constexpr std::string_view	mm::node::kRestoreStep = "restore"
constexpr std::string_view	mm::node::kOpenPhaseDetectionProcedure = "open-phase-detection"
	Procedure name for open phase detection, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kOpenPhaseDetectionStep = "open-phase-detection"
	The step open phase detection's own measurement reports against.
constexpr std::string_view	mm::node::kPolePairDetectionProcedure = "pole-pair-detection"
	Procedure name for pole pair detection, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kPolePairDetectionStep = "pole-pair-detection"
	The step pole pair detection's own measurement reports against.
constexpr std::string_view	mm::node::kMotorPhaseOrderDetectionProcedure
	Procedure name for motor phase order detection, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kMotorPhaseOrderDetectionStep = "motor-phase-order-detection"
	The step motor phase order detection's own measurement reports against.
constexpr std::string_view	mm::node::kOffsetDetectionProcedure = "offset-detection"
	Procedure name for the whole commissioning sequence, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kCommutationOffsetMeasurementProcedure
	Procedure name for commutation offset measurement, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kCommutationOffsetMeasurementStep
	The step commutation offset measurement's own measurement reports against.
constexpr std::string_view	mm::node::kSetBrakeStep = "set-brake"
	The step that puts the brake where the configured method needs it.
constexpr std::string_view	mm::node::kPhaseResistanceMeasurementProcedure
	Procedure name for phase resistance measurement, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kPhaseResistanceMeasurementStep = "phase-resistance-measurement"
	The step phase resistance measurement's own measurement reports against.
constexpr std::string_view	mm::node::kPhaseInductanceMeasurementProcedure
	Procedure name for phase inductance measurement, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kPhaseInductanceMeasurementStep = "phase-inductance-measurement"
	The step phase inductance measurement's own measurement reports against.
constexpr std::string_view	mm::node::kTorqueConstantMeasurementProcedure
	Procedure name for torque constant measurement, as it appears in its URL and its snapshot key.
constexpr std::string_view	mm::node::kTorqueConstantMeasurementStep = "torque-constant-measurement"
	The step torque constant measurement's own measurement reports against.
constexpr std::string_view	mm::node::kFirmwareInstallationProcedure = "firmware-installation"
	Procedure name, as it appears in its URL and its snapshot key.

Detailed Description

SOMANET procedure bodies — the work a ProcedureManager run performs.

Firmware installation, the one procedure that changes AL state.

Distinct from cia402_control.h in shape as well as content: a control function is addressed by bus position and borrows the device itself, while a procedure body receives a Device& already borrowed by the manager, plus the reporter to record progress on and the token to check for cancellation. Bodies bind whatever profile view they need, which is what keeps ProcedureManager profile-ignorant.

It takes DeviceManager& and a position rather than a Device&, because transitionToState is a whole-bus operation and this procedure is defined by its transitions. It resolves the device again for each step, so a rescan mid-install ends the run cleanly at the next step.