# Moveables

The Moveables API makes moving your axes and locksteps more convenient by providing a cohesive set of functions across both and letting users specify default units for movements to use.

## Set up

There are three functions you can use to get a moveable. First, to create from an axis, use `From Axis`:

**Python:**

```py
device = connection.get_device(1)
moveable = Moveable.from_axis(device.get_axis(1))
```

**JavaScript:**

```js
const device = connection.getDevice(1);
const moveable = await Moveable.fromAxis(device.getAxis(1));
```

**C#:**

```cs
var device = connection.GetDevice(1);
var moveable = Moveable.FromAxis(device.GetAxis(1));
```

**Java:**

```java
Device device = connection.getDevice(1);
Moveable moveable = Moveable.fromAxis(device.getAxis(1));
```

**MATLAB:**

```matlab
device = connection.getDevice(1);
moveable = zaber.motion.movement.Moveable.fromAxis(device.getAxis(1));
```

**C++:**

```cpp
Device device = connection.getDevice(1);
Moveable moveable = Moveable::fromAxis(device.getAxis(1));
```

Next, if your device is lockstep, you can use `From Lockstep`:

**Python:**

```py
device = connection.get_device(1)
moveable = Moveable.from_lockstep(device.get_lockstep(1))
```

**JavaScript:**

```js
const device = connection.getDevice(1);
const moveable = await Moveable.fromLockstep(device.getLockstep(1));
```

**C#:**

```cs
var device = connection.GetDevice(1);
var moveable = Moveable.FromLockstep(device.GetLockstep(1));
```

**Java:**

```java
Device device = connection.getDevice(1);
Moveable moveable = Moveable.fromLockstep(device.getLockstep(1));
```

**MATLAB:**

```matlab
device = connection.getDevice(1);
moveable = zaber.motion.movement.Moveable.fromLockstep(device.getLockstep(1));
```

**C++:**

```cpp
Device device = connection.getDevice(1);
Moveable moveable = Moveable::fromLockstep(device.getLockstep(1));
```

Finally, there is the `From Device` function that you can use for single-axis devices:

**Python:**

```py
device = connection.get_device(1)
moveable = Moveable.from_device(device)
```

**JavaScript:**

```js
const device = connection.getDevice(1);
const moveable = await Moveable.fromDevice(device);
```

**C#:**

```cs
var device = connection.GetDevice(1);
var moveable = Moveable.FromDevice(device);
```

**Java:**

```java
Device device = connection.getDevice(1);
Moveable moveable = Moveable.fromDevice(device);
```

**MATLAB:**

```matlab
device = connection.getDevice(1);
moveable = zaber.motion.movement.Moveable.fromDevice(device);
```

**C++:**

```cpp
Device device = connection.getDevice(1);
Moveable moveable = Moveable::fromDevice(device);
```

These all result in `moveable` being an instance of type `Moveable` with identical functionality. `Moveable`s have all of the movement methods from axis and lockstep so:

**Python:**

```py
moveable.move_absolute(100)
```

**JavaScript:**

```js
await moveable.moveAbsolute(100);
```

**C#:**

```cs
moveable.MoveAbsolute(100);
```

**Java:**

```java
moveable.moveAbsolute(new MeasurementOrValue(100));
```

**MATLAB:**

```matlab
moveable.moveAbsolute(100);
```

**C++:**

```cpp
moveable.moveAbsolute(100);
```

Will have the same effect as:

**Python:**

```py
axis = device.get_axis(1)
axis.move_absolute(100)
```

**JavaScript:**

```js
const axis = device.getAxis(1);
await axis.moveAbsolute(100);
```

**C#:**

```cs
var axis = device.GetAxis(1);
axis.MoveAbsolute(100);
```

**Java:**

```java
Axis axis = device.getAxis(1);
axis.moveAbsolute(100);
```

**MATLAB:**

```matlab
axis = device.getAxis(1);
axis.moveAbsolute(100);
```

**C++:**

```cpp
Axis axis = device.getAxis(1);
axis.moveAbsolute(100);
```

## Default Units

Often, you'll want to always use the same units without having to specify them on each call. For example, to create a `Moveable` that will always use units of millimeters, you can create a moveable like:

**Python:**

```py
mm_moveable = Moveable.from_axis(device.get_axis(1), DefaultMotionUnits(position=Units.LENGTH_MILLIMETRES))
```

**JavaScript:**

```js
const mmMoveable = await Moveable.fromAxis(device.getAxis(1), { units: { position: Length.MILLIMETRES } });
```

**C#:**

```cs
var mmMoveable = Moveable.FromAxis(device.GetAxis(1), new DefaultMotionUnits { Position = Units.Length_Millimetres });
```

**Java:**

```java
Moveable mmMoveable = Moveable.fromAxis(device.getAxis(1), new DefaultMotionUnits().withPosition(Units.LENGTH_MILLIMETRES));
```

**MATLAB:**

```matlab
mmMoveable = zaber.motion.movement.Moveable.fromAxis(device.getAxis(1), units=zaber.motion.movement.DefaultMotionUnits(zaber.motion.Units.LengthMillimetres));
```

**C++:**

```cpp
DefaultMotionUnits units;
units.setPosition(Units::LENGTH_MILLIMETRES);
Moveable mmMoveable = Moveable::fromAxis(device.getAxis(1), units);
```

Then, to move your device by 10 mm, instead of writing:

**Python:**

```py
axis.move_relative(10, Units.LENGTH_MILLIMETRES)
```

**JavaScript:**

```js
await axis.moveRelative(10, Length.MILLIMETRES);
```

**C#:**

```cs
axis.MoveRelative(10, Units.Length_Millimetres);
```

**Java:**

```java
axis.moveRelative(10, Units.LENGTH_MILLIMETRES);
```

**MATLAB:**

```matlab
axis.moveRelative(10, Units.Length("mm"));
```

**C++:**

```cpp
axis.moveRelative(10, Units::LENGTH_MILLIMETRES);
```

You can just write:

**Python:**

```py
mm_moveable.move_relative(10)
```

**JavaScript:**

```js
await mmMoveable.moveRelative(10);
```

**C#:**

```cs
mmMoveable.MoveRelative(10);
```

**Java:**

```java
mmMoveable.moveRelative(new MeasurementOrValue(10));
```

**MATLAB:**

```matlab
mmMoveable.moveRelative(10);
```

**C++:**

```cpp
mmMoveable.moveRelative(10);
```

If you need to use another unit, you can always still specify it by passing in a `Measurement`:

**Python:**

```py
mm_moveable.move_relative(Measurement(value=2, unit=Units.LENGTH_INCHES))
```

**JavaScript:**

```js
await mmMoveable.moveRelative({ value: 2, unit: Length.INCHES });
```

**C#:**

```cs
mmMoveable.MoveRelative(new Measurement { Value = 2, Unit = Units.Length_Inches });
```

**Java:**

```java
mmMoveable.moveRelative(new MeasurementOrValue(new Measurement(2, Units.LENGTH_INCHES)));
```

**MATLAB:**

```matlab
mmMoveable.moveRelative(zaber.motion.Measurement(2, zaber.motion.Units.LengthInches));
```

**C++:**

```cpp
mmMoveable.moveRelative(Measurement(2, Units::LENGTH_INCHES));
```

`DefaultMotionUnits` supports setting default units for Position (which also covers lengths and distances), Speed, Acceleration, and Time.

## Lockstep

All the methods that exist on axis exist on lockstep, but will sometimes get information from the whole lockstep to provide you with more correct info. So for example, if you have a lockstep of two devices, one with a travel of 10 mm, and one with a travel of 5 mm, and call `Get Limit Max`, it will return 5 mm since that is the furthest the combination of devices can travel, and if you call `Is Homed` it will check that all of the axes are homed.

The following methods will act on all axes in a lockstep when called:

- `Get Limit Max`
- `Get Limit Min`
- `Get Max Speed`
- `Set Max Speed`
- `Get Max Acceleration`
- `Set Max Acceleration`
- `Is Homed`
- `Is Parked`
