Moku:Lab Device Class

All interaction with pymoku starts with the creation of a Moku object. This can be done directly if one already knows the IP address of the target, or by using one of the get_by_ functions to look up a Moku by Name or Serial Number.

Note

If you are running on a Linux OS, use of the get_by_ functions require that your platform has access to libdnssd. This is provided by the Avahi libdnssd compatibility library. For example, on Ubuntu:

sudo apt-get install libavahi-compat-libdnssd1

A Moku object is useful only for flashing lights until an instrument is deployed to it. The deployment process defines the functionality of the Moku:Lab. For examples on how to deploy an instrument, see demo scripts on each of the Instruments pages below.

Example Usage

For more details on searching for your Moku:Lab and retrieving device configuration information, see the Bonjour Moku guide. The following example code and a wide range of other pymoku demo scripts can be found at the pymoku Github repository.

The Moku Class

class pymoku.Moku(ip_addr, load_instruments=None, force=False)

Core class representing a connection to a physical Moku:Lab unit.

This must always be created first. Once a Moku object exists, it can be queried for running instruments or new instruments deployed to the device.

close()

Close connection to the Moku:Lab.

deploy_instrument(instrument, set_default=True, use_external=False)

Attaches a MokuInstrument to the Moku, deploying and activating an instrument.

Either this function, deploy_or_connect or discover_instrument must be called before an instrument can be manipulated.

The instrument parameter can be a class or object. In the former case, the class is instantiated before being deployed, and the resulting object is returned.

Parameters:

• instrument (MokuInstrument subclass or instantiation thereof) – The instrument instance to attach.
• set_default (bool) – Set the instrument to its default config upon connection, overwriting user changes before this point.
• use_external (bool) – Attempt to lock to an external reference clock.

Returns:

Instrument object that has been deployed

Return type:

MokuInstrument object

deploy_or_connect(instrument, set_default=True, use_external=False)

Ensures the Moku:Lab is running the given instrument, either by connecting to an already-running instance, or deploying a new one.

instrument is the class of the instrument you wish to deploy, e.g. Oscilloscope. This function will check what instrument, if any, is already running on the Moku:Lab using discover_instrument. If that instrument is of the wrong type, a new instance of the given instrument class is created and deployed using deploy_instrument.

Parameters:

• instrument (MokuInstrument subclass) – A Class representing the instrument type required
• set_default (bool) – Set the instrument to its default config upon connection, overwriting user changes before this point.
• use_external (bool) – Attempt to lock to an external reference clock.

Returns:

An object of type instrument representing the running Instrument.

detach_instrument()

Detaches the MokuInstrument from this Moku.

This has little effect usually, as a new Instrument can be attached without detaching the old one. This is mostly useful when you want to save network bandwidth between measurements without closing the entire Moku device

discover_instrument()

Query a Moku:Lab device to see what instrument, if any, is currently running.

Return type:MokuInstrument or None Returns:The detected instrument ready to be controlled, otherwise None.

get_bootmode()

Returns:A string representing the boot mode of the attached Moku:Lab

static get_by_ip(ip_addr, timeout=10, force=False, *args, **kwargs)

Factory function, returns a Moku instance with the given IP address.

Parameters:

• serial (str) – Target IP address i.e. ‘192.168.73.1’
• timeout (float, seconds) – Operation timeout
• force (bool) – Ignore firmware compatibility checks and force the instrument to deploy.

Return type:

Moku

Returns:

Connected Moku object with specified IP address.

Raises:

MokuNotFound – If no such Moku:Lab is found within the timeout period.

static get_by_name(name, timeout=10, force=False, *args, **kwargs)

Factory function, returns a Moku instance with the given device name.

Parameters:

• serial (str) – Target device name i.e. ‘MyMoku’
• timeout (float, seconds) – Operation timeout
• force (bool) – Ignore firmware compatibility checks and force the instrument to deploy.

Return type:

Moku

Returns:

Connected Moku object with specified device name.

Raises:

MokuNotFound – if no such Moku:Lab is found within the timeout period.

static get_by_serial(serial, timeout=10, force=False, *args, **kwargs)

Factory function, returns a Moku instance with the given serial number.

Parameters:

• serial (str) – Target serial number i.e. ‘000123’
• timeout (float, seconds) – Operation timeout
• force (bool) – Ignore firmware compatibility checks and force the instrument to deploy.

Return type:

Moku

Returns:

Connected Moku object with specified serial number.

Raises:

MokuNotFound – if no such Moku:Lab is found within the timeout period.

get_colour_list()

Returns:Available colours for the under-Moku “UFO” ring lights

get_firmware_build()

Returns:Build number of the current Moku:Lab firmware.

get_hw_version()

Returns:Hardware version of connected Moku:Lab

get_instrument()

Returns:Currently running instrument object. If the user has not deployed the instrument themselves, then discover_instrument must be called first.

get_ip()

Returns:IP address of the connected Moku:Lab

get_led_colour()

Returns:The colour of the under-Moku “UFO” ring lights

get_name()

Returns:Name of connected Moku:Lab

get_serial()

Returns:Serial number of connected Moku:Lab

get_version()

Returns:Version of connected Moku:Lab

is_active()

Returns:True if the Moku currently is connected and has an instrument deployed and operating

is_owned()

Checks whether the Moku:Lab device is currently owned by another user.

Return type:bool Returns:True if someone, including you, currently owns the Moku:Lab device

is_owner()

Checks if you are the current owner of the Moku:Lab device.

Return type:bool Returns:True if you are the owner of the device.

static list_mokus(timeout=5, all_versions=True)

Discovers all compatible Moku instances on the network.

For most applications, the user should use the get_by_ functions. These functions are faster to return as they don’t have to wait to find and validate all Moku devices on the network, they can look for a specific one.

Parameters:

• timeout (float) – time for which to search for Moku devices
• all_versions (bool) – list all Moku:Labs on the network, ignoring compatibility

Return type:

[(ip, serial, name),..]

Returns:

List of tuples, one per Moku

owned_by()

Return the name of the device that currently owns the Moku:Lab.

This will be the iPad name or PC hostname of the device that most recently took ownership of the Moku:Lab. This will be the current PC’s hostname if is_owner returns True.

Return type:str Returns:String name of current owner

relinquish_ownership()

Drop your claim to the connected Moku:Lab device.

This will allow other clients to connect immedaitely rather than waiting for a timeout

set_led_colour(colour)

Parameters:colour (string) – New colour for the under-Moku “UFO” ring lights. Possible colours are listed by get_colour_list

set_name(name)

Parameters:name – Set new name for the Moku:Lab. This can make it easier to discover the device if multiple Moku:Labs are on a network

take_ownership()

Register your ownership of the connected Moku:Lab device.

Having ownership enables you to send commands to and receive data from the corresponding Moku:Lab.

Instruments

• Oscilloscope Instrument
  • Example Usage
  • The VoltsData Class
  • The Oscilloscope Class
• Datalogger Instrument
  • Example Usage
  • The Datalogger Class
• Waveform Generator Instrument
  • Example Usage
  • The WaveformGenerator Class
• Arbitrary Waveform Generator Instrument
  • Example Usage
  • The ArbitraryWaveGen Class
• Spectrum Analyzer Instrument
  • Example Usage
  • The SpectrumData Class
  • The SpectrumAnalyzer Class
• Phasemeter Instrument
  • Example Usage
  • The Phasemeter Class
• Frequency Response Analyzer Instrument
  • Example Usage
  • The FRAData Class
  • The FrequencyResponseAnalyzer Class
• PID Controller Instrument
  • Example Usage
  • The PIDController Class
• Lock-in Amplifier Instrument
  • Example Usage
  • The LockInAmp Class
• IIR Filter Box Instrument
  • Example Usage
  • The IIRFilterBox Class

Exceptions

exception pymoku.MokuException

Base class for other Exceptions

exception pymoku.MokuNotFound

Can’t find Moku. Raised from discovery factory functions.

exception pymoku.NetworkError

Network connection to Moku failed

exception pymoku.DeployException

Couldn’t start instrument. Moku may not be licenced to use that instrument

exception pymoku.InvalidOperationException

Can’t perform that operation at this time

exception pymoku.InvalidParameterException

Invalid parameter type or value for this operation

exception pymoku.ValueOutOfRangeException

Invalid value for this operation

exception pymoku.NotDeployedException

Tried to perform an action on an Instrument before it was deployed to a Moku

exception pymoku.FrameTimeout

No new InstrumentData arrived within the given timeout

exception pymoku.NoDataException

A request has been made for data but none will be generated

exception pymoku.InvalidConfigurationException

A request for an invalid instrument configuration has been made.

exception pymoku.StreamException(message, err=None)

exception pymoku.FileNotFound

Requested file or directory could not be found

exception pymoku.InsufficientSpace

There is insufficient memory/disk space for the action being performed

exception pymoku.MPNotMounted

The requested mount point has not been mounted

exception pymoku.MPReadOnly

The requested mount point is Read Only

exception pymoku.UnknownAction

The request was unknown

exception pymoku.MokuBusy

The Moku is busy

exception pymoku.UncommittedSettings

Instrument settings are awaiting commit.