Introduce Stepper Motor API

[jilaypandya]

Introduction

Zephyr at present does not have a provision to control stepper motors. Stepper Motor Controllers and Stepper Motor Devices do have a set of common functions which can be bundled together in a set of APIs as presented in this PR.

Problem description

There are quite a few stepper motor controllers out there which if upstreamed could benefit the community hugely, however, in contrast to Sensors API, there is a no API present in the Zephyr for such controllers as of now.

Proposed change

This RFC aims to introduce a set of APIs allowing generalised access to stepper motor controllers and devices along with establishing a common understanding as to how these devices should appear in a device tree.

Detailed RFC

A typical setup for controlling a stepper motor device, could be as follows

The stepper motor subsystem is divided into two APIs, namely:
- Stepper Motor Device API
- Stepper Motor Controller API

Now the question might arise as to why should the functionalities be divided into two different APIs. Brief explanation is like this:
- Business or proprietary logic could be implemented using stepper motor device api and does not have to be upstreamed
- Community benefiting implementation of a stepper motor controller could be upstreamed

The stepper motor device API provides following functions:
- Calibrating a Motor
- Freewheeling a motor in +/- direction
- Stopping the Motor
- Setting various Motor Positions
- Getting various Motor Positions

The stepper motor controller API provides following functions:
- Reset Stepper Motor Controller
- Write to Stepper Motor Controller
- Read from Stepper Motor Controller
- Direct Write Access to Stepper Motor Controller Specific Registers
- Direct Read Access to Stepper Motor Controller Specific Registers

The DTS snippet below aims to depict the actual hardware setup i.e. a stepper motor device is connected to a stepper motor controller which in turn is connected to a spi controller

In the example below, my_motor_controller is a motor bus node. All generic motor controller properties should be put in stepper-motor-controller.yaml. Just as my_motor_controller in on-bus:spi i.e. a spi-device, my_motor would be a child node of my_motor_controller and on-bus:motor i.e. a motor device. Presently some generic stepper motor device properties have been included in stepper-motor-device.yaml.

&spi_controller { // bus:spi
  status = "okay";

  my_motor_controller: my_motor_controller@0 { // bus:motor & on-bus:spi
    status = "okay";
    compatible = "my_motor,controller";
    reg = <0>;
    #address-cells = <1>;
    #size-cells = <0>;

    my_motor: my_motor_0@0{ //on-bus: motor
      status = "okay";
      compatible = "tmc5041-stepper-motor-device";
      reg=<0>;
      gear-ratio = "1.234567";
      micro-step-res = <256>;
      steps-per-revolution = <200>;
      stall-guard-setting = <6>;
      controller-spec-reg-settings = <SPEC_REG_ADD_FOR_MOTOR_0(0)  SPEC_REG_VALUE_FOR_MOTOR_0>;
    };

    my_motor: my_motor_1@1{ //on-bus: motor
      status = "okay";
      compatible = "tmc5041-stepper-motor-device";
      reg=<1>;
      gear-ratio = "9.876543";
      micro-step-res = <128>;
      steps-per-revolution = <200>;
      stall-guard-setting = <0>;
      controller-spec-reg-settings = <SPEC_REG_ADD_FOR_MOTOR_1(1)  SPEC_REG_VALUE_FOR_MOTOR_1>;
    };
  };
};

Dependencies

This change should not disrupt any existing component within the project.

[jilaypandya]

moved to #68547