# Oscilloscope

Zaber devices have a built-in data logging feature called the Oscilloscope. It can record the values
of multiple device or axis settings in lockstep and at a high data rate, neither of which are possible
using software only. All devices with Firmware 7 have this feature.

The library offers a helper class to make configuring the Oscilloscope and retrieving the recorded
data easier.

## Setup

Once you have a device reference in code, you can get a reference to the Oscilloscope feature just by using
the device object's Oscilloscope property:

**Python:**

```py
scope = device.oscilloscope
print(f"Oscilloscope can store {scope.get_max_buffer_size()} samples.")
```

**JavaScript:**

```js
const scope = device.oscilloscope;
console.log(`Oscilloscope can store ${await scope.getMaxBufferSize()} samples.`);
```

**C#:**

```cs
var scope = device.Oscilloscope;
Console.WriteLine($"Oscilloscope can store {scope.GetMaxBufferSize()} samples.");
```

**Java:**

```java
Oscilloscope scope = device.getOscilloscope();
System.out.println(String.format("Oscilloscope can store %d samples.", scope.getMaxBufferSize()));
```

**MATLAB (legacy):**

```matlabjava
scope = device.getOscilloscope();
fprintf("Oscilloscope can store %d samples.\n", scope.getMaxBufferSize());
```

**C++:**

```cpp
auto scope = device.getOscilloscope();
std::cout << "Oscilloscope can store " << scope.getMaxBufferSize() << " samples." << std::endl;
```

The Oscilloscope has a fixed maximum number of samples it can record, printed out by the
above sample code. There is also a fixed number of channels that can be recorded simultaneously,
which you can get by using the [`get_max_channels`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscope.md#getmaxchannels) method.

The buffer capacity is divided up between the channels. In recent Firmware versions the buffer is
evenly divided between the channels you add. In older Firmware versions there was a maximum
capacity of 1024 samples per channel regardless of how many channels you added. You can use
the [`get_buffer_size`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscope.md#getbuffersize) method after adding channels to determine how
many samples per channel you can record.

### Reset

Generally you want to reset the Oscilloscope before each use. This clears the data from the
previous recording and clears the list of channels to record.

**Python:**

```py
scope.clear()
```

**JavaScript:**

```js
await scope.clear();
```

**C#:**

```cs
scope.Clear();
```

**Java:**

```java
scope.clear();
```

**MATLAB (legacy):**

```matlabjava
scope.clear();
```

**C++:**

```cpp
scope.clear();
```

### Channels

Next, add the channels that you want to record. Most device and axis settings can be recorded.
You must specify the correct setting scope (0 for device settings or the axis number otherwise).

In this example we're adding the `pos` and `encoder.pos` settings from the same axis. This is a
common experiment done when tuning the performance of direct-drive devices because it shows lead,
lag and ringing as the device tries to match its ideal trajectory.

**Python:**

```py
scope.add_channel(1, "pos")
scope.add_channel(1, "encoder.pos")
```

**JavaScript:**

```js
await scope.addChannel(1, 'pos');
await scope.addChannel(1, 'encoder.pos');
```

**C#:**

```cs
scope.AddChannel(1, "pos");
scope.AddChannel(1, "encoder.pos");
```

**Java:**

```java
scope.addChannel(1, "pos");
scope.addChannel(1, "encoder.pos");
```

**MATLAB (legacy):**

```matlabjava
scope.addChannel(1, "pos");
scope.addChannel(1, "encoder.pos");
```

**C++:**

```cpp
scope.addChannel(1, "pos");
scope.addChannel(1, "encoder.pos");
```

There is a maximum number of channels you can add (currently six). You can query the maximum
using the [`get_max_channels`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscope.md#getmaxchannels) method.

### Timing

You should always specify the timebase for the recording. The timebase is the interval between samples,
and is the inverse of the sample rate. The default and minimum value is 0.1ms (10kHz), and it can be set
to multiples of 0.1ms. The example below explicitly sets it to 0.1ms (10kHz).

You can also optionally specify a delay between receipt of the start command and the recording
of the first sample. The delay uses the same time units as the timebase.

**Python:**

```py
scope.set_timebase(0.1, Units.TIME_MILLISECONDS)
scope.set_delay(0)
```

**JavaScript:**

```js
await scope.setTimebase(0.1, Time.MILLISECONDS);
await scope.setDelay(0);
```

**C#:**

```cs
scope.SetTimebase(0.1, Units.Time_Milliseconds);
scope.SetDelay(0);
```

**Java:**

```java
scope.setTimebase(0.1, Units.TIME_MILLISECONDS);
scope.setDelay(0);
```

**MATLAB (legacy):**

```matlabjava
scope.setTimebase(0.1, Units.TIME_MILLISECONDS);
scope.setDelay(0);
```

**C++:**

```cpp
scope.setTimebase(0.1, Units::TIME_MILLISECONDS);
scope.setDelay(0);
```

## Recording and Retrieving Data

To start the data recording, just use the [`start`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscope.md#start) method of
the Oscilloscope object. You can optionally specify a number of samples to record per channel.
The default is the maximum number of samples that will fit in the buffer.

Typically you will want to send a move command to the device in order to have something
interesting to record. The example below assumes a linear device and starts a 5cm movement.
You can send the move command either before or after calling [`start`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscope.md#start) but if you send it before you may miss data at the start of the movement, depending on the sample
rate and the connection speed.

When the recording is finished, use [`read`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscope.md#read) to retrieve the data.
You can call this method immediately after starting the recording and it will block until the data is
ready, or you can retrieve the data later if your program has other things to do.

You can call [`read`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscope.md#read) multiple times and get the same data, if no
more recordings have been started in the intervening time. Note that on slower connections like
serial ports, it can take several seconds to read the data from the device and this may cause other
commands sent to the same device to time out.

Optionally, you can call [`read`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscope.md#read) to abort a recording in progress.
If you do this, [`read`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscope.md#read) will return whatever data has been recorded so far.

**Python:**

```py
print("Starting experiment")
scope.start()
device.get_axis(1).move_relative(5, Units.LENGTH_CENTIMETRES)
data = scope.read()
```

**JavaScript:**

```js
console.log('Starting experiment');
await scope.start();
await device.getAxis(1).moveRelative(5, Length.CENTIMETRES);
const data = await scope.read();
```

**C#:**

```cs
Console.WriteLine("Starting experiment");
scope.Start();
device.GetAxis(1).MoveRelative(5, Units.Length_Centimetres);
var data = scope.Read();
```

**Java:**

```java
System.out.println("Starting experiment");
scope.start();
device.getAxis(1).moveRelative(5, Units.LENGTH_CENTIMETRES);
OscilloscopeData[] data = scope.read();
```

**MATLAB (legacy):**

```matlabjava
fprintf("Starting experiment\n");
scope.start();
device.getAxis(1).moveRelative(5, Units.LENGTH_CENTIMETRES);
data = scope.read();
```

**C++:**

```cpp
std::cout << "Starting experiment" << std::endl;
scope.start();
device.getAxis(1).moveRelative(5, Units::LENGTH_CENTIMETRES);
auto data = scope.read();
```

## Interpreting the Data

The [`read`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscope.md#read) method returns an array of [`OscilloscopeData`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscopedata.md) objects, one for each channel you added, in
the order they were added.

Each data object identifies the setting it records and the axis or device scope it was
recorded from. You can also retrieve the start delay and timebase from this object, and
there is a [`get_sample_time`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscopedata.md#getsampletime) helper method to calculate the time
of a given sample index, relative to the start of the recording. The device records all
channels in lockstep, so the time of a given sample index will be the same across all
channels from the same recording.

Use the [`get_data`](https://software.zaber.com/motion-library/api/py/ascii/oscilloscopedata.md#getdata) method of the data object to get the actual
sample values, with optional unit conversion.

The example below shows how to write the data to a `.csv` spreadsheet file. This example assumes the
two channels added in the above example code (position and temperature) and converts to appropriate
units.

**Python:**

```py
print("Writing results")
pos = data[0]
pos_samples = pos.get_data(Units.LENGTH_MILLIMETRES)
encoder = data[1]
encoder_samples = encoder.get_data(Units.LENGTH_MILLIMETRES)
with open("scope.csv", "wt") as file:
    file.write("Time (ms),Trajectory Position (mm),Measured Position (mm)\n")
    for i in range(len(pos_samples)):
        file.write(f"{pos.get_sample_time(i, Units.TIME_MILLISECONDS)},")
        file.write(f"{pos_samples[i]},{encoder_samples[i]}\n")
```

**JavaScript:**

```js
console.log('Writing results');
const pos = data[0]
const pos_samples = await pos.getData(Length.MILLIMETRES);
const encoder = data[1]
const encoder_samples = await encoder.getData(Length.MILLIMETRES);

const lines = [];
lines.push('Time (ms),Trajectory Position (mm),Measured Position (mm)');
pos_samples.forEach((sample, i) => {
    lines.push(`${pos.getSampleTime(i, Time.MILLISECONDS)},${sample},${encoder_samples[i]}`);
});

await fs.writeFile('scope.csv', lines.join('\n'));
```

**C#:**

```cs
Console.WriteLine("Writing results");
var pos = data[0];
var pos_samples = pos.GetData(Units.Length_Millimetres);
var encoder = data[1];
var encoder_samples = encoder.GetData(Units.Length_Millimetres);

using var writer = new StreamWriter("scope.csv");
writer.WriteLine("Time (ms),Trajectory Position (mm),Measured Position (mm)");
for (var i = 0; i < pos_samples.Length; i++)
{
    writer.WriteLine($"{pos.GetSampleTime(i, Units.Time_Milliseconds)},{pos_samples[i]},{encoder_samples[i]}");
}
```

**Java:**

```java
System.out.println("Writing results");
OscilloscopeData pos = data[0];
double[] pos_samples = pos.getData(Units.LENGTH_CENTIMETRES);
OscilloscopeData encoder = data[1];
double[] encoder_samples = encoder.getData(Units.LENGTH_CENTIMETRES);

try (FileWriter file = new FileWriter("scope.csv")) {
    file.write("Time (ms),Trajectory Position (mm),Measured Position (mm)\n");
    for (int i = 0; i < pos_samples.length; i++)
    {
        file.write(String.format("%f,%f,%f\n",
            pos.getSampleTime(i, Units.TIME_MILLISECONDS),
            pos_samples[i],
            encoder_samples[i]));
    }
}
catch (IOException e) {
    System.out.println("An error occurred.");
    e.printStackTrace();
}
```

**MATLAB (legacy):**

```matlabjava
fprintf("Writing results\n");
pos = data(1);
pos_samples = pos.getData(Units.LENGTH_CENTIMETRES);
encoder = data(2);
encoder_samples = encoder.getData(Units.LENGTH_CENTIMETRES);

file = fopen("scope.csv","w");
fprintf(file, "Time (ms),Trajectory Position (mm),Measured Position (mm)\n");
for i = 1:length(pos_samples)
    fprintf(file, "%f,%f,%f\n", ...
        pos.getSampleTime(i, Units.TIME_MILLISECONDS), ...
        pos_samples(i), ...
        encoder_samples(i));
end
fclose(file);
```

**C++:**

```cpp
std::cout << "Writing results" << std::endl;
OscilloscopeData& pos = data[0];
auto pos_samples = pos.getData(Units::LENGTH_MILLIMETRES);
OscilloscopeData& encoder = data[1];
auto encoder_samples = encoder.getData(Units::LENGTH_MILLIMETRES);

std::ofstream file("scope.csv");
file << "Time(ms), Trajectory Position(mm), Measured Position(mm)\n";
for (int i = 0; i < pos_samples.size(); i++)
{
    file << pos.getSampleTime(i, Units::TIME_MILLISECONDS) << "," << pos_samples[i] << "," << encoder_samples[i] << "\n";
}

file.close();
```

## Zaber Launcher Interoperability

If your device is connected to your computer via RS-232 or USB, you can optionally have Zaber Launcher graph
the recorded data for you.

1. Connect Zaber Launcher to the device first.
2. Open the Oscilloscope app and select the device.
3. In the Capture Settings section at the bottom of the window, change the Capture Mode to `Externally triggered`.
4. Press Start. Zaber Launcher will wait for your script to connect and initiate an oscilloscope recording.
5. Now run your script (connecting to the same serial port). When the data is ready and after your script has
   downloaded it, Zaber Launcher will also automatically download and plot it.

## Complete example

Below is a complete example program incorporating all of the above snippets plus
the initial code for openning the connection and finding a device.

**Python:**

```py
from zaber_motion import Units
from zaber_motion.ascii import Connection

with Connection.open_serial_port("COM3") as connection:
    connection.enable_alerts()

    device_list = connection.detect_devices()
    device = device_list[0]
    device.get_axis(1).home()

    scope = device.oscilloscope
    print(f"Oscilloscope can store {scope.get_max_buffer_size()} samples.")

    scope.clear()
    scope.add_channel(1, "pos")
    scope.add_channel(1, "encoder.pos")

    scope.set_timebase(0.1, Units.TIME_MILLISECONDS)
    scope.set_delay(0)

    print("Starting experiment")
    scope.start()
    device.get_axis(1).move_relative(5, Units.LENGTH_CENTIMETRES)
    data = scope.read()

    print("Writing results")
    pos = data[0]
    pos_samples = pos.get_data(Units.LENGTH_MILLIMETRES)
    encoder = data[1]
    encoder_samples = encoder.get_data(Units.LENGTH_MILLIMETRES)
    with open("scope.csv", "wt") as file:
        file.write("Time (ms),Trajectory Position (mm),Measured Position (mm)\n")
        for i in range(len(pos_samples)):
            file.write(f"{pos.get_sample_time(i, Units.TIME_MILLISECONDS)},")
            file.write(f"{pos_samples[i]},{encoder_samples[i]}\n")
```

**JavaScript:**

```js
import { promises as fs } from 'fs';

import { Length, Time } from '@zaber/motion';
import { Connection } from '@zaber/motion/ascii';

async function main() {
    const connection = await Connection.openSerialPort('COM3');
    try {
        await connection.enableAlerts();

        const deviceList = await connection.detectDevices();
        const device = deviceList[0];
        await device.getAxis(1).home();

        const scope = device.oscilloscope;
        console.log(`Oscilloscope can store ${await scope.getMaxBufferSize()} samples.`);

        await scope.clear();
        await scope.addChannel(1, 'pos');
        await scope.addChannel(1, 'encoder.pos');

        await scope.setTimebase(0.1, Time.MILLISECONDS);
        await scope.setDelay(0);

        console.log('Starting experiment');
        await scope.start();
        await device.getAxis(1).moveRelative(5, Length.CENTIMETRES);
        const data = await scope.read();

        console.log('Writing results');
        const pos = data[0]
        const pos_samples = await pos.getData(Length.MILLIMETRES);
        const encoder = data[1]
        const encoder_samples = await encoder.getData(Length.MILLIMETRES);

        const lines = [];
        lines.push('Time (ms),Trajectory Position (mm),Measured Position (mm)');
        pos_samples.forEach((sample, i) => {
            lines.push(`${pos.getSampleTime(i, Time.MILLISECONDS)},${sample},${encoder_samples[i]}`);
        });

        await fs.writeFile('scope.csv', lines.join('\n'));
    } finally {
        // close the port to allow Node.js to exit
        await connection.close();
    }
}

main();
```

**C#:**

```cs
﻿using Zaber.Motion;
using Zaber.Motion.Ascii;

using var connection = Connection.OpenSerialPort("COM3");

var devices = connection.DetectDevices();
var device = devices[0];
var axis = device.GetAxis(1);
axis.Home();

var scope = device.Oscilloscope;
Console.WriteLine($"Oscilloscope can store {scope.GetMaxBufferSize()} samples.");

scope.Clear();

scope.AddChannel(1, "pos");
scope.AddChannel(1, "encoder.pos");

scope.SetTimebase(0.1, Units.Time_Milliseconds);
scope.SetDelay(0);

Console.WriteLine("Starting experiment");
scope.Start();
device.GetAxis(1).MoveRelative(5, Units.Length_Centimetres);
var data = scope.Read();

Console.WriteLine("Writing results");
var pos = data[0];
var pos_samples = pos.GetData(Units.Length_Millimetres);
var encoder = data[1];
var encoder_samples = encoder.GetData(Units.Length_Millimetres);

using var writer = new StreamWriter("scope.csv");
writer.WriteLine("Time (ms),Trajectory Position (mm),Measured Position (mm)");
for (var i = 0; i < pos_samples.Length; i++)
{
    writer.WriteLine($"{pos.GetSampleTime(i, Units.Time_Milliseconds)},{pos_samples[i]},{encoder_samples[i]}");
}
```

**Java:**

```java
package zaber.example;

import java.io.FileWriter;
import java.io.IOException;

import zaber.motion.Units;
import zaber.motion.ascii.Axis;
import zaber.motion.ascii.Connection;
import zaber.motion.ascii.Device;
import zaber.motion.ascii.Oscilloscope;
import zaber.motion.ascii.OscilloscopeData;

public class App
{
    public static void main(String[] args)
    {
        try (Connection connection = Connection.openSerialPort("COM3")) {
            connection.enableAlerts();

            Device[] deviceList = connection.detectDevices();
            Device device = deviceList[0];
            device.getAxis(1).home();

            Oscilloscope scope = device.getOscilloscope();
            System.out.println(String.format("Oscilloscope can store %d samples.", scope.getMaxBufferSize()));

            scope.clear();

            scope.addChannel(1, "pos");
            scope.addChannel(1, "encoder.pos");

            scope.setTimebase(0.1, Units.TIME_MILLISECONDS);
            scope.setDelay(0);

            System.out.println("Starting experiment");
            scope.start();
            device.getAxis(1).moveRelative(5, Units.LENGTH_CENTIMETRES);
            OscilloscopeData[] data = scope.read();

            System.out.println("Writing results");
            OscilloscopeData pos = data[0];
            double[] pos_samples = pos.getData(Units.LENGTH_CENTIMETRES);
            OscilloscopeData encoder = data[1];
            double[] encoder_samples = encoder.getData(Units.LENGTH_CENTIMETRES);

            try (FileWriter file = new FileWriter("scope.csv")) {
                file.write("Time (ms),Trajectory Position (mm),Measured Position (mm)\n");
                for (int i = 0; i < pos_samples.length; i++)
                {
                    file.write(String.format("%f,%f,%f\n",
                        pos.getSampleTime(i, Units.TIME_MILLISECONDS),
                        pos_samples[i],
                        encoder_samples[i]));
                }
            }
            catch (IOException e) {
                System.out.println("An error occurred.");
                e.printStackTrace();
            }
        }
    }
}
```

**MATLAB:**

```matlab
import zaber.motion.ascii.Connection;
import zaber.motion.Units;

connection = Connection.openSerialPort('COM3');
try
    connection.enableAlerts();

    deviceList = connection.detectDevices();
    device = deviceList(1);
    device.getAxis(1).home();

    scope = device.getOscilloscope();
    fprintf("Oscilloscope can store %d samples.\n", scope.getMaxBufferSize());

    scope.clear();
    scope.addChannel(1, "pos");
    scope.addChannel(1, "encoder.pos");

    scope.setTimebase(0.1, Units.TIME_MILLISECONDS);
    scope.setDelay(0);

    fprintf("Starting experiment\n");
    scope.start();
    device.getAxis(1).moveRelative(5, Units.LENGTH_CENTIMETRES);
    data = scope.read();

    fprintf("Writing results\n");
    pos = data(1);
    pos_samples = pos.getData(Units.LENGTH_CENTIMETRES);
    encoder = data(2);
    encoder_samples = encoder.getData(Units.LENGTH_CENTIMETRES);

    file = fopen("scope.csv","w");
    fprintf(file, "Time (ms),Trajectory Position (mm),Measured Position (mm)\n");
    for i = 1:length(pos_samples)
        fprintf(file, "%f,%f,%f\n", ...
            pos.getSampleTime(i, Units.TIME_MILLISECONDS), ...
            pos_samples(i), ...
            encoder_samples(i));
    end
    fclose(file);

    connection.close();
catch exception
    connection.close();
    rethrow(exception);
end
```

**C++:**

```cpp
#include <fstream>
#include <iostream>
#include <vector>
#include <zaber/motion/ascii.h>

using namespace zaber::motion;
using namespace zaber::motion::ascii;

int main() {
    Connection connection = Connection::openSerialPort("COM3");
    connection.enableAlerts();

    std::vector<Device> deviceList = connection.detectDevices();
    Device device = deviceList[0];
    device.getAxis(1).home();

    auto scope = device.getOscilloscope();
    std::cout << "Oscilloscope can store " << scope.getMaxBufferSize() << " samples." << std::endl;

    scope.clear();
    scope.addChannel(1, "pos");
    scope.addChannel(1, "encoder.pos");

    scope.setTimebase(0.1, Units::TIME_MILLISECONDS);
    scope.setDelay(0);

    std::cout << "Starting experiment" << std::endl;
    scope.start();
    device.getAxis(1).moveRelative(5, Units::LENGTH_CENTIMETRES);
    auto data = scope.read();

    std::cout << "Writing results" << std::endl;
    OscilloscopeData& pos = data[0];
    auto pos_samples = pos.getData(Units::LENGTH_MILLIMETRES);
    OscilloscopeData& encoder = data[1];
    auto encoder_samples = encoder.getData(Units::LENGTH_MILLIMETRES);

    std::ofstream file("scope.csv");
    file << "Time(ms), Trajectory Position(mm), Measured Position(mm)\n";
    for (int i = 0; i < pos_samples.size(); i++)
    {
        file << pos.getSampleTime(i, Units::TIME_MILLISECONDS) << "," << pos_samples[i] << "," << encoder_samples[i] << "\n";
    }

    file.close();

    return 0;
}
```
