Update README.md

README.md

@@ -1,13 +1,151 @@
 # Introduction
 
-A tiny and simple buzzer library, based on interrupt.
+A tiny and simple buzzer library, implements a simple turnon, turnoff, and the capabilitie to play loops and ringtones.
+
+All functions works in NON BLOCKING MODE, so, you application will never stops the execution while handling with the device, and, inclusivelly, implementing a `callback` when an operation end.
 
 Supports any microcontroller and Passive or Active buzzer.
 
 # How to Use
 
-.. soon ..
+First, declares your ```buzzer_t``` with, at least, the ```pwmOut``` or ```gpioOut``` (just pick one! the other fxn must be `NULL`). About the functions:
+
+- `void pwmOut(uint32_t freq)` : Is used for PASSIVE buzzers, this function returns `void` and receive only the the `freq` argument. When implementing, the freq=0, the device MUST turnoff PWM.
+- `void gpioOut(uint32_t val)` : Is used for ACTIVE buzzer, the value `val` needs to be turnon when is `1`, and `0` turnoff the Buzzer. These buzzers, doesn't can set frequency values.
+
+The lib will automatically identifies the Buzzer type on `buzzer_init()`, by checking the defined fxn.
+
+Another parameter that needs to be implemented, if user want's to user `buzzer_start` and `buzzer_start_array`, is the `interruptMs`, that only indicates how often you will call the `buzzer_interrupt` in a timer/task routine, in milliseconds.
+
+This parameter serves to cronometer the buzzer, turning on and off, for loops, ringtones, etc.
+
+## Configuring for PASSIVE Buzzer
+
+Bellow, is this example, we are configuring a buzzer in a generic chipset, with a 50ms timer interrupt and a PWM function.
+
+```C
+void __pwm_buzzer_chipset(uint32_t freq);
+
+// Buzzer Handler
+buzzer_t Buzzer = {
+  .pwmOut = __pwm_chipset,
+  .interruptMs = 50
+}
+
+// Functions
+void __pwm_buzzer_chipset(uint32_t freq){
+  if (freq == 0){
+    chipset_pwm_turnoff();
+  }
+  else{
+    chipset_pwm_turnon();
+    chipset_pwM_set_freq(freq);
+  }
+}
+
+// Interrupts
+void __tim_interrupt_50ms(){
+  buzzer_interrupt(&Buzzer);
+}
+
+// Main
+void main(){
+  buzzer_init(&Buzzer);
+}
+```
+
+## Configuring for ACTIVE Buzzer
+
+In this example, an active buzzer is configured and implemented, with 100ms timer interrupt and GPIO to control the Buzzer.
+
+```C
+void __gpio_pwm_chipset(uint32_t val);
+
+// Buzzer Handler
+buzzer_t Buzzer = {
+  .pwmOut = __pwm_chipset,
+  .interruptMs = 100
+}
+
+// Functions
+void __gpio_pwm_chipset(uint32_t val){
+  chipset_gpio(BUZZER_GPIO_Port, BUZZER_Pin, val);
+}
+
+// Interrupts
+void __tim_interrupt_100ms(){
+  buzzer_interrupt(&Buzzer);
+}
+
+// Main
+void main(){
+  buzzer_init(&Buzzer);
+}
+```
 
 # Examples
 
-.. soon ..
+For the examples, consideer a Passive Buzzer, configured with timer and everything :) For Active buzzers, all freq parameters can be `0` or `NULL`.
+
+## Turnon buzzer and Turnoff manually
+
+```C
+void main(){
+  ...
+  // turnon buzzer with a 1500Hz frequency
+  buzzer_turn_on(&Buzzer, 1500);
+  
+  // delay for 500ms
+  chipset_delay_ms(500);
+  
+  // turnoff buzzer
+  buzzer_stop(&Buzzer);
+}
+```
+
+## Turnon buzzer for 500ms
+
+```C
+void main(){
+  ...
+  // turnon buzzer with a 1500Hz frequency for 500ms
+  buzzer_start(&Buzzer, 1500, 500, BUZZER_LOOP_OFF);
+}
+```
+
+## "Blink" buzzer for period of 500ms
+
+```C
+void main(){
+  ...
+  // turnon buzzer with a 2500Hz frequency
+  buzzer_start(&Buzzer, 2500, 500, BUZZER_LOOP_ON);
+  
+  // The BUZZER_LOOP_ON parameter indicates that the Buzzer will be turnon for 500ms,
+  // turnoff for the same period, and repeat the process
+}
+```
+
+## Play Super Mario Ringtone and turnon a LED after finish
+
+```C
+// this callback is called when a buzzer_start or buzzer_start_array finish
+// the solicitaded operation. In this case, when the Mario Ringtone is
+// finished, the callback will be called
+void buzzer_end_callback(buzzer_t *buzzer){
+  led_red(TRUE);
+}
+
+void main(){
+  ...
+  // play Mario Theme ringtone, that's included on the library :D
+  buzzer_start_array(&Buzzer, mario_theme_time, mario_theme_melody, mario_theme_len);
+
+}
+```
+
+# Doubts
+
+Any doubts, or issues, just post an issue.
+
+Best regards folks.