search

arduino / summer-of-code

Arduino @ Google Summer of Code
40 stars 51 forks source link

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

Closed MisterAwesome23 closed 4 years ago

MisterAwesome23 commented 4 years ago

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

Serial.println(Hello);

Checklist: (February 20th - March 31st)

MisterAwesome23 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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: https://github.com/arduino/summer-of-code/issues/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.

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. https://github.com/arduino-libraries/ArduinoSound/pull/24
  2. https://github.com/arduino-libraries/USBHost/issues/14
  3. https://github.com/arduino-libraries/AudioFrequencyMeter/issues/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)

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)

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

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?

MisterAwesome23 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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: https://github.com/arduino/summer-of-code/issues/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.

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. Layout.png 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. Schematic.png 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: https://github.com/arduino/Arduino/pull/9920

Contributions

  1. https://github.com/arduino-libraries/ArduinoSound/pull/24
  2. https://github.com/arduino-libraries/USBHost/issues/14
  3. https://github.com/arduino-libraries/AudioFrequencyMeter/issues/15

Schedule of Deliverables

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

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)

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

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?

MisterAwesome23 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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

Got it. Thanks :)

MisterAwesome23 commented 4 years ago

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 commented 4 years ago

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

pra-dan commented 4 years ago

@AsherThomasBabu refer to this option. Its better: 

pip install grip
grip your_markdown.md --export your_markdown.html
AsherThomasBabu commented 4 years ago

Thank you so much @PrashantDandriyal! It works like a charm!

MisterAwesome23 commented 4 years ago

Thanks @PrashantDandriyal I did the same, except taking the -o as a docx file and then using doc export as pdf feature.

MisterAwesome23 commented 4 years ago

Application Review Period (March 31, 2020 - April 30, 2020) Checklists and Updates

From proposal

Created on 2nd April, 2020:

Updates (Last updated on 22th April, 2020)-

Number of libraries explored: 90 out of 90. Link to sheet Any suggestions/comments to improve this sheet and my exploring/research methodologies is most welcome.

Currently working on: Arduino_LSMDS63 pull 11 Arduino_CRC32 pull 9 (merged) Arduino_MKRGPS pull 7 ArduinoMDNS issues 6 Ciao issue 2 UnoWiFi-Developer-Edition-Lib fix issue 13

List of 10 appropriates for the project (approximate number before finalizing the actual ones)-

  1. Arduino_LSM6DS3
  2. Arduino_CRC32
  3. ArduinoGraphics
  4. NTPClient
  5. Arduino_APDS9960
  6. ArduinoSound
  7. ArduinoDMX
  8. ArduinoMDNS
  9. MadgwickAHRS
  10. Scheduler
Add-ons

Of the libraries selected for this project- (Can be added to Community Bonding Period) I would also like to cover the closed issues and pull requests to get more depth about the library which will help in formulating the example.

MisterAwesome23 commented 4 years ago

Thank you @per1234 and @alranel for for this issue tracker. Though I am not get selected for this project, looking forward to contribute to the Arduino Community and being a part of future opportunities :) [Closing this issue tracker]

per1234 commented 4 years ago

@MisterAwesome23 I've enjoyed our interactions and welcome your continued involvement with Arduino.

Regards, Per