From d2115ae5e73937a959d060bfe2881ff88e2498df Mon Sep 17 00:00:00 2001 From: AlexandraTrifan Date: Wed, 14 Aug 2024 17:09:19 +0300 Subject: [PATCH] doc: add AD-SWIOT1L-SL plugin documentation on github docs. Signed-off-by: AlexandraTrifan --- doc/plugins/index.rst | 9 +- doc/plugins/swiot1l/ad74413r.rst | 183 +++++++++++++++++++++++++++ doc/plugins/swiot1l/faults.rst | 80 ++++++++++++ doc/plugins/swiot1l/index.rst | 153 ++++++++++++++++++++++ doc/plugins/swiot1l/max14906.rst | 100 +++++++++++++++ doc/plugins/swiot1l/swiot_config.rst | 35 +++++ 6 files changed, 559 insertions(+), 1 deletion(-) create mode 100644 doc/plugins/swiot1l/ad74413r.rst create mode 100644 doc/plugins/swiot1l/faults.rst create mode 100644 doc/plugins/swiot1l/index.rst create mode 100644 doc/plugins/swiot1l/max14906.rst create mode 100644 doc/plugins/swiot1l/swiot_config.rst diff --git a/doc/plugins/index.rst b/doc/plugins/index.rst index 6a8d4ace78..255c827ef5 100644 --- a/doc/plugins/index.rst +++ b/doc/plugins/index.rst @@ -32,7 +32,13 @@ Application Specific plugins * :ref:`Power Supply ` -* SWIOT1L +* AD-SWIOT1L-SL + + * :ref:`Config ` + * :ref:`AD74413R ` + * :ref:`MAX14906 ` + * :ref:`Faults ` + * PQM * :ref:`RMS ` * :ref:`Harmonics ` @@ -58,4 +64,5 @@ Contents registermap/registermap m2k/index pqm/index + swiot1l/index diff --git a/doc/plugins/swiot1l/ad74413r.rst b/doc/plugins/swiot1l/ad74413r.rst new file mode 100644 index 0000000000..20628d8967 --- /dev/null +++ b/doc/plugins/swiot1l/ad74413r.rst @@ -0,0 +1,183 @@ +.. _ad74413r: + + +AD74413R +============================================================================ + +Overview +--------------------------------------------------------------------- + +The AD74413R tool is only available in the runtime mode, along with the +MAX14906 tool and the Faults tool. It represents the main interface for +the AD74413R chip and it dynamically shows all the channels configured +for that device. For each channel we can read/write data through this +interface using the libiio library. + +The possible functions of an AD74413R channel are as follows: high_z, +voltage_out, current_out, voltage_in, current_in_ext, current_in_loop, +resistance, digital_input, digital_input_loop, current_in_ext_hart and +current_in_loop_hart. For each selected function, one or two channels +will be generated within the device context, which will be used for +communication with the physical channel. + +Only the buffered input channel data can be displayed on the plot, and +in the case where a function generates both an input and an output +channel, the advanced menu will be associated with the output channel or +both channels. The channels generated according to the selected function +are as follow: + +.. list-table:: + :widths: 50 50 50 + :header-rows: 1 + + * - Function + - Input channel + - Output channel + * - high_z + - Voltage In + - - + * - voltage_out + - Current In + - Voltage Out + * - current_out + - Voltage In + - Current Out + * - voltage_in + - Voltage In + - - + * - current_in_ext + - Current In + - - + * - current_in_loop + - Current In + - Current Out + * - resistance + - Resistance + - - + * - digital_input + - Voltage In + - - + * - digital_input_loop + - Voltage In + - Current Out + * - current_in_ext_hart + - Current In + - - + * - current_in_loop_hart + - Current In + - Current Out + +Instrument Layout +--------------------------------------------------------------------- +.. image:: https://github.com/analogdevicesinc/scopy/blob/doc_resources/resources/swiot1l/ad74413r.png?raw=true + :align: center + +1. Run button + +- The run button will start an acquisition task that will collect data + from the active input channels. +- The acquisition task will stop upon user intervention. +- The data acquisition frequency is set by the user through the settings menu. +- All the data will be displayed on the plot. + +2. Single Button + + The single button will start a single capture acquisition for all the active + input channels. The acquisition task will stop once all the data is acquired + and displayed on the plot. + +3. Settings Button + + Show/Collapse the menu of general settings. + +4. Advanced Menu Button + + Show/Collapse the advanced menu of the channels. Each channel is associated + with an advanced menu through which various attributes can be modified. + +5. Menu Area + + Here is displayed the menu of general settings, as well as the advanced + menu for each channel. + +6. Channels list + + The functions assigned to each channel are displayed here. The functions + with indices from 1 to 4 are correlated with the physical channels + on the board. + 5 to 8 indices are correlated with the diagnostic channels. + When a channel is selected, it is highlighted. + +7. Plot + + Display data from all the active channels. Display the number + of units per vertical division. Display the instant value + for all channels. + +8. Info button + +9. Print button + + Save the plot with the data and channels into a PDF file. + +10. Config button + + When pressing the config button, Scopy will switch the SWIOT1L mode to config. + The device will briefly disconnect and then reconnect. After that it will + automatically display the Config Instrument. + +Channel item layout +--------------------------------------------------------------------- + +1. Enable button + + Enable/Disable a channel. If a channel is disabled, it will no longer + be displayed on the plot and data will not be acquired for it. + +2. Channel function name + +3. Menu button + + Show/Collapse the advanced menu of the selected channel. + +Plot Layout +--------------------------------------------------------------------- + +1. Drawing area for the curves + + Each input channel has a corresponding curve on the plot. + +2. Curves handle area + + Each curve is associated with a handle through which we can position the + curves at different values on the Y-axis. + +3. Acquisition status + + Display the number of acquired samples and the rate at which these samples + are acquired. The samples per second (SPS) is calculated based in the + frequency and the number of enabled channels. + + If you hover the info button you will find all the necessary information. + + +General settings layout +--------------------------------------------------------------------- + +1. Acquisition settings section + + Sampling frequency represents the frequency at which data is acquired. It is + a property shared by all the available channels. + Available options: 10, 20, 1200, 4800. The plot timespan can be set + between 100ms and 10s. + +2. Export section + + It provides the possibility to export data corresponding to the activated + input channels into a CSV file. You + can choose the channels for which data will be exported. + +3. Arrow button + + The menu can be detached and reattached by pressing the arrow button + in the top right corner. \ No newline at end of file diff --git a/doc/plugins/swiot1l/faults.rst b/doc/plugins/swiot1l/faults.rst new file mode 100644 index 0000000000..9d6f29cfc9 --- /dev/null +++ b/doc/plugins/swiot1l/faults.rst @@ -0,0 +1,80 @@ +.. _faults: + + +Faults +============================================================================ + +Overview +--------------------------------------------------------------------- + + +The Faults Instrument represents the diagnostic operation performed on +the AD-SWIOT1L-SL device, more accurately the AD74413R and MAX14906 +chips. The numeric value from each device is extracted from specific +registers and each bit represents a potential error or information about +the chip. For more information on the faults meaning, consider checking +the corresponding datasheets. + +Instrument layout +--------------------------------------------------------------------- +.. image:: https://github.com/analogdevicesinc/scopy/blob/doc_resources/resources/swiot1l/faults.png?raw=true + :align: center + + +1. Hexadecimal read Value + + The last value read from each device, in hexadecimal. + +2. Reset Stored + + Once a fault value is read twice consecutively, the stored bit is set + for that fault (meaning the fault is persistent). + Pressing the RESET STORED button clears all persistent faults. + +3. Clear Selection + + Each fault can be selected by clicking it. Scopy will display only the + faults that are selected. Pressing the CLEAR SELECTION button clears + all selected faults. This can also be achieved by individually + deselecting each fault. + +4. Run/Single Buttons + + The Single button performs 1 single read for both AD74413R and + MAX14906 faults. + The Run button performs a polling operation on both AD74413R and + MAX14906 every second. + +5. Faults Display + + Check the “Faults” dedicated section of this page. + +6. Faults Explanations + + Each fault is explained in this section. The first 4 faults from AD74413R + (VI_ERR_A, VI_ERR_B, VI_ERR_C and VI_ERR_D) have special meanings based on the + configuration of the channel. Only one of them will be shown when a specific + function is selected and all of them when no specific function is selected. + The explanations are highlighted for the faults that have the active bit set + (i.e. were active on the last read). + +Faults +--------------------------------------------------------------------- + +Each fault has 3 sections: + - **Stored Bit section:** + + The stored bit represents whether that specific fault has been + active twice consecutively, making it a persistent + bit. This can be cleared using the RESET STORED button. + + - **Active Bit section:** + + The active bit represents the value that was last read from the device. + + - **Bit index:** + + The index bit is a notation for identifying faults. + It does not represent the fault name. The name can be seen by + hovering over the fault or by checking the “Faults Explanation” area + corresponding to the index. \ No newline at end of file diff --git a/doc/plugins/swiot1l/index.rst b/doc/plugins/swiot1l/index.rst new file mode 100644 index 0000000000..6cdd0a521c --- /dev/null +++ b/doc/plugins/swiot1l/index.rst @@ -0,0 +1,153 @@ +.. _swiot1l_index: + + +AD-SWIOT1L-SL plugin +================================================================================ + +Overview +--------------------------------------------------------------------- + +The Scopy `AD-SWIOT1L-SL `_ plugin is responsible with the operation and +control of the AD-SWIOT1L-SL platform. The Scopy AD-SWIOT1L-SL +plugin, while based on the Scopy application infrastructure, is tailored +to provide all the specific functionalities of this system. + +.. note:: + For an overview of the AD-SWIOT1L-SL system, check the complete user guide: `AD-SWIOT1L-SL User `_ + +.. warning:: + The Scopy application is in the process of a major rework so a mismatch + between some parts of the documentation and the actual application may + exist. The new Scopy version is not officially released, so the + installers for Scopy with AD-SWIOT1L-SL plugin will be available at the + links provided below. + + +Software setup +--------------------------------------------------------------------- + +**Scopy for Windows** +`Download: Installer for latest release (Windows 64/32-bit); Updated: November +2023 `_ + +**Scopy for Windows portable** +`Download: Portable version for latest release (Windows 64/32-bit); Updated: November +2023 `_ + +**Scopy for Linux** +`Download: Scopy Flatpak installer; Updated: November 2023 +`_ + +**Scopy for OSX** +`Download: Scopy MacOS installer +`_ + +Software installation +--------------------------------------------------------------------- +**Windows** + + Once you downloaded the installer, run it and follow all the required steps. + After completion, system reboot is required. + +**Linux** + + Setup Flatpak using `the setup guide `_ for your Linux distribution. + + After Flatpak is setup get the **Scopy.flatpak** file from the downloaded archive and run: + + **flatpak install scopy–flatpak.flatpak** + +**MacOS** + + Double click the downloaded .dmg to make its content available. “Scopy” will + show up in the Finder sidebar and a window showing the content should open up. + Drag the application from the .dmg window into Applications to install and wait + for the process to finish. + +.. warning:: + The AD-SWIOT1L-SL system is not compatible with Scopy v1.4.1 or older + +Launching the application +--------------------------------------------------------------------- +.. video:: https://github.com/analogdevicesinc/scopy/raw/doc_resources/resources/swiot1l/connect.mov + +Scopy is able to control and operate multiple devices. In order to use +it for the AD-SWIOT1L-SL system, the user should click the “Add +Device”(+) button displayed on the front page of the application. + +The video attached above demonstrates the process of connecting to the +board. First it will scan the network in order to detect the device. If +the device is connected to the network and able to be scanned, it will +appear in the list as **ip:analog.local**. If the device is not +available in the list, but the IP is known, the user can manually write +the IP in the URI textbox and proceed forward. + +.. note:: + The default static IP for all the boards is **169.254.97.40** . + +Once found and verified Scopy will present a list of compatible +instruments. The list of instruments is explained below, but during this +step the user can enable or disable Scopy functionalities for this +board. + +Going forward the homepage of the board is displayed. The homepage +displays some basic information about the board, including its network +IP. It also contains three buttons. One will perform the connection to +the device, the second one performs identification and will blink a led +on the board and the third one will start a quick tutorial for Scopy +first time users. The tutorial is recommended in addition to this user +guide as it will highlight and explain the user interface controls for +the SWIOT1L available instruments. + +.. video:: https://github.com/analogdevicesinc/scopy/raw/doc_resources/resources/swiot1l/tutorial-config.mov + + +Power Supply Options +--------------------------------------------------------------------- +.. image:: https://github.com/analogdevicesinc/scopy/blob/doc_resources/resources/swiot1l/ps-warning.png?raw=true + :align: center + +This warning may appear in any of the instruments that interact with +AD-SWIOT1L-SL. The user should check the external power supply switch +position and verify which option is used to power the system. + +.. note:: + For more details on the power supply options, check the hardware user guide: `AD-SWIOT1L-SL Hardware User Guide `_ + + +System operation modes +--------------------------------------------------------------------- +**Configuration mode:** + When the system is powered up it will enter the Configuration + mode. This mode allows the user to choose device and function + configuration for each of the 4 physical channels. When entering the + Configuration mode, everything is reset to default values. Other than + the initial state after power up, the user can enter this mode by using + the **Config** button available in all the runtime instruments of Scopy + (instruments: AD74413R, MAX14906, Faults). + +**Runtime mode:** + In order to enter the Runtime mode, the user needs to configure the required + channels and use the **Apply** button provided in the Config Instrument. + In this mode the physical channels are configured and can be used to + control or acquire data. If any changes are needed, the user can go back + into Configuration mode by using the **Config** button mentioned above. + +More details on switching through the board states are provided on +specific instrument documentation. + +.. note:: + Switching between operation modes might take some time depending on the + network status. When switching from one mode to another the board is + briefly disconnected from Scopy, that is because the IIO Context that it + relies on needs to be destroyed and recreated based on the selected + configuration. + +.. toctree:: + :maxdepth: 3 + + swiot_config + ad74413r + max14906 + faults + ../registermap/registermap diff --git a/doc/plugins/swiot1l/max14906.rst b/doc/plugins/swiot1l/max14906.rst new file mode 100644 index 0000000000..818dc8f866 --- /dev/null +++ b/doc/plugins/swiot1l/max14906.rst @@ -0,0 +1,100 @@ +.. _max14906: + + +MAX14906 +======================================================================= + +Overview +--------------------------------------------------------------------- + +The MAX14906 instrument is only available in the runtime mode of +AD-SWIOT1L-SL, alongside AD74413R and Faults instruments. It represents +the main interface for the MAX14906 chip and it dynamically shows all +the channels configured for this specific device. + + +Instrument layout +--------------------------------------------------------------------- +.. image:: https://github.com/analogdevicesinc/scopy/blob/doc_resources/resources/swiot1l/max14906.png?raw=true + :align: center + +1. Run button + + The run button will start a polling task at a set time (1 second) for + all channels configured as MAX14906. + The plot will be cleared in all channels every time the run button is pressed. + +2. Settings page + + In the settings page the timespan can be changed, this will + change it for all channels. + +3. Channels + + Each channel will appear in this area. The layout might change + depending on how many channels are configured as MAX14906. + Channels can be detached and reattached by pressing the + arrow in the top-right corner of each channel. + +4. Config button + + When pressing the config button, Scopy will switch the SWIOT1L + mode to config. The device will temporarily close while + the switch is being made. After that it will automatically + reconnect to the SWIOT1L board, in config mode, + so that the device can be configured again. + +Channel Layout +--------------------------------------------------------------------- + +The channel layout can be detached and reattached to Scopy by +clicking the arrow on the upper right side. + +1. Name and placeholder + + Channel name, as displayed in the IIO Context. + Input for custom channel name, it has no functional use, except + for differentiating the channels based on the purpose given by the user. + +2. Channel Type + + INPUT/OUTPUT based on the channel configuration. + +3. Plot + + Displays the polled channel values. The plot history size is + given by the Timespan control. + +4. Output Mode + + Shows the function configured on the respective channel, the + available functions change based on whether the + channel is configured as INPUT or OUTPUT. The functions can + be changed without switching to config mode. + +5. Read Value + + Represents the read value on the specific channel. + +6. Current Limit + + Only available for the channels configured as OUTPUT. + +7. Set Value + + Only available for the channels configured as OUTPUT. Shows + the value that will be written to the channel (the + value is written on the hardware only once, when the switch is toggled). + +Settings tab +--------------------------------------------------------------------- + +1. Timespan for polling + + This control changes the plot timespan for all the enabled channels. + +2. Config Button + + Pressing the config button sets the device mode to configuration. + After that, the device will disconnect briefly, reconnect and the + Config Instrument will be automatically opened. \ No newline at end of file diff --git a/doc/plugins/swiot1l/swiot_config.rst b/doc/plugins/swiot1l/swiot_config.rst new file mode 100644 index 0000000000..7d44b8add0 --- /dev/null +++ b/doc/plugins/swiot1l/swiot_config.rst @@ -0,0 +1,35 @@ +.. _swiot_config: + +Configuration +============================================================================ + +Overview +-------------------------------------------------------------------- + +.. image:: https://github.com/analogdevicesinc/scopy/blob/doc_resources/resources/swiot1l/config.png?raw=true + :align: center + +The Config Instrument is only available when the AD-SWIOT1L-SL system is +in configuration mode. This mode allows the user to define, for each of +the 4 physical channels, the device that will control the channel and +the function defined for that device. The channel can also be disabled, +in which case it will not be configured. + + 1. Channel index + 2. Channel state (enabled/disabled) + 3. Chip configured on that channel + 4. Function selected (chip specific) + 5. Channel to chip mapping + + The AD-SWIOT1L-SL board image contains a mapping of the AD74413R and + MAX14906 chips that highlights the connection between each chip and + the corresponding configured channel pin. + 6. Mode switch + + After configuring the system pressing the Apply button will switch the + SWIOT1L to runtime mode. The device will briefly disconnect while the + IIO Context is reconfigured and it will automatically reconnect to + the AD-SWIOT1L-SL board. + +Upon successful connection a different set of instruments will be available +to operate and control the system. \ No newline at end of file