Merge pull request #765 from PHOENIXCONTACT/rework/driver-api

Rework of Driver APIs

Author: dbeuchler

docs/migrations/v8_to_v10.md

@@ -76,3 +76,12 @@ These feature were infrequently used and has been removed to simplify the codeba
 
 - Moryx.Tools.FunctionResult: Moved to Moryx.Tools
 - Moryx.AbstractionLayer namespace: All classes have been moved to more specific domain namespaces e.g. Moryx.AbstractionLayer.Resources, Moryx.AbstractionLayer.Products, Moryx.AbstractionLayer.Processes etc.
+
+## Reworked driver APIs
+
+All driver APIs have been reworked to use TPL async/await instead of callbacks for the following reasons:
+
+- The same logic looks almost synchronous.
+- Cleaner and integrates seamlessly with .NET’s exception system.
+- You can chain tasks with LINQ-like methods or await syntax.
+- Async stack-traces in IDE show the actual logical call flow — even across await boundaries.

src/Moryx.AbstractionLayer/Drivers/Axis/AxisMovement.cs

@@ -0,0 +1,47 @@
+// Copyright (c) 2025, Phoenix Contact GmbH & Co. KG
+// Licensed under the Apache License, Version 2.0
+
+namespace Moryx.AbstractionLayer.Drivers.Axis;
+
+/// <summary>
+/// Defines a axis movement
+/// </summary>
+public class AxisMovement
+{
+    /// <summary>
+    /// The axis which should be moved
+    /// </summary>
+    public Axes Axis { get; }
+
+    /// <summary>
+    /// Target position of the axis to move to
+    /// </summary>
+    public double? TargetPosition { get; }
+
+    /// <summary>
+    /// Predefined position of the axis to move to
+    /// </summary>
+    public AxisPosition? PredefinedPosition { get; }
+
+    /// <summary>
+    /// Creates a new instance of <see cref="AxisMovement"/> with a target position
+    /// </summary>
+    /// <param name="axis">The axis which should be moved</param>
+    /// <param name="targetPosition">Target position of the axis to move to</param>
+    public AxisMovement(Axes axis, double targetPosition)
+    {
+        Axis = axis;
+        TargetPosition = targetPosition;
+    }
+
+    /// <summary>
+    /// Creates a new instance of <see cref="AxisMovement"/> with a predefined position
+    /// </summary>
+    /// <param name="axis">The axis which should be moved</param>
+    /// <param name="predefinedPosition">Predefined position of the axis to move to</param>
+    public AxisMovement(Axes axis, AxisPosition predefinedPosition)
+    {
+        Axis = axis;
+        PredefinedPosition = predefinedPosition;
+    }
+}

src/Moryx.AbstractionLayer/Drivers/Axis/AxisMovementResponse.cs

@@ -6,23 +6,8 @@ namespace Moryx.AbstractionLayer.Drivers.Axis
     /// <summary>
     /// Response of the marking file setup
     /// </summary>
-    public class AxisMovementResponse : TransmissionResult
+    public class AxisMovementResponse
     {
-        /// <summary>
-        /// Successfull movement of the axis
-        /// </summary>
-        public AxisMovementResponse() : base()
-        {
 
-        }
-
-        /// <summary>
-        /// Faulty movement of the axis
-        /// </summary>
-        /// <param name="errorMessage">Occured error</param>
-        public AxisMovementResponse(string errorMessage) : base(new TransmissionError(errorMessage))
-        {
-
-        }
     }
 }

src/Moryx.AbstractionLayer/Drivers/Axis/IAxesController.cs

@@ -9,19 +9,13 @@ namespace Moryx.AbstractionLayer.Drivers.Axis
     public interface IAxesController : IDriver
     {
         /// <summary>
-        /// Will move the axis of the laser to the given position
+        /// Will move the axes of the system to the given position
         /// </summary>
-        /// <param name="axis">The axis which should be moved</param>
-        /// <param name="targetPosition">The target position of the axis</param>
-        /// <param name="callback">The callback which will be executed after the axis movement</param>
-        void MoveAxis(Axes axis, double targetPosition, DriverResponse<AxisMovementResponse> callback);
-
-        /// <summary>
-        /// Will move the axis of the laser to the given position
-        /// </summary>
-        /// <param name="axis">The axis which should be moved</param>
-        /// <param name="targetPosition">The target position of the axis</param>
-        /// <param name="callback">The callback which will be executed after the axis movement</param>
-        void MoveAxis(Axes axis, AxisPosition targetPosition, DriverResponse<AxisMovementResponse> callback);
+        /// <param name="cancellationToken">The token to monitor for cancellation requests. The default value is None.</param>
+        /// <param name="movement">Array of axes which should be moved</param>
+        /// <exception cref="DriverStateException">Will be thrown when the driver is in wrong state</exception>
+        /// <exception cref="MoveAxesException">Will be thrown for errors during moving axes</exception>
+        /// <exception cref="OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.</exception>
+        Task<AxisMovementResponse> MoveAxesAsync(CancellationToken cancellationToken = default, params AxisMovement[] movement);
     }
 }

src/Moryx.AbstractionLayer/Drivers/Axis/MoveAxesException.cs

@@ -0,0 +1,11 @@
+// Copyright (c) 2025, Phoenix Contact GmbH & Co. KG
+// Licensed under the Apache License, Version 2.0
+
+namespace Moryx.AbstractionLayer.Drivers.Axis;
+
+/// <summary>
+/// Exception type which will be used for errors during moving axes of <see cref="IAxesController"/>
+/// </summary>
+public class MoveAxesException : Exception
+{
+}

src/Moryx.AbstractionLayer/Drivers/Axis/NumberedAxis.cs

@@ -12,6 +12,7 @@ public struct NumberedAxis : IEquatable<NumberedAxis>
         /// Axis
         /// </summary>
         public Axes Axis { get; }
+
         /// <summary>
         /// Number
         /// </summary>

src/Moryx.AbstractionLayer/Drivers/Camera/ICameraDriver.cs

@@ -1,26 +1,26 @@
 // Copyright (c) 2025, Phoenix Contact GmbH & Co. KG
 // Licensed under the Apache License, Version 2.0
 
-namespace Moryx.AbstractionLayer.Drivers.Camera
+namespace Moryx.AbstractionLayer.Drivers.Camera;
+
+/// <summary>
+/// Interface for camera devices, that provide image data
+/// </summary>
+public interface ICameraDriver<TImage> : IDriver where TImage : class
 {
     /// <summary>
-    /// Interface for camera devices, that provide image data
+    /// Capture a single image from the camera
     /// </summary>
-    public interface ICameraDriver<TImage> : IDriver where TImage : class
-    {
-        /// <summary>
-        /// Eventhandler to continously provide images from a camera
-        /// </summary>
-        event EventHandler<TImage> CapturedImage;
+    /// <param name="cancellationToken">The token to monitor for cancellation requests. The default value is None.</param>
+    /// <returns>
+    ///     The image that was captured or null in case no image
+    ///     could be retrieved
+    /// </returns>
+    /// <exception cref="OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.</exception>
+    Task<TImage> CaptureImageAsync(CancellationToken cancellationToken = default);
 
-        /// <summary>
-        /// Capture a single image from the camera
-        /// </summary>
-        /// <returns>
-        ///     The image that was captured or null in case no image
-        ///     could be retrieved
-        /// </returns>
-        Task<TImage?> CaptureImage();
-    }
+    /// <summary>
+    /// Event to continuously provide images from a camera
+    /// </summary>
+    event EventHandler<TImage> CapturedImage;
 }
-

src/Moryx.AbstractionLayer/Drivers/Driver.cs

@@ -11,7 +11,7 @@ namespace Moryx.AbstractionLayer.Drivers
     /// </summary>
     public abstract class Driver : Resource, IDriver, IStateContext
     {
-        /// <see cref="IDriver"/>
+        /// <inheritdoc />
         public IDriverState CurrentState { get; private set; }
 
         void IStateContext.SetState(IState state)
@@ -20,7 +20,7 @@ void IStateContext.SetState(IState state)
             StateChanged?.Invoke(this, CurrentState);
         }
 
-        /// <seealso cref="IDriver"/>
+        /// <inheritdoc />
         public event EventHandler<IDriverState> StateChanged;
     }
 }

src/Moryx.AbstractionLayer/Drivers/DriverNotRunningException.cs

@@ -0,0 +1,25 @@
+// Copyright (c) 2025, Phoenix Contact GmbH & Co. KG
+// Licensed under the Apache License, Version 2.0
+
+namespace Moryx.AbstractionLayer.Drivers
+{
+    /// <summary>
+    /// Exception for busy drivers. The driver cannot handle requests.
+    /// </summary>
+    public class DriverStateException : Exception
+    {
+        /// <summary>
+        /// Information about the required state of the driver for the execution
+        /// </summary>
+        public StateClassification RequiredState { get; }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DriverStateException"/> class.
+        /// </summary>
+        public DriverStateException(StateClassification requiredState)
+            : base($"Cannot handle the driver request. Driver is not in state {requiredState}!")
+        {
+            RequiredState = requiredState;
+        }
+    }
+}