Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
reference:add-ons:dmm-shield:pic32libraryuserguide [2018/07/04 11:00]
Cristian Fatu [Prerequisites]
reference:add-ons:dmm-shield:pic32libraryuserguide [2018/11/14 13:02] (current)
Cristian Fatu [Library Overall Structure]
Line 9: Line 9:
 ====== Overview ====== ====== Overview ======
  
-===== Description ===== +
-The overview diagram shows the general structure of the DMM Shield library, the library modules, and the relations between them. +
-From the perspective of providing to the user the access to the hardware, there as three stacked layers.\\  +
-The GPIO, SPI, and UART belong to the lowest level, which can be seen as the Data layer. GPIO provides a direct connection to the hardware digital pins, while SPI implements the SPI bit-bang protocol over the digital pins. UART provides the communication from the UART interface of the system board.\\  +
-The DMM, EPROM and CALIB modules belong to the middle layer, which can be seen as the Business layer. The DMM and EPROM functionality is implemented using the SPI module, while CALIB is using the DBB and EPROM modules.\\  +
-The DMMCMD module belongs to the highest layer, which can be seen as the Presentation layer. It provides a command interpreter that listens to the commands received over UART (from a terminal, for example), while the command output is sent back over UART.+
  
 ===== Prerequisites ===== ===== Prerequisites =====
Line 30: Line 25:
  
  
-====== Library Overall Structure ======+ ====== Library Overall Structure ======
 The following image shows the library modules and the links between them. The following image shows the library modules and the links between them.
-{{ :​reference:​add-ons:​dmm-shield:​libraryoverall.jpg?​800 |}}+{{ :​reference:​add-ons:​dmm-shield:​libraryoverall-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 ====== ====== Library Usage ======
  
Line 1240: Line 1244:
  
  
-==== Serial Number ==== +
-Each board has a unique 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 [[#​eprom_module|EPROM module]].+
  
 ==== EPROM_Init ==== ==== EPROM_Init ====
Line 1379: Line 1378:
 >#​include "​eprom.h"​\\ ​ >#​include "​eprom.h"​\\ ​
 >​EPROM_Erase(0x10);​ >​EPROM_Erase(0x10);​
 +===== 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.
 +The module provides an initialization function ([[#​serialno_init|SERIALNO_Init]]) and a data retrieving function [[#​serialno_readserialnofromeprom|SERIALNO_ReadSerialNoFromEPROM]].
 +It uses the [[#​eprom_module|EPROM module]] in order to access EPROM memory.
 +==== 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]].\\ ​
 +
 +
 +
 +==== SERIALNO_Init ====
 +=== Synopsis: === 
 +>void SERIALNO_Init();​
 +
 +=== Parameters: === 
 +
 +><​none> ​                                                                                             ​
 +
 +
 +=== Return Value: === 
 +><​none>​
 +
 +
 +=== Description:​ === 
 +>This function initializes the SERIALNO module.\\ ​
 +>It calls the initialization function for the EPROM module.\\ ​
 + 
 +=== Example: === 
 +
 +>#​include "​SERIALNO.h"​\\ ​
 +>​SERIALNO_Init();​
 +
 +==== SERIALNO_ReadSerialNoFromEPROM ====
 +=== Synopsis: === 
 +>uint8_t SERIALNO_ReadSerialNoFromEPROM(char *pSzSerialNo);​
 +
 +|char *pSzSerialNo|pointer to a character string to hold the serial number sequence| ​                                                                                            
 +                                                                           
 +
 +
 +=== Return Value: === 
 +uint8_t - The error code:
 +|ERRVAL_SUCCESS|0|success|
 +|ERRVAL_EPROM_MAGICNO|0xFD|wrong Magic No. when reading data from EPROM|
 +|ERRVAL_EPROM_CRC|0xFE|wrong CRC when reading data from EPROM|
 +
 +
 +=== Description:​ === 
 +>This function retrieves the Serial Number information (12 characters) from EPROM .\\ 
 +>​Therefore is important that the caller of this function allocates enough space in pSzSerialNo.\\ ​
 +>The function returns ERRVAL_SUCCESS when success.\\ ​
 +>The function returns ERRVAL_EPROM_MAGICNO when a wrong magic number was detected in the data read from EPROM.\\ ​
 +>The function returns ERRVAL_EPROM_CRC when the checksum is wrong for the data read from EPROM.\\ ​
 + 
 +=== Example: === 
 +
 +>#​include "​SERIALNO.h"​\\ ​
 +>char szSerialNo[13]; ​
 +>bResult = SERIALNO_ReadSerialNoFromEPROM(szSerialNo);​
 ===== SPI Module ===== ===== SPI Module =====
 The SPI module implements the SPI communication needed for [[#​dmmcmd_module|DMMCMD module]] and [[#​eprom_module|EPROM module]].\\ ​ The SPI module implements the SPI communication needed for [[#​dmmcmd_module|DMMCMD module]] and [[#​eprom_module|EPROM module]].\\ ​
Line 1384: Line 1445:
 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 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. The module should only be accessed through the functions from upper level modules.
 +
  
 ===== GPIO Module ===== ===== GPIO Module =====