Update documentation to 46b1f6a

analogdevicesinc · Jan 11, 2024 · d19262b · d19262b
commit d19262b
Show file tree

Hide file tree

Showing 2,988 changed files with 205,982 additions and 0 deletions.
diff --git a/_images/ad4130_hardware_connections.png b/_images/ad4130_hardware_connections.png
diff --git a/_images/ad4130_sensor_demo_console.png b/_images/ad4130_sensor_demo_console.png
diff --git a/_images/ad7606_auto_open_circuit.png b/_images/ad7606_auto_open_circuit.png
diff --git a/_images/ad7606_diagnostic_mux.png b/_images/ad7606_diagnostic_mux.png
diff --git a/_images/ad7606_gain_calibration.png b/_images/ad7606_gain_calibration.png
diff --git a/_images/ad7606_hardware_connections.png b/_images/ad7606_hardware_connections.png
diff --git a/_images/ad7606_manual_open_circuit.png b/_images/ad7606_manual_open_circuit.png
diff --git a/_images/ad7606_offset_calibration.png b/_images/ad7606_offset_calibration.png
diff --git a/_images/ad7689_hardware_connections.png b/_images/ad7689_hardware_connections.png
diff --git a/_images/ad77681_hardware_connections1.png b/_images/ad77681_hardware_connections1.png
diff --git a/_images/ad77681_hardware_connections2.png b/_images/ad77681_hardware_connections2.png
diff --git a/_images/app_interface.png b/_images/app_interface.png
diff --git a/_images/environmental_variables.png b/_images/environmental_variables.png
diff --git a/_images/flexible_iio_ecosystem.png b/_images/flexible_iio_ecosystem.png
diff --git a/_images/iio_data_capture_in_firmware.png b/_images/iio_data_capture_in_firmware.png
diff --git a/_images/iio_osc_connect_window.png b/_images/iio_osc_connect_window.png
diff --git a/_images/iio_osc_data_save.png b/_images/iio_osc_data_save.png
diff --git a/_images/iio_osc_dmm_tab.png b/_images/iio_osc_dmm_tab.png
diff --git a/_images/iio_osc_freq_domain_plot.png b/_images/iio_osc_freq_domain_plot.png
diff --git a/_images/iio_osc_high_frequency_graph.png b/_images/iio_osc_high_frequency_graph.png
diff --git a/_images/iio_osc_select_chn_samples.png b/_images/iio_osc_select_chn_samples.png
diff --git a/_images/iio_osc_sine_wave_capture.png b/_images/iio_osc_sine_wave_capture.png
diff --git a/_images/iio_osc_tabs.png b/_images/iio_osc_tabs.png
diff --git a/_images/iio_osc_time_domain_plot.png b/_images/iio_osc_time_domain_plot.png
diff --git a/_images/iio_osc_trapezoidal_wave_capture.png b/_images/iio_osc_trapezoidal_wave_capture.png
diff --git a/_images/mbed_build.png b/_images/mbed_build.png
diff --git a/_images/mbed_keil_studio_project_clone.png b/_images/mbed_keil_studio_project_clone.png
diff --git a/_images/mbedignore_changes.png b/_images/mbedignore_changes.png
diff --git a/_images/serial_ports_view.png b/_images/serial_ports_view.png
diff --git a/_images/stm32_auto_generated_files.png b/_images/stm32_auto_generated_files.png
diff --git a/_images/stm32_compiler_flag.png b/_images/stm32_compiler_flag.png
diff --git a/_images/stm32_exclude_files_option.png b/_images/stm32_exclude_files_option.png
diff --git a/_images/stm32_generate_code.png b/_images/stm32_generate_code.png
diff --git a/_images/stm32_project_directory.png b/_images/stm32_project_directory.png
diff --git a/_images/stm32_run_option.png b/_images/stm32_run_option.png
diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt
@@ -0,0 +1,27 @@
+Precision-converters-firmware
+=============================
+
+Analog Devices Inc. Precision Converters Firmware Applications
+
+This repository contains embedded firmware applications for Analog Devices 
+Precision Converters. The firmware applications are developed to interface with 
+Precision Converters (ADCs/DACs) in order to configure/access device parameters 
+and capture device data over a serial communication link. These applications are 
+primarily targeted for the SDP-k1 hardware platform, running Mbed OS, however 
+they can target other platforms as well. `See Understanding No-OS and Platform Drivers <https://www.analog.com/en/analog-dialogue/articles/understanding-and-using-the-no-os-and-platform-drivers.html>`_
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   /source/build/project_build.rst
+   /source/code_style.rst
+   /source/contributing.rst
+   /source/projects/index.rst
+
+=======
+Support
+=======
+
+Feel free to ask questions in the `EngineerZone <https://ez.analog.com/data_converters>`_
diff --git a/_sources/source/build/project_build.rst.txt b/_sources/source/build/project_build.rst.txt
@@ -0,0 +1,168 @@
+===========
+Build Guide
+===========
+
+.. collapse:: Build Prerequisites
+   :open:
+
+      Prior to building a firmware project, it is required to set up an environment so 
+      that the build process may find the necessary tools (compiler, linker, SDK etc.). 
+      Use the following steps to prepare your environment for building firmware projects 
+      for respective platform.
+
+      .. collapse:: Windows
+
+         .. collapse:: Mbed
+
+            .. collapse:: For Web/Online Build
+
+                  * Visit `Arm Keil website <https://www.keil.arm.com/>`_ to create an user account for accessing the web based Keil Studio IDE.
+
+                  * Open `Keil Studio Web IDE <https://studio.keil.arm.com/auth/login/>`_ with registered user account
+
+            .. collapse:: For Make Build
+
+                  * Clone Precision Converters Firmware repository with the --recursive flag (not needed if building with web IDE for Mbed platform):
+
+                  .. code-block:: bash
+
+                        git clone --recursive https://github.com/analogdevicesinc/precision-converters-firmware
+
+                  * If however you've already cloned the repository without the --recursive flag, you may initialize all the submodules in an existing cloned repo with:
+
+                  .. code-block:: bash
+
+                        git submodule update --recursive --init
+
+                  * Install `Make <https://gnuwin32.sourceforge.net/packages/make.htm>`_ in the root of 'C' drive without any spaces in the installation path. The path must be **C:\\GnuWin32\\…**. Add this path into the system environmental path variable (as shown in below screenshot).
+
+                  * Install `Git <https://git-scm.com/downloads>`_ and add a path of **C:\\Program Files\\Git\\usr\\bin\\** directory into system environmental path variable (please verify your git installation path is correct).
+
+                  * Install Mbed CLI 1 as per guide `here <https://os.mbed.com/docs/mbed-os/v6.15/build-tools/install-and-set-up.html>`_.
+
+                  * Install `GNU Arm Embedded compiler <https://developer.arm.com/downloads/-/gnu-rm.>`_ (for the development, 9-2019-q4-major version is used) and add a path of GNU Arm Embedded Toolchain bin directory into the system environmental path variable (as shown in below screenshot).
+
+                  * Configure the compiler location with Mbed CLI. This can be carried out by running the **mbed config -G GCC_ARM_PATH <path-to-your-gcc-compiler>** in Command Prompt. For example you can run **mbed config -G GCC_ARM_PATH "C:\\Program Files (x86)\\GNU Tools ARM Embedded\\9 2019-q4-major\\bin"** in command prompt. It will set mentioned compiler path to all the Mbed Projects.
+
+                     .. image:: /source/build/environmental_variables.png
+                        :width: 400
+
+
+         .. collapse:: STM32
+
+            .. collapse:: For STM32 IDE based Build
+
+                  * Install `STM32CubeIDE <https://www.st.com/en/development-tools/stm32cubeide.html>`_
+
+                  * Install `STM32CubeMX <https://www.st.com/en/development-tools/stm32cubemx.html>`_
+
+                  * Install `Git <https://git-scm.com/downloads>`_ and add a path of **C:\\Program Files\\Git\\usr\\bin\\** directory into system environmental path variable (please verify your git installation path is correct).
+
+                  * Install `Make <https://gnuwin32.sourceforge.net/packages/make.htm>`_ in the root of 'C' drive without any spaces in the installation path. The path must be **C:\\GnuWin32\\…**. Add this path into the system environmental path variable (as shown in below screenshot).
+
+                  * Install `GNU Arm Embedded compiler <https://developer.arm.com/downloads/-/gnu-rm.>`_ (for the development, 9-2019-q4-major version is used) and add a path of GNU Arm Embedded Toolchain bin directory into the system environmental path variable (as shown in below screenshot).
+
+                     .. image:: /source/build/environmental_variables.png
+                        :width: 400
+
+
+.. collapse:: Building a project
+   :open:
+
+      Once the build enviornment is setup, follow the guide below to build your project
+      and generate executable file (.bin/.hex)
+
+      .. collapse:: Windows
+
+
+         .. collapse:: Mbed
+
+            .. collapse:: Build Using Web/Online IDE
+
+                  * Clone the `Precision Converters Firmware repository <https://github.com/analogdevicesinc/precision-converters-firmware>`_ into Keil Studio using "File->clone…" menu.
+
+                     .. image:: /source/build/mbed_keil_studio_project_clone.png
+                        :width: 600
+
+                  * Once the project repository is imported, wait until all library dependencies are imported as shown in below screenshot. Now, open the '.medignore' file present in the root directory of repository. Add comment syntax (two forward slashes) in front of the project name which you want to build. This will ignore all other projects and build only the comment syntax selected project.
+
+                     .. image:: /source/build/mbedignore_changes.png
+                        :width: 600
+
+                  * Select the target device (default used for development is SDP-K1) and click on 'Clean build' option to build the project. After a successful build a binary will be downloaded to your computer- store this on your drive. Drag and drop this binary to the USB drive hosted by your controller board to flash the MCU.
+
+                     .. image:: /source/build/mbed_build.png
+                        :width: 400
+
+                  .. note::
+
+                        If you intend to build different project, then modify the .medignore file in the root directory as 
+                        mentioned in step2 and clean build project as mentioned in step3
+
+
+            .. collapse:: Build Using Make
+
+                  * Open Git bash and change current directory to project directory (eg. **precision-converters-firmware/projects/ad4130_iio** directory) which you want to build.
+
+                  * Type **make** on the git bash command prompt to build a project.
+
+                  * After successful build, binary file will be created into the **Project_Name/build** directory.
+
+                  * If you want to clean build, type **make reset** on git bash command which deletes all generated build files for the given project.
+
+                  .. note::
+
+                        Default TARGET_BOARD is SDP_K1 and COMPILER is GCC_ARM. Current Make based build only support GCC_ARM Compiler.
+
+                  * By default project is built for "SDP_K1" Board and "GCC_ARM" Compiler. If you want to build for other Mbed Board, For example If you want to build the project for "DISCO_F769NI" Board then run **make TARGET_BOARD=DISCO_F769NI** command in git bash command prompt. If you want to clean build, run **make reset TARGET_BOARD=DISCO_F769NI** command to delete the generated build files for the given project.
+
+
+         .. collapse:: STM32
+
+            .. collapse:: Build Using STM32 IDE
+
+                  * Open the respective project directory by navigating into the "precision_converters_firmware/projects/" folder.
+
+                  * In the "STM32" folder present within the project directory, double click and open the .ioc file present within.
+
+                     .. image:: /source/build/stm32_project_directory.png
+                        :width: 600
+
+                  * Click on the "Generate Code" option seen on the top right corner
+
+                     .. image:: /source/build/stm32_generate_code.png
+                        :width: 600
+
+                  * Upon successful generation of drivers for the selected MCU, the autogenerated files would be seen in the same directory where the .ioc file was present. Double click and open the ".project" file seen in the list of files
+
+                     .. image:: /source/build/stm32_auto_generated_files.png
+                        :width: 600
+
+                  * After the project is loaded to the STM32CubeIDE, unfold the adxxxx_iio project seen in the project explorer, right click the "app" folder, select "Settings" under the "C/C++ Build" section on the left pane and un-check the "Exclude resources from build" checkbox. This would ensure that the project specific files are included by the build system
+
+                     .. image:: /source/build/stm32_exclude_files_option.png
+                        :width: 600
+
+                  * In order to choose STM32 platform in the firmware, select the "ACTIVE_PLATFORM" as "STM32_PLATFORM" in the app_config.h from the respective project.
+
+                  * Add compiler flags "-u _printf_float" to the project settings.
+
+                     .. image:: /source/build/stm32_compiler_flag.png
+                        :width: 600
+
+                  * Program by clicking on the "Run adxxxx_iio" option seen or by performing a copy->paste option of the .hex file seen in the STM32/Debug folder
+
+                     .. image:: /source/build/stm32_run_option.png
+                        :width: 600
+
+
+
+.. collapse::  Running a project
+   :open:
+
+      Once the firmware build is successful and binary file is generated, copy the 
+      generated binary into USB drive hosted by your MCU board (e.g. USB drive hosted 
+      by SDP-K1 board on windows). This will flash the binary file into MCU present 
+      on the controller board. Programming might vary based on the tools used for building
+      a project. The 'Project Build' section above talks about this exception at the end
+      of all build steps.
diff --git a/_sources/source/code_style.rst.txt b/_sources/source/code_style.rst.txt
@@ -0,0 +1,48 @@
+Code Styles
+-----------
+
+To apply style guidelines, `astyle <https://astyle.sourceforge.net/>`_ is used.
+
+For the source code in the repository, the following configuration should be used
+through astyle_config file:
+
+.. code-block:: bash
+    
+    --style=linux
+    --indent=force-tab=8
+    --max-code-length=80
+    --suffix=none
+
+**Run manually:**
+
+To use it, copy the script above to a file named e.g. 'astyle_config'. Then, to 
+apply the style to the source file example.cpp, call 'astyle' with the following
+command: 
+
+.. code-block:: bash
+
+    astyle --options=astyle_config example.cpp
+
+The file example.cpp will be rewritten to match the style rules.
+
+**Run from script (Linux):**
+
+A shell script that automates the code style check is available at: `<https://github.com/analogdevicesinc/no-OS/blob/master/ci/astyle.sh>`_
+
+Run the script from the root of the repository, for example:
+
+.. code-block:: bash
+    
+    ./ci/astyle.sh
+
+All the changed files in the last commit from the current branch will be checked
+and rewritten. The differences will be displayed after code style is applied.
+
+**Run script with parameter:**
+
+Optionally, the commit range can be passed as parameter to the script, applying 
+code style on all changed files within the commits.
+
+.. code-block:: bash
+    
+    ./ci/astyle.sh <COMMIT_RANGE>
diff --git a/_sources/source/contributing.rst.txt b/_sources/source/contributing.rst.txt
@@ -0,0 +1,35 @@
+Contributing
+------------
+
+When contributing to Precision Converters Firmware please consider the following checklist:
+
+    * Copyright header has been added to source and header files
+
+    * Artistic Style (astyle) has been run to lint new code
+
+    * Add EEPROM validation code
+
+    * Add all context attributes (e.g. fw_version, hw_carrier, hw_mezzanine, hw_name, hw_mezzanine_status)
+
+    * IIO attributes in the firmware match the corresponding Linux driver attributes
+
+    * Create a readme.md in the project directory explaining how to use the project
+
+    * Validate EEPROM detection and context attributes creation using IIO clients (e.g. ACE, IIO Oscilloscope)
+
+    * Capture and verify ADC data using an IIO client
+
+    * Test on the target platform with USE_SDRAM and NO_SDRAM where applicable
+
+    * Test on the target platform with physical and virtual serial ports where applicable
+
+    * Test using the STM32 HAL where applicable
+
+    * Validate attributes, calibration, temperature sensing, etc using a client
+
+    * Update corresponding ADI Wiki pages
+
+    * Request links to those pages on the product page
+
+    * Open a pull request on Github
+
diff --git a/_sources/source/hardware/comm_interface.rst.txt b/_sources/source/hardware/comm_interface.rst.txt
@@ -0,0 +1,43 @@
+=======================
+Communication Interface
+=======================
+
+.. note::
+
+   For data transmission to IIO clients, IIO firmware applications uses *Virtual Serial*
+   Or *UART* as primary communication links. Firmware by default uses the Virtual Serial
+   interface for higher speed data transmission as SDP-K1 MCU board and Mbed firmware supports
+   both Virtual Serial and UART interface. If you target a different MCU board that does not 
+   support Virtual Serial, just set UART as communication link in the firmware (app_config.h file).
+
+SDP-K1 is powered through USB connection from the computer. SDP-K1 MCU board 
+acts as a serial device when connected to PC, which creates a serial ports to connect to IIO 
+client application running on PC. The serial port assigned to a device can be seen 
+through the device manager for windows-based OS as shown below:
+
+.. image:: /source/hardware/serial_ports_view.png
+   :width: 350
+
+.. note::
+
+   The serial port naming is used differently on different operating systems.
+   For example, Linux uses terms such as dev/ttyUSB* and Mac uses terms such as dev/tty.USB*.
+   Please check serial port naming for your selected OS.
+
+**Identifying Virtual Serial Port (Windows-OS):**
+
+To identify if serial port is virtual, right click on the port name and select 'Properties'.
+Select 'Events' from menu option and check for below highlighted VIDs/PIDs and 
+firmware name which is currently running on MCU.
+
+.. image:: /source/hardware/identifying_virtual_serial_port.png
+   :width: 350
+
+SDP-K1 can support high speed Virtual Serial USB interface, so by default Virtual Serial 
+is configured as default interface in the Mbed firmware. The interface can be set to 
+Physical (UART) serial port by defining macro **USE_PHY_COM_PORT** in the app_config.h file.
+
+.. code-block:: C
+
+   /* Enable the UART/VirtualCOM port connection (default VCOM) */
+   //#define USE_PHY_COM_PORT		// Uncomment to select UART