.. |MLA (TM)| unicode:: MLA U+2122 .. _advanced-hard-soft-label: Advanced Hardware and Software Topics ===================================== .. index: Calibration .. _calibration-label: 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 ). 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 :ref:`user-folder-label`. * 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 :func:`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. .. index:: changing active calibration changing the active calibration ------------------------------- The active calibration is most easily changed from the :ref:`mla-gui-label`. 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 :ref:`mla-config-ini-label`, 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 :func:`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 :func:`hardware.Hardware.upload_calibration`. There is also a guided, text-based, process for creating new calibrations. It is invoked by calling the function :func:`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 :ref:`analog-out-label`) 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**. .. index:: Ethernet communication, changing and resetting the IP number .. _ethernet-communication-label: 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 :ref:`mla-gui-label`, open the :ref:`python-shell-panel-label`. * 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 :ref:`mla-config-ini-label` 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 :ref:`quick-start-label` instructions * Edit :ref:`mla-config-ini-label` 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 (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. .. index: Lockin packet description .. _lockin-data-packet-label: 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.
<:math:`I_0`><:math:`Q_0`><:math:`I_1`><:math:`Q_1`><:math:`I_2`><:math:`Q_2`>...<:math:`I_{N-1}`><:math:`Q_{N-1}`>
(4*char) -- Indicates start of a packet (the characters are "IMP1"). (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. (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``. (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``. (uint32) -- Counter for how many measurement time windows that lockin calculation has been active. (uint32) -- Tells at which sample in the time window the trigger event occurred on trigger port ``TRIG IN 1``. <:math:`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. <:math:`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 (TM)| RAM memory, to the FPGA logic, and vise-versa. The |MLA (TM)| 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 :func:`osc.Osc.set_downsampling`, :func:`osc.Osc.start_time_stream`, :func:`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 :func:`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. .. index: Low-level programmer's model Low-level programmer's model ++++++++++++++++++++++++++++ .. _lowlevel-programmer-label: .. figure:: figures/programmers_model.png :width: 75 % :align: center