Configure a DMC4000-Controlled Motor

The DMC4000 model supports stepper motors controlled by DMC-40x0 series motion controllers.

Whereas a basic low-level stepper driver supported by the gpiostepper model sends power to a stepper motor based on PWM signals from GPIO pins, the DMC40x0 motion controller has many motion control features. When using it, you do not need to configure a board component because it handles computation and signal creation on the motion controller itself.

The DMC-40x0 controller can drive a variety of motor types, but the built-in Viam implementation supports only stepper motors at this time. You can drive other types of motors with Viam and the DMC-40x0 controller by creating a modular resource to add support for it.

Physically connect your motor to the DMC controller, and connect the controller to your machine’s computer. Power both on. Then, configure the motor:

Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Click the + icon next to your machine part in the left-hand menu and select Component. Select the motor type, then select the DMC4000 model. Enter a name or use the suggested name for your motor and click Create.

A DMC4000 motor config with the attributes configured per the JSON on the next tab in this doc.

Edit and fill in the attributes as applicable.

{
  "components": [
    {
      "name": "<your-motor-name>",
      "model": "DMC4000",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "amplifier_gain": <int>,
        "low_current": <int>,
        "ticks_per_rotation": <int>,
        "serial_path": <string>,
        "controller_axis": "<your-motion-controller-axis-label>",
        "home_rpm": <int>,
        "max_rpm": <float>,
        "max_acceleration_rpm_per_sec": <float>
      },
      "depends_on": []
    }
  ]
}

Example configuration for a stepper motor controlled by a DMC-40x0 motion controller:

{
  "components": [
    {
      "name": "my-dmc-motor",
      "model": "DMC4000",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "amplifier_gain": 3,
        "low_current": 1,
        "ticks_per_rotation": 200,
        "serial_path": "/dev/serial/by-path/usb-0:1.1:1.0",
        "controller_axis": "A",
        "home_rpm": 70,
        "max_rpm": 300
      },
      "depends_on": []
    }
  ]
}

The "serial_path" filepath used in this example is specific to serial devices connected to Linux systems. The "serial_path" filepath on a macOS system might resemble "/dev/ttyUSB0" or "/dev/ttyS0".

The following attributes are available for DMC4000 motors:

NameTypeRequired?Description
amplifier_gainintRequiredSet the per phase current (when using stepper amp).
low_currentintRequiredReduce the hold current.
ticks_per_rotationintRequiredNumber of full steps in a rotation. 200 (equivalent to 1.8 degrees per step) is very common. If your data sheet specifies this in terms of degrees per step, divide 360 by that number to get ticks per rotation.
serial_pathstringOptionalThe full filesystem path to the serial device, starting with /dev/. To find your serial device path, first connect the serial device to your machine, then:
  • On Linux, run ls /dev/serial/by-path/* to show connected serial devices, or look for your device in the output of sudo dmesg | grep tty. Example: "/dev/serial/by-path/usb-0:1.1:1.0".
  • On macOS, run ls /dev/tty* | grep -i usb to show connected USB serial devices, ls /dev/tty* to browse all devices, or look for your device in the output of sudo dmesg | grep tty. Example: "/dev/ttyS0".

If you do not provide a serial_path, the driver will attempt to auto-detect the path to your serial device.
controller_axisstringRequiredPhysical port label (A-H); select which “axis” the motor is wired to on the controller.
home_rpmintRequiredSet speed in revolutions per minute (RPM) that the motor will turn when executing a Home() command (using DoCommand()).
dir_flipboolOptionalFlip the direction of the signal sent if there is a DIR pin.
max_rpmfloatOptionalSet a limit on maximum revolutions per minute that the motor can be run at.
max_acceleration_rpm_per_secfloatOptionalSet the maximum revolutions per minute (RPM) per second acceleration limit.

Refer to your motor and motor driver data sheets for specifics.

Extended API

The DMC4000 model supports additional methods that are not part of the standard Viam motor API:

Home

Run the DMC homing routine.

Parameters:

  • None

Raises:

  • (error): An error, if one occurred.

For more information on do_command, see the Python SDK Docs.

my_motor = Motor.from_robot(robot=robot, name='my_motor')

# Home the motor
home_dict = {
  "command": "home"
}
await my_motor.do_command(home_dict)

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

  • (error): An error, if one occurred.

For more information, see the Go SDK docs on Home and on DoCommand.

// Home the motor
resp, err := myMotorComponent.DoCommand(ctx, map[string]interface{}{"command": "home"})

Jog

Move the motor indefinitely at the specified RPM.

Parameters:

  • rpm (float64): The revolutions per minute at which the motor will turn indefinitely.

Raises:

  • (error): An error, if one occurred.

For more information on do_command, see the Python SDK Docs.

my_motor = Motor.from_robot(robot=robot, name='my_motor')

# Run the motor indefinitely at 70 rpm
jog_dict = {
  "command": "jog",
  "rpm": 70
}
await my_motor.do_command(jog_dict)

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • rpm (float64): The revolutions per minute at which the motor will turn indefinitely.

Returns:

  • (error): An error, if one occurred.

For more information, see the Go SDK Docs on Jog and on DoCommand.

// Run the motor indefinitely at 70 rpm
resp, err := myMotorComponent.DoCommand(ctx, map[string]interface{}{"command": "jog", "rpm": 70})

Raw

Send raw string commands to the controller.

Parameters:

  • raw_input (String): The raw string to send to the controller.

Raises:

  • (error): An error, if one occurred.

For more information on do_command, see the Python SDK Docs.

my_motor = Motor.from_robot(robot=robot, name='my_motor')

raw_dict = {
  "command": "raw",
  "raw_input": "home"
}
await my_motor.do_command(raw_dict)

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • raw_input (String): The raw string to send to the controller.

Returns:

  • (error): An error, if one occurred.

For more information, see the Go SDK Docs on Raw and on DoCommand.

resp, err := myMotorComponent.DoCommand(ctx, map[string]interface{}{"command": "jog", "raw_input": "home"})

Test the motor

Once your motor is configured and connected, open the motor’s TEST panel on the CONFIGURE or CONTROL tabs. Use the buttons to try turning your motor forwards or backwards at different power levels and check whether it moves as expected.

Motor test panel.

If the motor does not appear on the TEST panel, or if you notice unexpected behavior, check your machine’s LOGS tab for errors, and review the configuration.

Troubleshooting

If your motor is not working as expected, follow these steps:

  1. Check your machine logs on the LOGS tab to check for errors.
  2. Review this motor model’s documentation to ensure you have configured all required attributes.
  3. Check that all wires are securely attached to the correct pins.
  4. Click on the TEST panel on the CONFIGURE or CONTROL tab and test if you can use the motor there.

If none of these steps work, reach out to us on the Community Discord and we will be happy to help.

Next steps

For more configuration and usage info, see:

Motor API

Give commands to operate a motor or get its current status.

Configure a machine

Create a machine in a few steps using Viam's modular system of components and services without writing much or any code.

Control a motor (2 min)

Use Viam to control a motor's speed and direction in just a few steps.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.