[GSoC'20] Name: Manthan Admane, Idea: write examples for official libraries

[MisterAwesome23]

---

Purpose of this issue : To initiate communication with Arduino community for GSoC20.

---

Serial.println(Hello);

• Final year computer engineering undergrad. Keen interest in electronics and experience with Arduino.
• Aiming to work on the idea- write examples for official libraries.
• Looking forward to it.

---

Checklist: (February 20th - March 31st)

• Read the official GSoC student guide and the GSoC FAQ.
• Review our ideas list.
• Ask questions about projects you're potentially interested in on the issue tracker
• Introduce yourself on our GSoC issue tracker.
• Fix a bug in one of our repositories [Aiming- https://github.com/arduino-libraries]
• Get feedback from us (via the issue tracker) before you submit a final application.

[MisterAwesome23]

Questions related to- Idea: write examples for official libraries

1. Where can I share my initial proposal drafts. Since I'm using markdown, should I convert it to a pdf or word and share it via GSoC official sharing option? Or is there any other way?

2. To finalize on the deliverable's and approximate milestones and dates, I wanted to know a rough expectation of 'how many' examples to be added. Also, wanted to know whether main focus is on just the number of examples to be added or the bonus- "Hardware prototype and Usage and project Hub" are equally important aspects.

[alranel]

Hello @MisterAwesome23. These comments on GitHub support Markdown formatting so you can just paste them here. To finalize the submission the GSoC interface shall be used.

The number of examples to write depends on their complexity. We don't care much about the quantity but we prefer quality. I suggest to work on 3 to 5 libraries and think about advanced examples that can inspire developers. A hardware prototype gives bonus points :)

[MisterAwesome23]

REQUEST FOR PROPOSAL FEEDBACK

Draft Date: 24 March, 2020.

Arduino @ Google Summer of Code 2020 Proposal

Project: Write Examples For Official Libraries

Name: Manthan Admane
GitHub Username: MisterAwesome23
GithubIssueTracker: #110
Email: admanemanthan23@gmail.com

---

Abstract

Right from beginner to all time pros, everyone starts a new project implementation with an idea in mind primarily and the intense drive to code secondly. To make this task of coding easier, every official library (even unofficial ones should) contains examples- leveraging basic syntax and functionality. Basically, they are a base code collection that makes it easy for the user to connect and to test a sensor, display, module, or any hardware (or even software service functionality) and focus on the "idea" instead. This project aims at adding adding improving appropriate examples to existing official libraries.

Technical Details

Based on discussions with authorities in charge of this project-
The project aims to acquire quality over quantity.
The project, in my opinion, should aim to address "FOUR" libraries completely than aiming more with lower efficiency.

As of today, Arduino has 90 official libraries many of which many need improvements especially in the examples section- the section which is very useful for beginners and are also the stepping stone of any new project.

To instantiate my research rather than manually going through each each library I wrote a simple python script to get names of all repositories:

import requests
import json

url = "https://api.github.com/orgs/arduino-libraries/repos"
payload = ""
headers = {
    'cache-control': "no-cache",
    'Postman-Token': "2955dab5-a5f5-407e-a5c8-7533464393c9"
    }
response = requests.request("GET", url, data=payload, headers=headers)

todos = json.loads(response.text)
loopEnd = len(todos)  

i = 0
while i < loopEnd:
  print(todos[i]["name"])
  i += 1

This prints out all the repositories. [Note: for some reason the github api returned 30 repositories and I'll be opening a issue for this]

Furthermore, I used the Google Sheets Api to formulate the following sheet automatically (kindly refer to the link)-

https://docs.google.com/spreadsheets/d/1LOpYnRRaj5A0UoGtOMZDg1WZ_abkdnXNdqQl3q_zyTI/edit?usp=sharing

Here I have mentioned all the libraries with the number of examples each have.

• The ones with zero are marked absent.
• Ones having equal six or more relevant examples are marked sufficient
• Others are marked accordingly.

This will help me and mentors to funnel down to which exact libraries to focus on.

Also, the issues column indicate the issue I think is relevant to me. Relevant in terms of what I can and am willing to work right now. With the COVID-19 lock-downs, I am in my hometown with in-capabilities to have a a physical hardware hands on hence these respective issues were targeted.
The issue column also contain any relevant piece of resource/comment which could be of help to the library.
Exploring and fixing these issues will familiarize me with the standards, rules and regulations of the Arduino community.
Issues I have started working on-

1. Changing amplitude example to output values in dB arduino-libraries/ArduinoSound#24
2. [DOC] https://www.arduino.cc/en/Reference/USBHost only talks about Due... arduino-libraries/USBHost#14
3. Get Code not working in Arduino.cc reference link of AudioFrequencyMeter arduino-libraries/AudioFrequencyMeter#15

Also, I aim on covering all 90 libraries having a fair idea of all the standard protocols each library should abide by before selecting the four (approximate number) libraries to be aimed under this project.

Moreover, in case the the project demands to work on an unofficial library as well, I'd be more than willing to research more on this and suggest a few interesting ones like boltiot-arduino-helper, though this should not be a priority in my opinion.

Finally, I would also like to express my interest in Google Season of Docs 2020 as well. I do understand it might be a bit too early to mention this, but the reason for mentioning is my willingness to continue with the same organisation on a similar path for a longer term rather than a short project based one only.

Schedule of Deliverables

Application Review Period (March 31, 2020 - April 27, 2020)

• Cover all 90 repositories under arduino-official libraries.
• Fix issues and create necessary pull-requests.
• Finalize on ten (approximate number) which I feel are most relevant to this project and align with my interests.

Community Bonding Period (April 27, 2020 - May 18, 2020)

1. Get familiar with the Style-guide and contribution guidelines for the Arduino community.
2. Discuss and finalize plan or timeline with my mentor.
3. Plan platform of communication for weekly calls/meetings, to submit my weekly report to the mentor (also finalize on report formats- Example: A GitHub blog).
4. Plan my work time-table for your summer.
5. Most importantly, get innately involved in the community like a family member :)

Phase 1 (May 18, 2020 - June 15, 2020)

• Deliverable 1
  • Week 1- Library One resource collection and familiarization. Draft examples and implementation.
  • Week 2- Finalize the example and fix problems for example along with a projectHub submission of the library.
• Deliverable 2
  • Week 3- Library Two working. Adjust working hours and styles with reference to Library One. Change buffer time and methodologies.
  • Week 4- Fix problems in the added examples and work on prototype examples.

Phase 2 (June 15, 2020 - July 13, 2020)

• Deliverable 3
  • Week 5- Library Three resource collection and familiarization. Focus on improving the efficiency of work from Week 1-4 learning's.
  • Week 6- Fix bugs and issues suggested by mentor and community. Proceed to projectHub possibilities.
• Deliverable 4
  • Week 7- Library FOUR resource collection and familiarization. Create examples and draft formal implementation diagrams for the respective example.
  • Week 8- Fix issues with newly added example and build a basic hardware prototype displaying the usage of added example.

Final Week (August 10, 2020 - August 17, 2020)

Finalize on all the documentations. Fix upcoming bugs and proof-read all implementations. Rather than focusing on adding more, the focus will be on consolidating what already has been implemented in the project.

Development Experience

One ongoing final year project (IoT + Data Science) and one completed project (Android app) both implemented remotely in team of four members via GitHub portraying familiarity with git.
1. https://github.com/SDLMiniProject/PPMS
2. https://github.com/BE-Project-cl-AIR-ity/clairity

Past project implementation and understanding with techniques like Pomodoro and Timeboxing gives me an efficiency advantage.

Other Experiences

Using GitHub API and GoogleSheets API for this very project to portraying my abilities to focus on efficiency of work.

University certified course on Internet of Things.

Wifi deauther under learning ethical hacking-
https://github.com/MisterAwesome23/esp8266_deauther

Why this project?

I have been applying to GSoC for past two years (not selected). One thing I've learned is- its all about Open Source Contributions and being a selfless part. Self learning and everything else are just supplementary positive add-ons. I personally have know Arduino since my childhood and I would choose contributing to something I consume than to work for something I have no direct co-relations to. This year I will be applying to one organisation and only one project- Write Examples For Official Libraries. I want to keep my area of work as niche as possible and contribute as much as I can no matter how small or big. Also, even if I do not get selected for GSoC2020 (which I really want be selected for) I'll continue with Arduino as my organisation and start for Google Summer of Docs 2020 abiding by my want to be innately connected to an open source community.

Do you have any other commitments during the GSoC period?

• I will be having my university practical examinations for four days and university final year written examinations (four exams). Because of the ongoing COVID-19 scenarios the dates are not consolidated or announced
• I will be starting my Masters in Management Information System Fall 2020. Again, dates not fixed / announced.

[MisterAwesome23]

Kindly review the proposal.
Also, I had a few questions-

1. Where can I open a common issue for the arduino-libraries organisation (This link- https://github.com/arduino-libraries/). Git hub API seems to return only 30 libraries when hit.

2. Also, can I use the Huzzah Father Board for now (Since it is the only one available with me right now with the COVID lock-down scenario), to demonstrate example, prototype and project architecture demonstration.

[per1234]

Note: for some reason the github api returned 30 repositories and I'll be opening a issue for this

This is due to pagination:
https://developer.github.com/v3/#pagination
It's not a bug. General purpose code that uses the GitHub API should correctly handle pagination. In this case, since the arduino-libraries organization currently has <100 repositories, the dirty workaround would be to simply set the per_page parameter to 100. Arduino frequently publishes new libraries so the count may not be <100 for very long.

Where can I open a common issue for the arduino-libraries organisation

GitHub does not provide any official way to do this. However, we use the arduino/Arduino issue tracker as our catch-all for issues that aren't specific to any of our other repositories. So that would be the appropriate place to open an issue related to the official Arduino libraries in general, rather than one or two in specific.

Also, can I use the Huzzah Father Board for now (Since it is the only one available with me right now with the COVID lock-down scenario), to demonstrate example, prototype and project architecture demonstration.

Some of our libraries are not architecture-specific. With these libraries, it is possible to use most Arduino-compatible boards for testing and development. However, many of our libraries are architecture-specific and very few of these are compatible with the ESP8266. This would limit your options for which libraries you can work on.

There can be subtle differences between 3rd party platforms like ESP8266 and the official Arduino platforms. In rare cases, this could result in code that works fine for ESP8266 not working on an official Arduino board. This is less likely with the simple programs of most example sketches.

Since Arduino doesn't make any ESP8266-based boards, it wouldn't make sense to provide ESP8266-specific examples with our libraries. That is something that would be better done as a 3rd party volunteer project and published in your own GitHub repository. The exception is the support libraries for Arduino IoT Cloud. Since ESP8266 is one of the boards supported by Arduino IoT Cloud, ESP8266 support has been added to the examples for those libraries. The approach so far has been to make the examples compatible with all boards supported by Arduino IoT Cloud, rather than making separate examples for each board.

[MisterAwesome23]

This is due to pagination:
https://developer.github.com/v3/#pagination
It's not a bug. General purpose code that uses the GitHub API should correctly handle pagination. In this case, since the arduino-libraries organization currently has <100 repositories, the dirty workaround would be to simply set the per_page parameter to 100. Arduino frequently publishes new libraries so the count may not be <100 for very long.

Thanks for this-
I can now get all repository names using curl and the following link-
https://api.github.com/orgs/arduino-libraries/repos?per_page=100

Also, can I use the Huzzah Father Board for now (Since it is the only one available with me right now with the COVID lock-down scenario), to demonstrate example, prototype and project architecture demonstration.

Oh I see your concern here and I'll keep a note of that. But, I actually meant, to demonstrate an example of how we will be actually working on the project, for the sake of proposal- can I use an example for Huzzah since that's the only physical board I have right now. Just to demonstrate and explore the projectHub and architecture creations which will be actually needed once assigned official libraries to work on under the official project.

[MisterAwesome23]

REQUEST FOR PROPOSAL FEEDBACK

Draft date: 26 March, 2020

---

Arduino @ Google Summer of Code 2020 Proposal

Project: Write Examples For Official Libraries

Name: Manthan Admane
GitHub Username: MisterAwesome23
GithubIssueTracker: #110
Email: admanemanthan23@gmail.com
Skype Name: live:admanemanthan23
Time zone: India (GMT+5:30)

---

Abstract

Right from beginner to all time pros, everyone starts a new project implementation with an idea in mind primarily and the intense drive to code secondly. To make this task of coding easier, every official library (even unofficial ones should) contains examples- leveraging basic syntax and functionality. Basically, they are a base code collection that makes it easy for the user to connect and to test a sensor, display, module, or any hardware (or even software service functionality) and focus on the "idea" instead. This project aims at adding adding improving appropriate examples to existing official libraries.

Technical Details

Based on discussions with authorities in charge of this project-
The project aims to acquire quality over quantity.
The project, in my opinion, should aim to address "FOUR" libraries completely than aiming more with lower efficiency.

As of today, Arduino has 90 official libraries many of which many need improvements especially in the examples section- the section which is very useful for beginners and are also the stepping stone of any new project.

To instantiate my research rather than manually going through each each library I wrote a simple python script to get names of all repositories:

import requests
import json

url = "https://api.github.com/orgs/arduino-libraries/repos?per_page=100"
payload = ""
headers = {
    'cache-control': "no-cache",
    'Postman-Token': "2955dab5-a5f5-407e-a5c8-7533464393c9"
    }
response = requests.request("GET", url, data=payload, headers=headers)

todos = json.loads(response.text)
loopEnd = len(todos)  

i = 0
while i < loopEnd:
  print(todos[i]["name"])
  i += 1

This prints out all the repositories names.

Furthermore, I used the Google Sheets Api to formulate the following sheet automatically (kindly refer to the link)-

https://docs.google.com/spreadsheets/d/1LOpYnRRaj5A0UoGtOMZDg1WZ_abkdnXNdqQl3q_zyTI/edit?usp=sharing

Here I have mentioned all the libraries with the number of examples each have.

• The ones with zero are marked absent.
• Ones having equal six or more relevant examples are marked sufficient
• Others are marked accordingly.

This will help me and mentors to funnel down to which exact libraries to focus on.

Also, the issues column indicate the issue I think is relevant to me. Relevant in terms of what I can and am willing to work right now. The issue column also contain any relevant piece of resource/comment which could be of help to the library.

Also, I aim on covering all 90 libraries having a fair idea of all the standard protocols each library should abide by before selecting the four (approximate number) libraries to be aimed under this project.

Moreover, in case the the project demands to work on an unofficial library as well, I'd be more than willing to research more on this and suggest a few interesting ones like boltiot-arduino-helper, though this should not be a priority in my opinion.

Illustration of writing example for an official library

With the COVID-19 lock-downs, I am in my hometown with minimum physical hardware available hands on hence this simple illustration was chosen. For the actual project implementation the complexity of the example can certainly be higher which will decided upon discussions with the assigned mentor.

[Note: This is just a demo example just to portray the methodologies that can be used in implementing actual project examples to official library]

Demo Example Name: SimpleSiren

Description (added to SimpleSiren.txt): Haven't we all used horns / sirens. Just a touch on switch and siren blows. Just a tap back and its stops honking. This library provides just this. A bare minimum framework simulating a siren functioning.

Components needed (added to SimpleSiren.ino header comments): Arduino board (UNO used to demonstrate), Push button switch, 10k Ohm Resistor, 220 Ohm Resistor, Buzzer.

Appropriate place to be added:
https://github.com/arduino/Arduino/tree/master/build/shared/examples/02.Digital/SimpleSiren

Layout (added as layout.png): An image showing how connections have to be made. This layout was created using Fritzing.

Link to Layout.png-
https://drive.google.com/file/d/1NOqEI5awx0pS5KBmi1cFsqaoITD3Kt0X/view?usp=sharing

Schematic (added as schematic.png): An image showing the schematic diagram of an UNO with SimpleSiren setup.

Link to Scehmatic.png-
https://drive.google.com/file/d/141HdATR8_6ggbrRTScs8v9CQuTajhFSN/view?usp=sharing

Code (saved as SimpleSiren.ino):

/*
  SimpleSiren

  Description:
  Haven't we all used horns / sirens. Just a touch on switch and siren blows.
  Just a tap back and its stops honking. This library provides just this.
  A bare minimum framework simulating a siren functioning.  

  A buzzer which is connected to digital pin 13 is blown,
  when pressing a pushbutton attached to pin 2.

  The circuit:
  - Buzzer attached from pin 13 to ground
  - pushbutton attached to pin 2 from +5V
  - 10K resistor attached to pin 2 from ground

  - Note: on most Arduinos do NOT come with a Buzzer on the board
    hence has to be attached to pin 13.

  created March 2020,
  by Manthan Admane
  
*/

// constants won't change. They're used here to set pin numbers:
const int buttonPin = 2;     // the number of the pushbutton pin
const int buzzerPin =  13;      // the number of the Buzzer pin

// variables will change:
int buttonState = 0;         // variable for reading the pushbutton status

void setup() {
  // initialize the Buzzer pin as an output:
  pinMode(buzzerPin, OUTPUT);
  // initialize the pushbutton pin as an input:
  pinMode(buttonPin, INPUT);
}

void loop() {
  // read the state of the pushbutton value:
  buttonState = digitalRead(buttonPin);

  // check if the pushbutton is pressed. If it is, the buttonState is HIGH:
  if (buttonState == HIGH) {
    // turn Buzzer on:
    digitalWrite(buzzerPin, HIGH);
  } else {
    // turn Buzzer off:
    digitalWrite(buzzerPin, LOW);
  }
}

As a demonstration of familiarity with git and GitHub, I've created a pull request with the above mentioned additions on official Arduino repository-
Link to pull: arduino/Arduino#9920

Contributions

1. Changing amplitude example to output values in dB arduino-libraries/ArduinoSound#24
2. [DOC] https://www.arduino.cc/en/Reference/USBHost only talks about Due... arduino-libraries/USBHost#14
3. Get Code not working in Arduino.cc reference link of AudioFrequencyMeter arduino-libraries/AudioFrequencyMeter#15

Schedule of Deliverables

Application Review Period (March 31, 2020 - April 27, 2020)

• Cover all 90 repositories under arduino-official libraries.
• Fix issues and create necessary pull-requests.
• Finalize on ten (approximate number) which I feel are most relevant to this project and align with my interests.

Community Bonding Period (April 27, 2020 - May 18, 2020)

1. Get familiar with the Style-guide and contribution guidelines for the Arduino community.
2. Discuss and finalize plan or timeline with my mentor.
3. Plan platform of communication for weekly calls/meetings, to submit my weekly report to the mentor (also finalize on report formats- Example: A GitHub blog).
4. Plan my work time-table for your summer.
5. Most importantly, get innately involved in the community like a family member :)

Phase 1 (May 18, 2020 - June 15, 2020)

• Deliverable 1
  • Week 1- Library One resource collection and familiarization. Draft examples and implementation.
  • Week 2- Finalize the example and fix problems for example along with a projectHub submission of the library.
• Deliverable 2
  • Week 3- Library Two working. Adjust working hours and styles with reference to Library One. Change buffer time and methodologies.
  • Week 4- Fix problems in the added examples and work on prototype examples.

Phase 2 (June 15, 2020 - July 13, 2020)

• Deliverable 3
  • Week 5- Library Three resource collection and familiarization. Focus on improving the efficiency of work from Week 1-4 learning's.
  • Week 6- Fix bugs and issues suggested by mentor and community. Proceed to projectHub possibilities.
• Deliverable 4
  • Week 7- Library FOUR resource collection and familiarization. Create examples and draft formal implementation diagrams for the respective example.
  • Week 8- Fix issues with newly added example and build a basic hardware prototype displaying the usage of added example.

Final Week (August 10, 2020 - August 17, 2020)

Finalize on all the documentations. Fix upcoming bugs and proof-read all implementations. Rather than focusing on adding more, the focus will be on consolidating what already has been implemented in the project.

Development Experience

One ongoing final year project (IoT + Data Science) and one completed project (Android app) both implemented remotely in team of four members via GitHub portraying familiarity with git.
1. https://github.com/SDLMiniProject/PPMS
2. https://github.com/BE-Project-cl-AIR-ity/clairity

Past project implementation and understanding with techniques like Pomodoro and Timeboxing gives me an efficiency advantage.

Other Experiences

Using GitHub API and GoogleSheets API for this very project to portraying my abilities to focus on efficiency of work.

University certified course on Internet of Things.

Wifi deauther under learning ethical hacking-
https://github.com/MisterAwesome23/esp8266_deauther

Why this project?

I have been applying to GSoC for past two years (not selected). One thing I've learned is- its all about Open Source Contributions and being a selfless part. Self learning and everything else are just supplementary positive add-ons. I personally have know Arduino since my childhood and I would choose contributing to something I consume than to work for something I have no direct co-relations to. This year I will be applying to one organisation and only one project- Write Examples For Official Libraries. I want to keep my area of work as niche as possible and contribute as much as I can no matter how small or big. Also, even if I do not get selected for GSoC2020 (which I really want be selected for) I'll continue with Arduino as my organisation and start for Google Summer of Docs 2020 abiding by my want to be innately connected to an open source community.

Do you have any other commitments during the GSoC period?

• I will be having my university practical examinations for four days and university final year written examinations (four exams). Because of the ongoing COVID-19 scenarios the dates are not consolidated or announced
• I will be starting my Masters in Management Information System Fall 2020. Again, dates not fixed / announced.

[MisterAwesome23]

I see updating drafts here repeated reduces readability.
Instead I will add a comment every time with an updated markdown proposal link (like I am doing right now)-

https://github.com/MisterAwesome23/ArduinoGSOC2020/blob/master/GSoC_Proposal.md

Kindly review. Suggestions are most welcome :)

---

Also, for the following pull requests

arduino-libraries/Keyboard#30
arduino-libraries/Keyboard#32
arduino-libraries/Mouse#12
arduino-libraries/Mouse#13
arduino-libraries/Mouse#15

Since all of this are included in the bundle and already present, I'd suggest closing these pull requests unless they add something new (as simply review simple migrations is an add-on task ).

Instead open an issue to migrate the codes from bundle repository to here at official libraries repositories. @per1234 does this seem okay?

[per1234]

@per1234 does this seem okay?

No. The mechanism we use for making changes in repositories is pull requests. The only way these changes can be made is via pull requests. If we close those PRs, someone else is just going to have to open a new pull request to do the same thing.

[MisterAwesome23]

someone else is just going to have to open a new pull request to do the same thing.

Got it. Thanks :)

[MisterAwesome23]

I have submitted the final proposal for the project: Write Examples For Official Libraries @ Arduino.
Looking forward to it and being the part of the community :)

[AsherThomasBabu]

@MisterAwesome23 were you able to get the conversion to pdf with pandoc?

[pra-dan]

@AsherThomasBabu refer to this option. Its better:

pip install grip
grip your_markdown.md --export your_markdown.html