Merge branch 'docu_library' into github_dev

Author: vladysor

docs/Contributing/index.md

@@ -5,7 +5,112 @@ nav_order: 7
 permalink: /contributing/
 ---
 
-show here that they can add their own projects into projects/ by pull request
-issues
+# Contributing
+{: .fs-8 .fw-500 .no_toc}
+---
+
+Whether you're fixing bugs, adding new functionality, improving documentation, or creating your own projects, your contribution is highly valued and appreciated!
+{: .fw-500}
+
+- TOC
+{:toc}
+
+## Getting Started
+Before diving in, familiarize yourself with SensEdu:
+1.  Read through this wiki
+2.  Run basic examples and finished projects
+3.  Explore existing [issues] and [roadmap]({%link Contributing/index.md %}#roadmap)
+
+If you are still not sure, feel free to open a [discussion](https://github.com/ShiegeChan/SensEdu/discussions) and we'll find a job for you!
+
+## How to Contribute
+
+### Report Bugs
+Found a bug or unexpected behavior?  Help us fix it:
+1. Search for existing [issue] to avoid duplicates
+2. Create a new [issue] with `bug` label, providing:
+   1. Steps to reproduce
+   2. Expected vs actual behaviour
+   3. Screenshots, logs, oscilloscope waveforms or any additional data
+
+### Suggest Features
+Have an idea for a new sensor driver, project or optimization? 
+
+1. Create an issue with the `enhancement` label:
+   1. Descibe your idea in detail
+   2. Provide some usage examples
+
+### Improve Documentation
+Clear documentation is essential for our educational purposes, help us:
+* Fix typos or grammatical errors
+* Clarify ambiguous explanations to ensure everything is easy to understand
+* Fill in missing explanations
+
+{: .warning}
+The documentation is targeted to beginner students as well. Try to avoid logical skips, use simple language and add diagrams, image or code examples!
+
+### Improve Code
+
+1. Review the [library wiki section]({% link Library/index.md %}) and [naming convention]({% link Contributing/index.md %}#library-contributions)
+2. Assign yourself an [issue] or [discussion]
+3. Create a Pull Request (PR) and ask for a review
+
+{: .warning}
+Try to keep PRs small, focusing on one feature/fix
+
+### Submit Project
+Created something amazing using SensEdu? Share it with us! Check [Project Submissions]({% link Contributing/index.md %}#project-submissions) for detailed instructions.
+
+
+## Library Contributions
+
+Please follow naming convention used throught the code. Some of it described in [library main page]({% link Library/index.md %}). Be careful with usign new timers and dma streams, make sure they are free. Read through developers notes for each peripheral you want to modify.
+
+If you are an experienced embedded systems developer, feel free to optimize library code for better performance.
+
+{: .warning}
+Before pushing your library changes, make sure that **ALL** examples are working properly
+
+
+## Project Submissions
+
+If you have developed any projects using our shield, please feel free to push it to `projects\your_project\` directory. Additional examples for usage are much appreciated even if they are quite similar to already developed projects.
+
+If you are not sure, which project to develop there are some suggestions:
+* FSK (Frequency-Shift Keying) modulated communication between multiple boards
+* Radar speed gun
+* Weather station with barometric pressure sensor
+
+
+## Roadmap
+
+- [x] DAC Channel 2 support
+- [x] Automatic buffer alignment for DAC
+- [x] Cache coherence issues with DAC
+- [x] ADC3 support
+- [ ] Automatic buffer alignment for ADC
+- [ ] Rewrite ADC sampling frequency calculations
+- [ ] Separate timers for each ADC and DAC channel
+- [ ] Ultrasonic measurements performance boost using DMA
+- [ ] XCorr calibration algorithm
+- [ ] Improved Arduino-MATLAB serial communication
+- [ ] SensEdu library barometric sensor support
+- [ ] Examples for barometric pressure usage
+- [ ] 2-3 Fully developed projects as SensEdu showcase
+
+---
+
+Thank You to All Contributors!
+{: .fw-500 .mb-1}
+
+<ul class="list-style-none">
+{% for contributor in site.github.contributors %}
+  <li class="d-inline-block mr-1">
+     <a href="{{ contributor.html_url }}"><img src="{{ contributor.avatar_url }}" width="32" height="32" alt="{{ contributor.login }}"></a>
+  </li>
+{% endfor %}
+</ul>
 
-before pushing any changes in library, check every single related example to work properly
+[issue]: https://github.com/ShiegeChan/SensEdu/issues
+[issues]: https://github.com/ShiegeChan/SensEdu/issues
+[discussion]: https://github.com/ShiegeChan/SensEdu/discussions

docs/Library/ADC.md

@@ -20,6 +20,30 @@ The STM32H747 features three 16-bit ADCs with up to 20 multiplexed channels each
 
 ## Errors
 
+Main ADC error code is `0x20xx`. Find the way to display errors in your Arduino sketch [here]({% link Library/index.md %}#error-handling).
+
+An overview of possible errors for ADC:
+
+* `0x2000`: No Errors
+* `0x2001`: ADC was initialized before initialization
+* `0x2002`: Passed ADC instance is not either `ADC1`, `ADC2` nor `ADC3`
+* `0x2003`: ADC failed to disable
+* `0x2004`: ADC failed to power up
+* `0x2005`: Selected pin for ADC is not reachable. Refer to the [table]({% link Library/ADC.md %}#notes) to find proper pins for each ADC instance
+* `0x2006`: Unexpected pin number during initialization. Must be at least 1
+* `0x2007`: Unexpected address or memory size for DMA
+* `0x2008`: Unexpected sampling frequency. Must be at least 1kHz
+* `0x2009`: Software polling in `SENSEDU_ADC_MODE_ONE_SHOT` is currently broken. Use `SENSEDU_ADC_MODE_CONT` or `SENSEDU_ADC_MODE_CONT_TIM_TRIGGERED`. If you want to look into this and have a try fixing it, refer to [this issue]
+
+An overview of critical errors. They shouldn't happen in normal user case and indicate some problems in library code:
+
+* `0x20A0`: PLL configuration failed
+* `0x20A1`: Internal logic for channel selectrion failed
+* `0x20A1`: Internal logic for setting sample time failed
+* `0x20A2`: Operation mode selection accepted unexpected value. Should never happen, since all possible values of type `SENSEDU_ADC_CONVMODE` must be handled internally
+* `0x20A3`: Data management mode selection accepted unexpected value. Should never happen, since all possible values of type `SENSEDU_ADC_DMA` must be handled internally
+
+
 ## Structs
 
 ### SensEdu_ADC_Settings

docs/Library/DAC.md

@@ -29,6 +29,17 @@ Each of the methods are usefull for different applications.
 
 ## Errors
 
+Main DAC error code is `0x30xx`. Find the way to display errors in your Arduino sketch [here]({% link Library/index.md %}#error-handling).
+
+An overview of possible errors for DAC:
+* `0x3000`:
+* `0x3001`:
+* `0x3002`:
+
+An overview of critical errors. They shouldn't happen in normal user case and indicate some problems in library code:
+* `0x30A0`:
+* `0x30A1`:
+
 ## Structs
 
 ### SensEdu_DAC_Settings

docs/Library/Timers.md

@@ -18,6 +18,12 @@ Timers allow precise event scheduling, such as creating delays or setting sampli
 
 ## Errors
 
+Main timers error code is `0x10xx`. Find the way to display errors in your Arduino sketch [here]({% link Library/index.md %}#error-handling).
+
+An overview of possible errors for timers:
+* `0x1000`: No Errors
+* `0x1001`: Unexpected DAC frequency. Maximum possible is 60MHz, refer to [these calculations]({% link Library/Timers.md %}#frequency-settings) for more details
+
 ## Functions
 
 ### SensEdu_TIMER_DelayInit

docs/Projects/index.md

@@ -5,9 +5,31 @@ nav_order: 5
 permalink: /projects/
 ---
 
-# Projects
+# Projects with SensEdu shield and Arduino GIGA R1 platform using SensEdu Library
 {: .fs-8 .fw-500}
 ---
 
-(short description)
+The following is the documentation of some of the projects already done by the developers of the board and the library. These projects aim to show how to use 
+the board shield with Arduino GIGA R1 platform, and at the same time utilize the custom SensEdu Library. 
+
+{: .note}
+The SensEdu Library is *NOT* dependent on the SensEdu Board and Arduino GIGA platform, rather on the microcontroller of the platform you are using. 
+
+As per the documentation for the board (insert link), the shield is mainly used as a tranciever utilizing the speakers and the microphones on the board. 
+Therefore, some of the project ideas are: 
+* ultrasound distance measurements - obtaining the distance of an object by measuring the TOF (*time-of-flight*) of the reflected signal
+* data processing on MCU with cross-correlation algorithm - advanced signal processing 
+* wifi communication - Arduino GIGA R1 platform supports WiFi communication which can be used for faster data transfer between two or more systems
+* chirp signal generation - there are many different applications that utilize the chirp signal and the first part of those applications is having the actual chirp
+* wheather station - with the pressure sensor provided on the SensEdu shield
+
+
+
+
+
+
+
+
+
+
 {: .fw-500}

docs/index.md

@@ -58,6 +58,7 @@ SensEdu was made possible thanks to these freely available tools:
 * [Arduino] and [Arduino IDE 2.x]
 * [STM32H747 Documentation] and [STM32CubeMX]
 * [Jekyll] and [Just the Docs] template
+* [KiCAD]
 
 Thank You to All Contributors!
 {: .fw-500 .mb-1}
@@ -77,4 +78,5 @@ Thank You to All Contributors!
 [Jekyll]: https://jekyllrb.com/
 [Just the Docs]: https://github.com/just-the-docs/just-the-docs/tree/main
 [STM32H747]: https://www.st.com/en/microcontrollers-microprocessors/stm32h747-757.html
-[Arduino GIGA R1 WiFi]: https://docs.arduino.cc/hardware/giga-r1-wifi/
+[Arduino GIGA R1 WiFi]: https://docs.arduino.cc/hardware/giga-r1-wifi/
+[KiCAD]: https://www.kicad.org/

libraries/SensEdu/src/adc.c

@@ -214,22 +214,22 @@ adc_data* get_adc_data(ADC_TypeDef* ADC) {
 
 static ADC_ERROR check_settings(SensEdu_ADC_Settings* settings) {
     if (settings->adc != ADC1 && settings->adc != ADC2 && settings->adc != ADC3) {
-        return ADC_ERROR_WRONG_ADC;
+        return ADC_ERROR_WRONG_ADC_INSTANCE;
     } 
 
     if (settings->pin_num < 1) {
-        return ADC_ERROR_WRONG_INIT_SETTINGS_PARAMETERS;
+        return ADC_ERROR_INIT_PIN_NUMBER;
     } 
 
     if (settings->dma_mode == SENSEDU_ADC_DMA_CONNECT) {
         if (settings->mem_address == 0x0000 || settings->mem_size == 0) {
-            return ADC_ERROR_WRONG_INIT_SETTINGS_PARAMETERS;
+            return ADC_ERROR_INIT_DMA_MEMORY;
         }
     }
 
     if (settings->conv_mode == SENSEDU_ADC_MODE_CONT_TIM_TRIGGERED) {
         if (settings->sampling_freq < 1000) {
-            return ADC_ERROR_BAD_SAMPLING_FREQ;
+            return ADC_ERROR_INIT_SAMPLING_FREQ;
         }
     } 
 
@@ -292,7 +292,7 @@ void configure_pll2(void) {
 void adc_init(ADC_TypeDef* ADC, uint8_t* arduino_pins, uint8_t adc_pin_num, SENSEDU_ADC_CONVMODE mode, SENSEDU_ADC_DMA adc_dma) {
 
     if (READ_BIT(ADC->CR, ADC_CR_ADCAL | ADC_CR_JADSTART | ADC_CR_ADSTART | ADC_CR_ADSTP | ADC_CR_ADDIS | ADC_CR_ADEN)) {
-        error = ADC_ERROR_ADC_CONFIG_VOLTAGE_REGULATOR;
+        error = ADC_ERROR_ADC_INIT;
     }
 
     // exit deep power-down

libraries/SensEdu/src/adc.h

@@ -15,19 +15,21 @@ extern "C" {
 
 typedef enum {
     ADC_ERROR_NO_ERRORS = 0x00,
-    ADC_ERROR_WRONG_ADC = 0x01, // use only ADC1 or ADC2
-    ADC_ERROR_PLL_CONFIG = 0x02,
-    ADC_ERROR_ADC_CONFIG_VOLTAGE_REGULATOR = 0x03,
-    ADC_ERROR_ADC_DISABLE_FAIL = 0x04,
-    ADC_ERROR_ADC_ENABLE_FAIL = 0x05,
-    ADC_ERROR_PICKED_WRONG_CHANNEL = 0x06,
-    ADC_ERROR_WRONG_SEQUENCE = 0x07,
-    ADC_ERROR_SAMPLE_TIME_SETTING = 0x08,
-    ADC_ERROR_WRONG_OPERATION_MODE = 0x09,
-    ADC_ERROR_WRONG_DATA_MANAGEMENT_MODE = 0x0A,
-    ADC_ERROR_WRONG_INIT_SETTINGS_PARAMETERS = 0x0B,
-    ADC_ERROR_BAD_SAMPLING_FREQ = 0x0C,
-    ADC_ERROR_NOT_SUPPORTED_MODE = 0x0D
+    ADC_ERROR_ADC_INIT = 0x01,
+    ADC_ERROR_WRONG_ADC_INSTANCE = 0x02,
+    ADC_ERROR_ADC_DISABLE_FAIL = 0x03,
+    ADC_ERROR_ADC_ENABLE_FAIL = 0x04,
+    ADC_ERROR_PICKED_WRONG_CHANNEL = 0x05,
+    ADC_ERROR_INIT_PIN_NUMBER = 0x06,
+    ADC_ERROR_INIT_DMA_MEMORY = 0x07,
+    ADC_ERROR_INIT_SAMPLING_FREQ = 0x08,
+    ADC_ERROR_NOT_SUPPORTED_MODE = 0x09,
+
+    ADC_ERROR_PLL_CONFIG = 0xA0,
+    ADC_ERROR_WRONG_SEQUENCE = 0xA1,
+    ADC_ERROR_SAMPLE_TIME_SETTING = 0xA2,
+    ADC_ERROR_WRONG_OPERATION_MODE = 0xA3,
+    ADC_ERROR_WRONG_DATA_MANAGEMENT_MODE = 0xA4
 } ADC_ERROR;
 
 typedef enum {