Advanced Hardware and Software Topics

Calibration

A calibration is used to convert quantities between physical units and the digital units of the AD- and DA-converters. The MLA comes with a factory calibration for converting to voltage units. However, in a specific measurement the user may want to include the gain of a pre-amplifier in the calibration, or some other calibration constant which converts to some other physical quantity that is linear in the digital units, for example displacement, magnetic field or current. In these cases the user can create their own custom calibration file with the proper calibration constants and units so the quantity of interest can be read off directly in the software.

The calibration file uses the well-established .ini file format (see for example <http://wikipedia.org/wiki/INI_file>). Multiple calibration files can coexist in the system, but only one is active.

A calibration file can be stored in either of the two following places:

  • The settings\calibration subfolder of the user folder.

  • The MLA hardware unit itself. Calibration files stored here will automatically be copied to the settings\calibration folder every time the MLA software starts and connects to the MLA. These calibrations will follow the MLA when it is connected to a new computer. To copy your own custom calibration file to the MLA, see the function hardware.Hardware.upload_calibration().

Three different calibrations are delivered with the MLA:

  • factory.ini – a calibration made at the factory, specific for the particular MLA unit. This calibration file is stored in the MLA and activated by default.

  • native_digital.ini – Select this calibration if you want to use raw digital values in the AD- and DA-converters. This calibration file will be written to the settings\calibration folder every time the software starts.

  • generic.ini – A standard calibration that should be quite close for unmodified MLA boxes. This calibration file will be written to the settings\calibration folder every time the software starts.

changing the active calibration

The active calibration is most easily changed from the MLA GUI. From the Configuration pull-down menu, choose Calibration and select your calibration. The active calibration is checked in the menu. The name of this active file is stored in the MLA and it will be recalled every time the software connects to the MLA. The ability of the MLA to remember the active calibration can be overridden so that the software will remember the active calibration. By setting the key override_calibration = yes in the file mla_config.ini, the software will load the calibration file specified by the key calibration_filename in this same file. This override functionality can be useful if the MLA is used in two or more different measurement setups, each with a separate computer.

The active calibration may also be set from a script or python terminal by calling the function mla.convert.set_calfile().

creating a new calibration

Do not edit any of the existing calibrations. Such edits will be overwritten when the software starts. A new calibration should created by copying an existing calibration to a new file name and editing the contents. To copy the new calibration file to the MLA see hardware.Hardware.upload_calibration().

There is also a guided, text-based, process for creating new calibrations. It is invoked by calling the function mla.run_calibration_sequence(). If the calibration sequence is finished the new calibration will be stored in the MLA and activated as the default calibration. The MLA GUI can be quickly set up for this sequence by running the built-in script calibrate.py.

calibration file format

The conversion between physical and digital units uses parameters offset and range according to the following formula:

digital = physical * DIGITAL_RANGE/range + offset

and equivalently

physical = (digital-offset) * range/DIGITAL_RANGE.

where DIGITAL_RANGE is an internal constant of the software containing the highest possible (unsigned) number for the corresponding digital quantity (eg. 65535 for a 16-bit value).

This means that the range parameter corresponds to the maximum peak-to-peak amplitude of the physical quantity. And the offset parameter corresponds to the digital offset correction required to make a digital zero correspond to a physical zero.

Each port has a range and offset parameter, defined in the calibration file. For ports IN 1-IN 4 the parameters are called AD_offset and AD_range. For ports OUT 1 and OUT 2 the parameters are called DA_offset and DA_range. The ports OUT 1 and OUT 2 have an additional common mode voltage controlled by the AUXDAC (see signal outputs) which is calibrated with the parameters auxdac_range and auxdac_offset. For ports OUT A, OUT B, OUT C, OUT D the parameters are called slowDA_offset and slowDA_range.

Ethernet communication

The MLA supports gigabit Ethernet communication. Four different ports are used:

  • 4250 (TCP) – Messages. This port is used to send commands and queries to the MLA. The reply to the queries are also sent on this port. This is the only port where data is sent in both directions.

  • 4251 (UDP) – Debug. This port is used by server to send debug messages. Listening to this port is optional.

  • 4252 (TCP) – Time data. This port is used to send data sampled in the time domain. The data format is int16. There are no headers or meta data in this stream.

  • 4253 (TCP) – Lockin data. This port is used to send lockin data.

setting the IP number

The IP number of the MLA can be changed using the IMP MLA software from a computer which is able to connect to the MLA.

  • Start the IMP MLA Software and wait until connection is established.

  • In the MLA GUI, open the Python shell panel.

  • Type the Python command setup.set_ip_address(‘NEW_IP’, ‘OLD_IP’) where the arguments are the new IP number that you want to set, and the current IP number. If the current IP is the default IP you can omit the second argument.

  • Exit the software.

  • Edit mla_config.ini and add mla_ip = NEW_IP under the heading [COMMUNICATION].

  • Configure the controlling computer such that it is able to reach the MLA at its new IP through its network.

  • Cycle the power of the MLA and restart the software.

    Caution

    The MLA is not designed to be exposed directly to the internet, please ensure it is only accessible through local networks.

resetting the IP number

The method above requires knowledge of the MLAs current IP address. If you have lost the current IP address and therefore can not connect to the MLA, the following trick allow you to “unbrick” the MLA. The MLA will have its original default IP address 192.168.42.50 for a few seconds during bootup.

  • Turn off the MLA and quit the MLA software.

  • Connect the MLA directly to an ethernet port on the computer and set the computer IP according to the Quick Start Guide instructions

  • Edit mla_config.ini and make sure it says mla_ip = 192.168.42.50 under the heading [COMMUNICATION] and unbrick=True under the heading [FPGA].

  • Start the MLA Software, but do not power up the MLA.

  • When the software is repeatedly trying to ping, power up the MLA.

Message format

<Message length><Message ID><Payload>

  • Message length (uint32) in bytes. The length includes its own four bytes.

  • Message ID (unit32).

  • Payload. The payload can be uint32, int32 or a string depending on the message ID.

Streams

Before a message can be sent to the MLA it must be packaged into a stream. A stream can contain one or more messages. The MLA will not execute a command until an entire stream has been received. When a full stream has been received, the MLA will execute all commands in the stream sequentially with no delay between each command. A stream starts with characters “star” followed by the length of the stream (not including the “star” or the length word). Then each message is appended directly after each other.

Lockin data packet

The lockin data is transmitted in packets where each packet contains the multifrequency data for a single measurement time window. The format of the lockin data packets is described here.

<header><cfg_cnt><trig1_cnt><trig2_cnt><data_cnt><trig_pos><I_0><Q_0><I_1><Q_1><I_2><Q_2>…<I_{N-1}><Q_{N-1}>

<header> (4*char) – Indicates start of a packet (the characters are “IMP1”).

<cfg_cnt> (uint32) – A counter for how many times the configuration has been changed. Useful to determine which frame belongs to which configuration when rapidly changing configuration parameters, for example in a frequency sweep.

<trig1_cnt> (uint32) – Counter for how many trigger events received at port TRIG IN 1. When scanning an image, the line trigger output from the scanner is connected to TRIG IN 1.

<trig2_cnt> (uint32) – Counter for how many trigger events received at port TRIG IN 2. When scanning an image, the frame trigger output from the scanner is connected to TRIG IN 2.

<data_cnt> (uint32) – Counter for how many measurement time windows that lockin calculation has been active.

<trig_pos> (uint32) – Tells at which sample in the time window the trigger event occurred on trigger port TRIG IN 1.

<I_i> (int64) – Demodulated value of I quadrature at tone with index i. N is the number of tones in the MLA. Data is in raw format, not divided by number of samples, and phase is relative to drive phase at this tone.

<Q_i> (int64) – Demodulated value of Q quadrature at tone with index i. N is the number of tones in the MLA. Data is in raw format, not decided by number of samples, and phase is relative to drive phase at this tone.

Direct Memory Access (DMA)

Direct Memory Access (DMA) allows data to be copied from the MLA™ RAM memory, to the FPGA logic, and vise-versa. The MLA™ has DMA channels for fast transfer of big data blocks between the FPGA logic that controls the hardware, and the MLA RAM memory that can buffer large amounts of data (768 MByte) for communication with computer.

There are two DMA channels for transferring waveform data from the RAM to the DA-converters. This means that it is possible to simultaneously generate arbitrary waveforms on both of the fast DA-converters. The cosine waveforms used for the lockin measurements are generated in real time in the FPGA logic and thus they do not need any DMA resource.

There are also two DMA channels for transferring measurement data from the FPGA logic to the RAM memory. Measurement data can be either raw time samples, down-sampled time samples, or lockin data. This means that it is possible to simultaneously measure two time data channels, or one time data channel and one lockin data channel. By default, DMA channel 0 is used for time samples, and DMA channel 1 is used for lockin data.

To use the DMA resources differently than default, set the dma_channel parameter in some function calls such as osc.Osc.set_downsampling(), osc.Osc.start_time_stream(), lockin.Lockin.start_lockin() etc.

In the start-up of the MLA sequence, each of the four DMA channels are associated with 128 megabytes of RAM memory on the MLA. This can be reconfigured with the function hardware.Hardware.configure_memory(), see for example the built-in script check_noise_floor.py where 760 megabytes are associated with the DMA for ad converter 0 to allow a very long and continuous time trace to be measured at 250 Msamples/sec.

Low-level programmer’s model

_images/programmers_model.png