# Sending arbitrary commands

The library includes methods for the most commonly used device commands.
There are additional commands available to devices, and a set of generic methods for sending arbitrary commands to a device is included in the library.

Constructing the low level commands for these methods requires knowledge of the underlying [Zaber Binary Protocol](https://www.zaber.com/protocol-manual?protocol=Binary).

## Generic command method

The following example demonstrates how to send an arbitrary command:

**JavaScript:**

```js
const response = await connection.genericCommand(1, CommandCode.ECHO_DATA, 12345);
console.log('Response:', response);
```

**Python:**

```py
response = connection.generic_command(1, CommandCode.ECHO_DATA, 12345)
print("Response:", response)
```

**C#:**

```cs
var response = connection.GenericCommand(1, CommandCode.EchoData, 12345);
Console.WriteLine("Response: " + response);
```

**Java:**

```java
Message response = connection.genericCommand(1, CommandCode.ECHO_DATA, 12345);
System.out.println("Response data: " + response.toString());
```

**MATLAB (legacy):**

```matlabjava
response = connection.genericCommand(1, CommandCode.ECHO_DATA, 12345);
fprintf('Response data: %s.\n', response.toString());
```

**MATLAB:**

```matlab
response = connection.genericCommand(1, CommandCode.EchoData, 12345);

% Note: data class `toString` methods were added in toolbox version 8.4.0
fprintf('Response data: %s\n', response.toString());
```

**C++:**

```cpp
Message response = connection.genericCommand(1, CommandCode::ECHO_DATA, 12345);
std::cout << "Response data: " << response.toString() << std::endl;
```

In the example above, the `Echo Data` command is sent to device number `1`.
The method returns a response which contains the fields from the reply of the device.

Binary protocol move commands return a response when movement is complete or when another command has pre-empted it.
The default timeout for the `generic_command` method is 0.5 seconds, so if you are using it to send movement commands, a timeout exception is thrown if the movement takes longer to complete.
In this case, you should adjust the timeout by setting the `timeout` argument to the number of seconds you expect the movement to take.
The example below homes the device with a timeout of `10` seconds.

**JavaScript:**

```js
await connection.genericCommand(1, CommandCode.HOME, 0, { timeout: 10 });
```

**Python:**

```py
connection.generic_command(1, CommandCode.HOME, 0, 10)
```

**C#:**

```cs
connection.GenericCommand(1, CommandCode.Home, 0, 10);
```

**Java:**

```java
connection.genericCommand(1, CommandCode.HOME, 0, 10);
```

**MATLAB (legacy):**

```matlabjava
connection.genericCommand(1, CommandCode.HOME, 0, 10);
```

**MATLAB:**

```matlab
connection.genericCommand(1, CommandCode.Home, 0, 10);
```

**C++:**

```cpp
connection.genericCommand(1, CommandCode::HOME, 0, 10);
```

If the device rejects the command, the method throws an exception.
If you want to override this behaviour and examine the response in case of rejection,
change the last argument, `check_errors`, to false.

In addition to the `generic_command` method, there are two related methods. The first is `generic_command_no_response`, which does not wait for a response from the device after issuing the command. The second method is `generic_command_multi_response`, which reads all responses on the port after issuing the command. The `generic_command_multi_response` method is used when sending a command to device `0`, as doing this sends the command to all the devices on the port.

In addition to the `Connection` class, these methods can also be found in the `Device` class (removing the need to specify device arguments).

## Unit conversions

You may also send arbitrary commands with unit conversions on both its parameter and the returned data.
The example below demonstrates the use of the `generic_command_with_units` method to move the device by `3` millimetres and convert the returned position to centimetres.

**JavaScript:**

```js
const position = await device.genericCommandWithUnits(CommandCode.MOVE_RELATIVE, 3, Length.MILLIMETRES, Length.CENTIMETRES, { timeout: 10 });
console.log('Position in centimetres:', position);
```

**Python:**

```py
position = device.generic_command_with_units(CommandCode.MOVE_RELATIVE, 3, Units.LENGTH_MILLIMETRES, Units.LENGTH_CENTIMETRES, 10)
print("Position in centimetres:", position)
```

**C#:**

```cs
var position = device.GenericCommandWithUnits(CommandCode.MoveRelative, 3, Units.Length_Millimetres, Units.Length_Centimetres, 10);
Console.WriteLine("Position in centimetres: " + position);
```

**Java:**

```java
double position = device.genericCommandWithUnits(CommandCode.MOVE_RELATIVE, 3, Units.LENGTH_MILLIMETRES, Units.LENGTH_CENTIMETRES, 10);
System.out.println("Position in centimetres: " + position);
```

**MATLAB (legacy):**

```matlabjava
position = device.genericCommandWithUnits(CommandCode.MOVE_RELATIVE, 3, Units.LENGTH_MILLIMETRES, Units.LENGTH_CENTIMETRES, 10);
fprintf('Position in centimetres: %d\n', position);
```

**MATLAB:**

```matlab
position = device.genericCommandWithUnits(CommandCode.MoveRelative, 3, Units.Length("mm"), Units.Length("cm"), 10);
fprintf('Position in centimetres: %f\n', position);
```

**C++:**

```cpp
double position = device.genericCommandWithUnits(CommandCode::MOVE_RELATIVE, 3, Units::LENGTH_MILLIMETRES, Units::LENGTH_CENTIMETRES, 10);
std::cout << "Position in centimetres: " << position << std::endl;
```

## Command Reference

To see the full command reference, visit:

- [Binary Protocol Manual (firmware version 6.xx)](https://www.zaber.com/wiki/Manuals/Binary_Protocol_Manual)
- [Binary Protocol Manual (firmware version 7.xx)](https://www.zaber.com/protocol-manual?protocol=Binary)

## API Reference

- [`Connection`](https://software.zaber.com/motion-library/api/py/binary/connection.md)
- [`Device`](https://software.zaber.com/motion-library/api/py/binary/device.md)
