Digilent provides the ZmodADC1410 Library used to access ZmodADC1410 functionality.
It is part of a pack of libraries to handle the Zmod modules functionality. They cover both Linux and baremetal (standalone) platforms.
The Zmod Base Library implements the functionality that is common to all Zmods.
For each Zmod, separate libraries are implemented, based on the Zmod Base Library. This document describes the ZmodADC1410 Library.
The current usage instructions / demos are provided for the ZmodADC1410 attached to Eclypse board, still ZmodADC1410 can be attached to any Zynq board providing the SYZYGY connector.

Note: At the time of writing, the ZmodADC1410 library only supports the Zmod Scope 1410-105 (formerly known as the Zmod ADC 1410.

The following image shows the overall structure of Zmod Libraries.

The ZmodADC1410 and Zmod Base Library run on the Zynq PS (processing system).
A ZmodADC1410 specific IP core needs to be instantiated in the programmable logic (PL). This IP core can be accessed from the Zynq PS through its registers. The IP core is able to communicate with the memory through a DMA engine. Each Zmod has one particular AXI DMA IP core associated.
Basically:

• The ZMODADC1410 IP (labeled ZMOD_ADC in the above image) features an internal buffer.
• The ZMODADC1410 IP acquires data (fills its internal buffer) from its on-board analog to digital converter device.
• Eventually, the ZMODADC1410 IP waits for a trigger condition before starting the acquisition.
• The ZMODADC1410 IP reports when its internal buffer is full.
• The ZMODADC1410 Library initiates an AXI DMA receive transfer, transferring data from the IP's internal buffer into a memory buffer allocated by ZMODADC1410 Library. This buffer contains data for both channels.

Read more on ZMODADC1410 IP behaviour below in the page.

The ZMODADC1410 Library implementation uses the Zmod Base Library, which provides the needed functionality in order to access hardware resources in a consistent manner. No hardware related functionality is implemented on ZMODADC1410 Library.
The ZMODADC1410 Library implementation consists of:

• a CPP class called ZMODADC1410 Class, derived(inherited) from ZMOD base class. ZMODADC1410 class is implemented in the zmodadc1410.h, zmodadc1410.cpp source files.
• ZMODADC1410 specific registers and register fields definitions contained in the zmodadc1410.h header file.

The ZMODADC1410 class constructor calls the ZMOD base class constructor providing all the required parameters. For these parameters and how they can be obtained by the user, read ZMOD class Constructor / Destructor chapter.
The constructor also calls initCalib calibration initialziation function, providing the ZmodADC1410 unique ID and the length of the ZmodADC1410 calibration area (see Calibration functions of ZMOD class).

ZMODADC1410 class provides functions that implement the analog to digital converter function. Read ZMODADC1410 IP behaviour chapter for details about ZMODADC1410 IP functionality.
The acquisition related functions of ZMODADC1410 class are implemented using basic ZMOD class functionality.

• The allocChannelsBuffer function allocates acquisition buffer, while the freeChannelsBuffer frees the allocated buffer. For these functions, the length is provided in number of elements in the acquisition buffer (each element has a 4-byte representation).
• The channelData and signedChannelData functions extract 14-bit data for each channel, from one 32-bit value stored in the acquisition buffer.
• the setTrigger function sets the trigger values for a specific channel, level, edge and window position.
• the isBufferFull function reads the “buffer full” status bit.
• the waitForBufferFullPolling function waits (blocks) until the “buffer full” status bit is set.
• the enableBufferFullInterrupt function enables / disables the “buffer full” interrupt. Note that “buffer full” interrupt cannot be enabled on Linux.
• the start and stop functions start and stop the acquisition process. For example, if the acquisition process is started and waiting for a trigger condition, the acquisition process can be stopped, the trigger condition can be modified and the acquisition process resumed.
• the acquireTriggeredPolling function automates the process by calling some of the previously described functions. Processes:
  • sets the trigger condition details (channel, trigger mode, trigger value, window position)
  • starts the acquisition
  • waits until IP internal buffer is full - the IP status is checked by polling
  • transfers data from the internal buffer over the AXI DMA
• the acquireImmediatePolling function is similar to the above mentioned function, the difference being that no trigger condition is defined.
• the autoTestRamp function automates the following process:
  • configures the analog to digital converter into a ramp test mode. In this mode, it generates raising consecutive values in a ramp manner.
  • starts the acquireTriggeredPolling function
  • interprets the acquired data to be consistent with the ramp pattern, trigger condition, window position. It returns the status of this comparison.
• the setGain function allows setting the gain (LOW / HIGH) corresponding to the values range (HIGH / LOW) for a specific channel.
• the setCoupling function allows setting the coupling (AC / DC) for a specific channel.
• the getVoltFromSignedRaw function converts a signed value (as element in the acquisition buffer) to a value in Volts.

The Calibration functions of ZMOD class chapter provides information about all the calibration functionality provided by the base ZMOD class.
The readUserCalib function calls the base class function readUserCalib in order to populate the calibration data, then interprets the calibration data as ZMODADC1410 calibration, computes and sets the ZMODADC1410 IP calibration coefficients.
The ZMODADC1410 class provides setCalibValues function that allows the user to set the calibration pair values (gain, additive) for a specific channel (1, 2) and gain (LOW, HIGH). This function only changes the calibration data image, so in order to actually apply the changes, the writeUserCalib function must be called.

As explained in the IP Register access functions of ZMOD class, the ZMOD class provides read/write register and read/write register bit field functions, both in signed and unsigned versions: readReg, writeReg, readRegFld, writeRegFld, readSignedRegFld and writeSignedRegFld.
The registers and register bit fields common to all Zmods are defined in the base class header zmod.h and are prefixed by ZMOD_REG and ZMOD_REGFLD.
The registers and register bit fields specific to ZMODADC1410 are defined in the ZMODADC1410 class header (zmodadc1410.h) and are prefixed by ZMODADC1410_REG and ZMODADC1410_REGFLD.
The following table lists the common and ZMODADC1410 specific register definitions. The ZMODADC1410 specific register definitions are highlighted in green.

The ZMODADC1410 library is delivered as part of the Zmod libraries pack.
The library usage is similar for all Zmod libraries, and it is explained in the Library usage chapter of Zmod Base Library user guide.

Basically, the ZMODADC1410 IP (labeled ZMOD_ADC Library block diagram of the Overview section) directly interfaces with the ZmodADC1410 device performing an initial configuration and providing an easy to use interface that the upper level IPs or software can use to transfer data or configuration information to the device. It exposes to the PS a set of command and status registers that the ZmodADC1410 library functions use to control the IP. The ZMODADC1410 Library uses these registers to control the IP and read its status.
Using these registers, the ADC acquisition can be configured, started or stopped. The ADC acquisition is composed of the following steps:

• ADC output data is captured and decoded. The ZmodADC1410’s ADC multiplexes its 2 channels on one 14-bit wide double data rate (DDR) parallel interface. The ZmodADC1410 IP demultiplexes the input data channel and resynchronizes the received data with its internal clock.
  

The ZMODADC1410 IP supports two gain range settings: HIGH and LOW. The HIGH input RANGE of the ADC (-25 to +25 V) corresponds to a LOW gain selection in the library functions - using the gain parameter in the setGain() function of the zmodadc1410 library files, while the LOW input RANGE of the ADC (-1V to +1V) corresponds to a HIGH setting value of the gain parameter inside the library mentioned above.
The raw data exported by the ZMODADC1410 should be further analyzed considering the gain parameter setting used for the acquisition.

For more details about the input ranges of the module, consult the ZMODADC1410 Reference Manual

• Sample data is calibrated by applying calibration coefficients. The ZMODADC1410 IP applies calibration coefficients over the digital values received from Analog to Digital converter, in order to compensate the offset and gain errors introduced by the ADC associated circuitry. For this, the IP provides calibration registers where the calibration coefficients are set. The ZmodADC1410 Library initialization functions available in the library reads the raw values for the gain and offset calibration coefficients from the Zmod’s nonvolatile memory, processes them, and configures the calibration registers.
• The internal buffer is filled upon detecting a valid trigger condition. The trigger module allows setting the trigger channel, trigger mode, trigger edge, trigger level and window position. The internal buffer has a maximum length of 2^14 - 1 samples and is 32 bits wide, accommodating both ZmodADC1410 channels. The internal buffer length must be set using the IP registers.
• Buffer data is transferred from the ZMODADC1410 IP internal buffer to system memory through a DMA engine. The ZMODADC1410 IP reports when its internal buffer is full. While the internal buffer is full, no new acquisition is performed. The ZMODADC1410 Library initiates an AXIDMA-S2MM (AXIDMA receive) transfer, transferring data from the ZMODADC1410 IP internal buffer into a memory buffer allocated by ZMODADC1410 Library. The transferred length must be set using the ZmodADC1410 IP registers and the AXI DMA IP registers. The ZMODADC1410 IP can be configured to raise a Buffer Full interrupt, still this interrupt can only be handled by baremetal hardware platform.
  

For more details on ZmodADC1410 IP interface consult the ZmodADC1410 IP User Guide.
Read more on Parameters chapter below for more details.

The ADC Linux demo performs (repeatedly) un-triggered acquisitions and writes the data to a file and to the standard output.
The file only contains the content of one acquisition, as it is overwritten. Function called from main is adcDemo(), with the following parameters:

• channel - the channel where samples were acquired - default is channel 1
• gain - the gain for the channel - default is high range
• length - the buffer length to be used - default is set to 400h

This function further calls the writeADCData() function, which formats the data contained in the buffer and writes it to a file and to the standard output - SDK console.
The file is overwritten any time the function is called. It displays the acquired value (in mV), raw value (as 14 bits hexadecimal value) and time stamp within the buffer (in time units) on the UART terminal.
Parameters transmitted from the user further to library functions:

• filename - the file name to contain the acquisition formatted data
• acqBuffer - the buffer containing acquired data
• channel - the channel where samples were acquired
• gain - the gain for the channel
• length - the buffer length to be used

The user is able to dynamically change the parameters values of adcDemo() function in order to analyze the module capabilities or use it in further projects. The application is contained in the generic workspace and is suggestively called ZmodADC1410_Demo_Linux. The location and name of the file containing one buffer acquisition is found in the location: /home/eclypse/buffer_data.csv

Steps to run the Demo:

1. Install the demo and libraries files, as indicated in the Environment Setup section of the Base Library User Guide.
2. Connect the required hardware to the host PC: Eclypse board, Zmod ADC1410, power supply and USB cable. We recommend using a waveforms/signal generator of your choice, together with BNC - SMA adapters, to obtain the analog signal to be converted.
3. Load the Petalinux image on the SD card and plug it in the SD card slot on the Eclypse board.
4. Optionally, you can edit the uEnv.txt file on the SD card, prior to plug it in the Eclypse board SD slot: change the configuration to use from zmod=adc-dac to zmod=adc, in order to use the git branch containing only the ADC Demo projects.
5. Connect the board to a Ethernet network using an Ethernet cable.
6. Boot the Petalinux using the UART terminal, as instructed in the SD card image download section of the Base Library User Guide.
7. Run the demo project from within SDK application. Follow the 3.2.1.1.3, 3.2.1.1.4 and 3.2.1.1.5 steps of the Base Library User Guide to setup the environment prior to run the project.
8. Use the waveform/signal generator to send the ADC a signal to be converted: ex. DC signal of selected amplitude.
9. Visualize the data acquired in either SDK console or .csv file.
10. Further use and analyze the data received.

The ADC Baremetal demo is in fact a simple ADC acquisition and test, performing a un-triggered acquisition. The demo also provides another function that is not called (testZMODADC1410Ramp_Auto) which puts the ADC in the test mode (ramp).
It also verifies the acquired data to be consistent with the conditions specified by the trigger settings. Function called from main is adcDemo(), with the following parameters:

• channel - the channel where samples will be acquired - default is channel 1
• gain - the gain for the channel - default is high range
• length - the buffer length to be used - default is set to 400h

This function further calls the formatADCDataOverUART() function, which formats the data contained in the buffer and sends it over UART.
It displays the acquired value (in mV), raw value (as 14 bits hexadecimal value) and time stamp within the buffer (in time units) on the UART terminal.
Parameters transmitted from the user further to library functions:

• padcZmod - pointer to the ZMODADC1410 class object
• acqBuffer - the buffer containing acquired data
• channel - the channel where samples were acquired
• gain - the gain for the channel
• length - the buffer length to be used

The user could change the parameters values of adcDemo() function in order to analyze the module capabilities or use it in further projects. The application is contained in the generic workspace and is suggestively called ZmodADC1410_Demo_Baremetal

Steps to run the Demo:

1. Install the demo and libraries files, as indicated in the Environment Setup section of the Base Library User Guide.
2. Connect the required hardware to the host PC: Eclypse board, Zmod ADC1410, power supply and USB cable. We recommend using a waveforms/signal generator of your choice, together with BNC - SMA adapters, to obtain the analog signal to be converted.
3. Run the demo project from within SDK application.
4. Start the selected waveform/signal generator and select a DC signal of certain set amplitude.
5. Open the PC UART terminal and visualize the data acquired: Sample value, Raw value and Time stamp.
6. Further use and analyze the data received.