Datalogger Instrument

The Datalogger instrument provides file logging (to CSV and Binary formats) and network streaming of time-series voltage data. It contains a built-in Waveform Generator that can control the Moku:Lab analog outputs as well.

For file logging or network streaming, use the _data_log or _stream_data type functions, respectively.

Note

To convert .li binary formatted log files, use the moku_convert command line utility that comes with your pymoku installation. Alternatively, you can download an exectuable version here.

Example Usage

For an in-depth walkthrough on using the pymoku Datalogger Instrument, see the pymoku Datalogger tutorial. The following example code and a wide range of other pymoku demo scripts can be found at the pymoku Github repository.

datalogger_basic.py
#
# pymoku example: Basic Datalogger
#
# This example demonstrates use of the Datalogger instrument to log time-series
# voltage data to a (Binary or CSV) file.
#
# (c) 2019 Liquid Instruments Pty. Ltd.
#
from pymoku import Moku
from pymoku.instruments import Datalogger
import time

# Connect to your Moku by its device name
# Alternatively, use Moku.get_by_serial('#####') or Moku('192.168.###.###')
m = Moku.get_by_name('Moku')

try:
	i = m.deploy_or_connect(Datalogger)

	# 100 samples per second
	i.set_samplerate(100)

	# Stop an existing log, if any, then start a new one. 10 seconds of both channels to the
	# SD Card (rather than internal storage). Use the Moku's binary file format for better speed
	# and size performance.
	i.stop_data_log()
	i.start_data_log(duration=10, use_sd=True, ch1=True, ch2=True, filetype='bin')

	# Track progress percentage of the data logging session
	progress = 0
	while progress < 100:
		# Wait for the logging session to progress by sleeping 0.5sec
		time.sleep(0.5)
		# Get current progress percentage and print it out
		progress = i.progress_data_log()
		print("Progress {}%".format(progress))

	# Upload the log file to the local directory
	i.upload_data_log()
	print("Uploaded log file to local directory.")

	# Denote that we are done with the data logging session so resources may be cleand up
	i.stop_data_log()

except StreamException as e:
	print("Error occured: %s" % e)
finally:
	m.close()
datalogger_streaming.py
#
# pymoku example: Livestream Datalogger
#
# This example demonstrates how you can use the Datalogger to live-stream
# dual-channel voltage data over the network.
#
# (c) 2019 Liquid Instruments Pty. Ltd.
#
from pymoku import Moku
from pymoku.instruments import Datalogger

# Connect to your Moku by its device name
# Alternatively, use Moku.get_by_serial('#####') or Moku('192.168.###.###')
m = Moku.get_by_name('Moku')

try:
	# Deploy the Datalogger to your Moku
	i = m.deploy_or_connect(Datalogger)

	# 10Hz sample rate
	i.set_samplerate(10)

	# Stop a previous session, if any, then start a new dual-channel data stream in real
	# time over the network.
	i.stop_stream_data()
	i.start_stream_data(duration=10, ch1=True, ch2=True)

	while True:
		# Get 10 samples off the network at a time
		samples = i.get_stream_data(n=10)

		# Break out of this loop if we received no samples
		# This denotes the end of the streaming session
		if not any(samples): break

		# Print out the new samples
		print("Received: Channel 1 (%d smps), Channel 2 (%d smps)" % (len(samples[0]),len(samples[1])))

	# Denote that we are done with the data streaming session so resources may be cleand up
	i.stop_stream_data()

except StreamException as e:
	print("Error occured: %s" % e)
finally:
	# Close the connection to the Moku to release network resources
	m.close()

The Datalogger Class

class pymoku.instruments.Datalogger

Datalogger instrument object.

To run a new Datalogger instrument, this should be instantiated and deployed via a connected Moku object using deploy_instrument. Alternatively, a pre-configured instrument object can be obtained by discovering an already running Datalogger instrument on a Moku:Lab device via discover_instrument.

__init__()

Create a new Datalogger instrument, ready to deploy to a Moku.

type = "datalogger"

Name of this instrument.

commit()

Apply all modified settings.

Note

If the autocommit feature has been turned off, this function can be used to manually apply any instrument settings to the Moku device. These instrument settings are those configured by calling all set_ and gen_ type functions. Manually calling this function allows you to atomically apply many instrument settings at once.

data_log_filename()

Returns the current base filename of the logging session.

The base filename doesn’t include the file extension as multiple files might be recorded simultaneously with different extensions.

Return type:str
Returns:The file name of the current, or most recent, log file.
gen_off(*args, **kwargs)

Turn Waveform Generator output(s) off.

The channel will be turned on when configuring the waveform type but can be turned off using this function. If ch is None (the default), both channels will be turned off, otherwise just the one specified by the argument.

Parameters:ch (int; {1,2} or None) – Channel to turn off, or both.
gen_rampwave(*args, **kwargs)

Generate a Ramp with the given parameters on the given channel.

This is a wrapper around the Square Wave generator, using the riserate and fallrate parameters to form the ramp.

Parameters:
  • ch (int; {1,2}) – Channel on which to generate the wave
  • amplitude (float, [0, 2.0] volts) – Waveform peak-to-peak amplitude
  • frequency (float, [0, 100e6] hertz) – Frequency of the wave
  • offset (float, [-1.0, 1.0] volts) – DC offset applied to the waveform
  • symmetry (float, [0, 1.0]) – Fraction of the cycle rising.
  • phase (float, degrees [0, 360]) – Phase offset of the wave
gen_sinewave(*args, **kwargs)

Generate a Sine Wave with the given parameters on the given channel.

Parameters:
  • ch (int; {1,2}) – Channel on which to generate the wave
  • amplitude (float, [0.0,2.0] Vpp) – Waveform peak-to-peak amplitude
  • frequency (float, [0,250e6] Hz) – Frequency of the wave
  • offset (float, [-1.0,1.0] Volts) – DC offset applied to the waveform
  • phase (float, [0-360] degrees) – Phase offset of the wave
gen_squarewave(*args, **kwargs)

Generate a Square Wave with given parameters on the given channel.

Parameters:
  • ch (int; {1,2}) – Channel on which to generate the wave
  • amplitude (float, [0, 2.0] volts) – Waveform peak-to-peak amplitude
  • frequency (float, [0, 100e6] hertz) – Frequency of the wave
  • offset (float, [-1.0, 1.0] volts) – DC offset applied to the waveform
  • duty (float, [0, 1.0]) – Fractional duty cycle
  • risetime (float, [0, 1.0]) – Fraction of a cycle taken for the waveform to rise
  • falltime (float [0, 1.0]) – Fraction of a cycle taken for the waveform to fall
  • phase (float, degrees 0-360) – Phase offset of the wave
get_frontend(channel)

Get the analog frontend configuration.

Parameters:channel (int; {1,2}) – Channel for which the relay settings are being retrieved
Returns:Array of bool with the front end configuration of channels - [0] 50 Ohm - [1] 10xAttenuation - [2] AC Coupling
get_samplerate()
Returns:The current instrument sample rate
get_stream_data(n=0, timeout=None)

Get any new instrument samples that have arrived on the network.

This returns a tuple containing two arrays (one per channel) of up to ‘n’ samples of instrument data. If a channel is disabled, the corresponding array is empty. If there were less than ‘n’ samples remaining for the session, then the arrays will contain this remaining amount of samples.

Parameters:
  • n (int) – Number of samples to get off the network. Set this to ‘0’ to get all currently available samples, or ‘-1’ to wait on all samples of the currently running streaming session to be received.
  • timeout (float) – Timeout in seconds
Return type:

tuple
Returns:

([CH1_DATA], [CH2_DATA])
Raises:
get_timestep()

Returns the expected time between streamed samples.

This returns the inverse figure to get_samplerate. This form is more useful for constructing time axes to support, for example, get_stream_data.

Return type:float
Returns:Time between data samples in seconds.
progress_data_log()

Estimates progress of a logging session started by a start_data_log call.

Return type:float
Returns:[0.0-100.0] representing 0 - 100% completion of the current logging session.Note that 100% is only returned when the session has completed, the progress may pause at 99% for a time as internal buffers are flushed.
Raises:StreamException: if an error occurred with the current logging session.
set_defaults(*args, **kwargs)

Can be extended in implementations to set initial state

set_frontend(channel, fiftyr=True, atten=False, ac=False)

Configures gain, coupling and termination for each channel.

Parameters:
  • channel (int; {1,2}) – Channel to which the settings should be applied
  • fiftyr (bool) – 50Ohm termination; default is 1MOhm.
  • atten (bool) – Turn on 10x attenuation. Changes the dynamic range between 1Vpp and 10Vpp.
  • ac (bool) – AC-couple; default DC.
set_precision_mode(*args, **kwargs)

Change aquisition mode between downsampling and decimation. Precision mode, a.k.a Decimation, samples at full rate and applies a low-pass filter to the data. This improves precision. Normal mode works by direct downsampling, throwing away points it doesn’t need.

Parameters:state (bool) – Select Precision Mode
Raises:ValueError – if input parameter is invalid
set_samplerate(*args, **kwargs)

Manually set the sample rate of the instrument.

This interface allows you to specify the rate at which data is sampled.

Note

The samplerate must be set to within the allowed range for your datalogging session type. See the Datalogger instrument tutorial for more details.

Parameters:samplerate (float; 0 < samplerate < 500Msmp/s) – Target samples per second. Will get rounded to the nearest unit.
Raises:ValueOutOfRangeException – if samplerate is out of range.
set_source(*args, **kwargs)

Sets the source of the channel data to either the analog input or internally looped-back digital output.

This feature allows the user to capture the Waveform Generator outputs.

Parameters:
  • ch (int; {1,2}) – Channel Number
  • source (string, {'in1', 'in2', 'out1','out2', 'ext'}) – Where the specified channel should source data from (either the input or internally looped back output)
  • lmode (string, {'clip','round'}) – DAC Loopback mode (ignored ‘in’ sources)
Raises:
  • ValueOutOfRangeException – if the channel number is incorrect
  • ValueError – if any of the string parameters are incorrect
start_data_log(duration=10, ch1=True, ch2=True, use_sd=True, filetype='csv')

Start logging instrument data to a file.

Progress of the data log may be checked calling progress_data_log.

All outstanding settings must have been committed before starting the data log. This will always be true if pymoku.autocommit=True, the default.

Note

The Moku’s internal filesystem is volatile and will be wiped when the Moku is turned off. If you want your data logs to persist either save to SD card or move them to a permanent storage location prior to powering your Moku off.

Parameters:
  • duration (float) – Log duration in seconds
  • ch1 (bool) – Enable streaming on Channel 1
  • ch2 (bool) – Enable streaming on Channel 2
  • use_sd (bool) – Whether to log to the SD card, else the internal Moku filesystem.
  • filetype (string) – Log file type, one of {‘csv’,’bin’,’mat’,’npy’} for CSV, Binary, MATLAB or NPY (Numpy Data) respectively.
Raises:
start_stream_data(duration=10, ch1=True, ch2=True)

Start streaming instrument data over the network.

Samples being streamed can be retrieved by calls to get_stream_data.

All outstanding settings must have been committed before starting the stream. This will always be true if pymoku.autocommit=True, the default.

Parameters:
  • duration (float) – Log duration in seconds
  • ch1 (bool) – Enable streaming on Channel 1
  • ch2 (bool) – Enable streaming on Channel 2
Raises:
stop_data_log()

Stops the current instrument data logging session.

This must be called exactly once for every start_data_log call, even if the log terminated itself due to timeout. Calling this function doesn’t just stop the session (if it isn’t already stopped), but also resets error and transfer state, ready to start a new logging session.

stop_stream_data()

Stops instrument data being streamed over the network.

Should be called exactly once for every start_stream_data call, even if the streaming session stopped itself due to timeout. Calling this function not only causes the stream to stop, but also resets error and transfer state, ready to start a new streaming session.

sync_phase(*args, **kwargs)

Synchronize the phase of both output channels.

The phase of both channels is reset to their respestive phase offset values.

upload_data_log()

Load most recently recorded data file from the Moku to the local PC.

Raises: