BeagleBoard/GSoC/fix-bugs-bonescript

=Fix Bugs in BoneScript, Improve BBUI =


 * Run through the issues list at http://github.com/jadonk/bonescript/issues and fix the issues without breaking the API.(primary)
 * Create a similar BeagleBone User Interface for PocketBeagle which can also support the BaconBits Cape.(Secondary)
 * Add all available BoneScript function blocks to Blockly-BoneScript and Improve the User Interface.(Stretch Goal)

Student: Vaishnav M A Mentors: Jason Kridner,Anuj Deshpande Code: https://github.com/beagleboard/bonescript https://github.com/jadonk/blockly-bonescript Wiki: http://elinux.org/BeagleBoard/GSoC/fix-bugs-bonescript GSoC: Not Yet Submitted

=Status= This project aims to fix errors in currently existing projects : BoneScript,Improve features of Beaglebone-UI and if time permits improve Blockly-BoneScript.

My first pull request to https://github.com/jadonk/bonescript, this one was a simple mistake that caught in my eye while going through the source code.I have also added analogWrite on DOUT.

=Proposal= The Hello World Application was Cross-Compiled(and tested using QEMU Emulator) and Pull Request #112 was generated.

About me
IRC: vaishnav98_ || vaishnav98 Github: vaishnav98 School: College of Engineering,Trivandrum under Kerala Technological University Country: India Primary language : English Typical work hours : 11 AM-6:30 PM GMT (3:30 PM to 10:30 PM Indian Standard Time) Can also switch to 3 AM-10:30 AM GMT (7:30 AM to 3:00 PM Indian Standard Time) Software Skills : JavaScript,Linux,Python,UI Design,PCB Design,HTML/CSS,basic knowledge in C++ and C Hardware Skills : Circuit Prototyping and Soldering,HomeBrewing PCBs. Previous GSoC participation: No Previous Application Submitted, I am very much interested to work on this project so that i can contribute to the BeagleBoard Community while improving my skills and experiences.

About my project
' Project name '': Fix Bugs in BoneScript, Improve BBUI '''

Description
BoneScript is an existing Node.js library specifically optimized for the Beagle family and featuring familiar Arduino function calls, exported to the browser.The BoneScript library provides several functions for easy interaction with hardware which otherwise would have required the users to manipulate the SysFs files directly(assuming use of no other libraries),which is obviously confusing for a beginner-level user.BoneScript definitely lowers the bar of entry to the world of Embedded Systems Programming using the Beagle family boards thus encouraging more people to get familiar with the boards and create innovative projects.

Overview
BoneScript library even though being widely used by BeagleBone users has compatibility issues across boards,some bugs and unfinished features.The primary aim of my project is to solve most of the open issues reported and add some more features which will be of benefit to the users. My approach to solving the issues is to not make any API-breaking changes so that none of the other BoneScript dependent projects are disturbed. A secondary objective of my project is to add Improvements to the BeagleBone User Interface to provide a similar interface for PocketBeagle that can also support the BaconBits cape examples, so as to provide PocketBeagle beginners a Graphical User Interface from which they can try out the example codes easily(similar to BBUI).I would also like to work on Blockly-Bonescript project to add more features and code deployment.As a stretch objective to the project i plan to work on the blockly-BoneScript to provide a blocks editor for BoneScript not only converts the blocks code to BoneScript but will also deploy the code using Sockets.io.

Current Issues and Solution Implementation
The open issues reported at the BoneScript Github Repository can be broadly classified as :

Feature Requests
These are requests to add some additional features to BoneScript which improves the usability of the library. These issues come under this category :

Issue #27 Add C Support
This issue is related to providing support for adding C functions that are compiled on the target without creating separate node modules for each function. Adding support to call external C functions from existing bonescript code opens a wide range of possibilities to the user, and as quoted by the author it also makes possible to use Arduino-for-userspace-linux project to maximum advantage.

Solution: My proposed solution to add support for C routines is to use the Node.js add-on Foreign-Function-Interface, this library makes it possible to load and call dynamic C libraries using pure JavaScript.This library requires the dynamic C library to be compiled as a shared object and the 'path of shared object,function-name and the types of input arguments,return type' to be input as the argument to the ffi.Library function.

Implementation: To implement this solution i plan to write a function, CallExternalCfunction('path',[ 'returnType' ,[ 'inArgType']],callback); which checks whether the file in the path is a shared object and if not run the command (at the path): gcc -shared -fpic example.c -o example.so  //to compile as shared object using ShellJS and then call the ffi.Library function with the corresponding arguments

Issue #66 Interchanging Analog and Digital functions
This issue relates to adding features that make the user possible to use : 1) digitalRead on Analog IN 2)analogRead on Digital IN 3)analogWrite on Digital OUT 4)digitalWrite on Analog OUT

The first two features has been already implemented by the author,but can be improved by taking the Threshold value as an argument and i have implemented the third feature in the pull request i submitted.The last feature can be possibly implemented by writing a 0 duty cycle pwm or 100% duty cycle pwm on the Analog OUT pins depending on the value and Threshold, this can be only done reliably after verifying other issues such as the generation of spikes(Issue # 88) when writing 0 duty cycle and solving those issues first.

Issue #150( also Issue #148) BoneScript Development on non-BeagleBone Platforms
These Issues relates to developing BoneScript code from non-BeagleBone platforms and deploying to BeagleBone easily(and remotely).The secondary goal of this project deals mainly with thius issue, as the author commented BeagleBone User Interface is a working project which partly solves the issue but requires more improvements, so i would like to work on the BBUI to add more features, add PocketBeagle support and BaconBits cape support.

Implementation:- Currently the BeagleBone UI works only for BeagleBone Black(atleast the UI) to provide a demonstration for basic functions.I plan to work on this to change the canvas image to PocketBeagle and make corresponding changes to the functions and add one more page to the user interface to add BaconBits cape support for PocketBeagle,which aims to provide a UI for BaconBits from which the user can interact to the PocketBeagle with BaconBits Cape without any coding experience.

Issue #98 Add Support to HCSR04 Sensor
This issue relates to providing support for using the HCSR04 UltraSound sensor within BoneScript,this would be very difficult to implement with BoneScript alone, so my plan is to use already existing PRU firmware for HCSR04 sensor, run commands using ShellJS to build,install and run the driver and use node-ffi to provide interaction between the C function and BoneScript Code to return the measurement value.

Issue #120 Install BoneScript on Snappy Ubuntu Core
This issue relates to providing steps to install BoneScript on Snappy Ubuntu Core, as described in the closed Issue #53, it is possible to install the latest version of BoneScript sucessfully in ubuntu ,so i plan to implement solution to this issue by trying to install BoneScript on snappy ubuntu core, if problems occur try to solve them and then provide step by step instructions for installation.

Issue #94 Smooth PWM Output
This issue relates to the writing of Zero duty cycle pwm while writing the Period value, but as described in issue #88, this generates spikes in the output , the person who reported the problem has come up with a solution to this issue by writing a function enablePWM, which enable/disables pwm output on the pin , so i plan to solve the issue by implementing his solution and testing the output to see improvements and if problems occur, solve them.

Suggestions/Improvements
These are issues that suggest changes to the structure of BoneScript codebase to add functionalities to standardise the codebase.

Issue #151 TypeScript Definition File
This issue relates to adding TypeScript definitions to BoneScript, which is very useful when making improvements and addition to the large codebase, even though TypeScript is less flexible than JavaScript , it is more reliable and more tools are available for developing in TypeScript ,so it will be a benefit to add TypeScript definition to BoneScript.

Implementation: The person who reported the issue has come up with a draft TypeScript definition for Bonescript, i would like to use his work as my starting material and verify all the definitions add more and separate the interfaces and constants to separate modules.

Issue #82 module.exports instead of exports
This issue relates to use module.exports in BoneScript instead of exports, the issue was raised because Node.js doesn't export the object that 'exports' currently references, but exports the properties of what 'exports' originally reference , but Node.js does export the object 'module.exports' references, allowing  to call it like a function. I plan to implement module.exports replacing exports wherever possible and examining possible issues.

Issue #75 and #125 Sync and Async Functions
These issues relate to the overloading of Sync and Async functions depending on whether callback provided, this goes against the convention of sync labelled functions in Node.js. An acceptable solution to this problem without making breaking changes is to create sync and async copies of every dual purpose function, even though this i s difficult to maintain it solves the issue and in future most of the synchronous logic can be removed when users get used to it.

Implementation: I plan to split out the overloading of Sync and Async functions and create separate clean Asynchronous Implementation and a fully synchronous implementation in the same project which share all the global variables, so that ordinary usage will not be disturbed and calling from within a fiber will result in the usage of aynschronous counterparts.

Issue #152 and #124 Node-style Callbacks
Currently BoneScript mostly uses value only callbacks which goes against the Node.js convention of error first and value next callback, but implementing this directly is a breaking change , so there are two options , one is the user must adjust with the present style call backs or the separate implementation can be made for providing node-style callbacks depending on the value of nodeStyleCallback : boolean , but this would require a lot of changes with the assosciated functions, so i do not plan to make this change unless it has some other benefits other than following the standard.

Issue # 110 Pin Mux Error on P8_40
This issue reports an error in the bone.js pin definitons, my suggestion to solve these kind of issues quickly is to add pinmaps to a separate pinmap.json file with each definition under the parent 'pinkey' (eg: p8_24) and modifying the getpin function accordingly this makes the getpin function more efficient upto an extent by looking at the parent for 'pinkey' rather than searching for the child 'pinkey'.This change will also make it a lot easier to add and modify pin-config for new boards very easily.

Issue #158 and #161 PWM udev delays
These issues relate to the arbitrary delay and failing when using pwm which caused by the delay for udev to set permissions.udev device manager will set the permissions on the files used to control pwm to allow these files to be accessed without root privileges. It takes udev a while to set the permissions and we need to wait for it to complete its work to avoid EACCES errors, this delay seems to be mostly unavoidable and a workaround for this problem is to loop around and access the files until no EACCES error is thrown but in the JS library it won't be much practical as there would be a unpredictable delay.My plan is to run the file access commands using shellJS library if an EACCES error was thrown previously, so that it will be a more reliable alternative.

Issue #161 Handle case when debugfs not already mounted
This issue relates to the case when getPinMode fails to fetch the mux mode if /sys/kernel/debug/pinctrl/44e10800.pinmux/pins isn't already mounted.A possible solution to this issue is to add a few lines to the getpinMode function to check whether the corresponding file is mounted using ShellJS and if not mount the file using the corresponding mount command : mount -t debugfs none /sys/kernel/debug/.

Issue #88 Disable PWM Output
This issue deals with the case when there are spikes produce when writing a zero duty cycle pwm to a pin, the exact cause of this function is not known but the reporter of the issue has stated that manually writing a zero to the pin works well so my plan to solve this issue is to write a function stopAnalogWrite to write the command to stop the pwm output on particular pin using shellJS : eg(pinP9_22) : echo 0 > /sys/devices/ocp.3/bs_pwm_test_P9_22.16/run

General Issues
Some Issues that seems to be user specific has not been detailed in the above description and some of the issues seems not to be reproducible, i am planning to devote an entire week to try reproducing issues described in #78 , #77,#76 ,#89 ,#111,#122,#93,#85(Seems to be solved with a update) and find their solutions if possible.

There are also some general issues which are related to the lack of support for bug-fixing and solving compatibility issues related to the library, these threads in a way convey the impact and importance of this project.These issues can be closed after the successful completion of this project.

Secondary Goals
The most important Seondary Goal of my project is to provide a BBUI like interface for PocketBeagle and BaconBits Cape so as to provide a good getting-started material for PocketBeagle users with limited programming knowledge.I plan to start this project from the existing BBUI Project, edit the canvas and create separate projects for PocketBeagle and PocketBeagle with BaconBits which allows the users to run examples on their board through the network

Stretch Goals
Blockly-BoneScript a visual blocks editor for BoneScript, i would like to work on improving the existing project Blockly-BoneScript to create a visual blocks editor for BoneScript , presently the Blockly-BoneScript is just a blocks to BoneScripts converter , but my aim is to modify this to add more function blocks and to add sockets.io support so that the user can directly run code form the blocks on the board without performing additional tasks.

Timeline
I am planning to work on the Feature Additions first and then move to Improvements and finally fix the bugs so that i can clear all the bugs caused by the new features and improvements.

Prior to Coding Period
I will use this time to go through the entire codebase of BoneScript( and OctalBoneScript) thoroughly and understand the impact of the improvements made, and find more bugs and perfomance issues in the library.I would also try to make a prototype of BaconBits cape during this period with available materials, so that i can test the examples i write for PocketBeagle UI.

Community Bonding Period: April 23 - May 13

 * Discuss with the Mentor about any specific coding styles to be followed
 * Make changes to some of the goals according to mentors opinion
 * Discuss about the scope on new feature implementation and their impacts
 * Fix timings for periodic meeting with mentors
 * Discuss about Documentation Guidelines to be Followed
 * Review the entire documentation and get prepared for working

Week 1: May 14 - May 20

 * Add External C Function Support
 * Demonstrate simple example with external C Function
 * Modify Some Examples in UserSpace Arduino Linux to be compatible(make functions exportable) and test new feature.
 * Write StopAnalogWrite function to write perfect 0 V on pwm
 * Implement digitalWrite on Analog OUT.

Week 2: May 21 - May 27

 * Smooth PWM Output Implement Solution and Testing
 * Add Support for HCSR04 Sensor (and if time permits DHT21,DHT22,AM2303 throught similar steps)
 * Try installing BoneScript on Snappy Ubuntu Core and solve issues, prepare documentation for installation steps

Week 3: May 28 - June 3

 * BoneScript Development on non-BB platforms
 * Make Edits to BBUI, add Pocket Beagle Interface
 * Test simple examples (usr led blink,AnalogRead .. etc) on PocketBeagle from UI
 * Add BaconBits Cape Support to PocketBeagleUI
 * Test All the features and prepare documentation for PocketBeagleUI

Week 4: June 4 - June 10

 * Preparing TypeScript definition file
 * Separate the Interfaces from the TypeScript definition file
 * test BoneScript functions using TypeScript
 * implement module.exports in case of exports
 * determine the possible issues caused by the changes made by me

At the end of Phase I, i will be able to deliver : BoneScript with C Support,Interchange Digital and Analog functions,Pocketbeagle UI and TypeScript Definition.

Week 5: June 11 - June 17

 * Solve the possible errors that might have occured in Phase I work
 * Make manageable sync and async copies of all dual purpose functions
 * determine the issues caused by dual implementation and solve them

Week 6: June 18 - June 24

 * Review the entire work, fix bugs and prepare documentation
 * Start with Bug Fixing : pinmaps to separate pinmap.json and modify getpin and related functions
 * try fixing the PWM udev delays issue using proposed method
 * fix handle case when debugfs not mounted
 * Review the stopAnalogWrite function

Week 7: June 25 - July 1

 * try to reproduce half the ambiguous issues from the repository
 * if able to reproduce some of the try finding solutions
 * if not able to reproduce, try to reproduce the rest of the issues and solve them.

Week 8: July 2 - July 8
By the end of Phase II, I will be able to Deliver BoneScript with all of the reproducible bug-fixes
 * complete previous weeks work if any
 * contact the issue reporters if the error is not reproducible(if possible)
 * make documentation for all the work completed

Week 9: July 9 - July 15

 * Recevie feedback from mentors
 * Optimize the existing code for perfomance
 * Proper Commenting in code
 * Try all existing examples and note the issues

Week 10: July 16 - July 22

 * Solve the issues in examples
 * test for compatibility issues across packages
 * Optimize the code for readablitity

Week 11 and 12: July 22 - Aug 5
After discussing with the mentor, if the work upto week 10 is satisfactory , i would like to work more on the Stretch Goal and Secondary Goal of the Project else if the work was not satisfactory, these two weeks are reserved as buffer time for finishing required work.
 * Improve the PocketBeagle UI and fix issues
 * Add function blocks to Blockly-Bonescript for all possible BoneScript Functions
 * Add sockets.io support to blockly-bonescript for deploying code

Experience and approach
I am a Second year undergraduate pursuing electronics and communication engineering, i spend most of my spare time for Web Designing,Web App Development and work related to embedded develoment.I have some experience working with BeagleBone Black and Raspberry Pi , also i have a lot of experience working with Microcontrollers(AVR C ) and has enough working experience with linux. As my recent project ESTA.me, a forum and announcements Progressive Web App developed for my university ,largely relies on Node.Js ,JavaScript,TypeScript, and HTML/CSS, I can definitely complete the above milestones to fix the errors in BoneScript and produce a better BeagleBone UI.

My Works(all uploaded on my Github Repository):

ietcet.org - website designed by me for the Student Chapter of IET in my university.

ESTA.me - Forum/NoticeBoard Web/Mobile app designed by me (PlayStore).

h2o.ietcet.org- a volunteer management portal for charity society made using WordPress.

Contingency
As my project largely relies on JavaScript, i would atleast know what to search for in Google to solve a particular issue that cannot be solved with my knowledge ,so even if my mentors are not available for a short period of time, it won't much affect the quality of my work, If i am not able to find the solution to a problem by searching ,going through forums,IRCand mailing lists, i will try to proceed my work by focussing on designing the BeagleBone UI as this will be a easy task for me and also work on documenting the finished work.

Approach
I don't have any other commitments during my vacation, so i can devote about 7-9 hours a day , ie around 50 hours a week to achieve my milestones.I am willing to spend more time if i am not able achieve any of the targets set by me.

Benefit
BoneScript definitely is a wonderful piece of work that lowers the bar of entry to BeagleBone Embedded development due to its arduino like functions which most of the users would be familiar with.The project presently has many unsolved bugs and issues which needs to be solved.This project aims to solve most of the issues add improvements to the project and create a better user experience.Some of comments mentioning the importance of this project are given below :

User smullereus on github.com : I just bought a BeagleBone black and am trying to get up to speed with bonescript. It looks excellent to me and helps me getting started as I already know JavaScript and Node.js. However, I noticed that there are still some bugs and unfinished features. It would be really sad to see this project die. It would be a big loss for BeagleBone, which is suited a lot better than Raspberry Pi for many projects.

User Mark A Yodner on Beagleboard Google Group:

Sounds like an interesting project. I had a student to a similar project[1] based on Google's Blockly[2]. I made a few refinements to it[3], but haven't worked on it lately. Doing block programming in Could 9 sounds like a neat idea. --Mark

Mentor Jason Kridner on BeagleBoard GSOC Google Group:

Mostly seems reasonable, though I'd say the cape need to change.