MPAE-17979: Added code example and readme

.gitignore

@@ -1,6 +1,18 @@
 # Untracked files in MPLABX projects
 /**/build/*
+/**/queuelogs/*
 /**/nbproject/*
 !/**/nbproject/*.xml
 /**/dist/*
 /**/.generated_files/*
+
+**/defmplabxtrace.log
+**/defmplabxtrace.log.inx
+/mcc-manifest-autosave.yml
+/mcc-manifest-generated-success.yml
+
+__pycache__/
+
+*.bak*
+*.yml
+*.csv

.main-meta/main.json

@@ -4,27 +4,27 @@
     "content": {
         "metaDataVersion": "1.3.0",
         "name": "com.microchip.mcu8.mplabx.project.avr64du32-cnano-usb-cdc-datalogger-mplab-mcc",
-        "version": " ",
-        "displayName": "",
+        "version": "1.0.0",
+        "displayName": "USB CDC Datalogger using AVR DU Microcontroller",
         "projectName": "avr64du32-cnano-usb-cdc-datalogger-mplab-mcc",
-        "shortDescription": "\r\nThis example shows how to exchange data between the AVR DU microcontroller and a host computer using the USB Communication Device Class (CDC).",
+        "shortDescription": "This example shows how to exchange data between the AVR DU microcontroller and a host computer using the USB Communication Device Class (CDC).",
         "ide": {
             "name": "MPLAB X",
             "semverRange": ">=6.20.0"
         },
         "compiler": [
             {
                 "name": "XC8",
-                "semverRange": "^2.46.0"
+                "semverRange": "^3.00.0"
             }
         ],
         "dfp": {
-            "name": "",
-            "semverRange": ""
+            "name": "AVR-Dx_DFP",
+            "semverRange": "^2.6.303"
         },
         "configurator": {
-            "name": "",
-            "semverRange": ""
+            "name": "MCC",
+            "semverRange": ">=5.7.1"
         },
         "device": {
             "metaDataVersion": "1.0.0",
@@ -36,9 +36,24 @@
                 "versionRange": "*"
             }
         },
-        "author": "Mori Adrian Rosland",
-        "peripherals": [],
-        "keywords": [],
+        "author": "Rebekka Alve",
+        "peripherals": [
+            "USB",
+            "SPI",
+            "I2C",
+            "RTC",
+            "AC"
+        ],
+        "keywords": [
+            "USB-C",
+            "USB Protocol",
+            "USB 2.0",
+            "Serial Communication",
+            "Communication",
+            "USB",
+            "MCC",
+            "Melody"
+        ],
         "additionalData": {
             "longDescription": {
                 "metaDataVersion": "1.0.0",

README.md

@@ -8,44 +8,197 @@
    </picture>
 </a>
 
-# Update the title for avr64du32-cnano-usb-cdc-datalogger-mplab-mcc here
+# USB Communication Device Class (CDC) Data Logger with AVR® DU
+This example demonstrates how to establish communication between the AVR DU microcontroller 
+and a host computer using the Universal Serial Bus (USB) Communication Device Class (CDC).
 
-<!-- This is where the introduction to the example goes, including mentioning the peripherals used -->
+In this setup, the AVR DU is connected to a temperature sensor and an EEPROM memory. 
+Both the temperature sensor and the memory are peripherals on the Curiosity Nano Explorer board. 
+The AVR DU samples and stores temperature data every six seconds, and it is configured to store up to 42 samples (256 bytes).
+These temperature samples can be read by the host PC using the USB CDC.
 
-## Related Documentation
+<p><img src="images/hw_setup.jpeg" width="700"/></p>
 
-<!-- Any information about an application note or tech brief can be linked here. Use unbreakable links!
-     In addition a link to the device family landing page and relevant peripheral pages as well:
-     - [AN3381 - Brushless DC Fan Speed Control Using Temperature Input and Tachometer Feedback](https://microchip.com/00003381/)
-     - [PIC18F-Q10 Family Product Page](https://www.microchip.com/design-centers/8-bit/pic-mcus/device-selection/pic18f-q10-product-family) -->
+### Program Overview
 
-## Software Used
+The two images below showcase how the AVR DU program and Python script work:
 
-<!-- All software used in this example must be listed here. Use unbreakable links!
-     - MPLAB® X IDE 5.30 or newer [(microchip.com/mplab/mplab-x-ide)](http://www.microchip.com/mplab/mplab-x-ide)
-     - MPLAB® XC8 2.10 or a newer compiler [(microchip.com/mplab/compilers)](http://www.microchip.com/mplab/compilers)
-     - MPLAB® Code Configurator (MCC) 3.95.0 or newer [(microchip.com/mplab/mplab-code-configurator)](https://www.microchip.com/mplab/mplab-code-configurator)
-     - MPLAB® Code Configurator (MCC) Device Libraries PIC10 / PIC12 / PIC16 / PIC18 MCUs [(microchip.com/mplab/mplab-code-configurator)](https://www.microchip.com/mplab/mplab-code-configurator)
-     - Microchip PIC18F-Q Series Device Support (1.4.109) or newer [(packs.download.microchip.com/)](https://packs.download.microchip.com/) -->
+<p><img src="images/program_avr.svg" width="750"/></p>
 
-- MPLAB® X IDE 6.20.0 or newer [(MPLAB® X IDE 6.20)](https://www.microchip.com/en-us/development-tools-tools-and-software/mplab-x-ide)
-- MPLAB® XC8 2.46.0 or newer compiler [(MPLAB® XC8 2.46)](https://www.microchip.com/en-us/tools-resources/develop/mplab-xc-compilers/xc8)
+<p><img src="images/flowchart_pc.svg" width="750"/></p>
 
 ## Hardware Used
 
-<!-- All hardware used in this example must be listed here. Use unbreakable links!
-     - PIC18F47Q10 Curiosity Nano [(DM182029)](https://www.microchip.com/Developmenttools/ProductDetails/DM182029)
-     - Curiosity Nano Base for Click boards™ [(AC164162)](https://www.microchip.com/Developmenttools/ProductDetails/AC164162)
-     - POT Click board™ [(MIKROE-3402)](https://www.mikroe.com/pot-click) -->
+- [AVR64DU32 Curiosity Nano](https://www.microchip.com/en-us/development-tool/EV59F82A?utm_source=GitHub&utm_medium=TextLink&utm_campaign=MCU8_AVR-DU&utm_content=avr64du32-cnano-usb-cdc-datalogger-mplab-mcc-github&utm_bu=MCU08)
+- [Curiosity Nano Explorer Board](https://www.microchip.com/en-us/development-tool/EV58G97A?utm_source=GitHub&utm_medium=TextLink&utm_campaign=MCU8_AVR-DU&utm_content=avr64du32-cnano-usb-cdc-datalogger-mplab-mcc-github&utm_bu=MCU08)
+  - [MCP9808 Temperature Sensor](https://www.microchip.com/en-us/product/mcp9808)
+  - [25CSM04 4-Mbit SPI Serial EEPROM](https://www.microchip.com/en-us/product/25CSM04)
+
+## Software Used
+
+- [MPLAB® X IDE 6.20 or newer](https://www.microchip.com/en-us/tools-resources/develop/mplab-x-ide?utm_source=GitHub&utm_medium=TextLink&utm_campaign=MCU8_AVR-DU&utm_content=avr64du32-cnano-usb-cdc-datalogger-mplab-mcc-github&utm_bu=MCU08)
+- [MPLAB® XC8 2.46 or a newer compiler](https://www.microchip.com/en-us/tools-resources/develop/mplab-xc-compilers?utm_source=GitHub&utm_medium=TextLink&utm_campaign=MCU8_AVR-DU&utm_content=avr64du32-cnano-usb-cdc-datalogger-mplab-mcc-github&utm_bu=MCU08)
+- [MPLAB® Code Configurator (MCC) Melody core 5.7.1 or newer](https://www.microchip.com/en-us/tools-resources/configure/mplab-code-configurator?utm_source=GitHub&utm_medium=TextLink&utm_campaign=MCU8_AVR-DU&utm_content=avr64du32-cnano-usb-cdc-datalogger-mplab-mcc-github&utm_bu=MCU08)
+- [AVR-Dx Series Device Pack v2.4.286 or newer](https://packs.download.microchip.com)
+
+## Related Documentation
+
+More details and code examples on the AVR64DU32 can be found at the following links:
+
+- [AVR64DU32 Product Page](https://www.microchip.com/en-us/product/AVR64DU32?utm_source=GitHub&utm_medium=TextLink&utm_campaign=MCU8_AVR-DU&utm_content=avr64du32-cnano-usb-cdc-datalogger-mplab-mcc-github&utm_bu=MCU08)
+- [USB CDC Virtual Serial Port Example](https://mplab-discover.microchip.com/com.microchip.ide.project/com.microchip.mcu8.mplabx.project.avr64du32-cnano-usb-cdc-virtual-serial-port-mplab-mcc)
+- [USB Device Stack User Guide](https://onlinedocs.microchip.com/oxy/GUID-49CD424A-D8EB-4F60-95E5-12E07036AA34-en-US-4/index.html)
 
 ## Setup
 
-<!-- Explain how to connect hardware and set up software. Depending on complexity, step-by-step instructions and/or tables and/or images can be used -->
+### Physical Setup
+Place the AVR DU Curiosity Nano onto the Curiosity Nano Explorer board before programming device.
+
+### MCC Setup
+
+
+This project uses the following MCC device libraries and drivers:
+
+- USB - for communication with the host PC
+- I<sup>2</sup>C - for communication with the temperature sensor
+- SPI - for communication with the EEPROM memory
+- AC  - to measure the voltage on the USB connection
+- RTC - to generate interrupts that tell the device to sample temperature data and monitor the USB connection
+
+After setting up the drivers, the project will look similar to this:
+<p><img src="images/mcc_overview.png" width="700"/></p>
+
+### USB Devic Stack Setup
+
+#### USB General setings
+
+The configurator is set so that the AVR DU will identify as a CDC device on the highest level. The toggle switch for adding the Virtual Serial example code is also enabled.
+<p><img src="images/usb_general_settings.png" width="500"/></p>
+
+#### USB Device Descriptors
+In this example, the Device Descriptors section is left as default. For other applications, information on the product can be added here.
+
+#### USB Interfaces
+This example requires a communication and a data interface.
+<p><img src="images/usb_interfaces.png" width="500"/></p>
+
+
+#### USB CDC Communication Interface
+The communication interface configures the communication flow in the setup. The Abstract Control Model (ACM) is used as a subclass, but few of the supported commands are needed. However, three Functional Descriptors are required:
+* Header - Required for Functional Descriptors
+* ACM - Shows the host what commands the device supports (D1 indicates that device supports basic Line Coding and Control Line State commands)
+* Union - Tells the Host the relationship between two or more interfaces
+
+You can copy the settings from the screenshot below.
+<p><img src="images/usb_cdc_interface.png" width="650"/></p>
+
+#### USB CDC Data Interface
+All communication is sent over the data interface for this Virtual Serial Port application. The Packet Size field determines how much data can be transmitted in one USB packet. The data sent can be bigger or smaller and the stack will transmit less or split it up into smaller packages.
+<p><img src="images/usb_cdc_data_interface.png" width="650"/></p>
+
+
+### Two-Wire Interface Setup (TWI0 Peripheral)
+
+The Two-Wire Interface (TWI) is used by the I<sup>2</sup>C host and must be configured as interrupt driven to communicate with the temperature sensor. Enable both the read and the write interrupts.
+<p><img src=images/twi_interrupts.jpg width="500">
 
-## Operation
+### Serial Peripheral Interface Setup (SPI0 Host)
 
-<!-- Explain how to operate the example. Depending on complexity, step-by-step instructions and/or tables and/or images can be used -->
+Select Mode 0 for the Serial Peripheral Interface (SPI) communication to the EEPROM. 
+<p><img src=images/spi_settings.jpg width="600">
+
+### USB Voltage Detection Setup
+To ensure that the USB peripheral only tries to attach to the bus when plugging in the Curiosity Nano to the PC, the Analog Comparator (AC) will periodically check if the voltage is within the acceptable range for V<sub>BUS</sub>.
+
+#### Voltage Reference Setup (V<sub>REF</sub>)
+The Voltage Reference is set to 2.048V.
+<p><img src="images/mcc_voltage_reference.jpg" width="600"/></p>
+
+#### Analog Comparator Setup (AC0)
+
+##### AC Hardware Settings
+Under this register, the Analog Comparator must be enabled by toggling "Enable" under "Hardware Settings".
+<p><img src="images/mcc_analog_comparator_ctrla.jpg" width="600"/></p>
+
+##### AC MUX Control Settings
+To measure the correct values, the positive input must be connected to AINP4, while the negative input is set to the reference pin DAC Reference for the Analog Comparator.
+<p><img src="images/mcc_analog_comparator_muxctrl.jpg" width="600"/></p>
+
+##### AC DAC Reference Settings
+The target voltage can be set directly in the "Requested Voltage (V)" input under "Hardware Settings". The DACREF register must be set to a value that can detect the correct voltage level at minimum 0.4V (DACREF = 50). 
+<p><img src="images/mcc_analog_comparator_dacref.jpg" width="600"/></p>
+
+### RTC Setup
+#### RTC Hardware Settings
+In this example, the RTC overflow interrupt for taking temperature samples is configured with a period of six seconds. Configure this as desired.
+<p><img src=images/rtc_hardware_settings.png width="600">
+
+#### RTC Interrupt Settings
+Enable the Periodic Interrupt Timer (PIT), used for USB voltage checks, and set the period to 1024 cycles. Enable the Overflow and the Periodic Interrupt in the interrupt settings.
+<p><img src=images/rtc_pit.jpg width="600">
+
+### Global Interrupt Setup
+The Interrupt Manager is found in the System Firmware drop-down menu. Here, global interrupts must be enabled for the interrupt driven communication to work.
+<p><img src=images/global_interrupts.jpg width="600">
+
+### Pin Configuration
+
+Configure pins PA7 and PD6 from the **Pin Grid View** as GPIO outputs. The remaining pins are already automatically configured.
+<p><img src=images/pins_locks.jpg width="700">
+
+Open **Pins** from the **System Firmware** drop-down menu. Rename PA7 to EEPROM_CS (EEPROM chip select) and PD6 to LED0, and select Start High for both.
+<p><img src=images/pins.png width="700">
+
+### Generate MCC
+Generate the MCC project by clicking the **Generate** button.
+<p><img src=images/mcc_generate.jpg width="450">
+
+### USB Notes
+
+In this project, the USB sends a complete EEPROM page of 256 bytes to the host computer on read commands. Therefore, the USB transmit and receive buffers must be configured to have a size of 256 bytes. Set the define in ``usb_config.h``.
+<p><img src=images/usb_note_one.png width="400">
+
+The current USB driver has an echo functionallity implemented by default. To remove this, go to the ``usb/usb_cdc/usb_cdc_virtual_serial_port.c`` file. Find the ``USB_CDCDataReceived()`` function and comment out/remove the ``USB_TransferWriteStart()`` function call (line 150):
+<p><img src=images/usb_note_two.png width="850">
+
+## How to Program Curiosity Nano Board
+
+Test this example by following these steps:
+
+### Programming the AVR
+1. Create a new MPLAB project and generate the MCC code as explained in the [MCC Setup section](#mcc-setup). Right click the ``main.c`` file and remove it from the project.
+2. Find your project folder in the file explorer. Insert the ``peripherals`` directory and the ``main.c`` file from the github source code.
+3. Add the ``peripherals`` folder to the Source Files and Header Files, 
+by right clicking and choosing Add Existing Items From Folders. 
+Remember to select the correct "files of type" to match the Source or Header files. 
+  <br><img src="images/add_files.jpg" width= "350">
+  <br><img src="images/add_files_name.jpg" width= "800">
+
+4. Add ``main.c`` by choosing Add Existing Item.
+5. Connect the PC to the DEBUGGER port on the Curiosity Nano Board by using a USB-C® cable.
+6. From the menu bar, choose **Make and Program Device**.
+    <br><img src="images/make_and_program_device.jpg" width= "400">
+
+
+### Running the Datalogger on the PC
+After the AVR has been successfully programmed, connect the AVR to the PC through the USB-C
+TARGET port. This will light LED0 on the Explorer Board. Go to the ``python_code`` directory from the downloaded source code. 
+Make sure to install pyserial using ``pip install pyserial`` before starting the script. 
+Run the ``datalogger.py`` script and interact with the AVR.
+
+The script can optionally be run with the argument ``--serialPortNum {COM PORT}``, which manually assings the specified serial port to the program. 
+
+When the program is up and running, the AVR can receive the following commands:
+- __read:__ Read the stored temperature data, which will be printed to the terminal
+- __status:__ Print the number of samples stored and the capacity
+- __reset:__ Wipe the memory
+- __save:__ Save the sample data to a CSV file
+- __exit:__ Exit the Python script
+<p><img src=images/temp_sens_terminal.png width="400">
 
 ## Summary
 
-<!-- Summarize what the example has shown -->
+By following this example, the user will:
+
+1. Understand the basics of CDC communication on the AVR DU, and how to send and receive data via USB to a host PC.
+2. Understand how EEPROM can be used to store temperature samples on the Curiosity Nano Explorer board.