diff --git a/docs/conf.py b/docs/conf.py index 22c9366a..bc32af0b 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,7 @@ ] needs_extensions = { - 'adi_doctools': '0.3.49' + 'adi_doctools': '0.3.50' } exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] @@ -25,7 +25,7 @@ # -- External docs configuration ---------------------------------------------- -interref_repos = ['doctools', 'hdl', 'pyadi-iio'] +interref_repos = ['doctools', 'hdl', 'pyadi-iio', 'scopy', 'no-OS'] # -- Options for HTML output -------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 7e4594b6..24d4f6a8 100755 --- a/docs/index.rst +++ b/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 diff --git a/docs/linux/kuiper/sdcard/index.rst b/docs/linux/kuiper/sdcard/index.rst index 87d80a8b..eba3f8fd 100644 --- a/docs/linux/kuiper/sdcard/index.rst +++ b/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 diff --git a/docs/software/libiio/index.rst b/docs/software/libiio/index.rst index 79824b22..21c7522b 100644 --- a/docs/software/libiio/index.rst +++ b/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) diff --git a/docs/software/libm2k/calibration.rst b/docs/software/libm2k/calibration.rst new file mode 100644 index 00000000..c3f2b9a8 --- /dev/null +++ b/docs/software/libm2k/calibration.rst @@ -0,0 +1,179 @@ +.. _libm2k calibration: + +Calibration +=========== + +Description of the ADALM2000 calibration API in +:dokuwiki:`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 `. + +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=[,,, , ,,, [...]] + +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 `. +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 + [-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) diff --git a/docs/software/libm2k/digital_communication.rst b/docs/software/libm2k/digital_communication.rst new file mode 100644 index 00000000..0734e9be --- /dev/null +++ b/docs/software/libm2k/digital_communication.rst @@ -0,0 +1,489 @@ +.. _libm2k digital_communication: + +Digital communication +""""""""""""""""""""" + +Libm2k includes bitbang implementations on a variety of protocols. + +How to install it? +================== + +Windows +------- + +In the *Select Additional Tasks* window, select *Install libm2k tools* option. + +How to build it? +================ + +Build and install libm2k. Instruction can be found +:ref:`here `. Make sure to enable tools option. + +Enable tools on Linux or OSX +---------------------------- + +.. shell:: + + ~/libm2k/build + $cmake -DENABLE_TOOLS=ON ../ + +Enable tools on Windows +----------------------- + +Check the *ENABLE_TOOLS* box in CMake GUI. + +Protocols +========= + +There is a common structure to use for all the protocols when trying to +communicate with other device using libm2k: + +* initialize the protocol +* read/write packets +* free the resources allocated by initialization + +Initialization of any protocol can be split into: + +* specific attributes initialization +* generic attributes initialization +* protocol descriptor initialization + +The structure that stores all ADALM-2000 specific attributes can be found in the +extra header, while all generic attributes are found in the standard header. For +example SPI generic attributes are found in *libm2k/tools/spi.hpp*, while SPI +specific attributes of ADALM-2000 are found in *libm2k/tools/spi_extra.hpp*. + +#. Instantiate and set all parameters of the init structure from the extra + header (m2k_protocol_init). +#. Instantiate and set all parameters of the init structure from the standard + header (protocol_init_param). This structure contains a parameter called + extra. The value of this parameter is supposed to be a reference to the + structure from the extra header. +#. Instantiate a protocol descriptor and then call the init function that will + populate the descriptor with the information found in initial structures. Use + this descriptor every time when a writing/reading operation is performed. + +SPI +--- + +Initialization parameters: + +* max_speed_hz - write/read frequency +* chip_select - index of any digital pin +* mode - spi mode +* extra: + + * clock - index of any digital pin + * mosi - index of any digital pin + * miso - index of any digital pin + * bit_numbering - {LSB | MSB} + * cs_polarity - {ACTIVE_LOW | ACTIVE_HIGH} + +Functions: + +* spi_init - initialize the SPI communication peripheral + + * desc - SPI descriptor + * param - structure that contains the SPI parameters + +* spi_write_and_read - write and read data to/from SPI + + * desc - SPI descriptor + * data - buffer with the transmitted/received data + * bytes_number - number of bytes to write/read + +* spi_remove - free the resources allocated by spi_init + + * desc - SPI descriptor + +Examples: + +Include headers + +.. code:: c++ + + #include + #include + #include + #include + +Setup SPI + +.. code:: c++ + + libm2k::contexts::M2k context = libm2k::contexts::m2kOpen("ip:192.168.2.1"); + + // first step of initialization + m2k_spi_init m2KSpiInit; + m2KSpiInit.clock = 1; + m2KSpiInit.mosi = 2; + m2KSpiInit.miso = 7; + m2KSpiInit.bit_numbering = MSB; + m2KSpiInit.context = context; + + // second step of initialization + spi_init_param spiInitParam; + spi_init_param.max_speed_hz = 1000000; + spi_init_param.mode = SPI_MODE_3; + spi_init_param.chip_select = 0; + spi_init_param.extra = (void)&m2KSpiInit; + + // third step of initialization + spi_desc desc = nullptr; + spi_init(&desc, &spiInitParam); + +Write data + +.. code:: c++ + + uint8_t data[2] = {0xAB, 0xFF}; + spi_write_and_read(desc, data, 2); + +Remove the descriptor + +.. code:: c++ + + spi_remove(desc); + libm2k::contexts::contextClose(context, true); + +I²C +--- + +Initialization parameters: + +* max_speed_hz - write/read frequency +* slave_address - 7/10 bit address +* extra: + + * scl - index of any digital pin + * sda - index of any digital pin + +Functions: + +* i2c_init - initialize the I²C communication peripheral + + * desc - I²C descriptor + * param - structure that contains the I²C parameters + +* i2c_write - write data to a slave device + + * desc - I²C descriptor + * data - buffer with the transmitted data + * bytes_number - number of bytes to write + * option - I²C transfer mode + + * 1 = 7 bit addressing + * 3 = 7 bit addressing with repeated start + * 4 = 10 bit addressing + * 6 = 10 bit addressing with repeated start + +* i2c_read - read data from a slave device + + * desc - I²C descriptor + * data - buffer with the received data + * bytes_number - number of bytes to read + * option - I²C transfer mode + +* i2c_remove - free the resources allocated by i2c_init + + * desc - I²C descriptor + +Examples: + +Include headers + +.. code:: c++ + + #include + #include + #include + #include + +Setup I²C + +.. code:: c++ + + libm2k::contexts::M2k context = libm2k::contexts::m2kOpen("ip:192.168.2.1"); + + // first step of initialization + m2k_i2c_init m2KI2CInit; + m2KI2CInit.scl = 0; + m2KI2CInit.sda = 1; + m2KI2CInit.context = context; + + // second step of initialization + i2c_init_param i2CInitParam; + i2CInitParam.max_speed_hz = 100000; + i2CInitParam.slave_address = 0x48; + i2CInitParam.extra = (void)&m2KI2CInit; + + // third step of initialization + i2c_desc desc = nullptr; + i2c_init(&desc, &i2CInitParam); + +Write and read the data + +.. code:: c++ + + uint8_t data_write[] = {0x0B}; + uint8_t data_read[] = {0}; + i2c_write(desc, data_write, sizeof(data_write), i2c_general_call | i2c_repeated_start); + i2c_read(desc, data_read, sizeof(data_read), i2c_general_call); + +Remove the descriptor + +.. code:: c++ + + i2c_remove(desc); + libm2k::contexts::contextClose(context, true); + +UART +---- + +Initialization parameters: + +* baud_rate - write/read frequency +* device_id - index of any digital pin +* extra: + + * parity - {NO_PARITY | ODD | EVEN | MARK | SPACE} + * bits_number - {5 | 6 | 7 | 8} + * stop_bits - {ONE | ONE_AND_A_HALF | TWO} + +Functions: + +* uart_init - initialize the UART communication peripheral + + * desc - UART descriptor + * param - structure that contains the UART parameters + +* uart_write - write data to UART + + * desc - UART descriptor + * data - buffer with the transmitted data + * bytes_number - number of bytes to write + +* uart_read - read data to UART + + * desc - UART descriptor + * data - buffer with the received data + * bytes_number - number of bytes to read + +* uart_get_errors - check if UART errors occurred + + * desc - UART descriptor + +* uart_remove - free the resources allocated by uart_init + + * desc - UART descriptor + +Examples: + +Include headers + +.. code:: c++ + + #include + #include + #include + #include + +Setup UART + +.. code:: c++ + + libm2k::contexts::M2k context = libm2k::contexts::m2kOpen("ip:192.168.2.1"); + + // first step of initialization + m2k_uart_init m2KUartInit; + m2KUartInit.bits_number = 8; + m2KUartInit.parity = NO_PARITY; + m2KUartInit.stop_bits = ONE; + m2KUartInit.context = context; + + // second step of initialization + uart_init_param uartInitParam; + uartInitParam.device_id = 0; + uartInitParam.baud_rate = 9600; + uartInitParam.extra = (void)&m2KUartInit; + + // third step of initialization + uart_desc desc = nullptr; + uart_init(&desc, &uartInitParam); + +Write data + +.. code:: c++ + + uint8_t dataWrite[] = {'A', 'D', 'I'}; + uart_write(desc, dataWrite, sizeof(dataWrite)); + +Remove the descriptor + +.. code:: c++ + + uart_remove(desc); + libm2k::contexts::contextClose(context, true); + +Libm2k and no-OS drivers +======================== + +Analog Devices offers a variety of :git-no-OS:`No-OS drivers ` +for a variety peripherals in a hardware agnostic format. +These drivers can be interfaced with the libm2k +in order to use the M2K as a master to configure/use the peripheral. +Documentation for the drivers available at :external+no-OS:doc:`drivers_doc`. + +In order to integrate libm2k with no-OS drivers some standard steps must be +followed: + +* drivers inclusion +* libm2k headers inclusion +* writing the logic + + * C++ file + * drivers included as external C + +Including all required driver files in the project is the first step in +integrating libm2k with no-OS drivers. + +The drivers will include some protocols, for example *"i2c.h"*. The afferent +header of libm2k, *libm2k/tool/i2c.hpp*, does not match with the header +included by the drivers (*"i2c.h"*). In order not to modify the drivers we are +going to create a header named after the protocol (*"i2c.h"*) in which the +libm2k header will be included. For example create the *"i2c.h"* header in which +you will include *libm2k/tools/i2c.hpp*. + +Each file that will call libm2k methods should be a C++ file. The inclusion of +any driver in a C++ file has to be marked as an external C file inclusion. + +Example: + +AD5592r can be independently configured as DAC outputs, ADC inputs, digital +outputs, or digital inputs. In this example we are going to generate ascending +voltage values, communicating with the chip using SPI. + +- Hardware configuration (ADALM-2000 <- -> AD5592r): + + - SCK: DIO_0 <- -> P4 + - MOSI: DIO_1 <- -> P2 + - MISO: DIO_2 <- -> P3 + - SS: DIO_3 <- -> P1 + - GND: GND <- -> P5 + - VLOGIC: V+ -> P6 + - Oscilloscope: 1+ <- I/O0 + +- Project structure: + + - ad5592r-base.h + - ad5592r-base.c + - ad5592r.h + - ad5592r.c + - delay.h + - delay.c + - spi.h + - i2c.h + - main.cpp + +- Get all AD5592r drivers from + :git-no-OS:`drivers/adc-dac/ad5592r` +- Get delay header from + :git-no-OS:`include/delay.h` +- Implement mdelay function from delay.h + +.. code:: c++ + + #include "delay.h" + #include + + void mdelay(uint32_t msecs) { + usleep(msecs * 1000); + } + +Create spi.h and i2c.h headers (we are not going to use I²C in this example, +but AD5592r drivers include I²C header). In each file include the afferent +header of libm2k. + +.. code:: c++ + + //spi.h + #include + +.. code:: c++ + + //i2c.h + #include + +Create main.cpp file: + +.. code:: c++ + + #include + #include + #include + #include + #include + + extern "C" { + #include "ad5592r.h" + } + extern struct ad5592r_rw_ops ad5592r_rw_ops; //default operations + + int main() + { + struct ad5592r_init_param init_param; + init_param.int_ref = true; // use the internal reference + + struct ad5592r_dev device; + device.ops = &ad5592r_rw_ops; //initialize the operations + + libm2k::contexts::M2k *context = libm2k::contexts::m2kOpen("ip:192.168.2.1"); + libm2k::analog::M2kPowerSupply *powerSupply = context->getPowerSupply(); + libm2k::analog::M2kAnalogIn *analogIn = context->getAnalogIn(); + + std::cout << "Calibrating . . ." << std::endl; + context->calibrateADC(); + + powerSupply->enableChannel(0, true); + powerSupply->pushChannel(0, 5); // power up the chip + + // first step of initialization + m2k_spi_init m2KSpiInit; // m2k specific attributes of SPI + m2KSpiInit.clock = 0; + m2KSpiInit.mosi = 1; + m2KSpiInit.miso = 2; + m2KSpiInit.bit_numbering = MSB; + m2KSpiInit.context = context; + + // second step of initialization + spi_init_param spiInitParam; // generic attributes of SPI + spiInitParam.max_speed_hz = 2500000; + spiInitParam.mode = SPI_MODE_2; + spiInitParam.chip_select = 3; + spiInitParam.extra = (void*)&m2KSpiInit; + + // third step of initialization + spi_init(&device.spi, &spiInitParam); // initialize SPI communication + + device.channel_modes[0] = CH_MODE_DAC; // set the first channel as a DAC + device.num_channels = 1; // enable just the first channel + ad5592r_init(&device, &init_param ); //initialize AD5592r + + for(int i = 0; i < 0xfff; i+=0x0f) { + ad5592r_write_dac(&device, 0, i); // generate voltage + std::cout << analogIn->getVoltage(0) << std::endl; //read voltage + } + + libm2k::contexts::contextClose(context, true); + } + +Compile the project: + +.. code:: c++ + + gcc -c delay.c + gcc -c ad5592r-base.c + gcc -c ad5592r.c + g++ -c main.cpp + g++ -o example delay.o ad5592r-base.o ad5592r.o main.o -lm2k + ./example diff --git a/docs/software/libm2k/index.rst b/docs/software/libm2k/index.rst new file mode 100644 index 00000000..eddc4165 --- /dev/null +++ b/docs/software/libm2k/index.rst @@ -0,0 +1,453 @@ +.. _libm2k: + +Libm2k +====== + +Libm2k is a C++ library for interfacing with the :ref:`m2k`, split into more +correlated components, interconnected by a context. + +These m2k components represent the functionalities of ADALM2000: + +- AnalogIn - oscilloscope or voltmeter +- AnalogOut - signal generator +- Digital - logic analyzer or pattern generator +- PowerSupply - constant voltage generator +- DMM - digital multimeter + +Libm2k can be used for encoding and decoding digital signals, communicating with +a wide variety of chips, using some well known protocols, such as SPI, I²C or +UART. Created based on no-OS communication headers, libm2k communication segment +is build to interact with ADI's chips in a generic way. Regardless of protocol, +there are three common steps in any communication process: initialization, +writing/reading, freeing the resources. A more detailed view of communicating +with a peripheral is documented at :ref:`libm2k digital_communication`. + +For an easier and faster control of m2k components, libm2k offers a command-line +frontend, called m2kcli. This command line tool also includes the functionality +of encoding and decoding digital signals. More information about m2kcli can be +found on at :ref:`libm2k m2kcli`. + +.. toctree:: + :hidden: + :glob: + + * + +ADALM2000 drivers +----------------- + +.. important:: + + Make sure you install the ADALM2000 drivers for your operating + system before using the board. + +Linux +~~~~~ + +In order to access some USB functions without root privileges, it's recommended +to install the ADALM2000 udev rules. Simply download +:git-m2k-fw:`53-adi-m2k-usb.rules ` +and copy into the */etc/udev/rules.d/* folder + +Windows +~~~~~~~ + +Instructions to install Windows drivers can be found +at :ref:`pluto-m2k drivers windows`. + +Mac OS X +~~~~~~~~ + +Instructions to install Mac OS X drivers can be found +at :ref:`pluto-m2k drivers osx`. + +How to install it? +------------------ + +Download +~~~~~~~~~ + +.. admonition:: Download + + Go to the :git-libm2k:`latest release page ` and + download the package that fits your system. + +Installation +~~~~~~~~~~~~ + +For Windows ++++++++++++ + + +Download the ``libm2k-Windows-setup.exe`` and run through all the required +steps. + +.. important:: + + For libm2k versions starting with v0.6.0: The libm2k Windows + installer does not include Python bindings. Check the Python bindings section + for more details. + +.. warning:: + + For libm2k versions older than v0.6.0: + Make sure you only select the libm2k Python bindings that correspond to your + installed Python version. + +For Linux ++++++++++ + +Download the ``libiio-ubuntu.deb`` for your system +(from the :git-libiio:`nightly builds `) and install it by running: + +.. shell:: + + $sudo apt install -f ./libiio-package.deb + +Download the libm2k-ubuntu.deb for your system and install it by running: + +.. shell:: + + $sudo apt install -f ./libm2k-package.deb + +For OSX ++++++++ + +Download the ``libiio-darwin.pkg`` for your system +(from the :git-libiio:`nightly builds `) and install it by running: + +.. shell:: + + $sudo installer -pkg /path/to/package.pkg -target / + +Download the libm2k-darwin.pkg for your system and install it by running + +.. shell:: + + $sudo installer -pkg /path/to/package.pkg -target / + +The ``m2kcli`` command line tool is also installed with the package. In order +to access it, the full path to it must be used +(*/Library/Frameworks/libm2k.framework/Tools/m2kcli*) or a symbolic link can +be created in the following way: + +.. shell:: + + $ln -s /Library/Frameworks/libm2k.framework/Tools/m2kcli /m2kcli + + +````: choose any location that is listed in the PATH +(example: */usr/local/bin* or */usr/bin*) + +.. note:: + + When installing the Python bindings, you must configure the library path + correctly. + After installing Python bindings (either by using the *.whl* provided on + the release page or via a `pip`), run the following command: + +.. shell:: + + $install_name_tool -add_rpath /Library/Frameworks/ \ + $ /Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/_libm2k.cpython-311-darwin.so + +.. attention:: + + Adjust the `3.11` and `311` references from the example to match your + specific Python version. + +.. _libm2k build: + +Building and installing bindings +-------------------------------- + +Python bindings +~~~~~~~~~~~~~~~ + +**Option 1 - Download wheel packages**: +The easiest way to use the libm2k Python bindings is to install them using **pip**. +Starting with version v0.6.0, libm2k releases provide an archive containing +**wheels** for Windows, Linux, MacOS corresponding to Python versions 3.7, 3.8, +3.9 and 3.10. + +.. shell:: + + $python3 -m pip install ./libm2k-0.6.0-cp310-cp310-win_amd64.whl + +**Option 2 - Use test.pypi.org**: +For every release starting with v0.6.0, all the Python wheels for libm2k will +be uploaded to test.pypi.org. +`Check the files and install instructions here `__ + +**Option 3 - Conda packages**: +If you are using Conda, libm2k packages are made available and updated at every +major release. +:dokuwiki:`Check out more details here `. + +**Option 4 - Build the bindings**: +The Python bindings are enabled by default if SWIG and a correct Python version +are detected on your system. +They can be specifically enabled or disabled by using the following: + +.. shell:: + + ~/libm2k/build + $cmake -DENABLE_PYTHON=ON/OFF .. + +C# bindings +~~~~~~~~~~~ + +The C# bindings are **disabled** by default. They can be specifically +enabled (requires SWIG and a correct C# compiler) or disabled by using the +following: + +.. shell:: + + ~/libm2k/build + $cmake -DENABLE_CSHARP=ON/OFF .. + +MATLAB bindings +~~~~~~~~~~~~~~~ + +MATLAB bindings come pre-packaged through installers for Linux and Windows. +Further documentation is provided at :ref:`m2k matlab`. + +LabVIEW bindings +~~~~~~~~~~~~~~~~ + +LabVIEW bindings come pre-packaged through a .vip installer for Windows. +Further documentation is provided at :ref:`m2k labview`. + +Other features +-------------- + +.. _m2kcli build: + +Build m2k tools - m2kcli +~~~~~~~~~~~~~~~~~~~~~~~~ + +Building m2kcli is disabled by default. It can be enabled by running the +following + +.. shell:: + + ~/libm2k/build + $cmake -DENABLE_TOOLS=ON .. + +Building with logging support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The logging system is **disabled** by default. It can be specifically +enabled(requires glog library) or disabled by using the following: + +.. shell:: + + ~/libm2k/build + $cmake -DENABLE_LOG=ON/OFF .. + +There is one more layer of controlling the logging. After building libm2k with +logging support the user must enable the logging system from code, calling the +method enableLogging(true). By default the logging system is disabled. + +Building the examples +~~~~~~~~~~~~~~~~~~~~~ + +Building the examples is disabled by default. It can be enabled by running the +following + +.. shell:: + + ~/libm2k/build + $cmake -DENABLE_EXAMPLES=ON .. + +Building on Linux +----------------- + +Dependencies +~~~~~~~~~~~~ + +Install git, cmake, swig, python: + +.. shell:: + + $sudo apt install git cmake swig g++ python3-dev \ + $ python3-setuptools libgoogle-glog-dev + +Build and install libiio. +Instructions can be found at :ref:`libiio build`. + +Install libm2k +~~~~~~~~~~~~~~ + +Build and install libm2k: + +.. shell:: + + $git clone https://github.com/analogdevicesinc/libm2k.git + $cd libm2k + $mkdir build + $cd build + $cmake ../ + $make + $sudo make install + +If the Python bindings were enabled, they will be **automatically** installed in +the site-packages folder specific for Python, once sudo make install is called. + +Building on OSX +--------------- + +Dependencies +~~~~~~~~~~~~ + +Install git, cmake, swig and python: + +.. shell:: + + $brew install git cmake g++ swig python3 libusb + +Download and install +:git-libiio:`libiio `. + +Install libm2k +~~~~~~~~~~~~~~ + +Build and install libm2k: + +.. shell:: + + $git clone https://github.com/analogdevicesinc/libm2k.git + $cd libm2k + $mkdir build + $cd build + $cmake ../ + $make + $sudo make install + +Install libm2k Python bindings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Make sure you installed libm2k first then run the following commands in order to +install the Python bindings in your system. + +.. shell:: + + ~/libm2k + $cd build + $python3 setup.py install_lib + +This will install *libm2k.py* and *_libm2k.so* in the site-packages folder used by +your python3 executable. + +Building on Windows +------------------- + +Get the latest installer from +`here `__. + +Dependencies +~~~~~~~~~~~~ + +#. libiio + + - Download the libiio zip from :git-libiio:`releases+`. + - Choose a location and extract libiio. + +#. CMake + + - Install CMake using an installer from the `official page `__. + +#. Swig + + - Download the SWIG zip from `this page `__. + - Choose a location and extract SWIG. + +#. Python3 + + - Download and install Python3 from the `official page `__. + - Set path to program files or ``C:\Python37``. + +#. glog + + - Clone `glog `__. + - Use the CMake-gui. At startup, select your platform. + - Enable BUILD_SHARED_LIBS and disable WITH_GFLAGS. + - Set CMAKE_CONFIGURATION_TYPES to Release + - Press 'Configure' button. + - Press 'Generate' button. + - Click 'Open Project' and build the solution. + - Note: glog.dll should be placed next to your libm2k application or in your system + +Install libm2k +~~~~~~~~~~~~~~ + +#. Clone libm2k or download zip and extract it. +#. Use the CMake-gui and open ``libm2k/CMakeLists.txt``. At startup, select + platform x64. + + .. image:: libm2k_windows_cmake.png + :width: 400px + +#. Press the Configure button. Some of the parameters will be set to their + correct value. +#. Browse the location where you extracted libiio and set ``IIO_LIBRARIES`` to + ``libiio/MS64/libiio.lib`` and ``IIO_INCLUDE_DIRS`` ``libiio/include``. +#. (Only if logging is enabled) Browse the location where glog was built. Set + ``GLOG_LIBRARIES`` to ``glog_build_dir/Release/glog.lib`` and + ``GLOG_INCLUDE_DIRS`` to your ``glog_build_dir``. +#. Press the Configure button again. +#. Set the ``PYTHON_EXECUTABLE`` to have the python install folder + (``C:/Python37/python.exe``). +#. Press the Configure button again. +#. Browse the location where you extracted SWIG and the SWIG_DIR to that + location. +#. Press the Configure button again. +#. If no errors, click Generate button in CMake-gui +#. Click Open Project in CMake-gui - this will open Visual Studio. + +**Build solution in visual studio** + +If you want to install the library in the system: + +#. Open a Command Prompt in the libiio folder and copy all the .dll files in + ``C:\Windows\System32``. +#. Open a Command Prompt in the build folder and copy libm2k.dll in + ``C:\Windows\System32``. + +**C# bindings** + +#. The C# bindings are built by default. In order to disable them, set + ``ENABLE_CSHARP=OFF`` in the CMake configuration. +#. In order to use the C# bindings, you need to copy the following dlls in your + build folder: ``libm2k-sharp.dll`` and ``libm2k-sharp-cxx-wrap.dll`` . These + can be found in ``C:\Program Files\Common Files\libm2k`` if you installed + libm2k using the system installer. Otherwise, you can download the latest + archive from appveyor: Appveyor artifacts and get the dlls from there. +#. Add ``libm2k-sharp.dll`` as a reference in your project. +#. Check the examples from :git-libm2k:`the source code `. + +Documentation +------------- + +API reference +~~~~~~~~~~~~~ + +An automatically generated documentation of the API can be found +`here `__. + +calibration +~~~~~~~~~~~ + +Libm2k offers a software solution for calibrating the board. Please visit the +dedicated :ref:`page ` for more information. + +m2kcli +~~~~~~ + +Documentation can be found at :ref:`libm2k m2kcli`. + +digital communication +~~~~~~~~~~~~~~~~~~~~~ + +See :ref:`libm2k digital_communication`. + diff --git a/docs/software/libm2k/libm2k_windows_cmake.png b/docs/software/libm2k/libm2k_windows_cmake.png new file mode 100644 index 00000000..b0fae830 --- /dev/null +++ b/docs/software/libm2k/libm2k_windows_cmake.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ce33fab7bb8edde6f5bee1d3f24e2b58e327d8e74aaac78ba3831a500bd46281 +size 19237 diff --git a/docs/software/libm2k/m2kcli.rst b/docs/software/libm2k/m2kcli.rst new file mode 100644 index 00000000..a4e5ff46 --- /dev/null +++ b/docs/software/libm2k/m2kcli.rst @@ -0,0 +1,1027 @@ +.. _libm2k m2kcli: + +Command line utility +"""""""""""""""""""" + +m2kcli is a command-line frontend for libm2k. + +m2kcli is composed from many commands, each representing a major functionality +of the ADALM-2000: + +- analog-in: oscilloscope and voltmeter +- analog-out: signal generator +- digital: logic analyzer and pattern generator +- power-supply + +m2kcli offers an easy way to communicate with other devices using digital +protocols such as: + +- SPI +- I²C +- UART +- UART Terminal + +How to install it? +================== + +Windows +------- + +In the *Select Additional Tasks* window, select *Install libm2k tools* option. + +How to build it? +================ + +Build and install libm2k. Instruction can be found +:ref:`here `. Make sure to enable tools +option. + +Enable tools on Linux or OSX +---------------------------- + +.. shell:: + + ~/libm2k/build + $cmake -DENABLE_TOOLS=ON ../ + +Enable tools on Windows +----------------------- + +Check the *ENABLE_TOOLS* box in CMake GUI. + +Commands +======== + +All commands require an URI. URI describes the context location. + +* auto - establish an USB connection detecting the available USB +* usb:XX.XX.X +* ip: XXX.XXX.XXX.XXX - standard ip address 192.168.2.1 +* serial:/dev/ttyAMA0,115200n8 +* local: + +Options: + +| **help** +| Show the help message and exit. + +| **quiet** +| Return the result only. + +analog-in +--------- + +synopsis +~~~~~~~~ + +.. code:: bash + + m2kcli analog-in + [-h | --help] + [-q | --quiet] + [-C | --calibrate] + [-v | --voltage channel=,... raw=] + [-c | --capture channel=,... buffer_size= raw= [nb_samples=] [format=]] + [-g | --get ...] + [-G | --get-channel channel=,... ...] + [-s | --set =...] + [-S | --set-channel channel= =...] + + +description +~~~~~~~~~~~ + +analog-in command controls the analogical input component, having two main +functions: oscilloscope and voltmeter. The available channels for analog in are +channel 0 and channel 1. + +Pinout: + +| ▤ ▥ □ □ □ □ □ □ □ □ □ □ □ □ □ +| ▤ ▥ □ □ □ □ □ □ □ □ □ □ □ □ □ + +Options: + +**calibrate** + +Calibrate the ADC. + +**voltage** + +Return the voltage of the given channels. The result is printed to standard +output. + +Mandatory arguments: + +* channel - one or both indexes are possible to be specified +* raw - 0 = processed values, 1 = raw values + +Examples: + +Retrieve the average voltage of both channels as raw values: + +.. shell:: + + $m2kcli analog-in auto -v channel=0,1 raw=1 + +Retrieve only the processed voltage for the first channel: + +.. shell:: + + $m2kcli analog-in auto --voltage channel=0 raw=0 -q + +-------------- + +**capture** + +Return a specific number of samples. The result is printed to standard output. + +Mandatory arguments: + +* channel - one or both indexes are possible to be specified +* buffer_size - the number of samples into one iio_buffer +* raw - 0 = processed values, 1 = raw values + +Optional arguments: + +* nb_samples – integer value that represents the number of samples to be + captured. + Default value is 0, continuously capturing samples until the process is force stopped +* format – csv/binary. The way the samples will be printed. Default type is csv + +Examples: + +Capture 2048 unprocessed samples from both channels using a buffer of length +1024 and save them into a binary file: + +.. shell:: + + $m2kcli analog-in auto --capture channel=0,1 buffer_size=1024 \ + $ nb_samples=2048 raw=1 format=binary > file.bin + +Continuous samples capturing: + +.. shell:: + + $m2kcli analog-in ip:192.168.2.1 -c channel=1 buffer_size=1024 raw=0 + +-------------- + +**get** + +Return the value of the global attributes. Enumerate the attributes with a space +between them. + +Attributes: + +* sampling_frequency +* oversampling_ratio +* trigger_source +* trigger_delay + +Examples: + +Display all global attributes + +.. shell:: + + $m2kcli analog-in auto --get all + +Get the sampling frequency and the oversampling ratio + +.. shell:: + + $m2kcli analog-in auto -g sampling_frequency oversampling_ratio + +-------------- + +**get-channel** + +Return the value of the attributes corresponding the the given channels. + +Mandatory arguments: + +* channel - one or both indexes are possible to be specified + +Attributes: + +* range +* trigger_level +* trigger_condition +* trigger_mode +* trigger_hysteresis + +Examples: + +Get all attributes of both channels + +.. shell:: + + $m2kcli analog-in --get-channel channel=0,1 all + +Get the triggering condition of the second channel + +.. shell:: + + $m2kcli analog-in -G channel=1 trigger_condition + +-------------- + +**set** + +Set the value of the global attributes. + +Attributes: + +* sampling_frequency - {1000 | 10000 | 100000 | 1000000 | 10000000 | 100000000} +* oversampling_ratio - integer +* trigger_source - {channel_1 | channel_2 | channel_1_or_channel_2 | channel_1_and_channel_2 | channel_1_xor_channel_2} +* trigger_delay - integer +* kernel_buffers - integer + +Examples: + +Set sampling_frequency and trigger_source + +.. shell:: + + $m2kcli analog-in auto --set sampling_frequency=100000 trigger_source=channel_1 + +-------------- + +**set-channel** + +Set the value of the attributes corresponding to the given channels. + +Mandatory arguments: + +* channel - one or both indexes are possible to be specified + +Attributes: + +* range - {high | low} +* trigger_level - integer +* trigger_condition - {rising_edge | falling_edge | low_level | high_level} +* trigger_mode - {always | analog | digital | digital_or_analog | digital_and_analog | digital_xor_analog | n_digital_or_analog | n_digital_and_analog | n_digital_xor_analog} +* trigger_hysteresis - double (volts) + +Examples: + +Set the range and the trigger_mode + +.. shell:: + + $m2kcli analog-in auto --set-channel channel=1 range=high trigger_mode=analog + +-------------- + +analog-out +---------- + +synopsis +~~~~~~~~ + +:: + + m2kcli analog-out + [-h | --help] + [-q | --quiet] + [-C | --calibrate] + [-9 | --generate channel=,... cyclic= raw= [buffer_size=] [format=]] + [-G | --get-channel channel= ...] + [-S | --set-channel channel= =...] + +description +~~~~~~~~~~~ + +analog-out command controls the analogical output component, having the main +functions of a signal generator. The available channels for analog out are +channel 0 and channel 1. + +Pinout: + +| □ □ □ □ ▤ □ □ □ □ □ □ □ □ □ □ +| □ □ □ □ ▥ □ □ □ □ □ □ □ □ □ □ + +Options: + +| **calibrate** +| Calibrate both DACs. + +| **generate** +| Generate signals for the specified channels. The samples are read from the + standard input. + +Mandatory arguments: + +* channel - one or both indexes are possible to be specified +* cyclic - 0 = non-cyclic mode, 1 = cyclic mode +* raw - 0 = processed values, 1 = raw values + +Optional arguments: + +* buffer_size - size of the output buffer; default value is 256 +* format - csv/binary. The way the samples will be read. Default type is csv + +Examples: + +Generate a cyclic signal based on the samples located in file.csv + +.. shell:: + + $m2kcli analog-out auto --generate channel=0 \ + $ cyclic=1 raw=0 buffer_size=1024 < file.csv + +-------------- + +**get-channel** + +Return the value of the attributes corresponding to the given channel. + +Mandatory arguments: + +* channel - one or both indexes are possible to be specified + +Attributes: + +* sampling_frequency +* oversampling_ratio + +Examples: + +Get all attributes of the first channel + +.. shell:: + + $m2kcli analog-out auto -G channel=0 all + +-------------- + +**set-channel** + +Set the value of the attributes corresponding to the given channel. + +Mandatory arguments: + +* channel - one or both indexes are possible to be specified + +Attributes: + +* sampling_frequency - {750 | 7500 | 75000 | 750000 | 7500000 | 75000000} +* oversampling_ratio - integer + +Examples: + +Set the sampling frequency of both channel to 7500 + +.. shell:: + + $m2kcli analog-out auto -S channel=0,1 sampling_frequency=7500 + +-------------- + +digital +------- + +synopsis +~~~~~~~~ + +:: + + m2kcli digital + [-h | --help] + [-q | --quiet] + [-c | --capture buffer_size= [nb_samples=] [format=]] + [-9 | --generate channel=,... cyclic= [buffer_size=] [format=]] + [-g | --get ...] + [-G | --get-channel channel=,... ...] + [-s | --set =...] + [-S | --set-channel channel=,... =...] + +.. _description-2: + +description +~~~~~~~~~~~ + +digital command controls the digital input and output component, having two main +functions: logic analyzer and pattern generator. The available channels for +digital are between 0 and 15. + +Pinout: + +| □ □ □ □ □ □ □ ■ ■ ■ ■ ■ ■ ■ ■ +| □ □ □ □ □ □ □ ■ ■ ■ ■ ■ ■ ■ ■ + +Options: + +| **capture** +| Return a specific number of samples. The result is printed to standard output. + +Mandatory arguments: + +* buffer_size - the number of samples into one iio_buffer + +Optional arguments: + +* nb_samples - integer value that represents the number of samples to be captured. + Default value is 0 , continuously capturing samples until the program is force + stopped +* format - csv/binary. The way the samples will be printed. Default type is csv + +Examples: + +Capture 100 samples + +.. shell:: + + $m2kcli digital auto -c buffer_size=60 nb_samples=100 + +Capture samples continuously, binary format + +.. shell:: + + $m2kcli digital auto -c buffer_size=1000 format=binary + +-------------- + +**generate** + +Generate digital signals for the specified channels.The samples are read from +the standard input. + +Mandatory arguments: + +* channel - one or more indexes are possible to be specified +* cyclic - 0 = non-cyclic mode, 1 = cyclic mode + +Optional arguments: + +* buffer_size - size of the output buffer; default value is 256 +* format - csv/binary. The way the samples will be read. Default type is csv + +Examples: + +Generate a cyclic signal for the given channels based on the samples located in file.csv + +.. shell:: + + $m2kcli digital auto -9 channel=0,1,4,5,14 cyclic=1 < file.csv + +-------------- + +**get** + +Return the value of the global attributes. + +Attributes: + +* sampling_frequency_in +* sampling_frequency_out +* trigger_delay +* trigger_mode + +Examples: + +Get all attributes + +.. shell:: + + $m2kcli digital auto -g all + +-------------- + +**get-channel** + +Return the value of the attributes corresponding the the given channels. + +Mandatory arguments: + +:: + + channel - one or more indexes are possible to be specified + +Attributes: + +* value +* output_mode +* trigger_condition + +Examples: + +Get all attributes for the given channels + +.. shell:: + + $m2kcli digital auto --get-channel channel=0,1,2,3,4 all + +-------------- + +**set** + +Set the value of the global attributes. + +Attributes: + +* sampling_frequency_in - double +* sampling_frequency_out - double +* trigger_delay - integer +* trigger_mode - {or | and} + +Examples: + +Set the trigger mode to 'or' + +.. shell:: + + $m2kcli digital auto -s trigger_mode=or + +-------------- + +**set-channel** + +Set the value of the attributes corresponding to the given channels. + +Mandatory attributes: + +* channel - one or more indexes are possible to be specified + +Attributes: + +* value - {0 | 1} +* output_mode - {open_drain | push_pull} +* trigger_condition - {rising_edge | falling_edge | low_level | high_level | any_edge | no_trigger} + +Examples: + +Set for the 7th channel the triggering condition to rising edge + +.. shell:: + + $m2kcli digital auto -S channel=7 trigger_condition=rising_edge + +-------------- + +power-supply +------------ + +synopsis +~~~~~~~~ + +:: + + m2kcli power-supply + [-h | --help] + [-q | --quiet] + [-C | --calibrate] + [-c | --capture channel=...] + [-9 | --generate channel=,... value=] + +description +~~~~~~~~~~~ + +power-supply command controls the power supply. The available channels for power +supply are channel 0 and channel 1. + +Pinout: + +| □ □ □ ▤ □ □ □ □ □ □ □ □ □ □ □ +| □ □ □ ▥ □ □ □ □ □ □ □ □ □ □ □ + +Options: + +| **calibrate** +| Calibrate the ADC. + +| **capture** +| Return the value, read by the power supply. The result is printed to standard + output. + +Mandatory arguments: + +* channel - one or both indexes are possible to be specified + +Examples: + +Get the voltage of both channels + +.. shell:: + + $m2kcli power-supply auto --capture channel=0,1 + +-------------- + +generate + +Generate the specified value for the given channels. + +Mandatory arguments: + +* channel - one or both indexes are possible to be specified +* value - double value, representing the voltage + +Examples: + +Generate 4V on both channels + +.. shell:: + + $m2kcli power-supply auto --generate channel=0,1 value=4 + +-------------- + +spi +--- + +synopsis +~~~~~~~~ + +:: + + m2kcli spi + [-h | --help] + [-i | --init [frequency= clk= mosi= [miso=] cs= mode= bit_numbering=] + [-w | --write data=,...] + +description +~~~~~~~~~~~ + +spi command communicates with an SPI device. + +Options: + +| **init** +| Initialize all channels used by the protocol to communicate. + +Mandatory arguments: + +* frequency - integer +* clk - index of any digital pin +* mosi - index of any digital pin +* cs - index of any digital pin +* mode - {0 | 1 | 2 | 3} +* bit_numbering - {MSB | LSB} + +Optional arguments: + +* miso - index of any digital pin; if miso is absent, write only mode will be activated + +-------------- + +**write** + +Write the given data and display back the read data. Before writing, the SPI +protocol must be initialized. + +Mandatory arguments: + +* data - list of bytes, comma separated values + +Examples: + +Electronics Lab 14 on our wiki page can be found +:dokuwiki:`here `. +Configure the connections for 'Unipolar output operation' mode: + +.. shell:: + + $m2kcli spi auto -i frequency=1000000 clk=1 mosi=2 miso=7 bit_numbering=MSB \ + $ cs=0 mode=3 -w data=0x09,0xC4 + +-------------- + +i2c +--- + +synopsis +~~~~~~~~ + +:: + + m2kcli i2c + [-h | --help] + [-i | --init frequency= address= scl= sda= [write_only=]] + [-w | --write data=,... option= [write_only=]] + [-r | --read bytes_number= option=] + +description +~~~~~~~~~~~ + +i2c command communicates with an I²C device. + +Options: + +| **init** +| Initialize all channels used by the protocol to communicate. + +Mandatory arguments: + +* frequency - integer +* address - 7/10 bit address +* scl - index of any digital pin +* sda - index of any digital pin + +Optional arguments: + +* write_only - In normal mode, i2c command tries to acknowledge the message, by + checking the ACK/NACK bits. In this case any other front-end cannot be used + for processing the output message. So the purpose of write_only argument is + to provide the possibility of combining m2kcli write mode with other front-end, + for example sigrok-cli, that can decode the message. + + * write_only=0: disable write only mode + * write_only=1: enable write only mode + * default value: 0 + +-------------- + +**write** + +Write the given data. Before writing, the I²C protocol must be initialized. + +Mandatory arguments: + +* data - list of bytes, comma separated values +* option - 3-bit number; only one addressing bit must be set; repeated start is optional + + * bit 0 - 7-bit addressing + * bit 1 - repeated start + * bit 2 - 10-bit addressing + +-------------- + +**read** + +Read a given number of bytes. Before reading, the I²C protocol must be +initialized. + +Mandatory arguments: + +* bytes_number - integer +* option - 3-bit number; only one addressing bit must be set; repeated start is optional + + * bit 0 - 7-bit addressing + * bit 1 - repeated start + * bit 2 - 10-bit addressing + +Examples: + +This example uses EVAL-ADT7420-PMDZ as a slave. Hardware configuration: + +* (ADALM2000) DIO_0 <--> Pin 1 (ADT7420) <--> 10 kilohms resistor <- V+ (ADALM2000) +* (ADALM2000) DIO_1 <--> Pin 3 (ADT7420) <--> 10 kilohms resistor <- V+ (ADALM2000) +* (ADALM2000) GND <--> Pin 5 (ADT7420) +* (ADALM2000) V+ -> Pin 7 (ADT7420) + +.. shell:: + + $m2kcli i2c ip:192.168.2.1 -i frequency=100000 address=0x48 scl=0 sda=1 -w data=0x0B option=3 + $m2kcli i2c ip:192.168.2.1 -i frequency=100000 address=0x48 scl=0 sda=1 -r bytes_number=1 option=1 + $m2kcli i2c ip:192.168.2.1 -i frequency=100000 address=0x48 scl=0 sda=1 -w data=0 option=3 + $m2kcli i2c ip:192.168.2.1 -i frequency=100000 address=0x48 scl=0 sda=1 -r bytes_number=2 option=1 + +-------------- + +uart +---- + +synopsis +~~~~~~~~ + +:: + + m2kcli uart + [-h | --help] + [-i | --init device= baud_rate= parity= bits_number= stop_bits=] + [-w | --write data=,...] + [-r | --read bytes_number= format=] + +description +~~~~~~~~~~~ + +uart command communicates with an UART device. + +Options: + +| **init** +| Initialize all channels used by the protocol to communicate. + +Mandatory arguments: + +* device - index of any digital pin +* baud_rate - integer +* parity - {none | odd | even | mark | space} +* bits_number - {5 | 6 | 7 | 8} +* stop_bits - {1 | 1.5 | 2} + +-------------- + +**write** + +Write the given data. Before writing, the UART protocol must be initialized. + +Mandatory arguments: + +* data - list of bytes, comma separated values + +-------------- + +**read** + +Read a given number of bytes. Before reading, the UART protocol must be +initialized. + +Mandatory arguments: + +* bytes_number - integer +* format - {text | number}; default type text + +Examples: + +Replicate the example found :dokuwiki:`here ` + +First terminal + +.. shell:: + + $m2kcli uart ip:192.168.2.1 -i device=1 baud_rate=9600 parity=none \ + $ bits_number=8 stop_bits=1 -r bytes_number=3 format=text + +Second terminal + +.. shell:: + + $m2kcli uart ip:192.168.2.1 -i device=0 baud_rate=9600 parity=none \ + $ bits_number=8 stop_bits=1 -w data=ADI + +-------------- + +uart-terminal +------------- + +synopsis +~~~~~~~~ + +:: + + m2kcli uart-terminal + [-h | --help] + [-i | --init rx= tx= baud_rate= parity= bits_number= stop_bits=] + +description +~~~~~~~~~~~ + +uart-terminal command continuously communicates with an UART device, simulating +a terminal. + +Options: + +| **init** +| Initialize the UART communication. + +Mandatory arguments: + +* rx - index of any digital pin +* tx - index of any digital pin +* baud_rate - integer +* parity - {none | odd | even | mark | space} +* bits_number - {5 | 6 | 7 | 8} +* stop_bits - {1 | 1.5 | 2} + +Examples: + +Connect ADALM-2000 to an UART device + +.. shell:: + + $m2kcli uart-terminal auto -i baud_rate=115200 rx=15 tx=7 stop_bits=1 \ + $ parity=none bits_number=8 + +-------------- + +USB to Serial UART adapter script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The script can be found +:git-libm2k:`here `. + +It creates an UART-Terminal using an ADALM2000 board and connects it to a +`PTY `__ (pseudoterminal interfaces). This +enables connection to a Serial Terminal Emulator (like GTKTerm, Picocom, +Minicom, Tera Term). + +To use the script, run it in a terminal and keep it running, after that, from +another terminal connect to the PTY using a terminal emulator and the settings +displayed on screen. When you want to close the connection just press ENTER +inside the terminal from where the script was ran. + +Example of usage, connect a Raspberry Pi to PC using a M2K board: + +First terminal + +.. shell:: + + $./m2k_tty.sh + M2K configurations: + URI: ip:192.168.2.1 + RX pin: 7 + TX pin: 15 + Sample details for UART: + Baud rate: 115200 + Number of data bits: 8 + Parity: none + Stop bits: 1 + Checking uart-terminal... + + m2kcli uart-terminal: 43847 is running + Done, connect to **/dev/pts/3** to access the uart terminal + + Press any key to close the connection + +In a second terminal connect using a terminal emulator to the previous displayed +path and the corresponding UART settings. + +Second terminal + +.. shell:: + + $picocom -b 115200 -r -l /dev/pts/3 + + port is : /dev/pts/3 + flowcontrol : none + baudrate is : 115200 + parity is : none + databits are : 8 + stopbits are : 1 + + Terminal ready + + Raspbian GNU/Linux 10 analog ttyS0 + + analog login: + analog login: root + Last login: Fri Sep 2 17:17:21 BST 2022 on ttyS0 + Linux analog 5.10.63-v7l+ #2 SMP Fri Jun 24 15:44:30 EEST 2022 armv7l + + root@analog:~# + +And the connection will stay active as long as the first terminal will stay +active. To close the connection, just press a key inside the first terminal. + +:: + + m2kcli uart-terminal: 43847 is running + Done, connect to /dev/pts/3 to access the uart terminal + + Press any key to close the connection + + -Killed m2kcli uart-terminal + -Killed socat + --Connection closed + +Requirements: + +- `socat `__ +- :ref:`libiio ` +- libm2k with :ref:`m2kcli ` + +It uses the socat command to create two connected +`PTYs `__ and using the m2kcli uart-terminal +command makes the connection between a PTY and our UART-Terminal. After all of +that is done, the user can connect to the other PTY using a Serial Port Terminal +Emulator (like GTKTerm, Picocom, Minicom, Tera Term). + +-------------- + +m2kcli and sigrok-cli +===================== + +Sigrok is a portable, cross-platform, free open source signal analysis software. +sigrok-cli is a command-line frontend for sigrok. A a much wider documentation +about sigrok-cli can be found on this wiki +`page `__. + +sigrok-cli can be used for decoding digital signals. m2kcli does not have the +functionality of continuously decoding SPI or I²C signals. Using sigrok-cli for +decoding the data and m2kcli for capturing the data, we can simulate this +functionality. + +**How to get sigrok-cli?** + +Sigrok offers two main possibilities of getting the cli. Building from source or +downloading the packages. All the steps are well described on their wiki page. +For building sigrok-cli have a look at this +`page `__, while for downloading the binaries +and the distribution packages have a +look\ `here `__. + +**Example:** + +In the following example ADALM-2000 is connected to an I²C device and we are +using a Linux AppImage binary for sigrok-cli. + +.. shell:: + + $m2kcli digital auto -s sampling_frequency_in=1000000 + $m2kcli digital auto -c buffer_size=1000 format=binary | \ + $ sigrok-cli -i - -I binary:numchannels=16:samplerate=1mhz -P \ + $ i2c:scl=15:sda=7 -A i2c=address-read:address-write:data-read:data-write diff --git a/docs/tools/index.rst b/docs/tools/index.rst new file mode 100644 index 00000000..af562c08 --- /dev/null +++ b/docs/tools/index.rst @@ -0,0 +1,12 @@ +:orphan: + +Tools +===== + +.. toctree:: + :caption: Tools + :maxdepth: 2 + :glob: + + */index + diff --git a/docs/tools/m2k/adalm2000.jpg b/docs/tools/m2k/adalm2000.jpg new file mode 100644 index 00000000..9faef9ef --- /dev/null +++ b/docs/tools/m2k/adalm2000.jpg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cecd5c4d5b7c2eeeba707f24366061c21fcbab6c47e7e5513871cdef338e7331 +size 110605 diff --git a/docs/tools/m2k/devs/index.rst b/docs/tools/m2k/devs/index.rst new file mode 100644 index 00000000..253e5eaf --- /dev/null +++ b/docs/tools/m2k/devs/index.rst @@ -0,0 +1,62 @@ +.. _m2k devs: + +For Developers +============== + +The people who typical read these pages are those who write custom software or +HDL (for the FPGA) that run directly on the M2K device. This may put the M2K in +different modes, and support different external USB devices (including USB/LAB, +or USB/WiFi), extending the capabilities of the device, or completely changing +the data that is transferred to the host. Since the goal of the project is to +keep things as open as possible, the details on how to compile kernels, create +bit files, assemble FIT files and load them into the device, should be found +here. + +While we do have a few examples, and show how to re-create the default software +loads, since this the hardware can be nearly a blank slate for your project, you +can do anything you want. + +Content +------- + +.. + TODO Coming soon sections + Make sure all things are in ./devs + +#. Introduction *(Coming soon)* +#. Hardware + + #. Detailed Specifications *(Coming soon)* + #. :dokuwiki:`Schematics ` + #. Detailed Performance *(Coming soon)* + #. Accessing the Console\ *(Coming soon)* with the + :dokuwiki:`ADALM-JTAGUART ` adapter + #. Accessing FPGA JTAG\ *(Coming soon)* with the + :dokuwiki:`ADALM-JTAGUART ` adapter + +#. :external+hdl:doc:`index` + + #. :external+hdl:ref:`m2k` + #. :external+hdl:ref:`axi_ad9963` + #. :external+hdl:ref:`axi_adc_decimate` + #. :external+hdl:ref:`axi_dac_interpolate` + #. :external+hdl:ref:`axi_logic_analyzer` + #. :external+hdl:ref:`axi_adc_trigger` + #. :external+hdl:ref:`util_var_fifo` + #. :external+hdl:ref:`util_extract` + +#. Device Drivers + + #. :dokuwiki:`AXI ADC HDL Linux Driver ` + #. :dokuwiki:`AXI DAC HDL Linux Driver ` + #. AXI DMAC Linux Driver + #. etc. + +#. Building the Firmware image from source + + #. :ref:`pluto-m2k obtaining_the_sources` + #. :ref:`pluto-m2k building_the_image` + +#. :ref:`pluto-m2k usb_otg_host` +#. :ref:`pluto-m2k firmware dfu_update` +#. :ref:`pluto-m2k reboot` diff --git a/docs/tools/m2k/help_support.rst b/docs/tools/m2k/help_support.rst new file mode 100644 index 00000000..358d2626 --- /dev/null +++ b/docs/tools/m2k/help_support.rst @@ -0,0 +1,78 @@ +.. _m2k help_support: + +Support +======= + +If you have any questions regarding the ADALM2000 (M2k) or are experiencing any +problems following the user guides, or experiments feel free to ask us a +question. Questions can be asked on our :ez:`EngineerZone support community `, +specifically the :ez:`Virtual Classroom adieducation/university-program>`. +Calling on the phone, emailing someone directly, will only cause things to get +answered in much slower manner - if at all. + +Before asking questions please also take the time to check if somebody else +already asked the same question and already got an answer. EngineerZone is a big +place, with lots of places to post questions, and it's possible to ask a +question in the wrong place, where no one familiar with these +boards/parts/software monitors things, and it will go unanswered forever. Don't +get mad if this happens. The problem is between the chair and the keyboard +(you). If you are posting in the right place, and the question is unanswered for +a few working days, please bump the thread (we are human, and sometimes miss +things). + +ADALM2000 or Scopy Questions +---------------------------- + +End user/Student questions should always be posted in the +:ez:`Virtual Classroom `. +If you are not sure where to post your question, post it there, and we can move +it around for you. + +Linux Driver or libiio or Application Questions +----------------------------------------------- + +For questions regarding the ADI Linux distribution used in the M2k (which is +based `buildroot `__ with +:ref:`libiio` library, the Linux +drivers (including the +:dokuwiki:`AD936x driver `, or +the device trees for M2k, please use the :ez:`Linux Software Drivers ` sub-community. + +If you have generic userspace questions (*how do I use a standard linux tool*), +we should suggest to use your favorite `search tool `__ +to find that tool/utility/application support method (some use email, some use +web). If you think you have found a bug specific to ARM, please report this to +the package maintainers upstream. + +HDL / Vivado WebPack Questions +------------------------------ + +For questions regarding the M2k HDL design please ask them in the +:ez:`FPGA Reference Designs ` sub-community. If you have questions +about the Vivado HL WebPACK Edition, including any questions about compiling the +design with please go ask `Xilinx `__. + +Hardware Questions +------------------ + +For questions regarding the M2k hardware (schematic or layout) please ask them +in the :ez:`Virtual Classroom `. +sub-community. That is where the folks who designed and laid out the PCB hang +out. + +Bugs / Feature Requests +----------------------- + +If you think you have a bug to report, the best place to to this is the +:ez:`Virtual Classroom `. This way we can discuss if +the bug is a bug, or a feature request, or just missing documentation. + +If you think you have a real bug, where you have developed a real fix (first - +thanks), feel free to: + +#. post something on engineerzone +#. post something on the GitHub issue tracker +#. `Fork `__ the GitHub + repository, and fix it, and then send a pull request + +Either is OK with us. diff --git a/docs/tools/m2k/index.rst b/docs/tools/m2k/index.rst new file mode 100644 index 00000000..fd38ab52 --- /dev/null +++ b/docs/tools/m2k/index.rst @@ -0,0 +1,85 @@ +.. _m2k: + +ADALM2000 +========= + +.. toctree:: + :hidden: + :glob: + + */index + * + +The :adi:`ADALM2000` (M2K) Active Learning Module is an affordable +USB-powered data acquisition module that takes the capabilities of the +:adi:`ADALM1000` (M1K) Active Learning Module to the next level. +With 12-bit ADCs (at 100MSPS) and DACs (at 150MSPS), the ADALM2000 with the +:dokuwiki:`Scopy ` software, brings the power of high performance lab +equipment to the palm of your hand, enabling electrical engineering students and +hobbyists to explore signals and systems into the tens of MHz without the cost +and bulk associated with traditional lab gear. The ADALM2000, when coupled with +Analog Devices' :external+scopy:doc:`Scopy ` graphical application +software running on a computer, provides the user with the following high +performance instrumentation: + +- Two-channel oscilloscope with differential inputs +- Two-channel arbitrary function generator +- 16-channel digital logic analyzer (3.3V CMOS and 1.8V or 5V tolerant, + 100MS/s) +- 16-channel pattern generator (3.3V CMOS, 100MS/s) +- 16-channel virtual digital I/O +- Two input/output digital trigger signals for linking multiple instruments + (3.3V CMOS) +- Two-channel voltmeter (AC, DC, ±25V) +- Network analyzer – Bode, Nyquist, Nichols transfer diagrams of a circuit. + Range: 1Hz to 10MHz +- Spectrum Analyzer – power spectrum and spectral measurements (noise floor, + SFDR, SNR, THD, etc.) +- Digital Bus Analyzers (SPI, I²C, UART, Parallel) +- Two programmable power supplies (0…+5V , 0…-5V) + +Introduction +------------ + +ADALM2000 is a portable lab. It's more than the combinations of a few parts, but +to understand the capabilities of the unit, you must understand the fundamental +operation of each part inside the unit. Depending on who you are, and what you +want to do, you may have different needs, and different wants. It's expected +that many people will stop when they solve their immediate problem and don't +want to go any deeper into the stack. There are 3 main categories of users: + +#. :ref:`ADALM2000 Users & Students `: + + - ADALM2000 users normally interact with real world analog signals using + :external+scopy:doc:`Scopy ` or + :dokuwiki:`Alice ` + - Everyone should read this section, as it describes the device, and + describes how to get the drivers and host software installed properly. + +#. ADALM2000 Application Developers: + + - Want to write their application interface for the ADALM2000 to run on the + PC, but do not need to modify the ADALM2000 firmware or need to know the + details on the ADALM2000's inner workings + - Use :dokuwiki:`scopy's scripting ability `. + Write scripts in javascript and then call scopy via the command line. + - Use :ref:`libm2k` to write + C++/C#/Python applications that capture and generate data from the host + PC. + +#. :ref:`ADALM2000 Firmware Developers `: + + - normally write custom software or HDL (for the FPGA) that run directly on + the ADALM2000 device. This may put the ADALM2000 in different modes, and + support different external USB devices (including LAN (via USB), or WiFi + (vs USB)), extending the capabilities of the device. This includes all the + information to compile HDL projects, compile kernels, change to custom USB + PID/VID and/or run custom user space applications. + +It's expected that most people will work their way down through each section, +reading and skimming most of the content. The content is in a constant state of +improvement, so if you do have a question, please ask at +:ez:`EngineerZone `, +or check the :ref:`help and support ` page. + +.. esd-warning:: diff --git a/docs/tools/m2k/install-vipackage.png b/docs/tools/m2k/install-vipackage.png new file mode 100644 index 00000000..7a414804 --- /dev/null +++ b/docs/tools/m2k/install-vipackage.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9c0806ec02fce8d565dd532af2d4f361776f11f4f8d344d52ff8bf7c7fd7ae99 +size 55281 diff --git a/docs/tools/m2k/labview.rst b/docs/tools/m2k/labview.rst new file mode 100644 index 00000000..9e70bb11 --- /dev/null +++ b/docs/tools/m2k/labview.rst @@ -0,0 +1,97 @@ +.. _m2k labview: + +Using With LabVIEW +"""""""""""""""""" + +The ADALM2000 (M2K) can be controlled in LabVIEW. Controlling M2K is provided +through a set of bindings for libm2k. + +The C++ API reference is available on +`here `__. + +The LabVIEW VI documentation is available on +`here `__. + +Releases +======== + +Always use the latest release VI Package from the +:git-libm2k-labview:`releases/latest+`. + +Installing +========== + +The first step is to install libm2k using the Windows system installer. Go to +:git-libm2k:`libm2k release page ` or use +the `nightly builds `__. + +The LabVIEW wrapper is available only starting from official version v0.4.0. + +In the libm2k system installer, check the "Install wrapper for LabVIEW bindings" +box. The base library and the wrapper will be installed in your system. + +Download the latest ADALM2000 VI Package from the Release section on the +following page: +:git-libm2k-labview:`ADALM2000 LabVIEW repository `. +Load the VIP package in the VI Package Manager, install the package. +After that, there will be a new palette, named Analog Devices -> ADALM2000, +in LabVIEW. + +Windows Support +--------------- + +After checking the "Install wrapper for LabVIEW bindings" box, the system +installer will install libm2k.dll and libm2k_lv.dll in your Windows system. +If libm2k_lv does not appear in the system path, the LabVIEW bindings will +not find the exposed methods and will not work. + +In the VI Package Manager, you should load the .vip package and then install +it. + +.. image:: install-vipackage.png + +.. note:: + + The VI Package was tested on version 2015 and 2020 of LabVIEW on + Windows. + +.. note:: + + As this is still under development, bugs might arise. + +.. note:: + + Not every libm2k method is supported yet, but may be added + in the future. + +Support +======= + +For support questions please post them on EngineerZone under the +:ez:`Virtual Classroom Forum `. + +If you find any bugs please report them on the +:git-libm2k:`libm2k issues tracker `. + +Examples and LabVIEW palette +============================ + +The ADALM2000 palette can be found under the "Analog Devices" category. + +.. image:: pallette-preview.png + +This contains the following subpalettes: + +- **AnalogIn** - VIs for ADC control +- **AnalogOut** - VIs for DAC control +- **Digital** - VIs for the Digital pins control +- **Power Supply** - Vis for the ADALM2000 power supplies +- **Examples** - A few examples on how the VIs can be used. + +And the following VIs: + +- **Close.vi** - Will destroy the currently open libm2k context +- **Instrument Handler.vi** - Will create a libm2k context +- **Search ADALM2000.vi** - Will search the currently available ADALM2000 and + return a list of URIs. + diff --git a/docs/tools/m2k/matlab.rst b/docs/tools/m2k/matlab.rst new file mode 100644 index 00000000..001d2365 --- /dev/null +++ b/docs/tools/m2k/matlab.rst @@ -0,0 +1,264 @@ +.. _m2k matlab: + +Using with MATLAB +================= + +The :adi:`ADALM2000` (M2K) can be controlled programmatically in a number of +languages, including MATLAB. Controlling M2K and access the data streams is +provided through a set of bindings for libm2k. If you are already familiar with +libm2k, moving into MATLAB is minimal work. If you are unfamiliar, there is +extensive `libm2k API documentation available `__. + +Quick Start +----------- + +To get started with libm2k+MATLAB there are integrated installers available for +:mw:`Windows and Linux `. +Simply download the MLTBX file and open it within MATLAB. This will install the +necessary libraries and classes to interface with M2K. The installer packages +the dependent libraries libiio, libm2k, and the MATLAB bindings so they do not +need to be installed externally. +The only requirement is the +:ref:`M2K driver `. +For manual build see :ref:`m2k matlab build`. + +After installation of the driver and the MLTBX file, you will have access to the +bindings through +:mw:`MATLAB's clib interface for C++ libraries `. +For libm2k this +will be in the form: + +:: + + clib.libm2k.libm2k. + +.. important:: + + Note that not every libm2k method is supported due to MATLAB + limitations but these methods are usually uncommon. + +This is a common API styling MATLAB uses for external languages or even internal +components that are Java-like or class-like. Below is a simple example of how to +call into the library and construct an M2K object, then call into the API from +that object. + +.. code:: matlab + + %{ + This example reads the analog voltage from channel 0 of the analog input + %} + %% Setup + m2k = clib.libm2k.libm2k.context.m2kOpen(); + + %% Setup analog in + ain = m2k.getAnalogIn(); + ain.enableChannel(0,true); + voltage = ain.getVoltage(0); + disp(voltage); + + %% Get more data + d3 = ain.getSamplesInterleaved(1024); + plot(d3) + + %% Cleanup + clib.libm2k.libm2k.context.contextCloseAll(); + clear m2k + +More examples are :git-libm2k-matlab:`available on GitHub `. + +Inspecting the API +------------------ + +The MATLAB bindings follow the `C++ API `__. +Since MATLAB has an interpreter it can be very helpful when exploring the API. +This can be don through help or doc commands. +For example, if you want to understand the M2kAnalogIn method +getAvailableSampleRates you can query it directly. + +.. code:: matlab + + >> help clib.libm2k.libm2k.analog.M2kAnalogIn.getAvailableSampleRates + clib.libm2k.libm2k.analog.M2kAnalogIn/getAvailableSampleRates + Method of C++ class libm2k::analog::M2kAnalogIn.getAvailableSampleRates + + This content is from the external library documentation. + + Inputs + obj read-only clib.libm2k.libm2k.analog.M2kAnalogIn + + Outputs + RetVal clib.array.libm2k.Double + The list of available samplerates for this device + +This can be done through the class definitions or even created objects: + +.. code:: matlab + + >> m2k = clib.libm2k.libm2k.context.m2kOpen() + + m2k = + + M2k with no properties. + + >> help m2k + --- help for clib.libm2k.libm2k.context.M2k --- + + clib.libm2k.libm2k.context.M2k Representation of C++ class libm2k::context::M2k. + Contains the representation of the M2k + + @class M2k + @brief Controls the ADALM2000 + + This content is from the external library documentation. + + @defgroup m2k M2k + @brief Contains the representation of the M2k + + @class M2k + @brief Controls the ADALM2000 + + Documentation for clib.libm2k.libm2k.context.M2k + +.. _m2k matlab build: + +Manual Build +------------ + +You require two main dependencies which have build/install instructions (make +sure you are using compatible versions): + +- :ref:`libiio` +- :ref:`libm2k` + +Once these are built and installed the MATLAB bindings can be built. To do this +follow these steps: + +Inside libm2k repo go to */bindings/matlab* + +Next, update the locations of the +:git-libm2k:`libm2k headers ` +to point to where libm2k is build. On Ubuntu these may look similar to: + +.. code:: matlab + + includepath = fullfile('/usr','local','include'); + hppPath = fullfile('/usr','local','include','libm2k'); + libs = '/usr/local/lib/libm2k.so'; + +Next uncomment the following code section: + +.. code:: matlab + + clibgen.generateLibraryDefinition(headers,... + 'IncludePath', includepath,... + 'Libraries', libs,... + 'PackageName', myPkg,... + 'Verbose',true,... + 'DefinedMacros', ["_HAS_CONDITIONAL_EXPLICIT=0"]) + delete definelibm2k.mlx + +This part should be commented at this point : + +.. code:: matlab + + % pkg = definelibm2k_linux64; + % build(pkg); + +Make sure "definelibm2k.m" does not exist. If exists remove it. + +Run "build_library_linux64.m" (on Linux) or "build_library_win64.m" (on Windows) + +Inside "definelibm2k.m" you will get an error for a "inputoutput" value replace +it with "input" + +Inside "definelibm2k.m" uncomment all functions that you need and replace +"" with the right value Before : + +.. code:: matlab + + %% C++ class method |m2kOpen| for C++ class |libm2k::context::ContextBuilder| + % C++ Signature: static libm2k::context::M2k * libm2k::context::ContextBuilder::m2kOpen() + %m2kOpenDefinition = addMethod(ContextBuilderDefinition, ... + % "static libm2k::context::M2k * libm2k::context::ContextBuilder::m2kOpen()", ... + % "MATLABName", "m2kOpen", ... + % "Description", "m2kOpen Method of C++ class libm2k::context::ContextBuilder.", ... + % "DetailedDescription", "This content is from the external library documentation." + newline + ... + % "" + newline + ... + % "@private"); % Modify help description values as needed. + %defineOutput(m2kOpenDefinition, "RetVal", "clib.libm2k.libm2k.context.M2k", ); + %validate(m2kOpenDefinition); + +After: + +.. code:: matlab + + %% C++ class method |m2kOpen| for C++ class |libm2k::context::ContextBuilder| + % C++ Signature: static libm2k::context::M2k * libm2k::context::ContextBuilder::m2kOpen() + m2kOpenDefinition = addMethod(ContextBuilderDefinition, ... + "static libm2k::context::M2k * libm2k::context::ContextBuilder::m2kOpen()", ... + "MATLABName", "m2kOpen", ... + "Description", "m2kOpen Method of C++ class libm2k::context::ContextBuilder.", ... + "DetailedDescription", "This content is from the external library documentation." + newline + ... + "" + newline + ... + "@private"); % Modify help description values as needed. + defineOutput(m2kOpenDefinition, "RetVal", "clib.libm2k.libm2k.context.M2k", 1); + validate(m2kOpenDefinition); + +Replace the content from "definelibm2k_linux64.m" (on Linux) or the content from +"definelibm2k_win64.m" (on Windows) with the content from "definelibm2k.m" + +Comment the following code section: + +.. code:: matlab + + clibgen.generateLibraryDefinition(headers,... + 'IncludePath', includepath,... + 'Libraries', libs,... + 'PackageName', myPkg,... + 'Verbose',true,... + 'DefinedMacros', ["_HAS_CONDITIONAL_EXPLICIT=0"]) + delete definelibm2k.mlx + +If on Linux uncomment: + +.. code:: matlab + + pkg = definelibm2k_win64; + build(pkg); + +If on Windows uncomment: + +.. code:: matlab + + pkg = definelibm2k_linux64; + build(pkg); + +Run "build_library_linux64.m" ( on Linux ) or "build_library_win64.m" ( on +Windows ) + +.. code:: matlab + + >> builder + Using g++ compiler. + Generated definition file definelibm2k.mlx and data file 'libm2kData.xml' + contain definitions for 344 constructs supported by MATLAB. + 49 construct(s) require(s) additional definition. To include these + construct(s) in the interface, edit the definitions in definelibm2k.mlx. + Build using build(definelibm2k). + ... + ... + Building interface file 'libm2kInterface.so'. + Interface file 'libm2kInterface.so' built in folder '/tmp/libm2k-matlab/libm2k'. + To use the library, add the interface file folder to the MATLAB path. + +This will create a library named libm2kInterface.so in the libm2k folder. Simply +adding that folder to path will allow you to use the bindings. + +Support +------- + +For support questions please post them on EngineerZone under the +:ez:`Virtual Classroom Forum `. + +If you find any bugs please report them on the +:git-libm2k:`libm2k issues tracker on GitHub `. diff --git a/docs/tools/m2k/pallette-preview.png b/docs/tools/m2k/pallette-preview.png new file mode 100644 index 00000000..f8be3fcb --- /dev/null +++ b/docs/tools/m2k/pallette-preview.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:444260ea8f273176c7d622c3ed43c0dcbc1232962f1fba243c92ef58dad6b32f +size 19205 diff --git a/docs/tools/m2k/users/index.rst b/docs/tools/m2k/users/index.rst new file mode 100644 index 00000000..7440d446 --- /dev/null +++ b/docs/tools/m2k/users/index.rst @@ -0,0 +1,75 @@ +.. _m2k users: + +For End Users +============= + +.. image:: ../adalm2000.jpg + :align: right + :width: 400px + +Contents +-------- + +.. + TODO pluto customizing to pluto-m2k + Make sure all things are in ./users + +#. :dokuwiki:`Introduction to the Hardware ` + + #. :dokuwiki:`What's with the name? ` *ADALM2000?* + #. :dokuwiki:`Understanding the Internals ` + +#. :dokuwiki:`Quick Start ` +#. Intro to the Software. Installing Device Drivers on: + + #. :dokuwiki:`Windows ` + #. :dokuwiki:`Linux ` + #. :dokuwiki:`MAC ` + +#. Upgrading the the ADALM2000 :ref:`Firmware `. +#. Common customization: + + #. :dokuwiki:`/university/tools/pluto/users/customizing#multiple_devices>` + #. :dokuwiki:`/university/tools/pluto/users/customizing#changing_the_root_password_on_the_target>` + #. :dokuwiki:`/university/tools/pluto/users/customizing#enabling_persistent_ssh_keys>` + #. :dokuwiki:`/university/tools/pluto/users/customizing#changing_the_usb_ethernet_compatibility_mode>` + +#. Once the driver are configured and set up, you can interact with the + :adi:`ADALM2000` Active Learning Module from: + + #. :external+scopy:doc:`Scopy `, intrument guides: + + #. :external+scopy:ref:`oscilloscope` + #. :external+scopy:ref:`spectrum_analyzer` + #. :external+scopy:ref:`network_analyzer` + #. :external+scopy:ref:`signal_generator` + #. :external+scopy:ref:`logic_analyzer` + #. :external+scopy:ref:`pattern_generator` + #. :external+scopy:ref:`digitalio` + #. :external+scopy:ref:`voltmeter` + #. :external+scopy:ref:`power_supply` + + #. :dokuwiki:`ALICE Active Learning Interface (for) Circuits (and) Electronics for M2K: ` + #. :ref:`MATLAB with libm2k ` + +#. After everything is up and running, you can start building your own circuits + using the following kit: + + - :dokuwiki:`ADALP2000 Product Description ` + +#. A list of applications and lab activities developed with + :adi:`ADALM2000` can found here: + + - :dokuwiki:`ADALM2000 Based Lab Activity Material, Electronics I and II ` + +Videos +------ + +To make the whole experience easier and more enjoyable, we created a series of +videos, which provide a detailed description of the module and how to operate +it. `Check out the whole series `__ +or take a look at the first video of the series right here. + +.. video:: https://www.youtube.com/watch?v=LCf-_iREESQ + + ADALM2000 Video Series: Video 1 — Unboxing diff --git a/docs/tools/m2k/windows-eject.png b/docs/tools/m2k/windows-eject.png new file mode 100644 index 00000000..6533b869 --- /dev/null +++ b/docs/tools/m2k/windows-eject.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3e8a3d9e401d4cdd448238987324adc7c804b6f80963b5786e050d7044d12738 +size 277758 diff --git a/docs/tools/pluto-m2k/building_the_image.rst b/docs/tools/pluto-m2k/building_the_image.rst new file mode 100644 index 00000000..ac7037d0 --- /dev/null +++ b/docs/tools/pluto-m2k/building_the_image.rst @@ -0,0 +1,508 @@ +.. _pluto-m2k building_the_image: + +Building the Firmware Image +""""""""""""""""""""""""""" + +It is recommenced to use the pre-build images, which can be +found at :git-plutosdr-fw:`PlutoSDR Firmware releases `. +found at :git-m2k-fw:`M2k Firmware releases `. +These are build and tested by Analog Devices, and should work on your PlutoSDR +without issues. + +If you want to change functionality, you will need to follow +these instructions. To test your image, it is recommended to use the +:ref:`RAM Boot ` rather than +writing to flash the first time. This keep the default firmware while you are +testing your image, so if something goes wrong - its a quick power cycle to fix +things. + +Prerequisites +============= + +#. Make sure to download, or upgrade your + :ref:`Sources ` + + - Make sure you have the recommended/required Vivado versions. It's likely + listed in the *archive* section of the Xilinx web site. To check out what + you need, look at the following tcl file (which was checked out in the + sources link above). + + .. shell:: + + ~/github/temp/plutosdr-fw + $grep -i REQUIRED_VIVADO_VERSION $(find ./ -name "adi*.tcl") | grep set + set required_vivado_version "2021.1" + +#. You need :xilinx:`Xilinx Vivado Design Suite ` to + compile the Verilog into the FPGA bit file. +#. You need :xilinx:`Xilinx Vivado Vitis ` + to compile C code for the ARM inside the AMD Zynq. + + - If you are using very old versions of Xilinx tools, you need to make sure + that you have the 32-bit libraries (the Xilinx tools are distributed as + 32-bit binaries). + +.. shell:: + + ~/github/temp/plutosdr-fw + $find /opt/Xilinx/ -name vivado -executable -type f | xargs file | grep ELF + /opt/Xilinx/Vivado/2021.2/bin/unwrapped/lnx64.o/vivado: ELF 64-bit LSB executable, + x86-64, version 1 (GNU/Linux), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, + for GNU/Linux 2.6.18, not stripped + +If it reports as a 32-bit binary (which the above did not), and you are running +on a 64-bit system, do: + +.. shell:: + + ~/devel + $dpkg --add-architecture i386 + $apt-get update + $sudo apt-get install libc6:i386 libstdc++6:i386 + +There are a few other tools that are necessary in order to build your own +Firmware Image. + +.. shell:: + + ~/devel + $sudo apt-get install git build-essential ccache device-tree-compiler \ + $ dfu-util fakeroot help2man libncurses5-dev libssl1.0-dev mtools rsync \ + $ u-boot-tools bc python cpio zip unzip file wget + +Building +======== + +.. hint:: + + It is recommended that if you are building in a Virtual Machine + (which is totally fine), the Base Memory be set to at least 4096 MBytes. The + AMD Xilinx :xilinx:`Vivado ` tools + require at least 1.6 Gig of memory when compile for the ``XC7Z010``. It has been + reported that 2048 Mbytes is not enough, and will cause the tools to hang. + +Starting the build process is just a matter of typing ``make`` within the +firmware repository. The Makefile requires a few environmental variables being +set, and of course the ARM GCC toolchain in the PATH. Some paths maybe adjusted +to match your Xilinx Vivado and Vitis install folders. + +.. shell:: + + ~/devel + $cd plutosdr-fw # or m2k-fw + $export CROSS_COMPILE=arm-linux-gnueabihf- + $export PATH=$PATH:/opt/Xilinx/Vitis/2021.2/gnu/aarch32/lin/gcc-arm-linux-gnueabi/bin + $export VIVADO_SETTINGS=/opt/Xilinx/Vivado/2021.2/settings64.sh + $make + +The initial build takes some time to complete, and also requires an INTERNET +connection, since `buildroot `__ downloads the source +packages from the WEB. + +.. hint:: + + Depending on your distribution, you may need to force Vivado to use + Gtk2. You can do that by adding: + + .. shell:: + + ~/devel/plutosdr-fw + $export SWT_GTK3=0 + +before you type ``make``. + +Build Artifacts +--------------- + +.. shell:: + + ~/devel/plutosdr-fw + $ls -AGhl build + total 52M + -rw-rw-r-- 1 michael 69 Apr 19 17:45 boot.bif + -rw-rw-r-- 1 michael 446K Apr 19 17:45 boot.bin + -rw-rw-r-- 1 michael 446K Apr 19 17:45 boot.dfu + -rw-rw-r-- 1 michael 575K Apr 19 17:45 boot.frm + -rw-rw-r-- 1 michael 8,3M Apr 19 17:45 pluto.dfu + -rw-rw-r-- 1 michael 8,3M Apr 19 17:45 pluto.frm + -rw-rw-r-- 1 michael 33 Apr 19 17:45 pluto.frm.md5 + -rw-rw-r-- 1 michael 8,3M Apr 19 17:45 pluto.itb + -rw-rw-r-- 1 michael 16M Apr 19 17:45 plutosdr-fw-v0.20.zip + -rw-rw-r-- 1 michael 471K Apr 19 17:45 plutosdr-jtag-bootstrap-v0.20.zip + -rw-r--r-- 1 michael 4,2M Apr 19 17:39 rootfs.cpio.gz + drwxrwxr-x 6 michael 4,0K Apr 19 17:45 sdk + -rw-rw-r-- 1 michael 940K Apr 19 17:45 system_top.bit + -rw-rw-r-- 1 michael 362K Apr 19 17:45 system_top.hdf + -rwxrwxr-x 1 michael 409K Apr 19 17:45 u-boot.elf + -rw-rw---- 1 michael 128K Apr 19 17:45 uboot-env.bin + -rw-rw---- 1 michael 129K Apr 19 17:45 uboot-env.dfu + -rw-rw-r-- 1 michael 4,6K Apr 19 17:45 uboot-env.txt + -rwxrwxr-x 1 michael 3,2M Apr 19 17:33 zImage + -rw-rw-r-- 1 michael 16K Apr 19 17:39 zynq-pluto-sdr.dtb + -rw-rw-r-- 1 michael 16K Apr 19 17:39 zynq-pluto-sdr-revb.dtb + +Testing on the target +--------------------- + +There is a script in the :git-plutosdr_scripts:`plutosdr_scripts <+>` repo +that will quickly download a build artifact (the ``pluto.dfu`` file) to an USB +attached PlutoSDR. This will load the image into RAM, and not write to flash, +enabling easy testing of images. However, since it is loading into RAM, it is +not a persistent update over power cycles or further reboots. + +.. shell:: + + ~/github/plutosdr-fw + $sudo ../plutosdr_scripts/pluto_ramboot + Found Pluto SDR at IP 192.168.3.1, running kernel: + Linux pluto 5.4.0-00535-g9c04de11ae53 #1 SMP PREEMPT Fri Aug 20 13:01:03 CEST 2021 armv7l GNU/Linux + Found Pluto SDR in dfu mode and downloading ./build/pluto.dfu + successfully downloaded + Found new PlutoSDR at 192.168.3.1, running kernel: + Linux pluto 5.4.0-00535-g9c04de11ae53 #1 SMP PREEMPT Tue Feb 15 16:17:50 EST 2022 armv7l GNU/Linux + +Main targets +------------ + +.. list-table:: + :header-rows: 1 + + - - File + - Comment + - - pluto.frm + - Main PlutoSDR firmware file used with the USB Mass Storage Device + - - pluto.dfu + - Main PlutoSDR firmware file used in DFU mode + - - boot.frm + - First and Second Stage Bootloader (u-boot + fsbl + uEnv) used with the + USB Mass Storage Device + - - boot.dfu + - First and Second Stage Bootloader (u-boot + fsbl) used in DFU mode + - - uboot-env.dfu + - u-boot default environment used in DFU mode + - - plutosdr-fw-vX.XX.zip + - ZIP archive containg all of the files above + - - plutosdr-jtag-bootstrap-vX.XX.zip + - ZIP archive containg u-boot and Vivao TCL used for JATG bootstrapping + +Other intermediate targets +-------------------------- + +.. list-table:: + :header-rows: 1 + + - - File + - Comment + - - boot.bif + - Boot Image Format file used to generate the Boot Image + - - boot.bin + - Final Boot Image + - - pluto.frm.md5 + - md5sum of the pluto.frm file + - - pluto.itb + - u-boot Flattened Image Tree + - - rootfs.cpio.gz + - The Root Filesystem archive + - - sdk + - Vivado/XSDK Build folder including the FSBL + - - system_top.bit + - FPGA Bitstream (from HDF) + - - system_top.hdf + - FPGA Hardware Description File exported by Vivado + - - u-boot.elf + - u-boot ELF Binary + - - uboot-env.bin + - u-boot default environment in binary format created form uboot-env.txt + - - uboot-env.txt + - u-boot default environment in human readable text format + - - zImage + - Compressed Linux Kernel Image + - - zynq-pluto-sdr.dtb + - Device Tree Blob for Rev.A + - - zynq-pluto-sdr-revb.dtb + - Device Tree Blob for Rev.B + +How does it work +---------------- + +.. warning:: + + All these steps are automatically handled by make. They are just + explained here, for those who are interested. + +Build Linux kernel +------------------ + +.. list-table:: + :header-rows: 1 + + - - Function + - File + - - PlutoSDR Linux Kernel Config + - :git-linux:`zynq_pluto_defconfig ` + +.. shell:: + :no-path: + + $make -C linux ARCH=arm zynq_pluto_defconfig + $make -C linux -j 8 \ + $ UIMAGE_LOADADDR=0x8000 \ + $ ARCH=arm CROSS_COMPILE=arm-xilinx-linux-gnueabi- \ + $ zImage + $cp linux/arch/arm/boot/zImage build/zImage + +Making custom kernel changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. attention:: + + Normal users should not need to change their kernel, and this is + only described for advanced users, or developers who periodically forget things + +The command + +.. shell:: + :no-path: + + $make -C linux ARCH=arm zynq_pluto_defconfig + +copies the file from ``arch/arm/configs/zynq_pluto_defconfig`` to ``.config`` +and + +.. shell:: + :no-path: + + $make -C linux -j 8 \ + $ ARCH=arm \ + $ CROSS_COMPILE=arm-xilinx-linux-gnueabi- \ + $ UIMAGE_LOADADDR=0x8000 \ + $ zImage + +builds it. + +If you want to make a custom kernel, the easiest thing to do, is modify the +``.config`` with + +.. shell:: + :no-path: + + $make -C linux ARCH=arm zynq_pluto_defconfig + $make -C linux ARCH=arm menuconfig + +and then make changes, save them, and then create the ``defconfig``. + +.. shell:: + :no-path: + + $make -C linux ARCH=arm savedefconfig + +Check your changes against the default image + +.. shell:: + :no-path: + + $diff -u ./linux/arch/arm/configs/zynq_pluto_defconfig linux/defconfig | less + +And if you are sure things are what you want, store them to the default file. + +.. shell:: + :no-path: + + $cp ./linux/defconfig ./linux/arch/arm/configs/zynq_pluto_defconfig + +then this will work next time you type ``make`` to build the firmware image. + +Build Devicetrees +----------------- + +.. list-table:: + :header-rows: 1 + + - - Function + - File + - - PlutoSDR Rev.A Device Tree + - :git-linux:`zynq-pluto-sdr.dts ` + - - PlutoSDR Rev.B Device Tree + - :git-linux:`zynq-pluto-sdr-revb.dts ` + +.. shell:: + :no-path: + + $make -C linux -j 8 ARCH=arm CROSS_COMPILE=arm-xilinx-linux-gnueabi- zynq-pluto-sdr.dtb + $cp linux/arch/arm/boot/dts/zynq-pluto-sdr.dtb build/zynq-pluto-sdr.dtb + $make -C linux -j 8 ARCH=arm CROSS_COMPILE=arm-xilinx-linux-gnueabi- zynq-pluto-sdr-revb.dtb + $cp linux/arch/arm/boot/dts/zynq-pluto-sdr-revb.dtb build/zynq-pluto-sdr-revb.dtb + +Build Buildroot User Space +-------------------------- + +.. list-table:: + :header-rows: 1 + + - - Function + - File + - - PlutoSDR Buildroot Config + - :git-buildroot:`zynq_pluto_defconfig ` + +.. shell:: + :no-path: + + $make -C buildroot ARCH=arm zynq_pluto_defconfig + $make -C buildroot TOOLCHAIN_EXTERNAL_INSTALL_DIR= \ + $ ARCH=arm CROSS_COMPILE=arm-xilinx-linux-gnueabi- \ + $ BUSYBOX_CONFIG_FILE=/home/michael/devel/pluto/plutosdr-fw/buildroot/board/pluto/busybox-1.25.0.config all + $cp buildroot/output/images/rootfs.cpio.gz build/rootfs.cpio.gz + +Configuring Buildroot +~~~~~~~~~~~~~~~~~~~~~ + +You need to copy over the correct file, to the ``.config``, edit it (with +``menuconfig``), and then save it to the right place so that the main build +system will use the new file. + +.. shell:: + :no-path: + + $make -C buildroot ARCH=arm zynq_pluto_defconfig + $make -C buildroot ARCH=arm menuconfig + $make -C buildroot ARCH=arm savedefconfig + $make + +Build FPGA Hardware Description File +------------------------------------ + +.. list-table:: + :header-rows: 1 + + - - Function + - File + - - Pluto HDL Project + - :git-hdl:`Files ` + +.. shell:: + :no-path: + + $source /opt/Xilinx/Vivado/2021.2/settings64.sh + $make -C hdl/projects/pluto + $cp hdl/projects/pluto/pluto.sdk/system_top.hdf build/system_top.hdf + +Build FPGA First Stage Bootloader (FSBL) +---------------------------------------- + +.. list-table:: + :header-rows: 1 + + - - Function + - File + - - Create FSBL TCL script + - :git-plutosdr-fw:`create_fsbl_project.tcl ` + +.. shell:: + :no-path: + + $source /opt/Xilinx/Vivado/2021.2/settings64.sh + $xsdk -batch -source scripts/create_fsbl_project.tcl + $cp build/sdk/hw_0/system_top.bit build/system_top.bit + +Build multi component FIT image (Flattened Image Tree) +------------------------------------------------------ + +.. list-table:: + :header-rows: 1 + + - - Function + - File + - - PlutoSDR Image Tree Source + - :git-plutosdr-fw:`pluto.its ` + +.. shell:: + :no-path: + + $u-boot-xlnx/tools/mkimage -f scripts/pluto.its build/pluto.itb + +Build Firmware DFU image +------------------------ + +.. shell:: + :no-path: + + $cp build/pluto.itb build/pluto.itb.tmp + $dfu-suffix -a build/pluto.itb.tmp -v 0x0456 -p 0xb673 + $mv build/pluto.itb.tmp build/pluto.dfu + +Build Firmware FRM image +------------------------ + +.. shell:: + :no-path: + + $md5sum build/pluto.itb | cut -d ' ' -f 1 > build/pluto.frm.md5 + $cat build/pluto.itb build/pluto.frm.md5 > build/pluto.frm + +Build u-boot +------------ + +.. list-table:: + :header-rows: 1 + + - - Function + - File + - - PlutoSDR u-boot Config + - :git-u-boot-xlnx:`zynq_pluto_defconfig ` + - - PlutoSDR u-boot Device Tree + - :git-u-boot-xlnx:`zynq-pluto-sdr.dts ` + +.. shell:: + :no-path: + + $make -C u-boot-xlnx ARCH=arm zynq_pluto_defconfig + $make -C u-boot-xlnx ARCH=arm CROSS_COMPILE=arm-xilinx-linux-gnueabi- UBOOTVERSION="PlutoSDR v0.20-PlutoSDR" + $cp u-boot-xlnx/u-boot build/u-boot.elf + +Build Zynq Boot Image +--------------------- + +.. shell:: + :no-path: + + $echo img:{[bootloader] build/sdk/fsbl/Release/fsbl.elf build/u-boot.elf } > build/boot.bif + $source /opt/Xilinx/Vivado/2021.2/settings64.sh + $bootgen -image build/boot.bif -w -o build/boot.bin + +Build Boot DFU Image +-------------------- + +.. shell:: + :no-path: + + $cp build/boot.bin build/boot.bin.tmp + $dfu-suffix -a build/boot.bin.tmp -v 0x0456 -p 0xb673 + $mv build/boot.bin.tmp build/boot.dfu + +Build u-boot default environment Image +-------------------------------------- + +.. shell:: + :no-path: + + $CROSS_COMPILE=arm-xilinx-linux-gnueabi- scripts/get_default_envs.sh > build/uboot-env.txt + $u-boot-xlnx/tools/mkenvimage -s 0x20000 -o build/uboot-env.bin build/uboot-env.txt + +Build u-boot default environment DFU Image +------------------------------------------ + +.. shell:: + :no-path: + + $cp build/uboot-env.bin build/uboot-env.bin.tmp + $dfu-suffix -a build/uboot-env.bin.tmp -v 0x0456 -p 0xb673 + $mv build/uboot-env.bin.tmp build/uboot-env.dfu + +Build Boot FRM image +-------------------- + +.. shell:: + :no-path: + + $cat build/boot.bin build/uboot-env.bin scripts/target_mtd_info.key | \ + $ tee build/boot.frm | md5sum | cut -d ' ' -f1 | tee -a build/boot.frm diff --git a/docs/tools/pluto-m2k/copyfirmware_osx2.png b/docs/tools/pluto-m2k/copyfirmware_osx2.png new file mode 100644 index 00000000..9ee9be81 --- /dev/null +++ b/docs/tools/pluto-m2k/copyfirmware_osx2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ddd4c829d04c672f7beec1c2b4fb6bf5b89b5a74272882b8665f6eb8d98c6944 +size 111668 diff --git a/docs/tools/pluto-m2k/device_manager_dfu.png b/docs/tools/pluto-m2k/device_manager_dfu.png new file mode 100644 index 00000000..1ed3979a --- /dev/null +++ b/docs/tools/pluto-m2k/device_manager_dfu.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5af0f46b9534552c4d347e4f154fe9575495213fd6eea7e7e68c99c57331a4e7 +size 34563 diff --git a/docs/tools/pluto-m2k/device_manager_installed.png b/docs/tools/pluto-m2k/device_manager_installed.png new file mode 100644 index 00000000..72cb4479 --- /dev/null +++ b/docs/tools/pluto-m2k/device_manager_installed.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a5efbbbeb0e83daaa8d2dae198aa68ca7f69726320c0c141dd70872593da6405 +size 46230 diff --git a/docs/tools/pluto-m2k/device_manager_m2k_installed.png b/docs/tools/pluto-m2k/device_manager_m2k_installed.png new file mode 100644 index 00000000..5a946d9a --- /dev/null +++ b/docs/tools/pluto-m2k/device_manager_m2k_installed.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:50b067c9fcb7ea295b9657b4ef1db2d60c3802f6c2af2b47a3d62a54207b385f +size 372236 diff --git a/docs/tools/pluto-m2k/dfu.png b/docs/tools/pluto-m2k/dfu.png new file mode 100644 index 00000000..fcd54c55 --- /dev/null +++ b/docs/tools/pluto-m2k/dfu.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ecee7a2842148ee356d62735071b4df8caf2f6db639a300f97b3943dab28fb59 +size 303553 diff --git a/docs/tools/pluto-m2k/dfumode_osx.png b/docs/tools/pluto-m2k/dfumode_osx.png new file mode 100644 index 00000000..534f08a3 --- /dev/null +++ b/docs/tools/pluto-m2k/dfumode_osx.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e89d6298356f0e48ab9c47f3772f63119587eda8a3b9be87e3b35f54a614701b +size 97452 diff --git a/docs/tools/pluto-m2k/drivers-uninst.png b/docs/tools/pluto-m2k/drivers-uninst.png new file mode 100644 index 00000000..d3980f0a --- /dev/null +++ b/docs/tools/pluto-m2k/drivers-uninst.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:01064c4f0c921589350f5486619e1768e728b70978aa8c82fdb411131ddb18e9 +size 72599 diff --git a/docs/tools/pluto-m2k/drivers.rst b/docs/tools/pluto-m2k/drivers.rst new file mode 100644 index 00000000..e05ea62f --- /dev/null +++ b/docs/tools/pluto-m2k/drivers.rst @@ -0,0 +1,603 @@ +.. _pluto-m2k drivers: + +Installing Drivers +"""""""""""""""""" + +Jump to the host of interest: + +* :ref:`pluto-m2k drivers linux` +* :ref:`pluto-m2k drivers osx` +* :ref:`pluto-m2k drivers windows` + +.. _pluto-m2k drivers linux: + +Linux Drivers +============= + +Make sure the following modules are installed in your kernel: + +- cdc-acm,cdc_ether +- rndis_host +- rndis_wlan +- usbnet + +On most modern distributions - these will be installed/compiled by default. It +should just be a simple matter to plug the USB cable into your Linux machine. We +have tested and verified on these distributions: + +- Ubuntu 16.04 LTS +- Red Hat Enterprise Linux 7 [1]_ +- SUSE Linux Enterprise Desktop 12 [2]_ +- Debian 8.x +- Debian 9.1 +- SUSE Leap 15 +- SUSE Leap 15.1 + +It is likely that other distributions can use the ADALM-PLUTO or ADALM2000, but +we are in a limited position to provide technical support for those +distributions. + +In order to access some USB functions without root privileges, it's +recommended to install the PlutoSDR or ADALM2000 udev rules. Simply download +:git-plutosdr-fw:`53-adi-plutosdr-usb.rules ` +or +:git-m2k-fw:`53-adi-m2k-usb.rules ` +and copy into into the */etc/udev/rules.d*/ folder. + +You can also use +:dokuwiki:`this plutosdr-m2k-udev.deb package ` +to install both the PlutoSDR and the ADALM2000 +udev rules. +To install the debian package, use one of the following: +``sudo apt-get install ./plutosdr-m2k-udev.deb`` or +``sudo dpkg -i plutosdr-m2k-udev.deb``. +Afterwards reload rules or restart udev, using either +``udevadm control --reload-rules`` or ``sudo service udev restart`` + +Example dmesg +------------- + +When plugging Pluto in (m2k should be similar), you (if you are looking), you +will see kernel messages of: + +:: + + [ 1776.708333] usb 8-2: new high-speed USB device number 3 using ehci-pci + [ 1776.843799] usb 8-2: New USB device found, idVendor=0456, idProduct=b673 + [ 1776.843811] usb 8-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 1776.843818] usb 8-2: Product: PLUTO + [ 1776.843824] usb 8-2: Manufacturer: Analog Devices Inc. + [ 1776.843830] usb 8-2: SerialNumber: 00000001 + [ 1776.853016] rndis_host 8-2:2.0 usb0: register 'rndis_host' at usb-0000:00:1d.7-2, RNDIS device, 9e:18:bb:fa:07:c6 + [ 1776.853957] cdc_acm 8-2:2.2: This device cannot do calls on its own. It is not a modem. + [ 1776.854080] cdc_acm 8-2:2.2: ttyACM0: USB ACM device + [ 1776.855371] usb-storage 8-2:2.4: USB Mass Storage device detected + [ 1776.855559] scsi9 : usb-storage 8-2:2.4 + [ 1777.852893] scsi 9:0:0:0: Direct-Access Linux File-Stor Gadget 0406 PQ: 0 ANSI: 2 + [ 1777.853329] sd 9:0:0:0: Attached scsi generic sg2 type 0 + [ 1777.854618] sd 9:0:0:0: [sdb] 16384 512-byte logical blocks: (8.38 MB/8.00 MiB) + [ 1777.856248] sd 9:0:0:0: [sdb] Write Protect is off + [ 1777.856252] sd 9:0:0:0: [sdb] Mode Sense: 0f 00 00 00 + [ 1777.856863] sd 9:0:0:0: [sdb] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA + [ 1777.859892] sdb: + [ 1777.862868] sd 9:0:0:0: [sdb] Attached SCSI removable disk + [ 1778.022282] FAT-fs (sdb): utf8 is not a recommended IO charset for FAT filesystems, filesystem will be case sensitive! + +Showing the three devices (ethernet, serial and mass storage) enumerating, and +interface with the devices in the normal linux methods. + +If you happen to see something like: + +:: + + [ 84.257337] usb usb1-port2: unable to enumerate USB device + +The solution is to use an external hub and after that all works. + +Serial +------ + +NOTE: For suse and probably other linux versions -- be sure you are also member +of the dialout group. + +.. shell:: + + $cat ~/.kermrc + set line /dev/ttyACM0 + set speed 115200 + set carrier-watch off + set flow-control none + $kermit -l /dev/ttyACM0 -b 115200 + C-Kermit 9.0.302 OPEN SOURCE:, 20 Aug 2011, for Linux+SSL+KRB5 (64-bit) + Copyright (C) 1985, 2011, + Trustees of Columbia University in the City of New York. + Type ? or HELP for help. + (/home/analog/github/iio-oscilloscope/) C-Kermit>c + Connecting to /dev/ttyACM0, speed 115200 + Escape character: Ctrl-\ (ASCII 28, FS): enabled + Type the escape character followed by C to get back, + or followed by ? to see other options. + ---------------------------------------------------- + + Login timed out after 60 seconds + + Welcome to Pluto + pluto login: root + Password: analog + $uname -a + Linux pluto 4.6.0-g88f1b2c #7 SMP PREEMPT Wed Nov 2 18:21:13 CET 2016 armv7l GNU/Linux + $exit + + Welcome to Pluto + pluto login: Ctrl-\ + (Back at imhotep.analog.com) + ---------------------------------------------------- + (/home/analog/github/iio-oscilloscope/) C-Kermit>exit + Closing /dev/ttyACM0...OK + +Mass Storage +------------ + +.. shell:: + + $mount | grep -i pluto + /dev/sdb1 on /media/analog/PlutoSDR type vfat + (rw,nosuid,nodev,relatime,uid=1000,gid=1000,fmask=0022,dmask=0022,codepage=437, + iocharset=utf8,shortname=mixed,showexec,utf8,flush,errors=remount-ro,uhelper=udisks2) + $ls -l /media/analog/PlutoSDR/ + total 8 + -rw-r--r-- 1 analog analog 206 Dec 31 1979 config.txt + -rw-r--r-- 1 analog analog 4721 Dec 31 1979 info.html + $firefox /media/analog/PlutoSDR/info.html + +Ethernet +-------- + +.. caution:: + + Like most of the network settings on Pluto or the M2k - things are + meant to be easy to use. This also means things are inherently insecure. + +.. shell:: + + $/sbin/ifconfig + enx00e022d6d804: flags=4163 mtu 1500 + inet 192.168.2.10 netmask 255.255.255.0 broadcast 192.168.2.255 + inet6 fe80::2e0:22ff:fed6:d804 prefixlen 64 scopeid 0x20 + ether 00:e0:22:d6:d8:04 txqueuelen 1000 (Ethernet) + RX packets 4 bytes 1030 (1.0 KiB) + RX errors 0 dropped 0 overruns 0 frame 0 + TX packets 47 bytes 10604 (10.3 KiB) + TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 + $ip addr show + 7: c: mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 + link/ether 00:e0:22:d6:d8:04 brd ff:ff:ff:ff:ff:ff + inet 192.168.2.10/24 brd 192.168.2.255 scope global dynamic enx00e022d6d804 + valid_lft 862988sec preferred_lft 862988sec + inet6 fe80::2e0:22ff:fed6:d804/64 scope link + valid_lft forever preferred_lft forever + +The *weird* ``enx00e022d6d804`` comes from systemd on a debian based +distribution (which my host is). The enu prefix (or sometimes wlu) would +describe the USB port, and the rest ``00e022d6d804`` is the host USB MAC +address. This is what it uses, rather than a USB path (like +``usb-0000:00:14.0-2``, which is how the kernel refers to things) since USB path +aren't persistent nor predictable (it changes depending on the port you plug +things into). + +.. _pluto-m2k drivers ssh-config: + +ssh config +~~~~~~~~~~ + +Adding a quick/short :git-plutosdr_scripts:`ssh config file `, +which describes the USB device can be helpful. It's maintained in github, and +it's a simple matter of grabbing the raw text file. You shouldn't do the exact +below unless you have no ``~/.ssh/config`` file. +Otherwise, click :git-plutosdr_scripts:`on this link ` +and copy/paste it into the system wide ``/etc/ssh/ssh_config`` file, or the user +specific ``~/.ssh/config`` file. + +.. shell:: + + $wget https:%%//%%raw.githubusercontent.com/analogdevicesinc/plutosdr_scripts/master/ssh_config -O ~/.ssh/config + --2017-01-26 19:47:51-- https:%%//%%raw.githubusercontent.com/analogdevicesinc/plutosdr_scripts/master/ssh_config + Resolving raw.githubusercontent.com (raw.githubusercontent.com)... 151.101.116.133 + Connecting to raw.githubusercontent.com (raw.githubusercontent.com)|151.101.116.133|:443... connected. + HTTP request sent, awaiting response... 200 OK + Length: 366 [text/plain] + Saving to: ‘~/.ssh/config’ + + ~/.ssh/config 100%[===============>] 366 --.-KB/s in 0s + + 2017-01-26 19:47:51 (6.49 MB/s) - ‘~/.ssh/config’ saved [366/366] + +Since the ssh key on the pluto changes every boot, we want to be able to never +store the key (so we store it to ``/dev/null``. This does make it easier to use +(don't need to continually edit the ``known_hosts`` file), but does make things +susceptible to man in the middle attacks. + +.. shell:: + + $ssh plutosdr + Warning: Permanently added 'pluto' (ECDSA) to the list of known hosts. + root@pluto's password: analog + $uname -a + Linux pluto 4.6.0-08511-gc1315e6-dirty #247 SMP PREEMPT Mon Oct 24 16:46:25 CEST 2016 armv7l GNU/Linux + $exit + Connection to 192.168.2.1 closed. + +if you have ``sshpass`` installed, you can use that so you dont need to type in +a password: + +.. shell:: + + ~/pluto + $sshpass -panalog ssh plutosdr + Warning: Permanently added 'pluto' (ECDSA) to the list of known hosts. + Welcome to: + ______ _ _ _________________ + | ___ \ | | | / ___| _ \ ___ \ + | |_/ / |_ _| |_ ___ \ `--.| | | | |_/ / + | __/| | | | | __/ _ \ `--. \ | | | / + | | | | |_| | || (_) /\__/ / |/ /| |\ \ + \_| |_|\__,_|\__\___/\____/|___/ \_| \_| + + http://wiki.analog.com/university/tools/pluto + +IIO devices +----------- + +For SUSE: https://software.opensuse.org/package/libiio -- pick the repo and +install via one click install + +.. shell:: + + $sudo apt-get install libiio-utils + Reading package lists... Done + Building dependency tree + Reading state information... Done + The following NEW packages will be installed: + libiio-utils + 0 upgraded, 1 newly installed, 0 to remove and 191 not upgraded. + Need to get 13.9 kB of archives. + After this operation, 74.8 kB of additional disk space will be used. + Get:1 http:%%//%%ftp.us.debian.org/debian stretch/main amd64 libiio-utils amd64 0.7-1 [13.9 kB] + Fetched 13.9 kB in 0s (70.1 kB/s) + Selecting previously unselected package libiio-utils. + (Reading database ... 279782 files and directories currently installed.) + Preparing to unpack .../libiio-utils_0.7-1_amd64.deb ... + Unpacking libiio-utils (0.7-1) ... + Setting up libiio-utils (0.7-1) ... + +Try to make sure you can talk to the device, and find the IIO devices: + +.. shell:: + + $iio_info -n 192.168.2.1 | grep device + IIO context has 5 devices: + iio:device0: adm1177 + iio:device1: ad9361-phy + iio:device2: xadc + iio:device3: cf-ad9361-dds-core-lpc + iio:device4: cf-ad9361-lpc + +Read from an IIO device buffer: + +.. shell:: + + $iio_readdev -n 192.168.2.1 -s 64 cf-ad9361-lpc | hexdump -x + 0000000 ff8d 003b 002a 0013 006c 0045 ffdb 0001 + 0000010 ffc1 ffd5 ffc0 0030 ffbf 0068 0042 008f + 0000020 0027 007e fff5 ffe2 ffea ffbb ffd1 0039 + 0000030 ffd1 006e 0030 0058 0025 0034 001b ffa0 + 0000040 ffde ffe9 ff88 006a ffff 0038 0071 0012 + 0000050 0031 ffdf ffd7 ffc3 ff72 ffed ffae 0016 + 0000060 0002 005d 001c 0031 ffff ffef ffec ffe9 + 0000070 ff97 fff6 ffac 0024 0012 0047 00d6 0095 + 0000080 0087 0076 ffe4 0036 ff96 fffa ff6b 0047 + 0000090 ffd8 0068 008e 0040 0133 ffc8 006a ffc4 + 00000a0 ff8d ff9d ff89 ff9d 0005 0012 002c 0073 + 00000b0 0036 005c 006c fff6 005d ffff fffc ffce + 00000c0 ffbc ffdc fff5 004d 0037 008a 004b 0045 + 00000d0 0044 ffad 0012 ff90 fff8 ffa3 ffa6 ffef + 00000e0 ffe8 0079 0086 0097 005e 0041 005f 0005 + 00000f0 007b ffe6 0025 ffa3 ffef 0011 ffef 0044 + +.. [1] + Our support follows Red Hat’s support policy for minor versions of RHEL. + +.. [2] + Our support follows SUSE’s support policy for minor versions of Enterprise + Desktop. + +.. _pluto-m2k drivers osx: + +Mac OS X Drivers +================ + +Serial +------ + +.. shell:: + + $ls -l /dev/tty. + crw-rw-rw- 1 root wheel 17, 0 Nov 7 15:13 /dev/tty.Bluetooth-Incoming-Port + crw-rw-rw- 1 root wheel 17, 2 Nov 7 15:28 /dev/tty.usbmodem1414 + adi-mm:tests analogdevices$ screen /dev/tty.usbmodem1414 115200 + + Welcome to Pluto + pluto login: root + Password: analog + $uname -a + Linux pluto 4.6.0-08511-gc1315e6-dirty #247 SMP PREEMPT Mon Oct 24 16:46:25 CEST 2016 armv7l GNU/Linux + # + CNTRL-A CNTRL-\ + Really quit and kill all your windows [y/n] y + [screen is terminating] + +Mass Storage +------------ + +.. shell:: + + $mount | grep Pluto + /dev/disk1s1 on /Volumes/PlutoSDR (msdos, local, nodev, nosuid, noowners) + +Ethernet +-------- + +.. hint:: + + In order to use the ADALM-PLUTO (aka. PlutoSDR) or ADALM2000 (aka. + M2k) with Mac OSX the ethernet compatibility mode must be set to **USB + CDC-NCM**. + +Please see instructions for +:dokuwiki:`changing the usb ethernet compatibility mode `. + +.. caution:: + + Like most of the network settings on Pluto or the M2k - things are + meant to be easy to use. This also means things are inherently insecure. + + +You should see something like this when you goto -> System Preferences -> +Network. + +.. image:: screen_shot_2017-01-12_at_2.36.55_pm.png + :width: 400px + +.. shell:: + + $ifconfig | grep -B 3 -A 3 192 + en4: flags=8863 mtu 1486 + ether 00:e0:22:6d:b2:d8 + inet6 fe80::2e0:22ff:fe6d:b2d8%en4 prefixlen 64 scopeid 0xa + inet 192.168.2.10 netmask 0xffffff00 broadcast 192.168.2.255 + nd6 options=1 + media: autoselect + status: active + +ssh config +~~~~~~~~~~ + +Please follow the same steps from Linux's :ref:`pluto-m2k drivers ssh-config`. + +.. _pluto-m2k drivers windows: + +Windows Drivers +=============== + +There are different aspects of the software for the ADALM-PLUTO and ADALM2000: + +- device drivers, which allows your PC to properly set up communication between + your PC and the actual device, and +- application code, like MATLAB, Simulink, GNU Radio, iio-oscilloscope (aka + osc), or scopy. + +To install the drivers, it's a simple matter of downloading and executing the +driver installer. + +.. important:: + + Before running the installer, please ensure that the + hardware supported by the drivers is not already connected. If the hardware is + connected when the installer is run, the installation of the driver files may + fail. + +.. admonition:: Download + + This download should support all of: Windows 11, Windows + 10, Windows 8.1, Windows 8, Windows 7 Service Pack 1. If you run into issues, + please :ez:`let us know `. + + :git-plutosdr-drivers-win:`Windows USB drivers for PlutoSDR and M2k (Windows 32-bit / 64-bit) ` + +At the end, you should see a picture like (either for Pluto or M2k): + +.. grid:: + :widths: 33 33 33 + + .. image:: win_your_device_is_ready_to_use.png + :width: 300px + + .. image:: device_manager_installed.png + :width: 300px + + .. image:: device_manager_m2k_installed.png + :width: 300px + +DFU Mode +-------- + +If you don't see the above, and see something like this instead, this means the +device is in +:ref:`dfu_update ` +mode. It's likely in this mode since a bad firmware is in the device; or a +firmware update failed for some reason. To recover from this, ensure the latest +firmware is installed on the device. + +.. image:: dfu.png + :width: 300px + +Drivers uninstall +----------------- + +From the control panel navigate to Programs and Features. Double click or right +click and select Uninstall. Uninstalling the PlutoSDR-M2k-USB-Win-Drivers +package will automatically remove the Windows Driver Packages (USBser, WinUSB +and Net) shown below as well. + +.. image:: drivers-uninst.png + :width: 800px + +USB Devices +----------- + +Once the drivers are installed, and the device (Pluto or M2k) is plugged in, the +following subsystems should be ready to use: + +- USB Composite Device (The device is a single USB gadget that has the ability + to perform more than one function, and needs to be exposed to the operating + system as multiple devices) +- USB Ethernet/RNDIS Gadget (Remote Network Driver Interface Specification + (`RNDIS `__) is a Microsoft proprietary + protocol used mostly on top of USB. It provides a virtual Ethernet link to + most versions of the Windows, Linux and OS X operating systems. To the host, + the usb device acts as an external Ethernet card) +- USB Mass Storage + (`USB Mass Storage `__ is a + set of protocols defined by the USB Implementers Forum that makes a USB + device accessible to any host computing device and enables file transfers + between the host and the USB device. To a host, the USB device acts as an + external hard drive.) +- Serial Console (115200-8N1), in this case COM15, but it will be different on + your PC. +- IIO USBD +- Linux File-Stor Gadget USB Device (which allows the USB mass storage to work + properly). + +Serial +------ + +You need to have find your favorite Terminal program, here are a few of the ones +we use (but don't support - if you have questions, please check with the +internet/google). + +- `Putty `__ +- `Tera Term `__ +- Or other Terminal program + +The terminal settings are 115200 baud, 8 bits, no parity, 1 stop bit. This is +referred to as 115200-8N1. The default username is ``root``, and the default +root password is ``analog``. + +Finding the serial port (which constantly changes, every time you plug a device +in), is just matter of checking device manager (see above). + +Mass Storage +~~~~~~~~~~~~ + +It should be a simple matter of opening the drive, in this case, double click on +"D", to get at the info.html page. + +.. image:: pluto_drive.png + +Ethernet +-------- + +.. caution:: + + Like most of the network settings on Pluto or the M2k - things are + meant to be easy to use. This also means things are inherently insecure. + +For example - the root password of Pluto is ``analog``. We post it on the +Internet. Think about that for a moment. This could allow anyone with an IP +connection to take over the device and use it for malicious purposes. + +**Never** set up a bridge between the Internet and a network connected Pluto +with the default images. + +Unfortunately - nothing on your host understands the what the IP address of the +usb device is. You, the human behind the keyboard need to understand this before +any sort of networking will work. There are two main ways to do this: + +Determine the IP address +~~~~~~~~~~~~~~~~~~~~~~~~ + +The IP address is set by the device and can be found by looking inside the +ADALM-PLUTO's mass storage device, and the ``info.html`` page. Just click on the +``version`` button at the top of the page: + +.. image:: version_button.png + +and then check out the Pluto IP address, and the host IP address. + +.. image:: pluto_ip_addr.png + +In this case, the IP address of the PLUTO device is ``192.168.2.1`` (which is +the default for all devices). If you need to change this (if you have multiple +devices), please check the :dokuwiki:`customizing Pluto ` +documentation. + +Checking from serial port +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Open your favorite serial application: + +.. shell:: + + Welcome to Pluto + pluto login: root + Password: analog + Welcome to: + %% + ______ _ _ _________________ + | ___ \ | | | / ___| _ \ ___ \ + | |_/ / |_ _| |_ ___ \ `--.| | | | |_/ / + | __/| | | | | __/ _ \ `--. \ | | | / + | | | | |_| | || (_) /\__/ / |/ /| |\ \ + \_| |_|\__,_|\__\___/\____/|___/ \_| \_| + %% + http:%%//%%wiki.analog.com/university/tools/pluto + + $ifconfig usb0 + usb0 Link encap:Ethernet HWaddr 00:05:F7:64:30:10 + inet addr:192.168.2.1 Bcast:192.168.2.255 Mask:255.255.255.0 + UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 + RX packets:502 errors:0 dropped:115 overruns:0 frame:0 + TX packets:7 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:1000 + RX bytes:66132 (64.5 KiB) TX bytes:2420 (2.3 KiB) + +IIO devices +~~~~~~~~~~~ + +The IIO device shows up in device manager, and allows you to make native IIO +connections to the device. + +Bringing up a Windows Console should show you something like this: + +.. shell:: ps1 + + /c/ + $iio_info -s + Library version: 0.16 (git tag: 5cdeaaa) + Compiled with backends: local xml ip usb serial + Available contexts: + 0: 0456:b673 (Analog Devices Inc. PlutoSDR (ADALM-PLUTO)), serial=104473222a87000618000600473ed57ae0 [usb:3.8.5] + + $iio_attr -a -C + Using auto-detected IIO context at URI "usb:3.8.5" + IIO context with 8 attributes: + local,kernel: 4.6.0-g651ed13 + usb,idVendor: 0456 + usb,idProduct: b673 + usb,release: 2.0 + usb,vendor: Analog Devices Inc. + usb,product: PlutoSDR (ADALM-PLUTO) + usb,serial: 104473222a87000618000600473ed57ae0 + usb,libusb: 1.0.22.11312 + + diff --git a/docs/tools/pluto-m2k/eject-right-pluto-win10.png b/docs/tools/pluto-m2k/eject-right-pluto-win10.png new file mode 100644 index 00000000..d9c7f47f --- /dev/null +++ b/docs/tools/pluto-m2k/eject-right-pluto-win10.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a8a43390ffaee037d325bf1b85c9757ae62d46b8976997b0936968a24bbcc73c +size 196984 diff --git a/docs/tools/pluto-m2k/eject_osx.png b/docs/tools/pluto-m2k/eject_osx.png new file mode 100644 index 00000000..8eab1c26 --- /dev/null +++ b/docs/tools/pluto-m2k/eject_osx.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:29e24494fb1aff99fcfffae9dc2e56d00bacefb88b5f15f83c61252eb72c13e4 +size 20735 diff --git a/docs/tools/pluto-m2k/firmware.rst b/docs/tools/pluto-m2k/firmware.rst new file mode 100644 index 00000000..f5f14636 --- /dev/null +++ b/docs/tools/pluto-m2k/firmware.rst @@ -0,0 +1,728 @@ +.. _pluto-m2k firmware: + +Firmware Updates +================ + +Latest Release +-------------- + +.. admonition:: Download ADI default firmware images + + - :git-plutosdr-fw:`Latest ADALM-PLUTO (PlutoSDR) Release ` + - :git-m2k-fw:`Latest ADALM2000 (M2k) Release ` + +This zip file should include these files: + +.. list-table:: + :header-rows: 1 + + - - Filename + - Purpose + - - ``boot.dfu`` + - DFU file for First Stage Boot Loader, and U-Boot + - - ``boot.frm`` + - Firmware file for First Stage Boot Loader, U-Boot and it's default + environment + - - ``pluto.dfu`` + - DFU file for Pluto Firmware, this would include FPGA Bit File, Linux + kernel (all drivers), and ram based file system + - - ``m2k.dfu`` + - DFU file for M2k Firmware, this would include FPGA Bit File, Linux + kernel (all drivers), and ram based file system + - - ``pluto.frm`` + - Firmware file for Pluto Firmware, this would include FPGA Bit File, + Linux kernel (all drivers), and ram based file system + - - ``m2k.frm`` + - Firmware file for M2k Firmware, this would include FPGA Bit File, Linux + kernel (all drivers), and ram based file system + - - ``uboot-env.dfu`` + - DFU file which includes the default U-Boot environment + +Determining the firmware version +-------------------------------- + +.. important:: + + This assumes that you have USB plugged into the middle + connector, as described at :ref:`the hardware section ` + and have :ref:`Windows drivers ` or + :ref:`Mac drivers ` installed. + +Before you update, check your existing version to understand if you really want +to upgrade. There are a few ways to determine the version of firmware on your +device. + +Host Command Line +~~~~~~~~~~~~~~~~~ + +Use your favourite shell to access ``iio_attr``, and ask the device: + +.. shell:: + + $iio_attr -a -C fw_version + Using auto-detected IIO context at URI "usb:4.25.5" + fw_version: v0.31 + +The version on this devices is ``0.31``. + +Log In via ssh +~~~~~~~~~~~~~~ + +SSH to the device. In the splash screen it will tell you... + +If you can't remember the username/password, if it is the default, it will be on +the mass storage device ``info.html`` page, under "Build Settings". By default, +it is username: ``root`` ; password is ``analog``. + +.. image:: pluto_password.png + +.. shell:: + + $ssh root@192.168.2.1 + Warning: Permanently added '192.168.2.1' (ECDSA) to the list of known hosts. + root@192.168.2.1's password: analog + Welcome to: + ______ _ _ _________________ + | ___ \ | | | / ___| _ \ ___ \ + | |_/ / |_ _| |_ ___ \ `--.| | | | |_/ / + | __/| | | | | __/ _ \ `--. \ | | | / + | | | | |_| | || (_) /\__/ / |/ /| |\ \ + \_| |_|\__,_|\__\___/\____/|___/ \_| \_| + + v0.31 + http://wiki.analog.com/university/tools/pluto%% + $ + +The version on this devices is ``0.31`` + +Check the mass storage device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are less keyboard prone, then you can check visually, as well. + +Open the ``PlutoSDR`` mass storage device or ``M2K`` mass storage device. This +will have a file called ``info.html``. Double clicking on this file should open +it in your favourite browser, clicking on the ``firmware`` tag in the top should +take you down to a section that looks like this: + +.. image:: plutofirmwareversion.png + :width: 900px + +The version on this devices is ``0.31`` + +Pluto rev C/D +~~~~~~~~~~~~~ + +All the above methods will work on a the most recent revisions, but there are +some additional methods that will only work on rev C or D. + +This assumes that you have USB plugged into the far right "power" connector, as +described at :ref:`the hardware section `. The 2nd USB connector +(the one labeled with the AC adapter logo) is not only power for USB OTG, but +also a USB console. This means you can do things without using SSH, although you +will need some sort of terminal application for your computer. + +If you see don't see anything - that may be normal until you say hello, with the +return key. Then you should see either the ``pluto>`` prompt (if you are in +U-Boot); or a prompt for username/password (if you are booted into Linux). + +then just follow the instructions above. + +Upgrading +--------- + +The easiest way to update the firmware is to use the mass storage device +included in the default image. There are times when this might not be possible +(when you aren't using the default image, or if you accidentally bricked your +device by unplugging it during a firmware upgrade). + +.. important:: + + There are very legitimate `Security Risks `__ + about loading random + firmware images onto devices like the ADALM-PLUTO or ADALM2000, however, we + decided early on that a learning tool must be open and accessible for people to + experiment on. Please only use firmware images you have received from trusted + locations. + +Mass Storage Update +------------------- + +Copy the ``pluto.frm`` or ``m2k.frm`` file onto the mass storage device, and +then eject it. If you have a Rev.C Pluto, copy the entire unzipped +``plutosdr-fw-v0.33.zip`` file. LED1 will start blinking rapidly. + +.. caution:: + + Don't disconnect the device until rapid blinking stops! + +Windows/OSX +~~~~~~~~~~~ + +#. Open the Pluto or M2k mass storage device +#. Download and open the firmware file +#. Copy the file to the Mass Storage device: + + #. Windows + + .. image:: win10_gui_update.png + :width: 800px + + #. OSX + + .. image:: copyfirmware_osx2.png + :width: 800px + +#. Eject (don't unplug) the mass storage device + + #. Windows (only eject as shown below!) + + .. image:: eject-right-pluto-win10.png + :width: 600px + + #. OSX + + .. image:: eject_osx.png + :width: 200px + +#. This will cause ``LED1`` to blink rapidly. This means programming is taking + place. Do not remove power (or USB) while the device is blinking rapidly. It + does take approximately 4 minutes to properly program the device. +#. Still do not unplug things. Try to be more patient. +#. Once the device is done programming, it will re-appear as a mass storage + device. +#. Now you can unplug it, and use it as normal. + +Linux +~~~~~ + +GUI +^^^ + +Command Line +^^^^^^^^^^^^ + +It's exactly the same as the GUI instructions, copy it, and then eject it, then +power cycle it. It's a little more tricky since ``eject`` needs the base device +(it wants ``/dev/sdb`` not ``/dev/sdb1``). + +.. shell:: + + ~/pluto + $cp ./pluto.frm /media/analog/PlutoSDR/ + $mount | grep PlutoSDR | awk '{print $1}' + /dev/sdb1 + $sudo eject /dev/sdb + #WAIT 4 minutes for firmware to update! Do not unplug the device. + +Network Update +-------------- + +Many people remotely deploy their PlutoSDR, (via a USB <-> Ethernet dongle), and +need to maintain their system over the network. To do that get the ``pluto.frm`` +file or the ``boot.frm`` file from the release zip file on the device and +install that with the ``update_frm.sh`` utility which is found on release since +2018 (v0.29) + +.. shell:: + :no-path: + + $ssh root@pluto.local + root@192.168.1.104's password: **analog** + Welcome to: + ______ _ _ _________________ + | ___ \ | | | / ___| _ \ ___ \ + | |_/ / |_ _| |_ ___ \ `--.| | | | |_/ / + | __/| | | | | __/ _ \ `--. \ | | | / + | | | | |_| | || (_) /\__/ / |/ /| |\ \ + \_| |_|\__,_|\__\___/\____/|___/ \_| \_| + + v0.33 + https://wiki.analog.com/university/tools/pluto%% + + $wget https://api.github.com/repos/analogdevicesinc/plutosdr-fw/releases/latest + Connecting to api.github.com (140.82.114.5:80) + Connecting to api.github.com (140.82.114.5:443) + wget: note: TLS certificate validation not implemented + saving to 'latest' + latest 100% |* * * * * *| 9728 0:00:00 ETA + 'latest' saved + $grep "browser_download_url.*plutosdr-fw-" latest | cut -d : -f 2,3 | awk '{print $1}' | tr -d \" + https://github.com/analogdevicesinc/plutosdr-fw/releases/download/v0.34/plutosdr-fw-v0.34.zip + $wget https://github.com/analogdevicesinc/plutosdr-fw/releases/download/v0.34/plutosdr-fw-v0.34.zip + Connecting to github.com (140.82.114.3:443) + wget: note: TLS certificate validation not implemented + Connecting to objects.githubusercontent.com (185.199.109.133:443) + saving to 'plutosdr-fw-v0.34.zip' + plutosdr-fw-v0.34.zip 100% |* * * * * * * * *| 19.2M 0:00:00 ETA + 'plutosdr-fw-v0.34.zip' saved + $unzip -l plutosdr-fw-v0.34.zip + Archive: plutosdr-fw-v0.34.zip + Length Date Time Name + --------- ---------- ----- ---- + 10580851 08-20-2021 14:13 pluto.dfu + 131088 08-20-2021 14:13 uboot-env.dfu + 10580868 08-20-2021 14:13 pluto.frm + 469532 08-20-2021 14:13 boot.dfu + 601645 08-20-2021 14:13 boot.frm + -------- ------- + 22363984 5 files + $unzip plutosdr-fw-v0.34.zip pluto.frm + Archive: plutosdr-fw-v0.34.zip + inflating: pluto.frm + $update_frm.sh ./pluto.frm + 161+1 records in + 161+1 records out + Done + $reboot + +.. _pluto-m2k firmware dfu_update: + +DFU Update +---------- + +`USB Device Firmware Upgrade `__ (DFU) +is an official USB device class specification of the USB Implementers Forum. It +specifies a vendor and device independent way of updating the firmware of a USB +device. The concept is to have only one vendor-independent update tool as part +of the operating system, which can then (given a particular firmware image) be +downloaded into the device. During the firmware upgrade operation (when the +Pluto or M2k is in "DFU" mode), the device changes its operating mode (it's no +longer an SDR or an instrument, no longer uses it's standard PID/VID, but +becomes a flash programmer). + +This should only be necessary to recover your device if something accidentally +happened during a firmware update (like having loose USB plugs, or bad USB +cables, which cause a power cycle during a normal firmware update.) + +Entering DFU mode +~~~~~~~~~~~~~~~~~ + +How to manually enter DFU mode? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In general, the preferred firmware upgrade is via the mass storage device. There +are 3 ways to enter the DFU mode manually: + +#. **Press the device button** with a toothpick, paper-clip or similar and then + apply power by plugging in the USB cable. +#. From the device linux console type **device_reboot sf**. There are three ways + to access the linux console: + + #. The USB console USB CDC ACM aka. ttyACM0 using putty, minicom, tera Term, + etc. + #. The UART console using :ref:`ADALM-JTAGUART `. + #. The network console using ssh/slogin. + +#. Directly from u-boot serial console type: **run dfu_sf**. Access to the uboot + command console is only available using + :ref:`ADALM-JTAGUART ` + +When does the device automatically enter DFU mode? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The device enters DFU mode in case booting the multi component FIT image +(Flattened Image Tree) fails. This may happen due to checksum failure caused by +a corrupted previous firmware update. + +How can I check if the device is in DFU mode? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the device is in DFU mode, the **DONE LED** is **OFF**, while **LED1** is +constantly **ON**. The device switches it’s USB PID to 0xB674 (PlutoSDR DFU) + +Windows +^^^^^^^ + +Check with Device Manager, and see if the DFU mode shows up. + +.. image:: device_manager_dfu.png + :width: 200px + +on Linux +^^^^^^^^ + +``0456`` is the Analog Devices Vendor ID (VID), by using using ``lsusb``, you +can check the mode. In normal use mode, the PlutoSDR will show up as Product ID +(PID) b673: + +.. shell:: + + $lsusb | grep 0456 + Bus 003 Device 008: ID 0456:b673 Analog Devices, Inc. + +And in DFU mode: + +.. shell:: + + $lsusb | grep 0456 + Bus 003 Device 009: ID 0456:b674 Analog Devices, Inc. + +On MAC +^^^^^^ + +Check on + +.. image:: dfumode_osx.png + :width: 300px + +Update using DFU mode +~~~~~~~~~~~~~~~~~~~~~ + +How to update the firmware using DFU mode? How to rewrite the default uboot +environment? + +Windows +^^^^^^^ + +The PlutoSDR/M2K driver package bundles also a dfu utility. There is a windows +command console batch script called +:git-plutosdr_scripts:`UPDATE.BAT ` +which eases the update procedure. + +#. Download and save + :git-plutosdr_scripts:`UPDATE.BAT ` +#. Download and unzip the latest PlutoSDR respectively M2k release + + #. :git-plutosdr-fw:`PlutoSDR Release ` + #. :git-m2k-fw:`M2k Release ` + +#. Open a windows command prompt +#. Execute UPDATE.BAT with the path to the pluto.dfu or m2k.dfu file. (In case + you need to rewrite the default uboot environment the use the uboot-env.dfu + file) +#. Wait for the script to complete + +.. shell:: ps1 + + /c/tmp + $UPDATE.BAT c:\tmp\pluto.dfu + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ + + Opening DFU capable USB device... + ID 0456:b674 + Run-time device DFU version 0110 + Claiming USB DFU Interface... + Setting Alternate Setting #1 ... + Determining device status: state = dfuIDLE, status = 0 + dfuIDLE, continuing + DFU mode device DFU version 0110 + Device returned transfer size 4096 + Copying data from PC to DFU device + Download [=========================] 100% 8694467 bytes + Download done. + state(7) = dfuMANIFEST, status(0) = No error condition is present + state(2) = dfuIDLE, status(0) = No error condition is present + Done! + + $ + +Linux +^^^^^ + +.. shell:: + + $sudo dfu-util -a firmware.dfu -D pluto.dfu + +``pluto.dfu`` is your firmware file in the dfu format. + +OSX +^^^ + +``dfu-util`` does not come with a default OSX install. You can install it with +brew as: + +.. shell:: + + $brew install dfu-util + +Updating the firmware is the same as Linux: + +.. shell:: + + $dfu-util -a firmware.dfu -D pluto.dfu + +``pluto.dfu`` is your firmware file in the dfu format. + +Debugging DFU +~~~~~~~~~~~~~ + +If those instructions didn't help - you might get here. Hopefully this will help +describe things. + +The first thing to try is to make sure the device (Pluto or M2k) is actually in +DFU mode. This is accomplished by asking the dfu utilities to list any devices +that it finds, their configuration, interface and altsetting. + + Although these examples are on a Linux machine, on Windows, it is +similar. When you installed the Pluto or M2k Windows Drivers, it put the +``dfu-utils`` on your hard drive (that's why you accepted the GPL when you +installed the Windows license). However, for many these are not on path. It's +easy to go to this directory, and run things from there. For example: + +.. shell:: ps1 + + /c/ + $cd 'c:\Program Files\Analog Devices\PlutoSDR-M2K' + $dfu-util.exe -l + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ + + Found DFU: [0456:b674] ver=0221, devnum=7, cfg=1, intf=0, path="1-1", alt=4, name="spare.dfu", serial="UNKNOWN" + Found DFU: [0456:b674] ver=0221, devnum=7, cfg=1, intf=0, path="1-1", alt=3, name="uboot-env.dfu", serial="UNKNOWN" + Found DFU: [0456:b674] ver=0221, devnum=7, cfg=1, intf=0, path="1-1", alt=2, name="uboot-extra-env.dfu", serial="UNKNOWN" + Found DFU: [0456:b674] ver=0221, devnum=7, cfg=1, intf=0, path="1-1", alt=1, name="firmware.dfu", serial="UNKNOWN" + Found DFU: [0456:b674] ver=0221, devnum=7, cfg=1, intf=0, path="1-1", alt=0, name="boot.dfu", serial="UNKNOWN" + +Just don't type in the ``sudo`` that is necessary on Linux. + +Here it found one device, with 5 "partitions" in the flash map. + +.. shell:: + + $sudo dfu-util --list + [sudo] password for rgetz: + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to %%http://sourceforge.net/p/dfu-util/tickets/%% + + Found DFU: [0456:b674] ver=0221, devnum=104, cfg=1, intf=0, path="3-1.6.6", alt=4, name="spare.dfu", serial="UNKNOWN" + Found DFU: [0456:b674] ver=0221, devnum=104, cfg=1, intf=0, path="3-1.6.6", alt=3, name="uboot-env.dfu", serial="UNKNOWN" + Found DFU: [0456:b674] ver=0221, devnum=104, cfg=1, intf=0, path="3-1.6.6", alt=2, name="uboot-extra-env.dfu", serial="UNKNOWN" + Found DFU: [0456:b674] ver=0221, devnum=104, cfg=1, intf=0, path="3-1.6.6", alt=1, name="firmware.dfu", serial="UNKNOWN" + Found DFU: [0456:b674] ver=0221, devnum=104, cfg=1, intf=0, path="3-1.6.6", alt=0, name="boot.dfu", serial="UNKNOWN" + +If this doesn't show up, try again. ``dfu-utils`` is known to work better the +2nd time. + +When the system boots, it follows this basic process: + +#. the U-Boot (``boot`` section) will load, +#. U-Boot will load it's environment (both the ``uboot-env`` and + ``uboot-extra-env`` sections), +#. U-Boot will then use that to load the kernel and ramfs (the ``firmware`` + section). + +.. note:: + + **dfu-util** - a short dfu primer + `DFU `__ has lots of options, + the ones to remember are: + + - ``-l`` List the currently attached DFU capable USB devices + - ``-a `` Specify the Altseting of the DFU Interface + - ``-D into device + - ``-U `` Read firmware from device into + - ``-R`` Issue USB reset signalling after upload or download has finished. + + The file releases always include: + + - ``boot.dfu`` + - ``pluto.dfu`` + - ``uboot-env.dfu`` + +And corruption of those sections can cause problems in the booting process. In +order, try writing the: + +#. firmware section: + + .. shell:: + + $sudo dfu-util -a firmware.dfu -D ./pluto.dfu + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to %%http://sourceforge.net/p/dfu-util/tickets/%% + + Match vendor ID from file: 0456 + Match product ID from file: b673 + Opening DFU capable USB device... + ID 0456:b674 + Run-time device DFU version 0110 + Claiming USB DFU Interface... + Setting Alternate Setting #1 ... + Determining device status: state = dfuIDLE, status = 0 + dfuIDLE, continuing + DFU mode device DFU version 0110 + Device returned transfer size 4096 + Copying data from PC to DFU device + Download [=========================] 100% 10623523 bytes + Download done. + state(7) = dfuMANIFEST, status(0) = No error condition is present + state(2) = dfuIDLE, status(0) = No error condition is present + Done! + +#. The U-Boot section: + + .. shell:: + + $sudo dfu-util -a boot.dfu -D ./boot.dfu + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to %%http://sourceforge.net/p/dfu-util/tickets/%% + + Match vendor ID from file: 0456 + Match product ID from file: b673 + Opening DFU capable USB device... + ID 0456:b674 + Run-time device DFU version 0110 + Claiming USB DFU Interface... + Setting Alternate Setting #0 ... + Determining device status: state = dfuIDLE, status = 0 + dfuIDLE, continuing + DFU mode device DFU version 0110 + Device returned transfer size 4096 + Copying data from PC to DFU device + Download [=========================] 100% 469388 bytes + Download done. + state(7) = dfuMANIFEST, status(0) = No error condition is present + state(2) = dfuIDLE, status(0) = No error condition is present + Done! + +#. the U-Boot environment : + + .. shell:: + + $sudo dfu-util -a uboot-env.dfu -D ./uboot-env.dfu + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to %%http://sourceforge.net/p/dfu-util/tickets/%% + + Match vendor ID from file: 0456 + Match product ID from file: b673 + Opening DFU capable USB device... + ID 0456:b674 + Run-time device DFU version 0110 + Claiming USB DFU Interface... + Setting Alternate Setting #3 ... + Determining device status: state = dfuIDLE, status = 0 + dfuIDLE, continuing + DFU mode device DFU version 0110 + Device returned transfer size 4096 + Copying data from PC to DFU device + Download [=========================] 100% 131072 bytes + Download done. + state(7) = dfuMANIFEST, status(0) = No error condition is present + state(2) = dfuIDLE, status(0) = No error condition is present + Done! + +#. the ``uboot-extra-env.dfu``. This is rarely needed to be changed. This is + where things like factory calibration and ppm offset are stored. A good idea + is just to check it: + + .. shell:: + + $sudo dfu-util -a uboot-extra-env.dfu -U ./uboot-extra-env.dfu + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to %%http://sourceforge.net/p/dfu-util/tickets/%% + + Opening DFU capable USB device... + ID 0456:b674 + Run-time device DFU version 0110 + Claiming USB DFU Interface... + Setting Alternate Setting #2 ... + Determining device status: state = dfuIDLE, status = 0 + dfuIDLE, continuing + DFU mode device DFU version 0110 + Device returned transfer size 4096 + Copying data from DFU device to PC + Upload [=========================] 100% 4096 bytes + Upload done. + + This will upload things from the device to your PC. It can be checked with + ``hexdump``. + + .. shell:: + + ~/Downloads/pluto2 + $hexdump -C ./uboot-extra-env.dfu + 00000000 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................| + + 00001000 + + Here we can see this is blank (all ``0xFF``), meaning that no custom + calibration data is currently used on this device. This is common for early + models. If you need to clear it, just make a file that starts with ``0xFF``, + and write it. Note that this section of flash is protected. Therefore, the + flash must be unlocked if you want to overwrite this partition. The U-Boot + environment sections are protected with a CRC32, so if something has become + corrupt, it will be skipped. Even if this partition is bad and CRC32 passes, + only the xo_correction is used and itself will fail gracefully if wrong + values provided. + +#. The last time your access things, you can tell the device to reset with the + ``-R`` option. + + .. shell:: + + $sudo dfu-util -R -a uboot-extra-env.dfu -U ./uboot-extra-env.dfu + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to %%http://sourceforge.net/p/dfu-util/tickets/%% + + Opening DFU capable USB device... + ID 0456:b674 + Run-time device DFU version 0110 + Claiming USB DFU Interface... + Setting Alternate Setting #2 ... + Determining device status: state = dfuIDLE, status = 0 + dfuIDLE, continuing + DFU mode device DFU version 0110 + Device returned transfer size 4096 + Copying data from DFU device to PC + Upload [=========================] 100% 4096 bytes + Upload done. + Resetting USB to switch back to runtime mode + +Release Notification +-------------------- + +When a new release is made, you can be automatically notified if you are +watching the release section on github. To do this, you need to be logged into +github with a valid account (and have a valid email where you want notifications +to show up). Then just go to the +:git-scopy:`Scopy <+>`; +:git-m2k-fw:`M2k Firmware <+>` or +:git-plutosdr-fw:`PlutoSDR Firmware <+>`. Scopy has built in notification (it will tell you on +startup if a new feature is available, but if you are a lab manager, and still +want to be notified - the default github notifications are the best solution). + +Click on the "Watch" button in the right hand side, then decide if you want to +watch everything, or just releases (under Custom). (Click on the picture if you +need it bigger). + +.. grid:: + :widths: 50 50 + + .. image:: watch.png + :width: 440px + + .. image:: watch2.png + :width: 440px diff --git a/docs/tools/pluto-m2k/index.rst b/docs/tools/pluto-m2k/index.rst new file mode 100644 index 00000000..1f1d50fa --- /dev/null +++ b/docs/tools/pluto-m2k/index.rst @@ -0,0 +1,10 @@ +Common PLUTO&M2K +================ + +These topics are common to the :ref:`pluto` and :ref:`m2k`: + +.. toctree:: + :titlesonly: + :glob: + + * diff --git a/docs/tools/pluto-m2k/obtaining_the_sources.rst b/docs/tools/pluto-m2k/obtaining_the_sources.rst new file mode 100644 index 00000000..5f5ce8a2 --- /dev/null +++ b/docs/tools/pluto-m2k/obtaining_the_sources.rst @@ -0,0 +1,57 @@ +.. _pluto-m2k obtaining_the_sources: + +Obtaining the Build Sources +=========================== + +Building the PlutoSDR or M2k Firmware Image involves several components managed +in individual source code repositories. However since these components are +heavily interrelated the approach taken utilizes +`Git-Submodules `__. + +Firmware image components (Submodules): + +- :git-linux:`/` +- :git-hdl:`/` +- :git-buildroot:`buildroot ` +- :git-u-boot-xlnx:`u-boot Bootloader ` + +Submodules allow you to keep a Git repository as a subdirectory of another, the +main Git repository. + +The main repositories can be found here: + +- :git-plutosdr-fw:`PlutoSDR-fw ` +- :git-m2k-fw:`M2k-fw ` + +Cloning the repository +---------------------- + +.. important:: + + The ``--recursive`` flag here is important otherwise the submodules are not + included. + The sources and all the build objects require approx 6 GByte of free disk space. + +PlutoSDR-fw +~~~~~~~~~~~ + +.. shell:: + + ~/devel + $git clone --recursive https://github.com/analogdevicesinc/plutosdr-fw.git + +M2k-fw +~~~~~~ + +.. shell:: + + ~/devel + $git clone --recursive https://github.com/analogdevicesinc/m2k-fw.git + +Updating your repository +------------------------ + +.. shell:: + + ~/devel/plutosdr-fw + $git pull --recurse-submodules diff --git a/docs/tools/pluto-m2k/pluto_drive.png b/docs/tools/pluto-m2k/pluto_drive.png new file mode 100644 index 00000000..a71493c1 --- /dev/null +++ b/docs/tools/pluto-m2k/pluto_drive.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ce434784f8e8ad2de8c9d8538c985d35c8bc8426bcc590374906a693f410a29a +size 156302 diff --git a/docs/tools/pluto-m2k/pluto_ip_addr.png b/docs/tools/pluto-m2k/pluto_ip_addr.png new file mode 100644 index 00000000..4c168095 --- /dev/null +++ b/docs/tools/pluto-m2k/pluto_ip_addr.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9bfa5927d2b47ad871d3c3947c50198e82ac8d1e2862d71ea18cf508d7e59aea +size 46020 diff --git a/docs/tools/pluto-m2k/pluto_password.png b/docs/tools/pluto-m2k/pluto_password.png new file mode 100644 index 00000000..d082b434 --- /dev/null +++ b/docs/tools/pluto-m2k/pluto_password.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bd4f6466265cad3d9da83ff0970ac87add16a72b646f406794792bae0f67a389 +size 31679 diff --git a/docs/tools/pluto-m2k/plutofirmwareversion.png b/docs/tools/pluto-m2k/plutofirmwareversion.png new file mode 100644 index 00000000..4b48da25 --- /dev/null +++ b/docs/tools/pluto-m2k/plutofirmwareversion.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a2089aa5bf9d6f655c0cb4e11a1dcff11d57ec17bbdc34f903ff65dd267ba965 +size 60912 diff --git a/docs/tools/pluto-m2k/reboot.rst b/docs/tools/pluto-m2k/reboot.rst new file mode 100644 index 00000000..33982055 --- /dev/null +++ b/docs/tools/pluto-m2k/reboot.rst @@ -0,0 +1,147 @@ +.. _pluto-m2k reboot: + +Rebooting +========= + +There are few different use cases, and methods to locally (USB/Serial), or +remotely (USB/Network) to reboot a Pluto/M2k. + +Pluto/M2k was designed never to have to be rebooted - but software bugs happen. +Before you reboot things - try to ask yourself "why", what went wrong, how do I +reproduce, and how can I file a bug report that will help someone debug. + +.. shell:: + + Welcome to: + ______ _ _ _________________ + | ___ \ | | | / ___| _ \ ___ \ + | |_/ / |_ _| |_ ___ \ `--.| | | | |_/ / + | __/| | | | | __/ _ \ `--. \ | | | / + | | | | |_| | || (_) /\__/ / |/ /| |\ \ + \_| |_|\__,_|\__\___/\____/|___/ \_| \_| + + v0.20 + http://wiki.analog.com/university/tools/pluto + + $device_reboot + Usage: /usr/sbin/device_reboot {ram|sf|reset|verbose|break} + sf : Reboot and enter Serial Flash DFU mode + ram : Reboot and enter RAM DFU mode + reset : Reboot + verbose: Reboot and start serial console Verbose + break : Reboot and HALT in u-boot + $ + +.. _pluto-m2k reboot dfu-ram: + +Reboot to DFU-RAM +----------------- + +.. shell:: + + $device_reboot ram + Stopping input-event-daemon: done + Stopping dropbear sshd: OK + Stopping MSD Daemon: OK + Stopping dhcpd Daemon & httpd Server: FAIL + Stopping network: OK + Stopping system message bus: done + Stopping UDC Gadgets + configfs-gadget gadget: unbind function 'rndis'/cbcaa480 + configfs-gadget gadget: unbind function 'Mass Storage Function'/cbc4e9c0 + configfs-gadget gadget: unbind function 'acm'/cc35e000 + configfs-gadget gadget: unbind function 'Function FS Gadget'/cc35e9e4 + Stopping logging: OK + umount: devtmpfs busy - remounted read-only + umount: can't unmount /: Invalid argument + The system is going down NOW! + Sent SIGTERM to all processes + Sent SIGKILL to all processes + Requesting system reboot + reboot: Restarting system + + U-Boot PlutoSDR v0.20-PlutoSDR-00041-g4bdff59 (Apr 19 2017 - 17:45:50 +0200) + + I2C: ready + DRAM: ECC disabled 512 MiB + SF: Detected N25Q256A with page size 256 Bytes, erase size 4 KiB, total 32 MiB + In: serial@e0001000 + Out: serial@e0001000 + Err: serial@e0001000 + Model: Zynq Pluto SDR Board + Hit any key to stop autoboot: 0 + Entering DFU RAM mode ... + Copying Linux from DFU to RAM... + +.. hint:: + + This specifies any shell prompt running on the development host. + +Following commands can be used to boot a fresh build of the firmware image. To +simply things, there is a script in :git-plutosdr_scripts:`plutosdr_scripts ` +``pluto_ramboot`` that can do all +these steps in one command. + +.. shell:: + + $sshpass -p analog ssh root@pluto '/usr/sbin/pluto_reboot ram;' + $sleep 5 + $sudo dfu-util -l + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to http:%%//%%sourceforge.net/p/dfu-util/tickets/ + + Found DFU: [0456:b674] ver=0221, devnum=11, cfg=1, intf=0, path="1-4", alt=1, name="firmware.dfu", serial="UNKNOWN" + Found DFU: [0456:b674] ver=0221, devnum=11, cfg=1, intf=0, path="1-4", alt=0, name="dummy.dfu", serial="UNKNOWN" + + $sudo dfu-util -d 0456:b673,0456:b674 -D ./build/pluto.dfu -a firmware.dfu + $sudo dfu-util -d 0456:b673,0456:b674 -a firmware.dfu -e + +Reboot to DFU-Flash +------------------- + +.. shell:: + + $device_reboot sf + Stopping input-event-daemon: done + Stopping dropbear sshd: OK + Stopping MSD Daemon: OK + Stopping dhcpd Daemon & httpd Server: FAIL + Stopping network: OK + Stopping system message bus: done + Stopping UDC Gadgets + configfs-gadget gadget: unbind function 'rndis'/df624600 + configfs-gadget gadget: unbind function 'Mass Storage Function'/cbc13600 + configfs-gadget gadget: unbind function 'acm'/cbc12780 + configfs-gadget gadget: unbind function 'Function FS Gadget'/cbc4e9e4 + Stopping logging: OK + umount: devtmpfs busy - remounted read-only + umount: can't unmount /: Invalid argument + The system is going down NOW! + Sent SIGTERM to all processes + Sent SIGKILL to all processes + Requesting system reboot + reboot: Restarting system + + U-Boot PlutoSDR v0.20-PlutoSDR-00041-g4bdff59 (Apr 19 2017 - 17:45:50 +0200) + + I2C: ready + DRAM: ECC disabled 512 MiB + SF: Detected N25Q256A with page size 256 Bytes, erase size 4 KiB, total 32 MiB + In: serial@e0001000 + Out: serial@e0001000 + Err: serial@e0001000 + Model: Zynq Pluto SDR Board + Hit any key to stop autoboot: 0 + Entering DFU SF mode ... + SF: Detected N25Q256A with page size 256 Bytes, erase size 4 KiB, total 32 MiB + +Reboot +------ + +.. shell:: + + $reboot diff --git a/docs/tools/pluto-m2k/screen_shot_2017-01-12_at_2.36.55_pm.png b/docs/tools/pluto-m2k/screen_shot_2017-01-12_at_2.36.55_pm.png new file mode 100644 index 00000000..0720a86f --- /dev/null +++ b/docs/tools/pluto-m2k/screen_shot_2017-01-12_at_2.36.55_pm.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:573b5ac9926cf540606ea472dd4ae0dd26eef847115da02d8c00d7c5f91b066e +size 81012 diff --git a/docs/tools/pluto-m2k/usb_otg_host.rst b/docs/tools/pluto-m2k/usb_otg_host.rst new file mode 100644 index 00000000..0afdcd0c --- /dev/null +++ b/docs/tools/pluto-m2k/usb_otg_host.rst @@ -0,0 +1,91 @@ +.. _pluto-m2k usb_otg_host: + +USB OTG – HOST function Support +=============================== + +When the device is powered from the Auxiliary Power Supply it support various +HOST functions, such as USB WIFI, Storage and HID. Using the correct cables is +the key to `OTG `__ operation. + +USB Wifi Support +---------------- + +PlutoSDR or M2k allows WIFI connectivity using ESSID and WPA-PSK passphrase. The +ESSID and Passphrase is set using the ``config.txt`` file in the Mass Storage +Device. The ESSID string is at most 32 alphanumeric characters, and the +passphrase is at least 8 and at most 63 ASCII characters. + +Supported WIFI chipsets +~~~~~~~~~~~~~~~~~~~~~~~ + +Linux supports a large number of USB 802.11 WIFI modules. Most of these also +require a firmware file to be available on the host device. Given the +constrained flash memory footprint of the device, the decision was made to +support only a number of popular Ralink and Realtek based chipset modules. This +includes also a few unstable drivers from the kernel staging area, so not all +modules will work equally well. + +Supported chipsets: + +- Ralink rt2501/rt61 +- Ralink rt73 +- Ralink rt27xx/rt28xx/rt30xx +- Realtek 81xx +- Realtek 87xx +- Realtek 88xx + +Many cheap and widely available modules will work - If you need a +recommendation. The models listed below have been tested: + +- TP-Link TL-WN725N Nano WLAN +- Cisco WUSB600N V2 + +USB Wired Ethernet Support +-------------------------- + +If you want to integrate the PlutoSDR or M2k into a wired Ethernet network +directly, without PC in between. Use a wired USB Ethernet adapter. Even though +the USB support on PlutoSDR or M2k is only USB 2.0 HIGH SPEED. It’s still +beneficial to purchase a USB 3.0 Gigabit Ethernet Adapter. Using those USB 3.0 +Gigabit Ethernet Adapters (in IIOD network back-end mode) the throughput can be +on par of with the IIOD USB back-end. + +Supported chipsets: + +- ASIX AX88xxx Based USB 2.0 Ethernet Adapters +- ASIX AX88179/178A USB 3.0/2.0 to Gigabit Ethernet +- Microchip LAN78XX Based USB Ethernet Adapters +- Realtek RTL8152/RTL8153 Based USB Ethernet Adapters +- SMSC LAN75XX based USB 2.0 gigabit ethernet devices +- SMSC LAN95XX based USB 2.0 10/100 ethernet devices + +Many cheap and widely available modules will work - If you need a +recommendation. The models listed below have been tested: + +- `Serach Amazon RTL8153 (USB 3.0 10/100/1000) `__ +- `Serach Amazon AX88772 (USB 2.0 10/100) `__ + +Mass Storage Drive Support +-------------------------- + +PlutoSDR or M2k allows in `OTG `__ +Host mode the attachment of USB Mass Storage Devices. The supported file system +is currently `FAT/FAT32 `__ +only. Kernel Hotplug mechanisms are used to automount the available partitions +under /media. Once the storage is mounted the LED1 will stay constantly ON. Upon +storage removal the media is un-mounted and the **LED1** will resume its +heartbeat flash. There is also a save unmount functionality implemented using +the :ref:`hidden button `. If pressed while a media +is mounted the media is unmounted and the **LED1** will also resume to heartbeat +flash. + +Someone may ask what’s the purpose of the USB Mass Storage Device Support? + +Auto Run Support +~~~~~~~~~~~~~~~~ + +After mounting the attached storage the filesystem root is scanned for files +named ``runme[XX][.sh]``. Where XX is optional or can be any decimal numbers +starting from 0..99. The number defines the sequence in which the scripts or +executables are executed. If the file extension is ``.sh`` the shell script is +sourced for speed. If no ``.sh`` extension a subprocess is forked. diff --git a/docs/tools/pluto-m2k/version_button.png b/docs/tools/pluto-m2k/version_button.png new file mode 100644 index 00000000..7013b824 --- /dev/null +++ b/docs/tools/pluto-m2k/version_button.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b0037c87761b6e12ce78ee6d359db3f9629999072b48742e56983ccd696c932a +size 38948 diff --git a/docs/tools/pluto-m2k/watch.png b/docs/tools/pluto-m2k/watch.png new file mode 100644 index 00000000..31a8175a --- /dev/null +++ b/docs/tools/pluto-m2k/watch.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:120d2f8e23d8754bbc624d06dbfd20293f8e97a77fbe37caedc2142d11d80b2f +size 225001 diff --git a/docs/tools/pluto-m2k/watch2.png b/docs/tools/pluto-m2k/watch2.png new file mode 100644 index 00000000..99d60e7e --- /dev/null +++ b/docs/tools/pluto-m2k/watch2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:31af7c5379ca6b1faf8997f87b3bb71415fc0f70ac58993c394583118e67f0d1 +size 217726 diff --git a/docs/tools/pluto-m2k/win10_gui_update.png b/docs/tools/pluto-m2k/win10_gui_update.png new file mode 100644 index 00000000..bdd7765b --- /dev/null +++ b/docs/tools/pluto-m2k/win10_gui_update.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bd3445b24ef9ca5e8ad7b4400bf554d2dade80c100097a752366d5b47bf20ecc +size 392154 diff --git a/docs/tools/pluto-m2k/win_your_device_is_ready_to_use.png b/docs/tools/pluto-m2k/win_your_device_is_ready_to_use.png new file mode 100644 index 00000000..7825659c --- /dev/null +++ b/docs/tools/pluto-m2k/win_your_device_is_ready_to_use.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:692bbf17eea9baf603a7b0186038ad40e56dcc31801388427f80108a33722df6 +size 18579 diff --git a/docs/tools/pluto/devs/index.rst b/docs/tools/pluto/devs/index.rst new file mode 100644 index 00000000..00be1d49 --- /dev/null +++ b/docs/tools/pluto/devs/index.rst @@ -0,0 +1,71 @@ +.. _pluto devs: + +For Developers +============== + +The people who typical read these pages are those who write custom software or +HDL (for the FPGA) that run directly on the Pluto device. This may put the Pluto +in different modes, and support different external USB devices (including +USB/LAB, or USB/WiFi), extending the capabilities of the device, or completely +changing the data that is transferred to the host. Since the goal of the project +is to keep things as open as possible, the details on how to compile kernels, +create bit files, assemble FIT files and load them into the device, should be +found here. + +While we do have a few examples, and show how to re-create the default software +loads, since this the hardware can be nearly a blank slate for your project, you +can do anything you want. + +Content +------- + +.. + Please make sure that all these are in ./devs + +#. Hardware + + #. :dokuwiki:`Detailed Specifications ` + #. :dokuwiki:`Schematics ` + #. :dokuwiki:`Detailed Performance ` + #. :dokuwiki:`Accessing FPGA JTAG ` with the + :dokuwiki:`ADALM-JTAGUART ` adapter + +#. C Applications or Shell scripts on the Pluto + + #. :dokuwiki:`Running Scripts from USB drive ` + #. :dokuwiki:`Creating compiled apps to run on-device ` + +#. :dokuwiki:`ADI Reference Designs HDL User Guide ` + + #. :dokuwiki:`AD9361 HDL reference design ` + #. :dokuwiki:`AXI_AD9361 ` + #. :dokuwiki:`High-Speed DMA Controller Peripheral ` + + + #. `AD9361 high performance, highly integrated RF Agile Transceiver™ Linux + device driver `__ + #. :dokuwiki:`AXI ADC HDL Linux Driver ` + #. :dokuwiki:`AXI DAC HDL Linux Driver ` + #. :dokuwiki:`AXI-DMAC DMA Controller Linux Driver ` + #. :adi:`ADM1177` Digital Power Monitor Linux Driver + #. etc. + +#. Building the Firmware image from source + + +#. :dokuwiki:`./devs/Controlling GPIOs ` +#. Accessing the AD9363 inside Pluto from userspace + + #. :git-libiio:`libiio local mode example ` + #. :dokuwiki:`Linux driver ` + +#. :dokuwiki:`Connecting the Pluto to the Internet ` +#. :dokuwiki:`Using U-Boot's DFU modes ` +#. :dokuwiki:`Boot magic explained ` +#. :dokuwiki:`Reboot Modes ` + +.. toctree:: + :hidden: + :glob: + + * diff --git a/docs/tools/pluto/devs/usb_otg.rst b/docs/tools/pluto/devs/usb_otg.rst new file mode 100644 index 00000000..b8c5ae8b --- /dev/null +++ b/docs/tools/pluto/devs/usb_otg.rst @@ -0,0 +1,115 @@ +.. _pluto devs usb_otg: + +USB OTG +======= + +The ADALM-PLUTO and ADLAM2000 support +`USB_On-The-Go `__. +This allows a few different use cases for these instruments. + +Running applications from USB drives +------------------------------------ + +The Pluto will automount any +`USB mass storage device `__ such as +`thumb drive `__ or +`Hard Drives `__. +The automounter will then look for some special file names: + +- ``runme[0-9].sh`` which it will run as a shell script +- ``runme[0-9]`` which it will run as a binary file. + +For those interested, it will do that via the automounter script in +``/lib/mdev/automounter.sh`` which is maintained +:git-buildroot:`here `. + +Note 1 : if you're editing the runme.sh file from windows, make sure you use +'LF' as file line ending. + +Note 2 : The power supply (and USB cable quality) of the ADALM-PLUTO have an +influence on the otg storage device plug detection. + +Basic Example +~~~~~~~~~~~~~ + +For those who just want to do something, create a ``runme0.sh`` file on a thumb +drive (FAT32 is fine) which looks like a normal unix +`shell script `__. +To debug your shell script, try your commands via ssh before putting them in the script. +This example requires at least firmware v0.22. + +.. code:: bash + + #!/bin/sh + + # the default directory the script runs in is /dev, so change to the drive + cd /media/sda1/ + + # create a file + touch foobar + + # change the RX_LO to 2.4GHz + iio_attr -a -c ad9361-phy RX_LO frequency 2400000000 + +and insert the USB thumb drive in to Pluto. + +The LED should stop blinking, and you have run your application. To safely +unmount the drive, you should press the button, which will cause the drive to by +sync'ed, file systems caches flushed, and properly unmount the drive. + +Advanced examples +~~~~~~~~~~~~~~~~~ + +Send a tone +^^^^^^^^^^^ + +The code below sets up a tone, and plays it out via the DDS (the AD9361's test +mode). It then unmounts the drive it is running on, so you can unplug the USB +drive. All that is necessary is to boot while the uSB drive is plugged in, and +that is it. This example requires at least firmware v0.22. + +.. code:: bash + + #!/bin/sh + + # the default directory the script runs in is /dev, so change to the drive + cd /media/sda1/ + + # create a file + touch foobar.txt + + echo default-on > /sys/class/leds/led0:green/trigger >> foobar.txt + + # Set the LO up + /usr/bin/iio_attr -a -c ad9361-phy TX_LO frequency 908460000 >> foobar.txt + + # Set the Sample frequency up, tone will appear at sampling_frequency/32 + /usr/bin/iio_attr -a -c -o ad9361-phy voltage0 sampling_frequency 32000000 >> foobar.txt + + # Turn the attenuation down + /usr/bin/iio_attr -a -c -o ad9361-phy voltage0 hardwaregain 0 + + # https://wiki.analog.com/resources/tools-software/linux-drivers/iio-transceiver/ad9361#bist_tone + # Inject 0dBFS tone at Fsample/32 into TX (all channels enabled) + /usr/bin/iio_attr -a -D ad9361-phy bist_tone "1 0 0 0" >> foobar.txt + + cd /root + + ACTION=remove_all /lib/mdev/automounter.sh + +Re purposing the button +^^^^^^^^^^^^^^^^^^^^^^^ + +The below script will change the function of the button. Rather than unmounting +things, it pressing the button will run a script. Holding the button for longer +than 5 seconds will unmount things. + +This requires a few different scripts, and modification of a configuration file. + +To manage the button, pluto uses the `input event daemon `__ +(`doc `__). +The default configuration file can be found at +:git-buildroot:`here `, +and simply calls the automounter (unmounter), when you press the button. Our +script kills that, and re-starts things with different configuration file (our +our mass storage device). diff --git a/docs/tools/pluto/hacking/back.png b/docs/tools/pluto/hacking/back.png new file mode 100644 index 00000000..43503848 --- /dev/null +++ b/docs/tools/pluto/hacking/back.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6e1062c5ef21dd6227648e5b8ace149769d4c61b0b8c513b861f484012c96674 +size 752603 diff --git a/docs/tools/pluto/hacking/button_plutosdr.png b/docs/tools/pluto/hacking/button_plutosdr.png new file mode 100644 index 00000000..e05380d7 --- /dev/null +++ b/docs/tools/pluto/hacking/button_plutosdr.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:882d9d703be15aa6ac2435410c7ca50d2a62fb25a3f83944ebf8094938a13c3d +size 4481363 diff --git a/docs/tools/pluto/hacking/button_side_plutosdr.jpg b/docs/tools/pluto/hacking/button_side_plutosdr.jpg new file mode 100644 index 00000000..57a94d96 --- /dev/null +++ b/docs/tools/pluto/hacking/button_side_plutosdr.jpg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6cd83963a6a24b354b0e5ca61d8e232ea679aa6116996b0be9cf2ea174c352cc +size 432544 diff --git a/docs/tools/pluto/hacking/gpo_rx_tx.png b/docs/tools/pluto/hacking/gpo_rx_tx.png new file mode 100644 index 00000000..8bb14397 --- /dev/null +++ b/docs/tools/pluto/hacking/gpo_rx_tx.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2b0aaedf399f55f4f9b9cd560581a9dc2b73f52ec7b1fb95a08c4d0159085804 +size 563025 diff --git a/docs/tools/pluto/hacking/hardware.rst b/docs/tools/pluto/hacking/hardware.rst new file mode 100644 index 00000000..a81dfb87 --- /dev/null +++ b/docs/tools/pluto/hacking/hardware.rst @@ -0,0 +1,336 @@ +.. _pluto hacking hardware: + +ADALM-PLUTO Hardware +==================== + +Whether you want to understand the changes between revisions, or just understand +how to probe the PCB, this is where all the information should be. + +.. _pluto hacking hardware connectors: + +Connectors +---------- + +The PlutoSDR includes a button (``S1`` on the PCB), and two USB connectors. + +.. image:: button_plutosdr.png + :width: 500px + +.. image:: button_side_plutosdr.jpg + :width: 450px + +The button can be defined by software, it is normally held on with a paper clip +or thumb tack during power on to put the device into a recovery mode. It can be +re-purposed to do other things. + +The first USB connector (the middle one) is the USB OTG connector (can be the +USB HOST connector (cabled to a USB peripheral), or the USB peripheral connector +(cabled to a USB Host)). + +The second USB connector (the one on the side) is for power only when running in +Host mode. + +Removing the case +----------------- + +.. image:: back.png + :width: 200px + +The plastic case comes off quite easily, with the removal of two +black `Phillips `__ +screws on the bottom of the case. This is a picture of the pre-production Rev B +boards. The production version may be different. +It will for sure be :dokuwiki:`CE and FCC certified ` +(already passed). + +Removing the screws will allow you to take the top off the case, and expose the +PCB. + +If you want to remove the PCB, and place it on the table, we recommend that you +attach +`Cylindrical Bumpers `__ +(also known as feet), on +the PCB to protect the components on the bottom of the PCB. These are not +included in the design, and must be purchased separately (as we don't expect too +many people wanting to do this). + +Revisions +--------- + +Different revisions of the PlutoSDR does not include any major functionality +changes, and there is no difference for end users (there may be minor internal +feature changes). While it is natural to want the "latest" version, there is no +:adi:`specified ` +functionality changes. All revisions are: + +- 1x Rx SMA, Tuning from 325 MHz to 3.8 GHz, 200 kHz - 20 MHz of instantaneous + bandwidth +- 1x Tx SMA, Tuning from 325 MHz to 3.8 GHz, 200 kHz - 20 MHz of instantaneous + bandwidth +- 1x USB 2.0 OTG +- 1x USB power adapter +- Linux / libIIO based software stack, compatible with MATLAB, Simulink, GNU + Radio, Python, and others. + +.. important:: + + When you order from ADI's + :adi:`authorized channels `, + you may get any revision listed below; there is no way to order one specific + revision (it's a single part number), so do not ask - it's not possible. + *Normally* inventory is managed via a FIFO (First In; First Out) mechanism, so + the oldest inventory is shipped when an order is placed. However - warehouses + have been known to misplace a box, and ship older inventory later. + +If you really want to purchase a specific version - I'm sorry. There is no way. +That's just what you read in the paragraph above. Emailing anyone to ask for a +specific version will just get the same answer, and will consume everyone's +time. Please don't do it. + +Which revision do I have? +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are three ways to tell which revision you have (and they should all +match): + +Look at the sticker +^^^^^^^^^^^^^^^^^^^ + +It's printed on the back of the Pluto SDR (on the sticker) the below in Rev B: + +.. image:: pluto_sticker.png + :width: 200px + +info.html page +^^^^^^^^^^^^^^ + +In the ``file:///D:/info.html#version`` page, it will tell you (assuming that +your Pluto SDR drive is "D"): + +.. image:: pluto_info_version.png + :width: 600px + +.. image:: pluto_info_version_c.png + :width: 600px + +Take it apart and look +^^^^^^^^^^^^^^^^^^^^^^ + +The PCBs are slightly different (these pictures are the top sides). + +.. image:: pluto_b.png + :width: 200px + +.. image:: pluto_c.png + :width: 195px + +If you look close, the revision of the PCB is etched in metal on the side +(Zoomed in for clarity). + +.. image:: pluto_b_zoom.png + :width: 200px + +.. image:: pluto_c_zoom.png + :width: 195px + +Revision D +---------- + +Revision C was never released, and was identical to rev C (minus 2 blue +wires [1]_), so we are only releasing rev D info. Since firmware is the same +between rev D and C, the firmware identifies and recognizes rev D hardware as +rev ``C``. + +Revision D started showing up in the wild early 2021. + +New Rev D features +~~~~~~~~~~~~~~~~~~ + +There are new internal rev D features: + +- addition of internal `U.FL `__ + connectors for: + + - second receive channel + - second transmit channel + - Clock input + - Clock output (only a copy of Clock input, not functional for the internal + clock) + +- USB UART +- breakout pins for I2C and SPI +- 3.3V GPO levels + +u.FL to SMA cables can be picked up for a few dollars at a variety of locations +including +`Digkey `__, +`Mouser `__, +`AdaFruit `__ or +`Sparkfun `__. + +.. image:: pluto.png + :width: 600px + +The standard features - Rx1, Rx2, USB OTG work as previously. See how to add +these to your units, check out how to +:dokuwiki:`set config settings `. + +.. video:: https://www.youtube.com/watch?v=ph0Kv4SgSuI + + Enable Dual Receive and Dual Transmit for the new revision of Pluto + +With a few more holes in the case, and a few dollars of cables, this should give +you something like (this connects the additional Rx and Tx, and CLK input): + +.. image:: pluto_with_wires.png + :width: 400px + +.. admonition:: Download + + - :dokuwiki:`Rev D Schematics <_media/university/tools/pluto/hacking/plutosdr_schematic_revd_0.1.pdf>` + - :dokuwiki:`Rev D Gerbers <_media/university/tools/pluto/hacking/plutosdr_gerber_revd.zip>` + - :dokuwiki:`Rev D Bill of materials <_media/university/tools/pluto/hacking/plutosdr_bom_revd.xlsx>` + - :dokuwiki:`Rev D Allegro Board File <_media/university/tools/pluto/hacking/plutosdr_brd_revd.zip>` + `compressed `__). Get the `Allegro FREE + Physical Viewer `__ + to view. + - :dokuwiki:`Rev D Cadence Project <_media/university/tools/pluto/hacking/plutosdr_cadence_revd.zip>` + `compressed `__) + - :dokuwiki:`Rev B 3D model (Case, bare PCB, connectors) <_media/university/tools/pluto/hacking/pluto_revb_3d.zip>` + versions. + - There are few pictures of rev D in the :dokuwiki:`Marketing ` section + as well. + +The 2nd Rx/Tx channel internal to the rev D is not test during production test. +If it works - bonus! If it doesn't work; Pluto is only advertised as a 1 Rx, 1 +Tx radio, and that is guaranteed/production tested on each unit - and that is +what you received. + +Why Do a rev E? +--------------- + +Don't know yet - we will keep track of the list here. + +Revision B +---------- + +.. admonition:: Download + + .. important:: + + Although the below files indicates the + Xilinx ``XC7Z010-1CLG225C`` is used in the PlutoSDR, it is actually the Xilinx + ``XC7Z010-1CLG225C4334`` (a single core version before the 7007 was released). + We keep using the "special" version. If you are starting a new design - use the + ``XC7Z007S-1CLG225C``. + + - :dokuwiki:`Rev B Schematics <_media/university/tools/pluto/hacking/plutosdr_schematic_revb.pdf>` + - :dokuwiki:`Rev B Gerbers <_media/university/tools/pluto/hacking/plutosdr_gerber_revb.zip>` + - :dokuwiki:`Rev B Bill of materials <_media/university/tools/pluto/hacking/plutosdr_bom_revb.xls>` + - :dokuwiki:`Rev B Allegro Board File <_media/university/tools/pluto/hacking/plutosdr_brd_revb.zip>` + `compressed `__). Get the `Allegro FREE + Physical Viewer `__ + to view. + - :dokuwiki:`Rev B Cadence Project <_media/university/tools/pluto/hacking/plutosdr_cadence_project_revb.zip>` + - :dokuwiki:`Rev B 3D model (Case, bare PCB, connectors) <_media/university/tools/pluto/hacking/pluto_revb_3d.zip>` + - There are few pictures of rev B in the :dokuwiki:`Marketing ` section + as well. + +Why do a Rev C? +~~~~~~~~~~~~~~~ + +- our "low-risk" OTG changes, caused problems, since we put the VBUS monitoring + (R88) on the wrong side of the fuse, and the inclusion of the DC choke. While + the DC choke reduces noise, and there is no DC difference between PGDN, and + GND, on certain hosts, with certain operating systems, there can be a 250mV + AC difference between PGND and GND. Since the analog comparators inside the + Microchip USB3320 will be referenced to GND (quiet), it appears to toggle + between host mode and device mode. A temp workaround was to change this + resistor (R88) from the recommended USB spec of 1k to 24.9k. R88 can be found + on the back side, underneath the USB connector. + + .. image:: pluto_r88.png + :width: 500px + +- We also had issue on ESD testing, and will be adding an ESD protection to the + RF connector. +- As a cost optimization (and feature enhancement), we may redo some of the + power section (replacing the NCP339AFCT2G, ADM1177, with the + `LTC4413 `__) - this is + still TBD based on lab work to be done. One of the usability issues - is that + the 2 NCP339AFCT2G devices are designed to be break before make - which + causes the power supply to reset if you plug the ADALM-PLUTO into a PC (which + causes it to boot), and then eventually a power supply (which causes the + supply to disappear for a small time, and then re-appear). We don't think + this is a huge issue, but it would be enhance the usability. It would mean + however, that we loose the ability to read USB voltage/current (which we + currently do in the :adi:`ADM1177`. +- :ez:`Request ` to pin out the 2nd channel with + pads/footprints. + +Revision A +---------- + +.. admonition:: Download + + - :dokuwiki:`Rev A Schematics <_media/university/tools/pluto/hacking/plutosdr_schematic_reva.pdf>` + - :dokuwiki:`Rev A Gerbers <_media/university/tools/pluto/hacking/plutosdr_gerber_reva.zip>` + - :dokuwiki:`Rev A Bill of materials <_media/university/tools/pluto/hacking/plutosdr_bom_reva.xls>` + - :dokuwiki:`Rev A Allegro Board File <_media/university/tools/pluto/hacking/plutosdr_brd_reva.zip>` + `compressed `__). Get the `Allegro FREE + Physical Viewer `__ + to view. + +Why do a Rev B? +~~~~~~~~~~~~~~~ + +- RF performance was bad. (EVM was poor, ~-32dBm; goal was -45dBm). This was + due to the Rakon oscillator having no PPSR [2]_, and us powering the + oscillator directly from a 1.8V digital rail (which was noisy). A LDO was + `dead bugged `__ + onto rev A, and it fixed the performance problem. We tried a few L/C & + ferrites, but it was not as good as the LDO, so we added an ultralow noise + LDO, the :adi:`ADM7160ACPZN1.8 ` to the design. +- RF performance was bad on certain PCs, even with with the added LDO (above). + This was tracked down to to noise on the power supply. We added a power choke + (DLW5BSM801TQ2L), and this went away, and we got much better results + independent of platform. +- Power supply noise was a little higher than we would have liked, and was + effecting RF performance, so sync'ed the multiple switchers together to + reduce input ripple. This also allowed us to reduce input capacitance on the + entire unit. +- were barely passing FCC, (due to noise @ 480MHz, which was also causing some + RF issues at 480 MHz), so added DLW21HN900SQ2L (90Ω choke) on the USB lines. +- swapped QSPI flash and DDR3L devices, to something not on the obsolete list. +- based on early end user feedback, added some test points to unused pins to + make extending the device a little easier. +- based on early end user feedback, added On-The-Go support for USB. This was + some minor power circuit, and monitoring VBUS, so was looked at as "low risk" + +Datasheets +---------- + +Here are some pointers to datasheets that are sometimes hard to find. + +- `Rakon `__ :dokuwiki:`1.8V RXO3225M 40MHz <_media/university/tools/pluto/hacking/rakon_rxo3225m_40mhz_513371_1.8v.pdf>` + +Before PlutoSDR +--------------- + +Like all things, PlutoSDR is a integration/copy/paste of previous known working +platforms. There were a few different AD936x /Zynq platforms that were worked on +that we borrowed things from: + +- :dokuwiki:`FMCOMMS3 FMC Card `, + which includes the baluns/RF and connection back to the Zynq +- :dokuwiki:`FMCOMMS5 FMC Card `, + which is where we borrowed the (buggy) oscillator design, since the AD9363 + can not be used with a crystal. +- PicoZed SDR (which is were most of the Zynq and USB comes from). + +.. [1] + Always doublecheck if UART ``Tx`` should be connected to ``Tx`` or ``Rx`` of + the next chip, English nomenclature is terrible + +.. [2] + Power Supply Rejection Ratio diff --git a/docs/tools/pluto/hacking/index.rst b/docs/tools/pluto/hacking/index.rst new file mode 100644 index 00000000..5a31f134 --- /dev/null +++ b/docs/tools/pluto/hacking/index.rst @@ -0,0 +1,41 @@ +.. _pluto hacking: + +For Hackers +=========== + +`Hacking `__ the ADALM-PLUTO is +possible (and encouraged). In this case - what we mean by *hacking* is the act +of programming or extending the functionality or use cases of the PlutoSDR, in a +spirit of playfulness and exploration. In order to do that, you should be +familiar with the device, from a :ref:`user ` and +:ref:`developer ` standpoint. + +Many aspects of the PlutoSDR are based from the +:dokuwiki:`AD-FMCOMMS3-EBZ `, and you +should be familiar with that, as it will help understand how to extend the +PlutoSDR. + +#. :ref:`pluto hacking hardware` +#. :ref:`Picking up yourself by accident ` +#. :ref:`Controlling an external Power Amp ` +#. :ref:`Help and Support ` + + +.. toctree:: + :hidden: + :glob: + + * + +Resources For Building Your Own SDR +----------------------------------- + +Hopefully you have reviewed the documentation on the +:dokuwiki:`AD9361 `, and the +:dokuwiki:`FMCOMMS2 `, +:dokuwiki:`FMCOMMS3 `, +:dokuwiki:`FMCOMMS4 `. +Those guides provide alot of background on the combination of the :adi:`AD9361`, +:adi:`AD9363`, or :adi:`AD9364` and the Xilinx Zynq. + +#. :dokuwiki:`Testing ` the ADALM-PLUTO SDR. diff --git a/docs/tools/pluto/hacking/listening_to_yourself.rst b/docs/tools/pluto/hacking/listening_to_yourself.rst new file mode 100644 index 00000000..bf6f13ac --- /dev/null +++ b/docs/tools/pluto/hacking/listening_to_yourself.rst @@ -0,0 +1,167 @@ +.. _pluto hacking listening_to_yourself: + +Self Reception +============== + +Everyone has sung to a song on the radio, and it sounds great, as long as the +radio is loud enough to drown out your terrible voice (or is that just me?). +This is a phenomenon known as self reception - when the signal you want to +receive is being overloaded by something else. + +The ADALM-PLUTO can do this too if you are not careful. The device will have Tx +LO Leakage, and the receiver will pick that up and may swamp out the signal you +desire to actually receive. + +Tx On, and sending a signal +--------------------------- + +It's easy to see this with offset tuning. Here is the ADALM-PLUTO with the Rx +set to 2400 MHZ, and the Tx set to 2402 MHz, with the internal DDS, set to 3 +MHz, and -30dB down (which would put things at 2405 MHz), with the default +antennas connected, and the LTE20 Filters loaded. + +.. image:: tx_lo_dds.png + :width: 600px + +This shows the peak at the signal (at 2405 MHz, where we expect it), and a LO +leakage at 2402 MHz. It's difficult to see what this really means in terms of +signal power, so we can look at the actual gain is set to by the Automatic Gain +Control (AGC), and the Receive Signal Strength Indicator (RSSI). + +.. image:: tx_lo_dds_rx1.png + :width: 200px + +We can see the RSSI is 66.25 dB, and the Hardware Gain is set to 43 dB. + +Tx On, and not sending a signal +------------------------------- + +If we simply disable the DSS, this is what we see: + +.. grid:: + :widths: 50 50 + + .. image:: tx_lo_leakage.png + :width: 600px + + .. image:: tx_lo_leakage_rx1.png + :width: 200px + +Now our RSSI has gone to 90.5 dB and the hardware gain is set to 68 dB (which is +still not at the max gain of the device), we are listening to our own LO +leakage, not the actual RF signal. + +Tx Off +------ + +If we power down the Tx LO with (``0`` is on, ``1`` is powerdown): + +.. shell:: + :no-path: + + $iio_attr -c ad9361-phy TX_LO powerdown 1 + dev 'ad9361-phy', channel 'altvoltage1' (output), id 'TX_LO', attr 'powerdown', value '0' + wrote 2 bytes to powerdown + dev 'ad9361-phy', channel 'altvoltage1' (output), id 'TX_LO', attr 'powerdown', value '1' + +This is the equivalent C source of: + +.. code:: c + + / Create IIO Context / + ctx = iio_create_context_from_uri("usb:1.3.5"); + + / Find IIO device in current context / + dev = iio_context_find_device(ctx, "ad9361-phy"); + + / Find the IIO output channel in the current device / + ch = iio_device_find_channel(dev, "TX_LO", true); + + / Write a one into the IIO channel attribute / + ret = iio_channel_attr_write_longlong(dev, "powerdown", 1); + +Then we get: + +.. grid:: + :widths: 50 50 + + .. image:: tx_lo_off.png + :width: 500px + + .. image:: tx_lo_off_rx1.png + :width: 200px + +Tx On, but offset more than your channel +---------------------------------------- + +If we shift things around a bit - if we configure things for an LTE10 signal, +(LTE10 filter, with an LTE10 signal going out the DAC at full scale), and set +the Tx and Rx to the same (2400 MHz), we can see this: + +.. grid:: + :widths: 50 50 + + .. image:: tx_lo_lte10.png + :width: 500px + + .. image:: tx_lo_lte10_rx1.png + :width: 200px + +By offsetting things in 10 MHz steps, how far do things need to be away, so that +it stops affecting the receiver: + +.. list-table:: + :header-rows: 1 + + - - offset + - 0 MHz + - 10 MHz + - 20 MHz + - 30 MHz + - 40 MHz + - 50 MHz + - 60 MHz + - - RSSI + - 48.50 dB + - 86.75 dB + - 105.00 dB + - 112.75 dB + - 116.75 dB + - 117.00 dB + - 117.5 dB + - - ACG Gain + - 25 dB + - 32 dB + - 59 dB + - 62 dB + - 67 dB + - 69 dB + - 71 dB + +This doesn't mean that you can't transmit/receive on adjacent channels, it just +means that the receiver noise floor will not be higher and therefore the +receiver will not appear as sensitive when you are doing this. + +Conclusion +---------- + +If you aren't using the transmitter - turn it off, your receiver noise floor +will decrease, increasing your receive sensitivity, allowing you to pick up +smaller signals from the air. + +.. list-table:: + :header-rows: 1 + + - - Test Case + - RSSI + - AGC Setting + - - Tx On, with Signal + - 66.25 dB + - 43 dB + - - Tx On, without signal + - 90.50 dB + - 68 dB + - - Tx Off + - 113.75 dB + - 71 dB + diff --git a/docs/tools/pluto/hacking/pluto.png b/docs/tools/pluto/hacking/pluto.png new file mode 100644 index 00000000..12bfec04 --- /dev/null +++ b/docs/tools/pluto/hacking/pluto.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9d29550cc7e74e9f8113e63c503e5e8b49624379fb294b26246bb1c7ae467f93 +size 560229 diff --git a/docs/tools/pluto/hacking/pluto_b.png b/docs/tools/pluto/hacking/pluto_b.png new file mode 100644 index 00000000..b614ea01 --- /dev/null +++ b/docs/tools/pluto/hacking/pluto_b.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2eb6dded8268252a776f5bce3594aa9b76d9a9ae5cabd0022ca81ae9369031c3 +size 8958190 diff --git a/docs/tools/pluto/hacking/pluto_b_zoom.png b/docs/tools/pluto/hacking/pluto_b_zoom.png new file mode 100644 index 00000000..cec0132d --- /dev/null +++ b/docs/tools/pluto/hacking/pluto_b_zoom.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8c8159d2d63b6a794261ee0bea74e6ffa94340a11c6b722d21a6cd1c8a228c69 +size 1342798 diff --git a/docs/tools/pluto/hacking/pluto_c.png b/docs/tools/pluto/hacking/pluto_c.png new file mode 100644 index 00000000..9ca8b3f8 --- /dev/null +++ b/docs/tools/pluto/hacking/pluto_c.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5dc128c3d11c416841458889d24c54c17d5e284c209eb597143e46174532b5cd +size 6731486 diff --git a/docs/tools/pluto/hacking/pluto_c_zoom.png b/docs/tools/pluto/hacking/pluto_c_zoom.png new file mode 100644 index 00000000..cda7ba9d --- /dev/null +++ b/docs/tools/pluto/hacking/pluto_c_zoom.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:406f229d020a9f6a0b5f1aa082089bdf3667495adc3cb65c13652bb9e5277d4c +size 830606 diff --git a/docs/tools/pluto/hacking/pluto_gpo_pins.png b/docs/tools/pluto/hacking/pluto_gpo_pins.png new file mode 100644 index 00000000..27f10860 --- /dev/null +++ b/docs/tools/pluto/hacking/pluto_gpo_pins.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1f6a70924f5dc817d6a0536d72d07b81f2064cb8eb81daced72ba1cafa8136d0 +size 508221 diff --git a/docs/tools/pluto/hacking/pluto_info_version.png b/docs/tools/pluto/hacking/pluto_info_version.png new file mode 100644 index 00000000..8bd96916 --- /dev/null +++ b/docs/tools/pluto/hacking/pluto_info_version.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:66dc40133f924d08709bd821bf98d3c87bcd6242358b16e491fdc958f50e57d3 +size 107778 diff --git a/docs/tools/pluto/hacking/pluto_info_version_c.png b/docs/tools/pluto/hacking/pluto_info_version_c.png new file mode 100644 index 00000000..c18b3a26 --- /dev/null +++ b/docs/tools/pluto/hacking/pluto_info_version_c.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:157cfa83338251d0154a1b8c5f2bca86a04f330214a2857a160821439967a6b0 +size 110042 diff --git a/docs/tools/pluto/hacking/pluto_r88.png b/docs/tools/pluto/hacking/pluto_r88.png new file mode 100644 index 00000000..67d1ea75 --- /dev/null +++ b/docs/tools/pluto/hacking/pluto_r88.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:45d7a038a4eccf754dd3a4712c715f69dd91d26ae6537d762f1bd9b978eac0a7 +size 734530 diff --git a/docs/tools/pluto/hacking/pluto_sticker.png b/docs/tools/pluto/hacking/pluto_sticker.png new file mode 100644 index 00000000..a5a487bd --- /dev/null +++ b/docs/tools/pluto/hacking/pluto_sticker.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:24db22f05e047ff558a3fe4fc7027ea3409a3a5677a9974de10857af8f9db183 +size 1726798 diff --git a/docs/tools/pluto/hacking/pluto_with_wires.png b/docs/tools/pluto/hacking/pluto_with_wires.png new file mode 100644 index 00000000..f17bbff5 --- /dev/null +++ b/docs/tools/pluto/hacking/pluto_with_wires.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ea47bdf8c5ce0bf41e8313291400fc31e2fde208fa8ed0f07d53e904a9ae97b2 +size 6964801 diff --git a/docs/tools/pluto/hacking/power_amp.rst b/docs/tools/pluto/hacking/power_amp.rst new file mode 100644 index 00000000..6920a7f3 --- /dev/null +++ b/docs/tools/pluto/hacking/power_amp.rst @@ -0,0 +1,281 @@ +.. _pluto hacking power_amp: + +Controlling External Devices +============================ + +While this was requested to better understand how to control external power +amplifiers for various software to implement +`push to talk `__ (PTT), and ensure the PA +was off during the Rx portion, this is good practice for any application which +is just doing Rx or just doing Tx for best performance. Even you you are not +concerned about controlling external devices, this may be a good read for some +(just skip the GPO discussions). + +There are two ways to implement General Purpose Output (GPO), Automatically (the +easy way), or Software Controlled (which is handled later). + +Background +---------- + +The :adi:`AD9363` transceiver inside the ADALM-PLUTO includes an +Enable State Machine (ENSM) that allows real time control over the current state +of the device. The device can be placed in several different states during +normal operation, including: + +- Wait — power save, synthesizers disabled +- Sleep — wait with all clocks and the BB PLL disabled +- Time Division Duplex (TDD) Tx — Tx signal chain enabled (Rx signal chain + powered down) +- Time Division Duplex (TDD) Rx — Rx signal chain enabled (Tx signal chain + powered down) +- Frequency Division Duplex (FDD) — Tx and Rx signal chains enabled, where both + Tx and Rx can be used simultaneously at different frequencies. +- Alert — synthesizers enabled + +In this document, we will mainly focus on the Frequency Division Duplex (FDD) +mode and the Time Division Duplex (TDD) Tx & Rx modes. + +While the default settings are FDD mode (where Tx and Rx signal chains are +always enabled), there are many use cases where TDD (Time Division Duplex) mode +is beneficial. The ENSM has two control modes (1) SPI control and (2) pin +control. If the TDD is a slotted system, where μsecond timing requirements must +be met, pin control from a FPGA based state machine is normally used. When the +TDD system is random, or push to talk, SPI control is possible. In SPI control +mode, the ENSM is controlled asynchronously by writing to SPI registers to +advance the current state to the next state. SPI control is considered +asynchronous to the device or sample clock because the SPI clock can be derived +from a different clock reference and can still function properly. The SPI +control ENSM mode is recommended when real-time control of the synthesizers is +not necessary. + +The AD9363 also include 4 ``GPO_[0:3]`` General-Purpose Output pins. These are +general-purpose logic output pins. These pins are designed to control other +peripheral devices such as regulators/switches via the SPI bus, or they function +as slaves for the internal AD9363 state machine. They can be configured to +assert when the the Rx or Tx is active. + +More information about the :adi:`AD9363` can be found on the product +page. + +ADALM-PLUTO implementation +-------------------------- + +VDD_GPO +~~~~~~~ + +The power connected to the ``VDD_GPO`` pin is 1.3 V The output voltage on the +``GPO_[0:3]`` pins is expected to be ``VDD_GPO × 0.8`` (1.04 V) and ``VDD_GPO`` +(1.30 V). With an output current of 10 mA (typical). The off resistance of the +GPO pins is 15 Ω. The on resistance of the GPO pins is 32 Ω. If you connect +regulators or switches, it may need to be level shifted/have the drive strength +increased to achieve the proper voltage control thresholds. + +With the 1.3 V ``VDD_GPO`` net, it is known/understood that the AUX_ADC and +AUX_DAC will not be functional. + +Pinout +~~~~~~ + +The :ref:`schematic ` connects the ``GPO_[0:3]`` pins to ``GPO[0:3]`` +nets and test points. + +.. image:: pluto_gpo_pins.png + :width: 400px + +Just connect these ``GPO[0:3]`` pins to whatever you need to control. + +Software +~~~~~~~~ + +There is a setup portion (if you are unsure of what these attributes do, check +out the +:dokuwiki:`documentation ` [1]_ : + +#. set up the part in TDD mode (``0`` is TDD mode, ``1`` is FDD mode): + + .. shell:: + + $iio_attr -a -D ad9361-phy adi,frequency-division-duplex-mode-enable 0 + +#. set up ``GPO_0`` to assert when in Tx mode + + .. shell:: + + $iio_attr -a -D ad9361-phy adi,gpo0-slave-tx-enable 1 + +#. write the new configuration to the part + + .. shell:: + + $iio_attr -a -D ad9361-phy initialize 1 + +Verify the setup is in TDD mode, by checking the ``ensm_mode_available`` +attribute, and making sure it includes ``rx`` and ``tx`` and not ``fdd``. + +.. shell:: + + $iio_attr -a -d ad9361-phy ensm_mode_available + dev 'ad9361-phy', attr 'ensm_mode_available', value :'sleep wait alert rx tx pinctrl' + +Then there is a run time configuration that is needed. + +#. To set the part into Receive only mode: + + .. shell:: + + $iio_attr -a -d ad9361-phy ensm_mode rx + +#. To set the part into Tx only mode: + + .. shell:: + + $iio_attr -a -d ad9361-phy ensm_mode tx + +When you change from Rx mode to Tx mode, any of the four pins will +assert/de-assert. + +.. important:: + + It should be noted that trying to capture a buffer (ie Rx) while + in Tx mode will pause/hang until timed out. And sending a buffer (Tx) while in + Rx mode will also pause/hang. Cancelling things will return. + +There is a short bash script that shows how to use pin control from userspace: +:git-linux_image_ADI-scripts:`test_ensm_pinctrl.sh` + +Test Results +~~~~~~~~~~~~ + +A small script on the Pluto SDR (or host) will demonstrate: + +.. code:: bash + + #!/bin/sh + + # Setup : Put into TDD mode, and setup GPO0 and GPO1 + iio_attr -q -a -D ad9361-phy adi,frequency-division-duplex-mode-enable 0 + iio_attr -q -a -D ad9361-phy adi,gpo0-slave-rx-enable 1 + iio_attr -q -a -D ad9361-phy adi,gpo1-slave-tx-enable 1 + iio_attr -q -a -D ad9361-phy initialize 1 + + while [ 1 ] ; do + iio_attr -q -a -d ad9361-phy ensm_mode rx + # capture buffer + iio_attr -q -a -d ad9361-phy ensm_mode tx + # transmit buffer + done + +by placing a scope on the GPO0 and GPO1 pins, you can see the levels switch, as +the Pluto transitions between Receive and Transmit. + +.. image:: gpo_rx_tx.png + :width: 600px + +.. tip:: + + While this shows the Rx/Tx switching in 30-35ms or so, this is + based on software control over SPI, running in an interpreted bash shell. Doing + things in a C application, would make things faster, and doing things via pin + control (via a state machine in the FPGA) can make things sub ~30 μs between Rx + and Tx swaps to handle slotted specifications like LTE. IF you need things to go + faster - just ask. + +OK, someone asked for the C code - it's pretty trivial, just longer. You will +need to change the uri, and put in proper error checking. + +.. code:: c + + #include + #include + #include + #include + #include + + + volatile sig_atomic_t stop = 0; + + void inthand(int signum) { + stop = 1; + } + + int main(int argc, char argv) + { + struct iio_context ctx; + struct iio_device dev; + struct iio_channel ch; + const char val_str; + ssize_t ret = 0; + char buf[256]; + + signal(SIGINT, inthand); + + / Create IIO Context / + ctx = iio_create_context_from_uri("usb:1.3.5"); + + / Find IIO device in current context / + dev = iio_context_find_device(ctx, "ad9361-phy"); + + / Write into the IIO debug attributes / + iio_device_debug_attr_write_bool(dev, "adi,frequency-division-duplex-mode-enable", 0); + iio_device_debug_attr_write_bool(dev, "adi,gpo0-slave-rx-enable", 1); + iio_device_debug_attr_write_bool(dev, "adi,gpo1-slave-tx-enable", 1); + iio_device_debug_attr_write_bool(dev, "initialize", 1); + + while (!stop) { + ret++; + iio_device_attr_write(dev, "ensm_mode", "rx"); + iio_device_attr_write(dev, "ensm_mode", "tx"); + } + iio_context_destroy(ctx); + printf("iteration = %li\n", ret); + return EXIT_SUCCESS; + } + +Over USB, you get: + +:: + + time ./foo + ^Citteration = 2693 + + real 0m5.283s + +or about 0.980876346 ms per Rx/Tx slot. + +.. list-table:: + :header-rows: 1 + + - - Platform + - transport + - Infrastructure + - Timing + - - host + - USB + - shell + - 80ms + - - host + - USB + - C code + - 0.6 to 1.3 ms + - - pluto + - local + - shell + - 30-35ms + - - pluto + - local + - C Code + - 0.2 to 0.6 ms + +Again, these are representative numbers for software control, faster is possible +with pin control. + +Testing in IIO Oscilloscope +--------------------------- + +The :dokuwiki:`Advanced Tab ` +indicates how to control these in the IIO oscilloscope. + +.. [1] + If you want to delay the assertion of these pins by ``n`` μs, that can be + done with the ``gpo0-rx-delay-us`` or ``gpo0-tx-delay-us`` attributes (which + we don't cover here diff --git a/docs/tools/pluto/hacking/tx_lo_dds.png b/docs/tools/pluto/hacking/tx_lo_dds.png new file mode 100644 index 00000000..f8d90630 --- /dev/null +++ b/docs/tools/pluto/hacking/tx_lo_dds.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ffd8c911b0de4d383c5a3a97b13b76042dc4236f9257b0dcedbeef47209935d6 +size 448951 diff --git a/docs/tools/pluto/hacking/tx_lo_dds_rx1.png b/docs/tools/pluto/hacking/tx_lo_dds_rx1.png new file mode 100644 index 00000000..7ec067c8 --- /dev/null +++ b/docs/tools/pluto/hacking/tx_lo_dds_rx1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f12bfcea02ea0b84a8e48689d5c157b7d506c9185fa7549d2ae353c54ae97170 +size 51245 diff --git a/docs/tools/pluto/hacking/tx_lo_leakage.png b/docs/tools/pluto/hacking/tx_lo_leakage.png new file mode 100644 index 00000000..45d40094 --- /dev/null +++ b/docs/tools/pluto/hacking/tx_lo_leakage.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:37c6f0094a1f1b2f4dd7d58921af7b3158d485d4ad84cf3b9620e8715a9da721 +size 415816 diff --git a/docs/tools/pluto/hacking/tx_lo_leakage_rx1.png b/docs/tools/pluto/hacking/tx_lo_leakage_rx1.png new file mode 100644 index 00000000..ee8849e6 --- /dev/null +++ b/docs/tools/pluto/hacking/tx_lo_leakage_rx1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:351bd0800f18aad372fd18215dd651634dfc8bd3c6b4b3bae6aaba1820d06e0b +size 51536 diff --git a/docs/tools/pluto/hacking/tx_lo_lte10.png b/docs/tools/pluto/hacking/tx_lo_lte10.png new file mode 100644 index 00000000..f7ec7dec --- /dev/null +++ b/docs/tools/pluto/hacking/tx_lo_lte10.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:95f3bb609208a6fc22049863c891ba4c6dbd0f1a503a7c1130b6257d2182d51c +size 452900 diff --git a/docs/tools/pluto/hacking/tx_lo_lte10_rx1.png b/docs/tools/pluto/hacking/tx_lo_lte10_rx1.png new file mode 100644 index 00000000..a73fc318 --- /dev/null +++ b/docs/tools/pluto/hacking/tx_lo_lte10_rx1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2305090261876a5f5656cc9c7d0d4ca26fc961ae1fde1d3df4d79d702f892b27 +size 60076 diff --git a/docs/tools/pluto/hacking/tx_lo_off.png b/docs/tools/pluto/hacking/tx_lo_off.png new file mode 100644 index 00000000..ccb07e42 --- /dev/null +++ b/docs/tools/pluto/hacking/tx_lo_off.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b951d63439d039da99fdfde61629f9b4e0e008c3ef80fb864fd2161d625e0c0a +size 466929 diff --git a/docs/tools/pluto/hacking/tx_lo_off_rx1.png b/docs/tools/pluto/hacking/tx_lo_off_rx1.png new file mode 100644 index 00000000..9bddd6bb --- /dev/null +++ b/docs/tools/pluto/hacking/tx_lo_off_rx1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a2a6f6b6e397564b30427db19a195c3a6435de13541fbe8eeffdb0b9f08c10b3 +size 57672 diff --git a/docs/tools/pluto/help_support.rst b/docs/tools/pluto/help_support.rst new file mode 100644 index 00000000..22c35306 --- /dev/null +++ b/docs/tools/pluto/help_support.rst @@ -0,0 +1,118 @@ +.. _pluto help_support: + +Support +======= + +If you have any questions regarding the ADALM-PLUTO (PlutoSDR) or are +experiencing any problems following the user guides, or experiments feel free to +ask us a question. Questions can be asked on our :ez:`EngineerZone support community `, +specifically the :ez:`Virtual Classroom `. +Calling on the phone, emailing someone directly, will only cause things to get +answered in much slower manner - if at all. + +Before asking questions please also take the time to check if somebody else +already asked the same question and already got an answer. EngineerZone is a big +place, with lots of places to post questions, and it's possible to ask a +question in the wrong place, where no one familiar with these +boards/parts/software monitors things, and it will go unanswered forever. Don't +get mad if this happens. The problem is between the chair and the keyboard +(you). If you are posting in the right place, and the question is unanswered for +a few working days, please bump the thread (we are human, and sometimes miss +things). + +End user/Student questions should always be posted in the +:ez:`Virtual Classroom `. If you are not sure where to +post your question, post it there, and we can move it around for you. + +As you transition from user to hacker to developer to SDR engineer, and dig +deeper into the stack (and we encourage that), you may have further questions +about why we did something, to save a little time, you may want to triage your +own question, and just post it in the right place, to save us the time of moving +things. (you will get answers faster). + +Linux Driver or libiio or Application Questions +----------------------------------------------- + +For questions regarding the the ADI Linux distribution used in PlutoSDR (which +is based `buildroom `__ with +:ref:`libiio` library, the Linux +drivers (including the :dokuwiki:`AD936x driver `, or +the device trees for PlutoSDR, please use the +:ez:`Linux Software Drivers ` +sub-community. + +If you have generic userspace questions (*how do I use a standard linux tool*), +we should suggest to use your favorite `search tool `__ +to find that tool/utility/application support method (some use email, some use +web). If you think you have found a bug specific to ARM, please report this to +the package maintainers upstream. + +HDL / Vivado WebPack Questions +------------------------------ + +For questions regarding the PlutoSDR HDL design please ask them in the +:ez:`FPGA Reference Designs ` sub-community. If you have questions +about the Vivado HL WebPACK Edition, including any questions about compiling the +design with please go ask `Xilinx `__. + +Hardware Questions +------------------ + +For questions regarding the PlutoSDR hardware (schematic or layout) please ask +them in the :ez:`Virtual Classroom `. +sub-community. That is where the folks who designed and laid out the PCB hang +out. + +General AD9361 Questions +------------------------ + +Questions about the AD9361 or AD9364, please use the +:ez:`AD9361 ` +sub-community. + +Detailed documentation on the AD9361 device can be found at: +:adi:`AD9361 Design support package ` + +AD9361/4 FIR Filter Wizard +-------------------------- + +Questions about the :dokuwiki:`AD936x FIR Filter Wizard ` can be +asked on :ez:`Analog Devices Filter Wizard Support support `. + +MATLAB/Simulink/RF Blockset Questions +------------------------------------- + +Questions about the AD936x RF Blockset model from MathWorks, or the PlutoSDR +Hardware support package can be asked either: + +- :mw:`MathWorks Technical Support ` + +Questions about the Analog Devices provided Filter Wizard, or streaming system +object, or Board Support Package can be asked: + +- :ez:`Analog Devices MATLAB/Simulink support ` + +GNU Radio and Python +-------------------- + +Questions about using the PlutoSDR with GNU Radio or python, can be asked on +Analog Devices' :ez:`Software Tools ` sub-community. +Generic questions about GNU Radio should be asked on their `mailing list `__. + +Bugs / Feature Requests +----------------------- + +If you think you have a bug to report, the best place to to this is the +:ez:`Virtual Classroom `. +This way we can discuss if the +bug is a bug, or a feature request, or just missing documentation. + +If you think you have a real bug, where you have developed a real fix (first - +thanks), feel free to: + +#. post something on engineerzone +#. post something on the github issue tracker +#. `Fork `__ the github + repository, and fix it, and then send a pull request + +Either is OK with us. diff --git a/docs/tools/pluto/index.rst b/docs/tools/pluto/index.rst new file mode 100644 index 00000000..0fe47e88 --- /dev/null +++ b/docs/tools/pluto/index.rst @@ -0,0 +1,121 @@ +.. _pluto: + +ADALM-PLUTO +""""""""""" + +.. toctree:: + :hidden: + :glob: + + */index + * + +.. image:: pluto_in_hand.png + :width: 250px + :align: right + +.. + TODO Create buy role + +The :adi:`ADALM-PLUTO` Active Learning Module (PlutoSDR) +`Buy `__ +is an easy to use tool available from Analog Devices +Inc. (ADI) that can be used to introduce fundamentals of +`Software Defined Radio (SDR) `__ or +`Radio Frequency (RF) `__ or +`Communications `__ as +advanced topics in electrical engineering in a self or instructor lead setting. +The PlutoSDR allows students to better understand the real-world RF around them, +and is applicable for all students, at all levels, from all backgrounds. Early +learning in a hands-on manner with the PlutoSDR will ensure a solid foundation +for students to build on, as they pursue science, technology, or engineering +degrees. + +The PlutoSDR Active Learning Module is a tool that closes the relationship +between theory and practical radio frequency activities of the user. It provides +a personal portable lab that, when used with a host, can augment the learning +that takes place in the classroom. A variety of software packages such as MATLAB +or Simulink provide an innovative graphical user interface (GUI), allowing +intuitive usage and minimizing the learning curve, enabling students to learn +faster, work smarter, and explore more! + +The :adi:`ADALM-PLUTO` Active Learning Module is a learning tool +for everyone. + +Based on the :adi:`AD9363`, it offers one receive channel and one +transmit channel which can be operated in full duplex, capable of generating or +measuring RF analog signals from 325 to 3800 MHz, at up to 61.44 Mega Samples +per Second (MSPS) with a 20 MHz bandwidth. The PlutoSDR is completely +self-contained, fits nicely in a shirt pocket or backpack, and is entirely USB +powered with the default firmware. With support for OS X™, Windows™, and Linux™, +it allows exploration and understanding of RF systems no matter where the user +is or when. + +Introduction +============ + +PlutoSDR is a self-contained RF lab in your hand. It's more than the combination +of a few parts, but to understand the capabilities of the module, you must +understand the fundamental operation of each part inside the module. Depending +on who you are, and what you want to do, you may have different needs, different +wants, and will use different software. It's expected that many people will stop +when they solve their immediate problem and don't want to go any deeper into the +stack. Before digging into the documentation, check out the module +:ref:`prerequisites `, and try to think about how you will +use the ADALM-PLUTO. + +.. tip:: + + PlutoSDR will populate as a Mass Storage Device when plugged into a + computer. The presented storage device contains a getting started guide + (info.html), configuration control for your device (config.txt), and licensing + information (LICENSE.html). + +#. :ref:`PlutoSDR Users & students ` + + - PlutoSDR users normally interact with RF signals with + :mw:`MATLAB, Simulink `, + :dokuwiki:`GNU Radio ` or + :ref:`custom C, C++ `, + :git-libiio:`C# `, + or :ref:`Python environment ` on a + host (x86) Windows, Linux or Mac or embedded Linux platform + (`Raspberry Pi `__, + `Beaglebone `__, + `96boards.org `__, insert your favorite embedded + Linux platform) over USB. + - If you want to see how to :ref:`generate or capture RF waveforms `, + this is the place. + - Everyone should read this section, as it describes the device, and + describes how to get the drivers and host software installed properly. + - Most users should find all the information they need in this section. + +#. :ref:`HDL and Embedded Software Resources `: + + - This material is for those who normally write custom software or HDL (for + the FPGA) that runs directly on the PlutoSDR. This may put the PlutoSDR in + different modes, and support different external USB devices (including LAN + (via USB), or WiFi (via USB)), extending the capabilities of the device. + This includes all the information to compile HDL projects, compile + kernels, change to custom USB PID/VID and/or run custom user space + applications. For example, you could set up: + + - a standalone airplane tracking station which communicates to the + internet via Wifi or LAN. + - a mobile terminal to emulate someone else's keyboard. + +#. :ref:`PCB and Layout Resources `: + + - This section may be useful for those taking the PCB out of the case and + making hardware modifications, or connecting GPIO to different devices, or + attempting to synchronize multiple PlutoSDRs together. Since this is + pretty wide open, we don't have any examples of this - but we do provide + the info needed, including all the schematics and layout. + +It's expected that most people will work their way down through each section, +reading and skimming most of the content. The content is in a constant state of +improvement, so if you do have a question, please ask at +:ez:`EngineerZone `, +or check the :ref:`help and support ` page. + +.. esd-warning:: diff --git a/docs/tools/pluto/pluto_in_hand.png b/docs/tools/pluto/pluto_in_hand.png new file mode 100644 index 00000000..7b76db40 --- /dev/null +++ b/docs/tools/pluto/pluto_in_hand.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6c6de262f0953c725b202178750309ada30ecb3414ad4ef598d2bf86a26044c8 +size 566024 diff --git a/docs/tools/pluto/prerequisites.rst b/docs/tools/pluto/prerequisites.rst new file mode 100644 index 00000000..3464f4a6 --- /dev/null +++ b/docs/tools/pluto/prerequisites.rst @@ -0,0 +1,160 @@ +.. _pluto prerequisites: + +Prerequisites +============= + +To understand what the prerequisites are for using the ADALM-PLUTO (PlutoSDR), +you need to understand what you are trying to do, and what software environment +you want to do it in. The PlutoSDR is a powerful/flexible device, which can be +used both in a standalone mode, or with a host, in multiple different software +environments. The one that is *best* is unique to the problem at hand, so we +don't specifically recommend a single solution. This page discusses both +hardware and software options, and lists the most common [1]_ configurations: + +The PlutoSDR supports USB 2.0 On-The-Go (OTG), and can be used in two different +modes: + +#. device, where the PlutoSDR communicates directly to a host, and streams data + from/to the host. + + - Host with at least one USB 2.0 Port, which can supply 500mA (no self + powered hubs), which runs Linux, OS X, or Windows + + - example: Personal Computer, Laptop, Tablet (running Linux), Raspberry + Pi, Beagle Board, etc. + - The only thing necessary is the included USB cable. If you need + something longer, it should work, but has not been tested. + +#. host, where the PlutoSDR is the "brains" of the system, and communicates to + other things via USB Wifi or USB Ethernet. + + - You need a USB OTG Cable, compatible USB dongle, and a USB Power supply + (must be purchased separately) + +You will also need an appropriate antenna for the frequency that you are +interested in. Although there is an :ref:`antenna ` included with +the purchase of the ADALM-PLUTO, it may not be appropriate for the frequency +that you are interested in (anything under 350 MHz). + +PlutoSDR as a Device +-------------------- + +You can stream data to any of these visualization tools, or SDR frameworks. + +IIO Oscilloscope +~~~~~~~~~~~~~~~~ + +The :ref:`iio-oscilloscope` is a +simple visualization tool that can be used with the PlutoSDR to control the +device and stream data into/output the device. + +It can be run on Linux and Windows (and soon MAC). + +MATLAB / Simulink +~~~~~~~~~~~~~~~~~ + +#. You need to have a license for MATLAB® and/or Simulink®. + + - Depending on who you are, and where you are, you already may have access + to a license. + + - If you are a student or faculty at a post-secondary institution + (University, Community College, etc), check out MathWorks + :mw:`Academic ` section. Many schools provide a + :mw:`Total Academic Headcount (TAH) ` + license or some require/ask their students to obtain :mw:`Student version ` [2]_ + - If you are a hobbyist, enthusiast or maker, check out :mw:`MATLAB Home `. + - There are many license options, if you are unsure, check out the + MathWorks `store ` + + - You need to have a host computer, which supports the minimum :mw:`System Requirements for MATLAB `. + - No matter which license you have [3]_, the following toolboxes are + required to use MATLAB with the PlutoSDR: + + - :mw:`DSP System Toolbox ` + - :mw:`Signal Processing Toolbox ` + - :mw:`Communications System Toolbox ` + + - You also will need a :mw:`supported and compatible compiler `, many which are zero cost, or + free. + - We have verified things on a subset of what MATHWORKS supports, including + Windows 10, Windows 8.1, Windows 8, Windows 7 Service Pack 1, macOS Sierra + 10.12, macOS El Capitan 10.11, macOS Yosemite 10.10, Ubuntu 14.04 LTS and + 16.04 LTS, Debian 7.x, 8.x. + +GNU Radio +~~~~~~~~~ + +#. GNU Radio is mostly a + `Linux `__ only tool. It + can be run on + `Windows `__, but + we have not tested in there. + + - We have verified things on Ubuntu 16.04 LTS, Debian 8.x and updated + versions. + +PlutoSDR as a host +------------------ + +To use PlutoSDR as a host, there are two different modes: + +#. Simple, easy, works out of the box. +#. Complex, difficult, requires you to recompile the firmware running on the + PlutoSDR. + +Either mode requires a power supply plugged into the Power USB connector, which +can provide power for both the USB dongle you are plugging in, and the Pluto SDR +itself. We recommend at least 5V, 1A or above, depending on the firmware image. + +#. AC adapters we have verified: + + - Farnell's `5.1V, 2.5A, Micro USB `__ + with international plugs + - Adafruit's `5V, 1A USB port `__ + `NEMA 1-15 `__ + plug, requires USB cable + - Adafruit's `5V, 2.4A Power Supply with MicroUSB Cable `__, + `NEMA 1-15 `__ plug + +#. Batteries we have verified: + + - Adafruit's `USB Battery Pack, 2.2 Ah, 5V @ 1A `__ + - Adafruit's `USB Battery Pack, 4 Ah, 5V @ 1A `__ + - Adafruit's `USB Battery Pack, 10 Ah, 5V @ 2A `__ + +Simple Host +~~~~~~~~~~~ + +The default firmware images supports a variety of USB devices including +:ref:`mass storage devices `, +some :ref:`Ethernet and WiFi devices ` +(but not all, since each takes up space in the firmware). + +You should be able to just plug things in with a OTG adapter or cable (which +supports OTG - many OTG cables don't properly connect the OTG ID signal, and the +PlutoSDR has no idea anything is plugged in), and have things work out of the +box to stream data over ethernet or Wifi. + +If the PlutoSDR finds a mass storage with specific shell or python script, it +will begin to save data to the mass storage device (enabling you to do low cost +`wireless site surveys `__), +which you can load into SDR frameworks later. + +Complex hosts +~~~~~~~~~~~~~ + +Almost every device which you can plug into a Linux host, you will be able to +plug into a PlutoSDR with a kernel re-compile. check out the +:ref:`Developers ` information. + +.. [1] + not all possible configurations are listed + +.. [2] + If you have MATLAB Student edition, you will need the optional + :mw:`Communications System Toolbox ` + +.. [3] + to check your installed/licensed toolboxes, type the ``ver`` + :mw:`command ` at a MATLAB command prompt diff --git a/docs/tools/pluto/transceiver_transferring_data.rst b/docs/tools/pluto/transceiver_transferring_data.rst new file mode 100644 index 00000000..f4e30aea --- /dev/null +++ b/docs/tools/pluto/transceiver_transferring_data.rst @@ -0,0 +1,127 @@ +.. _pluto transceiver_transferring_data: + +Controlling the transceiver and transferring data +================================================= + +PlutoSDR runs `Linux `__. +The :ref:`device drivers ` allowing you to control the +transceiver and capture samples are therefore part of to the Linux Industrial IO +(IIO) framework. IIO is a kernel subsystem for analog to digital or digital to +analog converters and related hardware. IIO communicates with user space via +`sysfs `__ and a character devices. From a +plain user interaction point of view this is quite intuitive, since everything +is just a file. However when controlling the device from software, this can be +quite painful, since you simple want to call a function or method, instead of +doing string manipulation and file IO. LibIIO fills this gap, provides all sorts +of device abstraction and handles all kind of IIO internals. LibIIO is cross +platform and also provides different language bindings, so that you can control +IIO devices from C, C++, C# or Python. + +If you’re not familiar with IIO, please start reading here: + +- :ref:`libiio` +- :ref:`libiio internals` +- `IIO Linux Kernel Documentation sysfs-bus-iio-\* `__ +- `IIO Documentation `__ +- `IIO High Speed `__ +- `Video from FOSDEM of how IIO is used in SDR applications `__ + +.. video:: https://www.youtube.com/watch?v=p_VntEwUe24 + + LibIIO - A Library for Interfacing with Linux IIO Devices - Dan Nechita, Analog Devices Inc + +Controlling the transceiver +--------------------------- + +The code snippet below is a minimalistic example without error checking. It +shows how to control the AD936x transceiver via a remote connection. + +#. Create IIO IP Network context. Instead of ``ip:xxx.xxx.xxx.xxx`` it'll also + accept ``usb:XX.XX.X`` +#. Get the AD936x PHY device structure +#. Set the TX LO frequency (see :dokuwiki:`AD9361 device driver documentation `) +#. Set RX baseband rate + +.. code:: c + + #include + + int main (int argc, char **argv) + { + struct iio_context *ctx; + struct iio_device *phy; + + ctx = iio_create_context_from_uri("ip:192.168.2.1"); + + phy = iio_context_find_device(ctx, "ad9361-phy"); + + iio_channel_attr_write_longlong( + iio_device_find_channel(phy, "altvoltage0", true), + "frequency", + 2400000000); /* RX LO frequency 2.4GHz */ + + iio_channel_attr_write_longlong( + iio_device_find_channel(phy, "voltage0", false), + "sampling_frequency", + 5000000); /* RX baseband rate 5 MSPS */ + + receive(ctx); + + iio_context_destroy(ctx); + + return 0; + } + +Receiving data +-------------- + +#. Get the RX capture device structure +#. Get the IQ input channels +#. Enable I and Q channel +#. Create the RX buffer +#. Fill the buffer +#. Process samples + +.. code:: c + + int receive(struct iio_context *ctx) + { + struct iio_device *dev; + struct iio_channel *rx0_i, *rx0_q; + struct iio_buffer *rxbuf; + + dev = iio_context_find_device(ctx, "cf-ad9361-lpc"); + + rx0_i = iio_device_find_channel(dev, "voltage0", 0); + rx0_q = iio_device_find_channel(dev, "voltage1", 0); + + iio_channel_enable(rx0_i); + iio_channel_enable(rx0_q); + + rxbuf = iio_device_create_buffer(dev, 4096, false); + if (!rxbuf) { + perror("Could not create RX buffer"); + shutdown(); + } + + while (true) { + void *p_dat, *p_end, *t_dat; + ptrdiff_t p_inc; + + iio_buffer_refill(rxbuf); + + p_inc = iio_buffer_step(rxbuf); + p_end = iio_buffer_end(rxbuf); + + for (p_dat = iio_buffer_first(rxbuf, rx0_i); p_dat < p_end; p_dat += p_inc, t_dat += p_inc) { + const int16_t i = ((int16_t*)p_dat)[0]; // Real (I) + const int16_t q = ((int16_t*)p_dat)[1]; // Imag (Q) + + /* Process here */ + + } + } + + iio_buffer_destroy(rxbuf); + + } diff --git a/docs/tools/pluto/users/antennas.rst b/docs/tools/pluto/users/antennas.rst new file mode 100644 index 00000000..f4e4b2df --- /dev/null +++ b/docs/tools/pluto/users/antennas.rst @@ -0,0 +1,75 @@ +.. _pluto users antennas: + +Antennas +======== + +The antennas connectors on the ADALM-PLUTO are standard polarity +`SubMiniature version A `__ (SMA) connectors. +There are many ways to +`characterize `__ an antenna, +from gain (or loss), radiation pattern, beamwidth, polarization, and impedance. + +The actual antennas included with the ADALM-PLUTO are +`Jinchang Electron `__ JCG401. +While the JCG401 is specified for 824-894 and 1710-2170MHz, they do +operate over a much wider range, but it should be understood that all antennas +are filters. They will have some frequency selectivity (however, they are not +brick wall filters). Just because something is specified for 824 MHz, does not +mean that it will not pick up something at 600MHz, or even 87MHz, or it might +not. + +The +:dokuwiki:`JCG401 datasheet <_media/university/tools/pluto/users/jcg401.pdf>`. +does spec radiation pattern, beamwidth, polarization, and +impedance, but leaves out performance (gain or loss) over frequency - since it +is spec'ed for 824-894 and 1710-2170MHz. We can quickly do that ourselves with +the help of a `E5071C ENA Series Network Analyzer `__. +We connect the two antennas to the two ports, calibrate with a wire, and then run a S\ :sub:`21` test. + +`S-parameters `__ describe +the input-output relationship between ports (or terminals) in an electrical +system. For instance, if we have 2 ports (intelligently called Port 1 and Port +2), then S\ :sub:`12` represents the power transferred from Port 2 to Port 1. +S\ :sub:`21` represents the power transferred from Port 1 to Port 2. In general, +S\ :sub:`NM` represents the power transferred from Port M to Port N in a +multi-port network. For an excellent side view into antennas check out Peter +Joseph Bevelacqua's excellent reference: http://antenna-theory.com + +Running an S\ :sub:`21` test on the E5071C will broadcast a tone from one +antenna (on port 2), and receive it on the other (port 1), and plot the results +(in dB) compared to a wire that was used during the calibration on the +instrument. It's interesting note that we are measuring both Rx and Tx +capabilities. It is possible that the Rx at sub 600MHz could be fine, and it is +just a Tx problem (unlikely, but I just wanted to point it out). + +.. image:: jcg401_full_range.png + :width: 500px + +You can see thing over 625 MHz, the antenna has pretty good performance, with +the exception of a tight notch at 1.12 GHz. This means unless you are really +close to an FM broadcast station, you will not be able to receive FM with this +antenna. (it has been done, and it does work - it just limits the distance +between you and the antenna. Remember that most terrestrial FM broadcast +stations are 10,000 to 20,000 watts). + +At the popular `ISM bands `__ of 900 +MHz, 2400 MHz, and 5725 MHz, performance is quite good. (click on the image to +make it larger). + +.. grid:: + :widths: 50 50 + + .. figure:: jcg401_900ism.png + :width: 400px + + 902 - 928 MHz ISM Band + + .. figure:: jcg401_2400ism.png + :width: 400px + + 2.4 -2.5 GHz ISM Band + + .. figure:: jcg401_5725ism.png + :width: 400px + + 5.725 - 5.875 GHz ISM Band diff --git a/docs/tools/pluto/users/index.rst b/docs/tools/pluto/users/index.rst new file mode 100644 index 00000000..06b8f680 --- /dev/null +++ b/docs/tools/pluto/users/index.rst @@ -0,0 +1,80 @@ +.. _pluto users: + +For End Users +============= + +.. image:: ../pluto_in_hand.png + :width: 200px + :align: right + +Everyone using Pluto should read these pages. They will demonstrate how to +interact with RF signals with MATLAB, Simulink, GNU Radio or custom C, C++, C#, +or Python code on a host (x86) or embedded (Raspberry Pi, Beaglebone, +96boards.org, etc.) platform over USB. As you can see, we have lots of examples +with MATLAB and Simulink, as we find that a very powerful environment, and a +path to a releasable radio (you can take your algorithms, and easily embed them +into a custom product). + +Contents +-------- + +.. + Make sure all things are in ./users + +#. :dokuwiki:`Introduction to the Hardware ` + + #. :dokuwiki:`What's with the name? ` *PlutoSDR?* + #. :dokuwiki:`Understanding the Internals ` + #. :dokuwiki:`How hot? ` + #. :dokuwiki:`How Far, How fast? ` + + #. :dokuwiki:`RF Output ` + + #. :dokuwiki:`Phase Noise & Accuracy ` + + #. :dokuwiki:`RF Input ` + + #. :dokuwiki:`Receiver Sensitivity ` + #. :dokuwiki:`Dealing with Non-Quadrature signals ` + + #. :dokuwiki:`Antennas ` + #. :dokuwiki:`Letter of Volatility ` + +#. :dokuwiki:`Quick Start ` +#. Intro to the Software. Installing Device Drivers on: + + #. :ref:`Windows ` + #. :ref:`Linux ` + #. :ref:`MAC ` + +#. Upgrading the the ADALM-PLUTO :dokuwiki:`Firmware ` . +#. :dokuwiki:`Calibrating ` the ADALM-PLUTO. +#. :dokuwiki:`Customizing ` the ADALM-PLUTO. +#. Once the driver are configured and set up, you can interact with the + :adi:`ADALM-PLUTO` Active Learning Module from: + + #. :dokuwiki:`IIO oscilloscope ` + #. `gqrx `__, an open source software defined radio receiver + (SDR) powered by the GNU Radio + #. :mw:`Official support for MATLAB and Simulink ` + #. :dokuwiki:`MATLAB IIO Bindings ` + #. :dokuwiki:`GNU Radio ` + #. `SDRangel `__, an Open Source Qt5 / + OpenGL 3.0+ SDR and signal analyzer frontend to various hardware. + #. `SDR# `__. The PlutoSDR frontend for + SDRsharp can be found here: + `sdrsharp-plutosdr `__ + #. `SoapySDR `__. The Soapy SDR + plugin for PlutoSDR can be found here: + `SoapyPlutoSDR `__ + #. `Access and control of PlutoSDR hardware using python bindings to libiio `__ + #. :dokuwiki:`Python Interfaces ` + #. :dokuwiki:`C Examples ` + +#. :dokuwiki:`/university/tools/pluto/Accessories ` + +.. toctree:: + :hidden: + :glob: + + * diff --git a/docs/tools/pluto/users/jcg401_2400ism.png b/docs/tools/pluto/users/jcg401_2400ism.png new file mode 100644 index 00000000..79538f80 --- /dev/null +++ b/docs/tools/pluto/users/jcg401_2400ism.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e72ebbf1484230a35e4098506da6c41eb17ff5fef65d73aec6ad12ab31afb49e +size 42552 diff --git a/docs/tools/pluto/users/jcg401_5725ism.png b/docs/tools/pluto/users/jcg401_5725ism.png new file mode 100644 index 00000000..a4c355c8 --- /dev/null +++ b/docs/tools/pluto/users/jcg401_5725ism.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:104238f360c672da862ab84c8d7c16b682027d65aa4aaa062c55be2d60b5b6cc +size 42272 diff --git a/docs/tools/pluto/users/jcg401_900ism.png b/docs/tools/pluto/users/jcg401_900ism.png new file mode 100644 index 00000000..ec8250b7 --- /dev/null +++ b/docs/tools/pluto/users/jcg401_900ism.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ed2bb5df82fce23668a0b533b6c457fcdd871854b733d86acd1c09741d814635 +size 41983 diff --git a/docs/tools/pluto/users/jcg401_full_range.png b/docs/tools/pluto/users/jcg401_full_range.png new file mode 100644 index 00000000..f206f05d --- /dev/null +++ b/docs/tools/pluto/users/jcg401_full_range.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ba4c056ede348e91eb1f6d0a93ccd2e498e31bac5b9bbad997239c5b6c8d8b09 +size 50424 diff --git a/docs/tools/uartjtag/adalm-uartjtag.png b/docs/tools/uartjtag/adalm-uartjtag.png new file mode 100644 index 00000000..3886bf2d --- /dev/null +++ b/docs/tools/uartjtag/adalm-uartjtag.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bee931a7c5a820bee23e2610fb761c7231b46c12c736a5ceb806fd4c5c1aeb53 +size 660822 diff --git a/docs/tools/uartjtag/index.rst b/docs/tools/uartjtag/index.rst new file mode 100644 index 00000000..d56b208a --- /dev/null +++ b/docs/tools/uartjtag/index.rst @@ -0,0 +1,92 @@ +.. _uartjtag: + +ADALM-UARTJTAG +============== + +.. image:: adalm-uartjtag.png + :width: 400px + :align: right + :alt: ADLAM-UARTJTAG photo + +In a few of the designs we have done, like the +:ref:`pluto` and :ref:`m2k` there hasn't been enough room on the +PCB for serial and JTAG, so we put it on a small breakout board, which +communicates to the main platform with a small 10-pin ribbon cable, which is +known as the :adi:`ADALM-UARTJTAG`. + +This includes the Silicon Labs +`CP2103-GM `__ +USB to UART bridge, which you can plug a USB cable into. + +This also includes connection to Xilinx JTAG cable as well. You will need a +:xilinx:`Xilinx JTAG Cable ` or +`equivalent `__ to use +it. + +Hardware +-------- + +Analog Devices provides a small adapter board +:adi:`ADALM-UARTJTAG` to be used for JTAG and UART, in order +to make that easier for programming and debugging. You are encouraged to use +this on your designs for the same reason we do - the standard JTAG connector is +huge, and there are times where good old fashion console UART is valuable for +doing debug. The 1.8V supply on the connector above is the I/O voltage, and can +be used anywhere between 1.8V and 3.3V. + +In the box, you should have received the UARTJTAG board, ribbon cable, and +jumper. + +.. image:: adalm-uartjtag.png + :width: 400px + +The PCB includes a jumper, which forces the Zynq to HALT on JTAG. This is great +for halting, and not allowing anything to run, but does pull down a chip select +for SPI flash, and will not allow the SPI flash to be found by the on-chip +bootloader, or by U-Boot. (If you are loading a U-Boot over JTAG). + +The pin connector is likely inserted into the ribbon cable: + +.. grid:: + :widths: 50 50 + + .. image:: uartjtagcablepluspins2.png + :width: 300px + + .. image:: uartjtagcablepluspins.png + :width: 200px + +but can be removed, and either soldered to the PCB, or left in the ribbon cable, +so you don't lose it. + +.. image:: uartjtagcable.png + :width: 300px + +If you do want more, they can be obtained from +`Samtec `__, +`Digikey `__ or +`Arrow `__. + +Anyone is free to use the same pinout on their platform - or copy the schematics +and make it themselves. + +Schematic, PCB Layout, Bill of Materials +---------------------------------------- + +.. admonition:: Download + + :adi:`ADALM-UARTJTAG Design & Integration Files ` + + - Schematic + - PCB Layout + - Bill of Materials + - Allegro Project (get the `Allegro FREE Physical Viewer `__ + to view) + +Device Driver +------------- + +.. admonition:: Downlaod + + `CP2103 Drivers `__ + diff --git a/docs/tools/uartjtag/uartjtagcable.png b/docs/tools/uartjtag/uartjtagcable.png new file mode 100644 index 00000000..7eb3739a --- /dev/null +++ b/docs/tools/uartjtag/uartjtagcable.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:42d81383c141915018276a4ed4e485292485fb0e9db77f666d554b58c205e916 +size 662228 diff --git a/docs/tools/uartjtag/uartjtagcablepluspins.png b/docs/tools/uartjtag/uartjtagcablepluspins.png new file mode 100644 index 00000000..054d2a2c --- /dev/null +++ b/docs/tools/uartjtag/uartjtagcablepluspins.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c8b2780778d8c7ad306e5a2131f3565df7872918dfed8b4424a8766e95885f09 +size 652585 diff --git a/docs/tools/uartjtag/uartjtagcablepluspins2.png b/docs/tools/uartjtag/uartjtagcablepluspins2.png new file mode 100644 index 00000000..0a55e823 --- /dev/null +++ b/docs/tools/uartjtag/uartjtagcablepluspins2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:08ac259df50e704d207c62f2d5857a87bde1b4783e0801f0c70dafd9b60579f8 +size 373971