Merge pull request #12 from PaulThbt/main

Chirp doc v1.0 & error management for chirp functions

Author: vladysor

docs/Library/DAC.md

@@ -49,14 +49,14 @@ typedef struct {
 #### Fields
 {: .no_toc}
 * `dac_channel`: Selects the DAC channel (channel 1 or channel 2)
-* `sampling_freq`: Specified DAC sampling frequency. Maximum value that can be set is 60 GHz. 
+* `sampling_freq`: Specified DAC sampling frequency. Maximum value that can be set is 15 MHz.
 * `mem_address`: Address of the array's first element written to DAC
-* `mem_size`: Number of array elements
+* `mem_size`: Number of array elements.
 * `wave_mode`: 
     * `SENSEDU_DAC_MODE_CONTINUOUS_WAVE` 
     * `SENSEDU_DAC_MODE_SINGLE_WAVE`
     * `SENSEDU_DAC_MODE_BURST_WAVE`
-* `burst_num`: Number of instances of specified LUT. 
+* `burst_num`: Number of instances of specified LUT.
 
 #### Notes
 {: .no_toc}

docs/Projects/Chirp.md

@@ -1,75 +1,145 @@
 ---
-title: Chirp
+title: Chirp Signal Generation
 layout: default
 math: mathjax
 parent: Projects
 nav_order: 2
 ---
 
-# PCB
-{: .fs-8 .fw-500}
+# Chirp Signal Generation
+{: .no_toc .fs-8 .fw-500}
 ---
 
-very cool pcb for sensedu shield for arduino giga r1... (short description)
+The **chirp signal generation project** aims at proviving basic code to generate **frequency modulated continuous waves (FMCW)** on the **SensEdu Shield** using the **Arduino Giga R1**. The projects provides two types of frequency modulation : **sawtooth** and **triangular**.
+
+Chirp signals are encountered in numerous fields like radar & sonar systems, telecommunications, signal processing and more. You will find more information on the potential applications from our upcoming FMCW radar project.
+
+<img src="{{site.baseurl}}/assets/images/Chirp_signal.png" alt="drawing" width="500"/>
+{: .text-center}
+
+Chirp signal sweeping from 100 Hz to 10 kHz
+{: .text-center}
+
+<img src="{{site.baseurl}}/assets/images/Chirp_spectro.png" alt="drawing" width="499"/>
+{: .text-center}
+
+Spectrogram of chirp sweeping from 100 Hz to 10 kHz
+{: .text-center}
+
+
 {: .fw-500}
 
-- TOC
+## Table of contents
+{: .no_toc .text-delta }
+1. TOC
 {:toc}
 
-## Chapter 1
+## Chirp Generation Function
+Arduino does not provide any built-in chirp signal function. There are workarounds using MATLAB's built-in chirp function but our idea was to create this signal directly in Arduino with the SensEdu library.
 
-TODO: exaplanations about component specifics, voltages, range
+The `generateSawtoothChirp` and `generateTriangularChirp` functions both calculate the values to generate a sawtooth chirp and triangular chirp respectively and copy these values to the DAC's buffer.
 
-TODO: voltage for DC jack
+```c
+void generateSawtoothChirp(uint16_t* array)
+void generateTriangularChirp(uint16_t* array)
+```
 
-TODO: aplifiers gain
+### Parameters
+* `uint16_t* array` : A pointer to an array where the generated chirp signal will be stored.
 
-TODO: screenshots of specific parts of schematics for better understanding
 
-TODO: eveything needed for board modifications, pitfalls and problems
 
-TODO: guide, how to order the board
+### Description
+The generate chirp functions use two arrays `lut_sine` and `vChirp` to calculate the chirp values :
 
+* `lut_sine` is a LUT containing the values of a quarter sine wave. The `x` variable defines the resolution of `lut_sine`. A larger `x` will result in a more detailed LUT with more values which in turn increases the precision of the chirp values which will be calculated.
+* `vChirp` is the array in which the chirp values are calculated.
 
-styling examples: 
-* check library documentation code
-* [link1]
-* [link2]
 
----
+The following steps describe how the function was implemented :
 
-example text
+**Step 1**{: .text-blue-000} : Generate the quarter-wave LUT
 
-[example link]
+```c
+// Generate the quarter-wave sine LUT
+    for (int i = 0; i < 90 * x; i++) {
+        float phase_deg = (float)i * 90.0 / (90 * x); // Phase angle in degrees
+        float phase_rad = phase_deg * Pi / 180.0; // Phase angle to radians
+        lut_sine[i] = sin(phase_rad-Pi/2); // Store sine value in the LUT
+    }
+```
+
+**Step 2**{: .text-blue-000} : Calculate the instantaneous phase of the chirp signal and wrap between 0-360 degrees
 
-example list:
-* sdsd
-* sdsds
-* sdsds
+```c
+for (int i = 1; i < samples_int + 1; i++) {
+        float phase_rad = 2.0 * Pi * (0.5 * sK * (i - 1) / fs + START_FREQUENCY) * (i - 1) / fs; // Phase angle in radians
+        float phase_deg = phase_rad * 180.0 / Pi; // Phase angle to degrees
+        float phase_deg_wrapped = fmod(phase_deg, 360.0); // Wrap phase angle to 0-360 degrees
+```
 
-example list 2:
-1. sdsd
-2. sdsds
-3. sdsds
+**Step 3**{: .text-blue-000} : Calculate the value of the chirp using a quadrant-based approach. Scale and offset values to get 12 bit values.
 
-`marked text`
+```c
+if (phase_deg_wrapped <= 90) {
+            vChirp[i - 1] = lut_sine[(int)(phase_deg_wrapped / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
+        } else if (phase_deg_wrapped <= 180) {
+            vChirp[i - 1] = -lut_sine[(int)((180.0 - phase_deg_wrapped) / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
+        } else if (phase_deg_wrapped <= 270) {
+            vChirp[i - 1] = -lut_sine[(int)((phase_deg_wrapped - 180.0) / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
+        } else {
+            vChirp[i - 1] = lut_sine[(int)((360.0 - phase_deg_wrapped) / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
+        }
+```
 
-**Bold text**
+{: .warning }
+In this configuration, the first value of the chirp signal array is 0 (or 0 V in amplitude at DAC output). This initial value can be changed by modifying `sine_lut`.
 
-*Italics*
+**Step 4**{: .text-blue-000} : Copy the chirp signal's values to the DAC buffer
 
-### subchapter 1
 ```c
-// cool code
+// Copy the chirp signal to the DAC buffer
+    for (int i = 0; i < samples_int; i++) {
+        array[i] = (uint16_t)vChirp[i];
+    }
 ```
 
-## Chapter 2
+---
+
+## Main code
+Check out the [DAC]({% link Library/DAC.md %}) section for more information on the DAC library and different DAC related functions.
+
+The `Chirp_SawtoothMod.ino` and `Chirp_TriangularMod.ino` files contain the main code to generate the chirp signal, send the chirp signal to the DAC and enable the DAC.
+
+The code contains the following user settings to adjust the chirp signal :
 
-{. :warning}
-callout #1
+* `CHIRP_DURATION`{: .text-green-000} : The period of the chirp signal in seconds
+* `START_FREQUENCY`{: .text-green-000} : The start frequency of the chirp signal in Hz
+* `END_FREQUENCY`{: .text-green-000} : The end frequency of the chirp signal in Hz
+
+A very important variable in the main code is the sampling frequency `fs`. Based on the Nyquist-Shannon sampling theorem, `fs` needs to be at least double the maximum frequency (or end frequency) of the chirp signal.
+Keep in mind this sampling frequency will also be the DAC's output frequency in the `SensEdu_DAC_Settings` function.
+
+{: .warning }
+`fs` needs to be at least 2*END_FREQUENCY in order for the chirp signal to be generated properly.
+
+The `samples_int` is an integer representing the amount of samples for one period of the chirp signal. This value also represents the memory size in the `SENSEDU_DAC_BUFFER` and `SensEdu_DAC_Settings` functions.
+
+{: .warning }
+In this implementation, `samples_int` cannot exceed 7688.
+
+The values of the chirp are printed in the serial monitor.
+```c
+// Print the chirp signal LUT
+    Serial.println("start of the Chirp LUT");
+    for (int i = 0 ; i < samples_int; i++) { // loop for the LUT size
+        Serial.print("value ");
+        Serial.print(i+1);
+        Serial.print(" of the Chirp LUT: ");
+        Serial.println(lut[i]);
+    }
+```
 
-{. :note}
-callout #1
 
 
 [example link]: https://github.com/ShiegeChan/SensEdu

docs/assets/images/Chirp_signal.png

@@ -18,17 +18,17 @@ SENSEDU_ERROR SensEdu_GetError(void) {
         return error;
     }
 
-    error |= DMA_GetError();
+    error |= DAC_GetError();
     if (error) {
-        error |= SENSEDU_ERROR_DMA;
+        error |= SENSEDU_ERROR_DAC;
         return error;
     }
 
-    error |= DAC_GetError();
+    error |= DMA_GetError();
     if (error) {
-        error |= SENSEDU_ERROR_DAC;
+        error |= SENSEDU_ERROR_DMA;
         return error;
     }
 
     return error;
-}
+}

docs/assets/images/Chirp_spectro.png

@@ -171,6 +171,10 @@ static DAC_ERROR check_settings(SensEdu_DAC_Settings* settings) {
     if (settings->dac_channel != DAC_CH1 && settings->dac_channel != DAC_CH2) {
         return DAC_ERROR_INIT_FAILED;
     } 
+    
+    if (settings->sampling_freq > 15000000) {
+        return DAC_ERROR_SAMPLING_FREQ_TOO_HIGH;
+    } 
 
     if (settings->mem_address == 0x0000) {
         return DAC_ERROR_INIT_FAILED;
@@ -179,7 +183,7 @@ static DAC_ERROR check_settings(SensEdu_DAC_Settings* settings) {
     if (settings->mem_address == 0) {
         return DAC_ERROR_INIT_FAILED;
     } 
-    
+
     if (settings->wave_mode == SENSEDU_DAC_MODE_BURST_WAVE && settings->burst_num < 1) {
         settings->burst_num = 1; // be careful not to stuck in interrupt
         return DAC_ERROR_INIT_FAILED;

libraries/SensEdu/src/SensEdu.c

@@ -13,7 +13,8 @@ typedef enum {
     DAC_ERROR_WRONG_CHANNEL = 0x02,
     DAC_ERROR_DMA_UNDERRUN = 0x03,
     DAC_ERROR_ENABLED_BEFORE_INIT = 0x04,
-    DAC_ERROR_WRONG_MODE = 0x05
+    DAC_ERROR_WRONG_MODE = 0x05,
+    DAC_ERROR_SAMPLING_FREQ_TOO_HIGH = 0x06
 } DAC_ERROR;
 
 typedef enum {

libraries/SensEdu/src/dac.c

@@ -5,20 +5,26 @@
 /* -------------------------------------------------------------------------- */
 
 #define CHIRP_DURATION          0.001   // Duration of the chirp (in seconds)
-#define START_FREQUENCY         30300   // Start frequency (in Hz)
-#define END_FREQUENCY           35300  // Stop frequency (in Hz)
+#define START_FREQUENCY         1000   // Start frequency (in Hz)
+#define END_FREQUENCY           30000  // Stop frequency (in Hz)
 
 /* -------------------------------------------------------------------------- */
 /*                              Global Variables                              */
 /* -------------------------------------------------------------------------- */
 
 static uint32_t lib_error = 0;
 static uint8_t increment_flag = 1; // Run time modification flag
-const float fs = 42 * END_FREQUENCY; // Sampling frequency
+const float fs =  100 * END_FREQUENCY; // Sampling frequency
 const float samples = fs * CHIRP_DURATION; // Number of samples
 const uint32_t samples_int = (uint32_t)samples;
 static SENSEDU_DAC_BUFFER(lut, samples_int); // Buffer for the chirp signal
 
+// Initialize DAC settings
+    SensEdu_DAC_Settings dac1_settings = {
+        DAC_CH2, fs, (uint16_t*)lut, samples_int,
+        SENSEDU_DAC_MODE_CONTINUOUS_WAVE, 1
+    };
+
 /* -------------------------------------------------------------------------- */
 /*                                    Setup                                   */
 /* -------------------------------------------------------------------------- */
@@ -27,17 +33,17 @@ void setup() {
     Serial.begin(115200);
     while(!Serial);
 
-    // Initialize DAC settings
-    SensEdu_DAC_Settings dac1_settings = {
-        DAC1, fs, (uint16_t*)lut, samples_int,
-        SENSEDU_DAC_MODE_CONTINUOUS_WAVE, 2
-    };
+    // Check if array size exceeds 7688 or fs exceeds 15 MHz
+    if (samples_int > 7688 || fs > 15000000) {
+        Serial.println("Error: samples_int exceeds 7688 or fs exceeds 15 MHz!");
+        while (true);
+      }
 
     // Generate the chirp signal
-    generateChirpSignal(lut);
+    generateSawtoothChirp(lut);
 
     SensEdu_DAC_Init(&dac1_settings);
-    SensEdu_DAC_Enable(DAC1);
+    SensEdu_DAC_Enable(DAC_CH2);
 
     // Check for errors
     lib_error = SensEdu_GetError();
@@ -49,6 +55,7 @@ void setup() {
 
     Serial.println("Setup is successful.");
 
+    // Print the chirp signal LUT
     Serial.println("start of the Chirp LUT");
     for (int i = 0 ; i < samples_int; i++) { // loop for the LUT size
         Serial.print("value ");
@@ -58,7 +65,6 @@ void setup() {
     }
 }
 
-
 /* -------------------------------------------------------------------------- */
 /*                                    Loop                                    */
 /* -------------------------------------------------------------------------- */
@@ -70,7 +76,4 @@ void loop() {
         Serial.print("Error: 0x");
         Serial.println(lib_error, HEX);
     }
-
-    /* delay(100);
-    SensEdu_DAC_Enable(DAC1); */
 }

libraries/SensEdu/src/dac.h

@@ -1,17 +1,17 @@
-const uint32_t x = 5; // cos LUT resolution
+const uint32_t x = 5; // sine LUT resolution
 const float Pi = 3.14159; // pi
 
-// Generate the chirp signal
-void generateChirpSignal(uint16_t* array) {
+// Generate chirp signal with a sawtooth modulation
+void generateSawtoothChirp(uint16_t* array) {
 
-    float lut_cos[90 * x]; // Quarter-wave LUT for cosine values
-    float vChirp[samples_int]; // Chirp signal LUT
+    float lut_sine[90 * x]; // Quarter-wave LUT for sine values
+    float vChirp[samples_int]; // Chirp signal array
 
-    // Generate the quarter-wave cosine LUT
+    // Generate the quarter-wave sine LUT
     for (int i = 0; i < 90 * x; i++) {
         float phase_deg = (float)i * 90.0 / (90 * x); // Phase angle in degrees
         float phase_rad = phase_deg * Pi / 180.0; // Phase angle to radians
-        lut_cos[i] = cos(phase_rad); // Store cosine value in the LUT
+        lut_sine[i] = sin(phase_rad-Pi/2); // Store sine value in the LUT
     }
 
     // Generate the chirp signal
@@ -24,18 +24,18 @@ void generateChirpSignal(uint16_t* array) {
         float phase_deg_wrapped = fmod(phase_deg, 360.0); // Wrap phase angle to 0-360 degrees
 
         if (phase_deg_wrapped <= 90) {
-            vChirp[i - 1] = lut_cos[(int)(phase_deg_wrapped / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
+            vChirp[i - 1] = lut_sine[(int)(phase_deg_wrapped / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
         } else if (phase_deg_wrapped <= 180) {
-            vChirp[i - 1] = -lut_cos[(int)((180.0 - phase_deg_wrapped) / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
+            vChirp[i - 1] = -lut_sine[(int)((180.0 - phase_deg_wrapped) / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
         } else if (phase_deg_wrapped <= 270) {
-            vChirp[i - 1] = -lut_cos[(int)((phase_deg_wrapped - 180.0) / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
+            vChirp[i - 1] = -lut_sine[(int)((phase_deg_wrapped - 180.0) / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
         } else {
-            vChirp[i - 1] = lut_cos[(int)((360.0 - phase_deg_wrapped) / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
+            vChirp[i - 1] = lut_sine[(int)((360.0 - phase_deg_wrapped) / 90.0 * (90 * x - 1))] * 2047.5 + 2047.5;
         }
     }
 
      // Copy the chirp signal to the DAC buffer
     for (int i = 0; i < samples_int; i++) {
-        array[i] = (uint16_t)vChirp[i]; 
+        array[i] = (uint16_t)vChirp[i];
     }
 }