How to Use NDrive Z1 With the NMotion Python SDK

This guide demonstrates how to use the NMotion Python SDK with the NDrive Z1 to perform a simple motion check.

Introduction

This guide shows how to use the NMotion Python SDK to communicate with and control an NDrive Z1 after initial configuration. Once connected, you’ll use Python to issue a simple control command and confirm communication with the drive.

Before starting, ensure the NDrive Z1 is connected to the CAN bus and assigned a unique Node ID using the NMotion CLI Tool and NLink Adapter.

For NDrive Z1 configuration and calibration, see the Getting Started: Integrating the M8325 BLDC Motor with the NDrive Z1 Using the Onboard Encoder.

Setting Up

1. 1

   Download the Library:

   Download the NMotion Python Library from the official website and select a version compatible with your system.

2. 2

   Extract the Files:

   Unzip the downloaded package and place its contents in your project directory. This is where your main.py will reside.

3. 3

   Connect the Hardware:

   Connect the NDrive Z1 to your PC using the NLink Adapter.

4. 4

   Open the Project:

   Launch your preferred IDE (such as VS Code, PyCharm, or Thonny) to begin coding.

info

The Library is compatible with Python versions 3.8, 3.9 and 3.10.

Usage

Create a new Python file named main.py in your project’s root directory and run the following example.

├── nmotion_transport
| └── <Python library files>
└── main.py

1. 1

   Import Required Modules

   Start by importing the required classes from the NMotion Python SDK and the standard Python libraries used in this example.

   main.py

   from nmotion_transport import USBInterface, Driver
   import time

   The time module is used to introduce short delays between commands, allowing the device time to respond reliably.

2. 2

   Initialize the Interface

   Identify the device port, then create and initialize an Interface object based on your connection type.

   Linux

   • Open a terminal and run dmesg -wH (sudo may be required).
   • Plug in the USB device and note the assigned port name (for example, ttyACM0), which corresponds to /dev/ttyACM0.

   
   

   Windows

   • Open Device Manager and look under Ports (COM & LPT).
   • The connected device will appear with its assigned COM port (for example, COM3).

   
   

   main.py

   iface = USBInterface("/dev/ttyACM0")

   warning

   Ensure that /dev/ttyACM0 is not in use by another application (for example, the NMotion CLI) before running the script.

3. 3

   Create a Driver Object

   Next, create a Driver object by specifying the CAN Node ID and the interface. In this example, the NDrive Z1 has a Node ID of 10.

   After creating the object, wait briefly to allow the device to establish communication with the interface.

   main.py

   # Create a Driver object with CAN Node ID 10
   drv1 = Driver(10, iface)
   
   # Wait for the device to initialize
   time.sleep(2)
4. 4

   Send a Motion Command

   Use the setPositionControl() method to send a simple motion command. In this example, the driver is commanded to move to a target position of 180° with a speed of 100°/s.

   main.py

   # Move to 180° at 100°/s
   set_status = drv1.setPositionControl(180, 100)
   
   # Wait for the motion to complete
   time.sleep(2)

   You can use the other methods provided by the Driver object to interact with and control the device as required by your application. Most methods return a status value indicating whether the operation was successful.

   See the Return Status reference for details.

   warning

   Add a short delay after each method call to ensure the driver has sufficient time to complete the current operation before the next command is issued. This helps prevent overlapping commands and ensures reliable motion control.

5. 5

   Read the Output Position

   Retrieve and print the encoder count using the getOutputPosition() method.

   main.py

   # Read the current output position
   (get_status, count) = drv1.getOutputPosition()
   
   # Display the encoder count
   print(f'Encoder count is: {count}')

   Retrieving driver values using a get method is straightforward. The function returns a tuple containing both the status and the requested value.

6. 6

   Clean Up

   After completing operations with the device, close the interface to release resources and properly terminate communication.

   main.py

   # Delete the driver object
   del drv1
   
   # Close the interface
   iface.close()

Complete Script

main.py

from nmotion_transport import USBInterface, Driver
import time

iface = USBInterface("/dev/ttyACM0")   

drv1 = Driver(10, iface)
time.sleep(2)

set_status = drv1.setPositionControl(180,100)
time.sleep(2)

(get_status, count) = drv1.getOutputPosition()
print(f'Encoder count is: {count}')

del drv1

iface.close()

Running the program

Run the script from the project directory:

$ python3 main.py

If you encounter errors, ensure that a compatible version of Python is installed.

Conclusion

By following this guide, you can connect to and control an NDrive Z1 using the NMotion Python SDK.