====== Arduino DMM Shield Library User Guide ====== ====== Overview ===== Digilent provides an Arduino library for DMM Shield. It runs on an Arduino board having DMMShield attached in the shield connector.\\ The interface to DMMShield functionality is implemented as a [[#command_interpreter|Command interpreter]] running over standard Arduino Serial Terminal, or as direct commands to be called from main sketch.\\ The library is implemented as a main library class and a set of modules (see [[#library_overall_structure|Library Overall Structure]]).\\ \\ ===== Supported Arduino boards ===== The library modules are ported to run on * 8 bit AVR boards like **Arduino UNO** and **Arduino Mega 2560** * 32 bits ARM boards like **Arduino DUE** Due to limited resources of Arduino UNO (specially the 2K available dynamic memory) the libraries minimize the use of the RAM memory resources by using the flash (program) memory to store constant data like scale registers configurations and messages.\\ The DMMShield can be used with both 3.3V and 5V voltage levels existing on the Arduino boards. ===== Prerequisites ===== ===Hardware=== * **Arduino board** * **USB cable** * **DMM Shield** ===Software=== * **Arduino MPIDE** ------- ===== Downloads ===== Arduino DMM Shield Project Repository -- [[https://github.com/Digilent/Arduino-DMMShield-Library/archive/master.zip|ZIP]] [[https://github.com/Digilent/Arduino-DMMShield-Library|Git Repo]] ------- o ====== Command interpreter ====== The user interface of the DMMShield functionality is implemented as a command interpreter, recognizing a set of commands covering all DMMShield functionality. It is implemented in [[#dmmcmd_module|DMMCMD module]].\\ It runs using the standard Serial Arduino terminal and that has these functions:\\ - It listens over UART for individual DMM Shield commands. The user will have to provide these commands in the Serial Arduino terminal. - The commands are recognized by [[#dmmcmd_module|DMMCMD module]] and implemented by calls to needed modules. - The command interpreter will send over UART the commands output messages, which can be seen in the Serial Arduino terminal. It is important to comply with each command expected formalism. One command might contain one or more arguments, as detailed in the subsequent sections of the document.\\ The following list enumerates the commands implemented in the DMMCMD module: * [[#dmmsetscale|DMMSetScale]] * [[#dmmmeasurerep|DMMMeasureRep]] * [[#dmmmeasurestop|DMMMeasureStop]] * [[#dmmmeasureraw|DMMMeasureRaw]] * [[#dmmmeasureawg|DMMMeasureAwg]] * [[#dmmcalib|DMMCalib]] * [[#dmmmeasureforcalib|DMMMeasureForCalib]] * [[#dmmfinalizecalib|DMMFinalizeCalib]] * [[#dmmsaveeprom|DMMSaveEPROM]] * [[#dmmimportcalib|DMMImportCalib]] * [[#dmmrestorefactCalibs|DMMRestoreFactCalibs]] * [[#dmmreadserialno|DMMReadSerialNo]] The following chapters provide details about data formatting: * [[#interpreting_values_provided_as_parameter|Interpreting values provided as parameter]] * [[#format_of_values_in_the_answer_text|Format of values in the answer text]]\\ ==== DMMSetScale ==== === Syntax: === >“DMMConfig ” === Example: === >“DMMConfig VoltageDC5” === Description: === >The DMMSetScale command configures the DMM for a specific scale. === Parameters: === The possible values from the are shown in the Scale column of the table from [[#appendix:_dmm_scales|Appendix: DMM Scales]]: === Answer: === ^ Answer ^ Meaning ^ | “Selected scale index is: ” \\ Example:\\ “Selected scale index is: 8” | Success.\\ The provided value is the scale index . | | “Missing valid configuration: \"\"” |the provided configuration is not valid.\\ The faulty string is provided between “”.| | " Invalid scale index" |invalid selected scale index.| | " DMM Configuration verify error" |the configuration verification failed.| ==== DMMMeasureRep ==== === Syntax: === >“DMMMeasureRep” === Description: === >This commands initiates a session of repetitive measurements. These repetitive measurements will be performed until the [[#dmmmeasurestop|DMMMeasureStop]] command is issued. === Parameters: === > === Answer: === > - After issuing the command: “Measure repeated”\\ > - Repeatedly, for each measurement:\\ ^ Answer ^ Meaning ^ | “Value: ” | The value included in the message is formatted as explained in [[#interpreting_values_provided_as_parameter|Interpreting values provided as parameter]] chapter.| | " Invalid scale index" |invalid selected scale index.| | " Valid DMM data timeout" |a valid data was not received within the expected time.| ==== DMMMeasureStop ==== === Syntax: === >“DMMMeasureStop” === Description: === >This command terminates the repetitive measurements session initiated by [[#dmmmeasurerep|DMMMeasureRep]] or [[#dmmmeasureraw|DMMMeasureRaw]] commands. === Parameters: === > === Answer: === >" Measure stop" ==== DMMMeasureRaw ==== === Syntax: === >“DMMMeasureRaw” === Description: === >This command initiates a session of repetitive measurements of raw values. Raw values are values acquired from DMM, without applying the calibration corrections. These repetitive measurements will be performed until the [[#dmmmeasurestop|DMMMeasureStop]] command is issued. === Parameters: === > === Answer: === > - After issuing the command: “Measure raw” > - Repeatedly, for each measurement: ^ Answer ^ Meaning ^ | “Value: ” | The value included in the message is formatted as explained in [[#interpreting_values_provided_as_parameter|Interpreting values provided as parameter]] chapter.| | " Invalid scale index" |invalid selected scale index.| | " Valid DMM data timeout" |valid data was not received within the expected time.| ==== DMMMeasureAvg ==== === Syntax: === >“DMMMeasureAvg” === Description: === >This commands performs one average measurement (taking the average value of a set of measurements). === Parameters: === > === Answer: === ^ Answer ^ Meaning ^ | “Avg. Value: ” | The value included in the message is formatted as explained in [[#interpreting_values_provided_as_parameter|Interpreting values provided as parameter]] chapter.| | " Invalid scale index" |invalid selected scale index.| | " Valid DMM data timeout" |a valid data was not received within expected time.| ==== DMMCalib ==== === Syntax: === >“DMMCalib ” === Example: === >“DMMCalibP 5.000115 V”\\ >“DMMCalibN -5.001185”\\ >“DMMCalibZ” === Description: === >This command performs the positive, negative, or on zero calibration, depending on the character following DMMCalib command (‘P’, ‘N’ or ‘Z’). This is performed by initiating a measurement and then saving the measured value to be later processed when all the needed data will be present and the calibration will be finalized. For positive and negative calibration, a reference value is provided as a parameter, which is also saved together with the measured value. === Parameters: === | | This parameter is only for positive and negative calibrations.\\ This is a character string containing a formatted value. For more details see [[#format_of_values_provided_as_parameter|Format of values provided as parameter]] chapter. | === Answer: === ^ Answer ^ Meaning ^ | " Calibration on positive done. Reference: , Measured: , Dispersion: %[Coeff: , ]"\\ Example:\\ “Calibration on positive done. Reference: 5.000115 V, Measured: 5.108844 V, Dispersion: 0.02% Coeff: -0.067295, 0.043947" | Success.\\ \\ \\ The dispersion is computed as the difference between the measured and the reference values, divided by the scale range.\\ \\ \\ The calibration coefficients are appended in the end of the message only if this calibration finalizes a calibration process.\\ \\ The values included in the message are formatted as explained in the [[#interpreting_values_provided_as_parameter|Interpreting values provided as parameter]] chapter. | | “Calibration on negative done. Reference: , Measured: , Dispersion: %[Coeff: , ]"\\ Example:\\ “Calibration on negative done. Reference: -5.001185 V, Measured: -5.109310 V, Dispersion: 0.02%" | ::: | | “Calibration on zero done: Measured Val = , Dispersion %[Coeff: , ]"\\ Example:\\ “Calibration on zero done. Measured Value: - 0.000028 V, Dispersion: 0.00%" | ::: | | " Invalid scale index" |invalid selected scale index. | | " Valid DMM data timeout" |a valid data was not received within expected time. | | " The provided value \"\" has a wrong measure unit." | \\ the measure unit does not match the scale unit. This shouldn’t occur if reference value is correctly provided. | | " The provided value \"\" must have a measure unit." | \\ the value must be followed by an Unit. This shouldn’t occur if reference value is correctly provided. | | “Missing valid reference value: \"\"” | \\ the provided reference value is not valid. This shouldn’t occur if reference value is correctly provided. | | "ERROR: Calibration measure dispersion error: Measured , Reference: , Dispersion: %, Max. dispersion: %" |the measurement dispersion is outside the expected limits.\\ The values are just for information, no need to be extracted. | ==== DMMSaveEPROM ==== === Syntax: === >“DMMSaveEPROM” === Description: === >This command saves to user EPROM all the calibrations. It is important to save calibration data to EPROM after calibrations are performed, otherwise, the calibrations are lost next time the board is powered off. === Parameters: === > === Answer: === ^ Answer ^ Meaning ^ | " calibrations written to EPROM"\\ Example:\\ " 4 calibrations written to EPROM" | Success.\\ The message also communicates the number of calibrations performed since the last power-up and not saved to EPROM.| | “EPROM write data ready timeout ” |the write to EPROM failed. | ==== DMMVerifyEPROM ==== === Syntax: === >“DMMVerifyEPROM” === Description: === >This function verifies the content of the calibration data against the user calibration data stored in EPROM. === Parameters: === > === Answer: === ^ Answer ^ Meaning ^ | " EPROM Calibration data is verified" | Success, the calibration data is identical with the user calibration data stored in EPROM.| | " EPROM Calibration data mismatch values found" |the calibration data is different than the user calibration data stored in EPROM. | | " EPROM write data ready timeout " |the write to EPROM failed. | | " Invalid EPROM magic number" |the magic number was not properly retrieved. | | " Invalid EPROM checksum" |the checksum does not match the content. | ==== DMMExportCalib ==== === Syntax: === >“DMMExportCalib” === Description: === >This command exports the content of the user calibration data as a table, showing for each scale index the additive and multiplicative coefficients. The coefficients are formatted as fractional numbers, with 6 decimals. === Parameters: === > === Answer: === ^ Answer ^ Meaning ^ | " Calibration data is exported , , ”>\\ Example:\\ Calibration data is exported\\ 00, 0.000000, 0.000000\\ 01, 0.000000, 0.000000\\ 02, 0.000000, 0.000000\\ 03, 0.000000, 0.000000\\ 04, 0.000000, 0.000000\\ 05, 0.000000, 0.000000\\ 06, 0.000000, 0.000000\\ 07, 0.000000, 0.000000\\ 08, -0.021222, -0.000072\\ 09, -0.032600, 0.000125\\ 10, 0.000000, 0.000000\\ 11, 0.000000, 0.000000\\ 12, -0.062725, 0.004843\\ 13, 0.000000, 0.000000\\ 14, 0.000000, 0.000000\\ 15, 0.000000, 0.000000\\ 16, 0.000000, 0.000000\\ 17, 0.000000, 0.000000\\ 18, 0.000000, 0.000000\\ 19, 0.000000, 0.000000\\ 20, 0.000000, 0.000000\\ 21, 0.000000, 0.000000\\ 22, 0.000000, 0.000000\\ 23, 0.000000, 0.000000\\ 24, 0.000000, 0.000000\\ 25, 0.000000, 0.000000\\ 26, 0.000000, 0.000000 | Success, the tabular data shows signed values, 6 digits for calibration coefficients.| | " EPROM Calibration data mismatch values found" |the calibration data is different than the user calibration data stored in EPROM. | | " Invalid EPROM magic number" |the magic number was not properly retrieved when reading from EPROM. | | " Invalid EPROM checksum" |the checksum does not match the content when reading from EPROM. | ==== DMMImportCalib ==== === Syntax: === >“DMMImportCalib , , ” === Example: === >“DMMImportCalib 10, 0.021222, -0.000125” === Description: === >This command imports the calibration data for a specific scale. It does not save calibration the data in EPROM. === Parameters: === ||the index of the scale whose coefficients are imported (integer number)| ||the multiplicative coefficient to be imported (signed float value)| ||the additive coefficient to be imported (signed float value)| === Answer: === ^ Answer ^ Meaning ^ | “Scale: , Calibration coefficients: Mult = , Add = ”\\ Example:\\ “Scale: 10, Calibration coefficients: Mult = 0.021222, Add = -0.000125”| Success, the calibration data is imported, the message communicates the scale index (integer value), the calibration multiplicative coefficient (6 decimals signed value) and the calibration additive coefficient (signed float value) | |" Invalid value, provide an integer number for the first token, corresponding to scale index"|The integer number corresponding to the scale index was not properly provided| |" Invalid value, provide a float number for the second token, corresponding to Mult. coefficient"|The float number corresponding to the Mult. coefficient was not properly provided| |" Invalid value, provide a float number for the third token, corresponding to Add. coefficient"|The float number corresponding to the Add. coefficient was not properly provided| | " The expected parameters were not provided on the UART command" |the three expected parameters were not provided.| ==== DMMRestoreFactCalibs ==== === Syntax: === >“DMMRestoreFactCalibs” === Description: === >This command restores the calibration data with the factory loaded values. It reads data from the factory calibration area of EPROM and saves it to the user calibration area of EPROM. === Parameters: === > === Answer: === ^ Answer ^ Meaning ^ | " Calibration data restored from FACTORY EPROM"| Success, the calibration data is restored from the Factory Calibration area of EPROM.| | " Invalid EPROM magic number"|the magic number was not properly retrieved.| | " Invalid EPROM checksum" |the checksum does not match the content.| | “EPROM write data ready timeout ” |the write to EPROM failed.| ==== DMMReadSerialNo ==== === Syntax: === >“DMMReadSerialNo” === Description: === >This command retrieves the 12 digits serial number information from EPROM. === Parameters: === > === Answer: === ^ Answer ^ Meaning ^ | “SerialNo = \"<12 characters serial number>\"”\\ Example:\\ " SerialNo = "210356A76C0C""| Success, the message contains serial number information.| | " Invalid EPROM magic number"|the magic number was not properly retrieved.| | " Invalid EPROM checksum" |the checksum does not match the content.| ==== Interpreting Values Provided as Parameter ==== Values formatted in character strings must be provided as parameters for some functions, for example the reference value provided as parameter to calibration functions in [[#command_interpreter|Command Interpreter]], see [[##dmmcalib|DMMCalib]].\\ Providing a value as a parameter must comply to the following rules: The value is composed by a fractional number followed by the unit. The unit is formed by the base unit (“V”, “A” or “Ohm”), eventually prefixed by multiple/submultiple designators (“u”, “m”, “k” and “M”). It is mandatory that the base unit matches the currently selected scale, otherwise the following error is returned: " The provided value has a wrong measure unit".\\ Example: “2.456789 mV” is correct for VoltageDC5 scale, and corresponds to the 0.002456789 value. ==== Format of Values in the Answer Text ==== Some functions return character strings representing values, for example get value functions of the [[#dmmcmd_module|DMMCMD module]], see [[##dmmmeasurerep|DMMMeasureRep]].\\ The values will be formatted as a fractional number (6 decimals), followed by the base unit (“V”, “A” or “Ohm”) corresponding to the current selected scale. No multiple / submultiple designators of the base unit are used. Example: 0.002456789 is formatted "0.002456 V" for all of the voltage scales. ====== Library Overall Structure ====== The library consists of a main class object and some modules, each implemented in a separate source / header file.\\ The following image shows the library modules and the links between them. {{ :reference:add-ons:dmm-shield:arduinolibraryoverall-1.jpg?800 |}} ===== Description ===== The diagram from [[#library_overall_structure|Library Overall Structure]] shows the general structure of the DMM Shield library, the library modules, and the relations between them.\\ The diagram is using green arrows for the calls from outside (calls to library functions provided as a public interface) and blue arrows for the inside calls (function calls between different modules).\\ From the perspective of providing to the user the access to the hardware, there as three stacked layers.\\ The [[#gpio_module|GPIO module]], [[#spi_module|SPI module]] and [[#uart_module|UART module]] belong to the lowest level, which can be seen as the Data layer. The [[#gpio_module|GPIO module]] provides a direct connection to the hardware digital pins, while the [[#spi_module|SPI module]] implements the SPI bit-bang protocol over the digital pins. The [[#uart_module|UART module]] provides the communication from the UART interface of the system board.\\ The [[#dmm_module|DMM module]], [[#eprom_module|EPROM module]], [[#calib_module|CALIB module]] and [[#serialno_module|SERIALNO module]] belong to the middle layer, which can be seen as the Business layer.\\ The [[#dmm_module|DMM module]] and [[#eprom_module|EPROM module]] functionality is implemented using the [[#spi_module|SPI module]].\\ The [[#calib_module|CALIB module]] functionality is implemented using the [[#dmm_module|DMM module]] and [[#eprom_module|EPROM module]].\\ The [[#serialno_module|SERIALNO module]] functionality is implemented using the [[#eprom_module|EPROM module]]. \\ ====== Library Usage ====== The library can be used as a normal Arduino library:\\ * The folder must be placed in the proper Arduino libraries folder\\ //for example \Documents\Arduino\libraries, depending on sketch location defined in Preferences window (File / Preferences).// * In the sketch, the library header must be included\\ // #include // * In the sketch the DMMShield can be used as any class object, for example by declaring an object of class DMMShield and calling its member functions\\ //DMMShield dmmShieldObj; // dmmShieldObj.CheckForCommand();// // ==== Further possible developments ==== The current DMMShield implementation provides all the DMM functions through a text [[#command_interpreter|Command interpreter]].\\ User may implement other approach in order to access the DMMShield modules: [[#dmm_module|DMM module]], [[#calib_module|CALIB module]] and [[#eprom_module|EPROM module]]. For example a function accessing the user locations of EPROM can be implemented, using the existing function in [[#eprom_module|EPROM module]]. ====== Library Modules ====== ===== DMMShield library main class ===== The DMMShield class implements the DMMShield Arduino library object main class.\\ Normally its functions are called from the Arduino sketch. The library is initialized using [[#dmmshield::begin|DMMShield::begin]] function.\\ As an interface between the user and DMMShield functionality, it provides three approaches: - All the DMMShield functionality is implemented in a command interpreter, in the [[#dmmcmd|DMMCMD Module]]. The command interpreter is accessed by calling [[#dmmshield::checkforcommand|DMMShield::CheckForCommand]] function. See [[#command_interpreter|Command Interpreter]] chapter for more details. - Each command of the command interpreter can be accessed using [[#dmmshield::processindividualcmd|DMMShield::ProcessIndividualCmd]] function. - Basic DMMShield functionality can be accessed using specific functions: * [[#dmmshield::setscale|DMMShield::SetScale]] function in order to set the scale.\\ * [[#dmmshield::getformattedvalue|DMMShield::GetFormattedValue]] function in order to retrieve and format the measured value.\\ ==== DMMShield::begin ==== === Synopsis: === >void DMMShield::begin(HardwareSerial *phwSerial); === Parameters: === |HardwareSerial *phwSerial|pointer to the HardwareSerial object| === Return Value: === > === Description: === > This function initializes the DMMShield library. > It calls the initialization function for DMMCMD module, providing the pointer to HardwareSerial object.\\ === Example: === >DMMShield dmmShieldObj; >void setup() >{ > Serial.begin(9600); > dmmShieldObj.begin(&Serial); >} ==== CheckForCommand ==== === Synopsis: === void DMMShield::CheckForCommand(); === Parameters: === > === Return Value: === > === Description: === >This function runs the command DMMCMD interpreter by calling command interpretter function from [[#dmmcmd_module|DMMCMD Module]]. >Basically the command interpreter checks if there is any available received text over HardwareSerial object (Serial Monitor). >If so, it searches in a list of commands and runs the specific functionality for each recognized command. >See [[#command_interpreter|Command Interpreter]] chapter for more details. === Example: === >DMMShield dmmShieldObj; >void setup() >{ > Serial.begin(9600); > dmmShieldObj.begin(&Serial); >} >void loop() >{ > dmmShieldObj.CheckForCommand(); > delay(500); >} ==== DMMShield::ProcessIndividualCmd ==== === Synopsis: === void ProcessIndividualCmd(char *szCmd); === Parameters: === |char *szCmd|the string containing the command to be processed| === Return Value: === > === Description: === > This function processes one individual command, sending the output to Serial monitor. > If the command is not recognized, "Unrecognized command" message is raised.\\ === Example: === >DMMShield dmmShieldObj; >void setup() >{ > Serial.begin(9600); > dmmShieldObj.begin(&Serial); > dmmShieldObj.ProcessIndividualCmd("DMMSetScale VoltageDC5"); >} ==== DMMShield::SetScale ==== === Synopsis: === uint8_t DMMShield::SetScale(int idxScale); === Parameters: === |uint8_t idxScale|the scale index| === Return Value: === > === Description: === > This function configures a specific scale as the current scale, by calling DMM_SetScale.\\ > In case of error, the error specific message is sent over UART.\\ > It returns ERRVAL_SUCCESS if the operation is successful. > It returns ERRVAL_DMM_CFGVERIFY if scale could not be configured. > It returns ERRVAL_DMM_IDXCONFIG if the scale index is not valid === Example: === >DMMShield dmmShieldObj; >void setup() >{ > Serial.begin(9600); > dmmShieldObj.begin(&Serial); > dmmShieldObj.SetScale(8); >} ==== DMMShield::GetFormattedValue ==== === Synopsis: === uint8_t DMMShield::GetFormattedValue(char *pString); === Parameters: === |char *pString| the string to receive the formatted value| === Return Value: === > === Description: === > This function acquires a measured value from DMM and formates it in the provided string.\\ > In case of error, the error specific message is sent over UART.\\ === Example: === >DMMShield dmmShieldObj; >void setup() >{ > Serial.begin(9600); > dmmShieldObj.begin(&Serial); > Serial.println("DMMShield Library Basic Commands demo"); > bErrCode = dmmShieldObj.SetScale(8); > if(bErrCode == 0) > { > Serial.println("5 V DC Scale"); > } >} >void loop() >{ > char szMsg[20]; > while(1) > { > delay(1000); > bErrCode = dmmShieldObj.GetFormattedValue(szMsg); > if(bErrCode == 0) > { > Serial.print("Value = "); > Serial.println(szMsg); > } > } >} ===== DMMCMD Module ===== The DMMCMD module implements the command interpreter. Its functions are detailed in the [[#command_interpreter|Command Interpreter]] chapter. ===== DMM Module ===== The DMM library module implements DMM (digital multimeter) related functions.\\ These functions configure the DMM device over the custom SPI in order to set a specific scale. It uses function defined in [[#spi_module|SPI module]]. It reads over the custom SPI the status / converter values specific to each scale, thus retrieving measured values.\\ The value retrieval function waits until the converters provide valid values. The values retrieved from DMM device are considered raw values.\\ It uses functions defined in [[#calib_module|CALIB module]]. The DMM module applies (controlled by a flag) calibration coefficients over the raw values, obtaining measured values.\\ For more details about this module, see the function comment headers / implementations from dmm.cpp and dmm.h files. ===== CALIB Module ===== CALIB module groups functions that implement calibration functionality of DMM Shield. The DMM Shield measuring hardware has errors due to DMM device and DMM Shield's additional components.\\ Calibration is the process of establishing some correction coefficients that, applied to the acquired values, allow more precise measurements. Calibration is done for each scale.\\ For each scale, calibration is done in multiple points: positive, on zero or negative, depending on scale). The positive/negative calibrations are done at a value close to the maximum/minimum scale value. The reference value is measured using a separate measuring device, as accurate as possible.\\ Calibration is done by calling calibration functions to inform the system that in a specific moment the reference values are applied to the DMM Shield connectors. The library functions initiate a DMM Shield measurement and then the measured value and reference value are stored, to be used when all the calibration data exists. See [[#dmm_module|DMM module]] for more details.\\ For more details about this module, see the function comment headers / implementations from calib.cpp and calib.h files. ===== EPROM Module ===== The DMM Shield provides a non-volatile EEPROM memory 93LC66BT, having 512 bytes (4kbits).\\ It is accessed over a custom SPI protocol, using digital IO pins exposed in the DMM Shield connector.\\ While the chip select is specific to EPROM, the SPI lines (data and clock) are shared with DMM device (see [[#dmm_module|DMM module]]). The EPROM is used to store the following system information: * Serial number: * 12 bytes payload (see [[#serial_number|Serial Number]]) * 2 extra bytes: magic number, checksum * Total 14 bytes, see the address space table below. * User Calibration: * 27*2*4 bytes payload (2 values of 4 byes (float) for 27 scales) * 2 extra bytes: magic number, checksum * Total 218 bytes, see the address space table below. * Factory Calibration: * 27*2*4 bytes payload (2 values of 4 byes (float) for 27 scales) * 2 extra bytes: magic number, checksum * Total 218 bytes, see the address space table below. Note that the structure of User Calibration area is identical to the structure of Factory Calibration area.\\ For more details about Calibration process, read more on [[#calib_module|CALIB module]].\\ Each of the tree above mentioned sections contains, for safety reasons, additional information: * a byte containing a specific number called magic number (0x23) * a byte containing the checksum of all the bytes written in the specific section When reading a section content from EPROM, these two security bytes are checked, returning errors when mismatches are found. \\ The following table details the address space: ^ Addresses (words) ^ Addresses (bytes) ^ Size ^ Content ^ | 0x93 – 0xFF | 0x0126 – 0x01FF | 109 words /\\ 218 bytes | Factory calibration data | | 0x8C – 0x92 | 0x0118 – 0x0125 | 7 words /\\ 14 bytes | Serial Number | | 0x1F – 0x8B | 0x003E – 0x0117 | 109 words /\\ 218 bytes | User calibration data | | 0x00 – 0x1E | 0x0000 – 0x003D | 31 words /\\ 62 bytes | Unused Memory | The addressing unit of the memory is a 16-bit word. As the memory capacity is 256 words, the word addresses are implemented using 8-bit byte type.\\ Apart from this system information stored in EPROM, applications can be implemented to store specific user data using write functions from EPROM module, to access the unused memory starting at address 0. These functions are protected against writing over the system areas detailed above.\\ For more details about this module, see the function comment headers / implementations from eprom.cpp and eprom.h files. ===== SERIALNO Module ===== The SERIALNO module implements the functions related to Serial Number data (stored during factory process into the EPROM memory). See [[#serial_number|Serial Number]] for more details about the information contained in the Serial Number. It uses the [[#eprom_module|EPROM module]] in order to access EPROM memory.\\ For more details about this module, see the function comment headers / implementations from serialno.cpp and serialno.h files. ==== Serial Number ==== Each board has a unique serial number information (called SerialNo), built as follows:\\ * 6 characters DMM Shield prefix (Digilent ID + Schematic ID): “210356”\\ * 6 characters unique serial of each board (read from the barcode label, after ‘D’): for example “A76C0C”\\ Example of DMM Shield SerialNo: “210356A76C0C”\\ This is written in the EPROM during the manufacturing procedure and shouldn’t be altered by the user. For more details see [[#serialno_module|SERIALNO module]] and [[#eprom_module|EPROM module]].\\ ===== SPI Module ===== The SPI module implements the SPI communication needed for [[#dmmcmd_module|DMMCMD module]] and [[#eprom_module|EPROM module]].\\ It uses the [[#gpio_module|GPIO module]] for configuring and accessing the output digital lines SPI clock and SPI data out, and the input digital line SPI data in.\\ The functions of this module allow the transfer of any number of bits, needed in order to implement the communication protocols with the above mentioned modules.\\ The module should only be accessed through the functions from upper level modules.\\ For more details about this module, see the function comment headers / implementations from spi.cpp and spi.h files. ===== GPIO Module ===== The GPIO module provides the lowest level, the hardware access level to the input / output digital lines. \\ It configures the required digital lines as input or output digital line, implements the functions to set a specific output digital line to 0 or 1 value, and to read the value of a digital input line.\\ It is accessed by [[#spi_module|SPI module]] in order to implement the custom SPI access, by [[#dmm_module|DMM module]] that accesses DMM SPI chip select and relays digital lines and by [[#eprom_module|EPROM module]] that accesses EPROM SPI chip select digital line.\\ This module is the only module dependent to the hardware.\\ The module should only be accessed through the functions from upper-level modules. ===== Appendix: DMM Scales ===== DMM Shield allows selecting one from the following set of scales. The following table shows all the scales, together with some extra columns related to how the message is formatted in the command and in the answer. ^ Index ^ Scale ^ Formatted values in commands ^^^ Formatted values in answers ^ ^:::^:::^ Valid values ^ Unit ^ Out of scale ^:::^ |0| Resistance50M |Signed value, 6 decimals|MOhm|"OVERLOAD"|Valid values: corresponding to the Ohm unit\\ Out of scale values: "INFINITY"| |1| Resistance5M |:::|MOhm|:::|:::| |2| Resistance500k |:::|kOhm|:::|:::| |3| Resistance50k |:::|kOhm|:::|:::| |4| Resistance5k |:::|kOhm|:::|:::| |5| Resistance500 |:::|Ohm|:::|:::| |6| Resistance50 |:::|Ohm|:::|:::| |7| VoltageDC50 |Signed value, 6 decimals|V|"OVERLOAD"|Valid values: corresponding to the V unit\\ Out of scale values: "INFINITY"| |8| VoltageDC5 |:::|V|:::|:::| |9| VoltageDC500m |:::|mV|:::|:::| |10| VoltageDC50m |:::|mV|:::|:::| |11| VoltageAC30 |:::|V|:::|:::| |12| VoltageAC5 |:::|V|:::|:::| |13| VoltageAC500m |:::|mV|:::|:::| |14| VoltageAC50m |:::|mV|:::|:::| |18| Diode |:::|V|:::|:::| |17| Continuity |Signed value, 6 decimals \\ This is similar to a resistance scale.|Ohm|“OPEN” |Valid values (contact on probes): corresponding to the Ohm unit\\ Out of scale values (no contact on probes): "INFINITY"| |16| CurrentDC5 |Signed value, 6 decimals|A|"OVERLOAD"|Valid values: corresponding to the A unit\\ Out of scale values: "INFINITY"| |17| CurrentAC5 |:::|A|:::|:::| |20| CurrentDC500m |:::|mA|:::|:::| |21| CurrentDC50m |:::|mA|:::|:::| |22| CurrentDC5m |:::|mA|:::|:::| |23| CurrentDC500u |:::|uA|:::|:::| |24| CurrentAC500m |:::|mA|:::|:::| |25| CurrentAC50m |:::|mA|:::|:::| |26| CurrentAC5m |:::|mA|:::|:::| |27| CurrentAC500u |:::|uA|:::|:::| ---- ===== Additional Resources ===== {{topic> dmm-shield-zynq-demo +resources}} {{topic>dmmshield dmm dmm-pic32-lib +doc}} ---- {{tag>doc dmm-shield-zynq-lib dmm}}