#





The NMotion Command Line Interface (CLI) Tool is a Python-based command line interface program that enables real-time control of NMotion components connected via [NLink Adapters](pathname:///nlink). 

:::info
Currently NMotion CLI tool only supports components which are connected to PC via our own [NLink Adapter](pathname:///nlink)
:::

The document provides instructions on how to setup and use the tool, and if you face any errors,  make sure to check out our [Troubleshooting](#troubleshooting) section.

## Setup

Download the tool from [Downloads](/support/downloads/software) page and extract it. Before using it, ensure that you install the required Python packages by running the command:



Since the tool uses [NMotion Transport Library](/software/nmotion_transport_library/nmotion-transport-library.0.1.4-beta), it is compatible with Python versions `3.8`, `3.9` and `3.10`.

## Usage

Go to the extracted folder, the directory structure will be as follows:

```cpp
nmotion-cli
├── nmotion_transport
|    └── <Nmotion Transport Python Library>
└── device_manager
|   └── <Manages connected devices>
└── utils
|   └── <Utilities used in code>
├── windows_requirements.txt
├── linux_requirements.txt
└── nmotion-cli.py
```

To use the nmotion-cli tool, first run the `nmotion-cli.py` script in your terminal to boot up the program.

```bash
$ python3 nmotion-cli.py
```

Once the program starts, the terminal interface will look like this,

```Python
NMotion CLI Tool v1.0
Please connect your NMotion Component via NLink device.
You can also type help() or quit().

In [1]:
```

Once it's running, connect the [NLink Adapter](pathname:///nlink) to a USB port on your computer. The tool will automatically detect the adapter.

```Python title="When NLink Adapter is connected to COM8 port."
NMotion CLI Tool v1.0
Please connect your NMotion Component via NLink device.
You can also type help() or quit().

Connected to NLink device at COM8. NLink_COM8 object created.
In [1]:
```

Next, connect the NMotion components to the [NLink Adapter](pathname:///nlink); the tool will detect these connections automatically and create appropriate class objects for each component.

```Python title="Device with CAN Node ID 23 is connected to the NLink Adapter."
NMotion CLI Tool v1.0
Please connect your NMotion Component via NLink device.
You can also type help() or quit().

Connected to NLink device at COM8. NLink_COM8 object created.
New Device with ID: 23 got connected. Device_23_COM8 object created.
In [1]:
```

### Accessing and Controlling Devices

The created class objects for devices can be used to give commands to the components. The commands are the same ones which is defined in the Device's Python API.

```Python title="Device with CAN Node ID 23 can be controlled by giving commands."
NMotion CLI Tool v1.0
Please connect your NMotion Component via NLink device.
You can also type help() or quit().

Connected to NLink device at COM8. NLink_COM8 object created.
New Device with ID: 23 got connected. Device_23_COM8 object created.
In [1]: Device_23.setSomething(120)
Out[1]: <ret_status_t.RETURN_OK: 0>
```

### Exporting and Importing Configurations
NMotion CLI provides the ability to export the complete configuration of a connected device to a file and import it back when required. This simplifies backup, deployment, and 
replication of settings across multiple devices.

:::info
At present, configuration import and export are supported only on NDrive Z1 device (`Driver`)
:::

**Exporting a Configuration**

The export command reads the current configuration from the connected device and saves it to a configuration file on the host computer. The exported file can be archived, shared with team members, or stored alongside project files for version control. Exporting a configuration is recommended before making significant changes to system settings, as it provides a convenient way to restore a known working configuration if needed.

```Python title="Exporting the configuration to device.json"
NMotion CLI Tool v1.0
Please connect your NMotion Component via NLink device.
You can also type help() or quit().

Connected to NLink device at COM8. NLink_COM8 object created.
New Device with ID: 23 got connected. Device_23_COM8 object created.
In [1]: export_configuration(Device_23_COM8, "device.json")

In [2]:
```

**Importing a Configuration**

The import command loads a previously exported configuration file and writes the contained settings to the connected device. This allows a fully configured setup to be restored in a matter of seconds without manually re-entering individual parameters. Importing configurations is particularly useful for restoring settings to a replacement device, deploying identical configurations across multiple devices, recovering from accidental configuration changes, and maintaining consistent, standardized setups throughout a system or production deployment.

```Python title="Importing a configuration from device.json"
NMotion CLI Tool v1.0
Please connect your NMotion Component via NLink device.
You can also type help() or quit().

Connected to NLink device at COM8. NLink_COM8 object created.
New Device with ID: 23 got connected. Device_23_COM8 object created.
In [1]: import_configuration(Device_23_COM8, "device.json")

In [2]:
```

### Live Plotting

The tool features live plotting capabilities for various variables that is accessible via the CLI tool. It includes a global `plotter` object with a `plot()` method, which accepts a function that returns the value to be plotted. When you pass this function to `plot()`, it will be executed repeatedly to produce a live plot. Make sure that the function returns the values which needs to be plotted in form of a `list`.

```Python title="Using Python's lambda function to plot a Device's Parameter."
NMotion CLI Tool v1.0
Please connect your NMotion Component via NLink device.
You can also type help() or quit().

Connected to NLink device at COM8. NLink_COM8 object created.
New Device with ID: 23 got connected. Device_23_COM8 object created.
In [1]: plotter.plot(lambda: [Device_23_COM8.getSomething()[1]])

In [2]:
```

## Troubleshooting

Here are some potential issues you might encounter with the tool and their solutions.

- **NMotion Components are not detected by NMotion CLI in Linux** <br/> This issue occurs due to insufficient port permissions for the user. Ensure you have the necessary permissions to access the USB port on your Linux system.
- **NLink Adapter is not detected by the tool in Windows** <br/> 
This issue is likely due to the wrong driver being loaded for the adapter. Use [Zadig](https://zadig.akeo.ie/) to change the driver of the adpater to USB Serial CDC, which may involve downgrading the current driver. To verify if the correct driver is installed, open Device Manager and check for a device labeled `NLink`. If it appears, then the driver is now correctly installed.
- **Attribute not found errors while calling API function** <br/>
This issue is likely due to the firmware version not being compatible with the Nmotion CLI tool. Ensure that you have updated the tool to the latest version to support the correct device. Refer to the table below for a list of supported devices and their corresponding versions.

## Supported Devices & Versions
|Device | Version |
|:---:|:----|
| NDrive Z1 | `Firmware Version = 0.3.6` , `Hardware Version = 2.0`  |
| Smart Actuators | `Firmware Version <= 0.3.2` |
| NCoder CAN | `Firmware Version <= 0.1.2` |
| NIMU | `Firmware Version <= 0.1` |