Add libm2k, pluto and m2k pages (#6)

university/tools/m2k/libm2k/calibration docs/software/libm2k/calibration.rst
university/tools/m2k/libm2k/digital_communication docs/software/libm2k/digital_communication.rst
university/tools/m2k/libm2k/libm2k docs/software/libm2k/index.rst
university/tools/m2k/libm2k/m2kcli docs/software/libm2k/m2kcli.rst
university/tools/m2k/developers docs/tools/m2k/devs.rst
university/tools/m2k/help_support docs/tools/m2k/help_support.rst
university/tools/m2k docs/tools/m2k/index.rst
university/tools/m2k/labview docs/tools/m2k/labview.rst
university/tools/m2k/matlab docs/tools/m2k/matlab.rst
university/tools/adalm2000/users docs/tools/m2k/users.rst
university/tools/pluto/help_support tools/pluto/help_support.rst
university/tools/pluto/prerequisites tools/pluto/prerequisites.rst
university/tools/pluto/devs/usb_otg tools/pluto/devs/usb_otg.rst
university/tools/pluto/controlling_the_transceiver_and_transferring_data tools/pluto/transceiver_transferring_data.rst
university/tools/pluto/users/antennas tools/pluto/users/antennas.rst
university/tools/pluto/devs/reboot tools/pluto-m2k/reboot.rst
university/tools/pluto/obtaining_the_sources tools/pluto-m2k/obtaining_the_sources
university/tools/pluto/drivers/windows tools/pluto-m2k/drivers
university/tools/pluto/users/firmware tools/pluto-m2k/firmware.rst
university/tools/pluto/drivers/windows tools/pluto-m2k/drivers.rst
university/tools/pluto/drivers/osx tools/pluto-m2k/drivers.rst
university/tools/pluto/drivers/linux tools/pluto-m2k/drivers.rst
university/tools/uartjtag tools/uartjtag/index.rst
university/tools/pluto/building_the_image tools/pluto-m2k/building_the_image.rst
university/tools/pluto/usb_otg_host_function_support tools/pluto-m2k/usb_otg_host_function_support.rst
university/tools/pluto/hacking/listening_to_yourself tools/pluto/hacking/listening_to_yourself.rst

Signed-off-by: Jorge Marques <[email protected]>

docs/conf.py

@@ -17,15 +17,15 @@
 ]
 
 needs_extensions = {
-    'adi_doctools': '0.3.49'
+    'adi_doctools': '0.3.50'
 }
 
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 source_suffix = '.rst'
 
 # -- External docs configuration ----------------------------------------------
 
-interref_repos = ['doctools', 'hdl', 'pyadi-iio']
+interref_repos = ['doctools', 'hdl', 'pyadi-iio', 'scopy', 'no-OS']
 
 # -- Options for HTML output --------------------------------------------------
 

docs/index.rst

@@ -1,5 +1,5 @@
 System Level Documentation
-===============================================================================
+==========================
 
 .. attention::
 
@@ -37,6 +37,13 @@ Contents
 
    eval/user-guide/index
 
+.. toctree::
+   :caption: Products & Tools
+   :maxdepth: 2
+   :glob:
+
+   tools/*/index
+
 .. toctree::
    :caption: University Program
    :maxdepth: 4

docs/linux/kuiper/sdcard/index.rst

@@ -123,9 +123,10 @@ files to block devices.
    .. shell::
 
       $time sudo dd \
-      $     if=2021-07-28-ADI-Kuiper-full.img \
+      $     bs=4194304 \
+      $     status=progress \
       $     of=/dev/mmcblk0 \
-      $     bs=4194304
+      $     if=2021-07-28-ADI-Kuiper-full.img
        [sudo] password for user:
        0+60640 records in 0+60640 records out 7948206080 bytes (7.9 GB) copied, 571.766 s, 13.9 MB/s
        real 7m54.11s user 0.29s sys 8.94s

docs/software/libiio/index.rst

@@ -275,10 +275,10 @@ Enabling IIOD USB Backend
 In order to use the libIIO USB Backend - support must be built into IIOD. A
 simple check is shown below:
 
-::
+.. shell::
 
-   root@analog:~# iiod -F foo
-   ERROR: IIOD was not compiled with USB support.
+   $iiod -F foo
+    ERROR: IIOD was not compiled with USB support.
 
 In this case LibIIO / IIOD needs to be built with USBD support. (WITH_IIOD_USBD)
 

docs/software/libm2k/calibration.rst

@@ -0,0 +1,179 @@
+.. _libm2k calibration:
+
+Calibration
+===========
+
+Description of the ADALM2000 calibration API in
+:dokuwiki:`libm2k </university/tools/m2k/libm2k/libm2k>`.
+
+Standard calibration
+--------------------
+
+.. danger::
+
+   Always disconnect analog inputs/outputs before calibration.
+
+The libm2k API offers three methods for calibrating the board:
+
+-  calibrateADC(): calibrate ADC
+-  calibrateDAC(): calibrate DAC
+-  isCalibrated(): true if at least one calibration procedure was performed on
+   the current session (firmware version < v0.26) or on the board since was
+   plugged in (firmware version >= v0.26). The function's output does not imply
+   that the last calibration is still valid.
+
+Python example:
+
+.. code:: python
+
+   import libm2k
+   ctx = libm2k.m2kOpen()
+   if ctx is None:
+       print("Connection Error: No ADALM2000 device available/connected to your PC.")
+       exit(1)
+   ctx.calibrateADC()
+   ctx.calibrateDAC()
+   # signal processing
+   libm2k.contextClose(ctx)
+
+Temperature calibration
+-----------------------
+
+.. important::
+
+   Only available from firmware version :git-m2k-fw:`v0.26 <v0.26:>`.
+
+Libm2k offers a way to use prerecorded calibration values that are stored in a
+context attribute. Using this approach, there is no need to disconnect the
+analog inputs/outputs at every run because the calibration parameters are stored
+on the device. Since calibration values are dependent on temperature, a script
+will record the values at different temperatures and eventually create a file
+that is compatible with libm2k and the context attribute format.
+
+Generating the file
+~~~~~~~~~~~~~~~~~~~
+
+The calibration values are written to the context attribute from a file on the
+ADALM2000 partition. The values will be stored on the device until they are
+overwritten.
+
+.. important::
+
+   There is a known limitation: The maximum temperature file size
+   is 4 kb. This will change in a future release.
+
+This file must be called 'm2k-calib-temp-lut.ini' and it should contain only a
+row having the following format:
+
+::
+
+   cal,temp_lut=[<temperature>,<adc_offset1>,<adc_offset2>,<adc_gain1> <adc_gain2>, <dac_offset1>,<dac_offset2>,<dac_gain1>,<dac_gain2> [...]]
+
+Example of file:
+
+::
+
+   cal,temp_lut=49.0,3038,2056,0.769531,1.07428,474,2026,0.597656,0.68335,49.2,3038,2056,0.769531,1.07428,474,2026,0.597656,0.68335,49.4,3038,2057,0.769531,1.073547,474,2024,0.597656,0.683777,49.6,3038,2057,0.769531,1.073547,474,2024,0.597656,0.683777
+
+.. caution::
+
+   The values differ from board to board.
+
+The file can be generated by using the following
+:git-libm2k:`script <bindings/python/calibration/generate_temperature_calib_lut.py>`.
+For better result, please consider exposing ADALM2000 to wider temperature
+variations, while the file is generated - will generate calibration values for
+more diverse points.
+
+synopsis
+^^^^^^^^
+
+::
+
+    generate_temperature_calib_lut <uri>
+                                   [-h | --help]
+                                   [-t | --temperature max_temp]
+                                   [-T | --timeout min]
+                                   [-v | --values nb_values]
+                                   [-f | --file path]
+                                   [-a | --append]
+
+description
+^^^^^^^^^^^
+
+Generate the temperature calibration lookup table.
+
+**temperature** The maximum temperature to stop at (default 75 °C).
+
+**timeout** The number of minutes after timeout will occur (default 30 minutes).
+
+**values** The maximum number of values to extract at the end.
+
+**file** The path to the generated file (default 'm2k-calib-temp-lut.ini').
+
+**append** Append the new computed values to the existent file.
+
+examples
+^^^^^^^^
+
+-  Create the ini file 'm2k-calib-temp-lut.ini'. The process can be stopped by
+   pressing 'CTRL + C', otherwise the process will stop when the temperature of
+   the board rises up to 75 °C or after 30 minutes
+
+.. shell::
+
+   $python3 generate_temperature_calib_lut.py ip:192.168.2.1
+
+-  Create the ini file 'example.ini'. The process can be stopped by pressing
+   'CTRL + C', otherwise the process will stop when the temperature of the board
+   rises up to 54 °C or after 15 minutes. Extract 5 values from all computed
+   calibration parameters. If the file is already created, the new computed
+   values will be appended.
+
+.. shell::
+
+   $python3 generate_temperature_calib_lut.py auto -v 5 -t 54 -T 15 -f "example.ini" -a
+
+Calibrating using the ini file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The purpose of this calibration type is to automate and to make the calibration
+process faster. Please make sure to have the following minimum requirements:
+
+-  A valid calibration file. The file can be generated using the script
+   mentioned above.
+-  Firmware v0.26 on your board
+-  libm2k v0.3.1
+
+After the board booted, copy the ini file inside the m2k drive. Then eject the
+drive (do not unplug!) and wait for ADALM2000 to boot. Once booted, the
+temperature calibration lookup table will be usable from libm2k.
+
+If you are using the -f or --file option you should rename the file to
+'m2k-calib-temp-lut.ini' before copying it to the device.
+
+In order to perform a fast calibration call the fallowing context method:
+calibrateFromContext(). The method hasContextCalibration() will validate if the
+temperature calibration can be performed on the current board. There are some
+reasons why the calibration can be performed:
+
+-  the values are not loaded onto the device
+-  the values are incorrect (not numerical values)
+-  some values are missing
+
+Python example:
+
+.. code:: python
+
+   import libm2k
+   ctx = libm2k.m2kOpen()
+   if ctx is None:
+       print("Connection Error: No ADALM2000 device available/connected to your PC.")
+       exit(1)
+   if ctx.hasContextCalibration():
+       ctx.calibrateFromContext()
+   else:
+       ctx.calibrateADC()
+       ctx.calibrateDAC()
+   # signal processing
+   libm2k.contextClose(ctx)