Difference between revisions of "BeagleBoard/GSoC/2020 Projects/Cape Compatibility"

From eLinux.org
Jump to: navigation, search
(Hardware required:)
(About you)
 
(22 intermediate revisions by 2 users not shown)
Line 4: Line 4:
 
[[Category: GSoCProposal2020]]
 
[[Category: GSoCProposal2020]]
  
= [https://elinux.org/BeagleBoard/GSoC/2020Proposal/DeepakKhatri Proposal for Cape compatibility layer for BeagleBone Black and BeagleBone AI]=
+
= [https://elinux.org/BeagleBoard/GSoC/2020_Projects/Cape_Compatibility Cape compatibility layer for BeagleBone Black and BeagleBone AI]=
 
<!--   
 
<!--   
 
{{#ev:youtube|Jl3sUq2WwcY||right|BeagleLogic}}latest video will go here  
 
{{#ev:youtube|Jl3sUq2WwcY||right|BeagleLogic}}latest video will go here  
 
A short summary of the idea will go here.
 
A short summary of the idea will go here.
 
-->
 
-->
''Student'': [http://elinux.org/User:Lorforlinux Deepak Khatri]<br>
+
''Student'': [[User:Lorforlinux|Deepak Khatri]] (lorforlinux)<br>
 
''Mentors'': [http://elinux.org/User:Jkridner Jason Kridner]<br>
 
''Mentors'': [http://elinux.org/User:Jkridner Jason Kridner]<br>
''Code'': https://github.com/deepaklorkhatri007/linux/tree/4.14<br>
+
''Code'': https://github.com/deepaklorkhatri007/linux/tree/4.14, TODO: Update to various trees and closer to mainline<br>
 
''Wiki'': https://elinux.org/BeagleBoard/GSoC/2020Proposal/DeepakKhatri<br>
 
''Wiki'': https://elinux.org/BeagleBoard/GSoC/2020Proposal/DeepakKhatri<br>
''GSoC'': [N/A]<br>
+
''GSoC'': https://summerofcode.withgoogle.com/projects/#5125259251941376<br>
 
<div style="clear:both;"></div>
 
<div style="clear:both;"></div>
  
Line 24: Line 24:
 
==About you==
 
==About you==
 
''IRC'': lorforlinux<br>
 
''IRC'': lorforlinux<br>
''Github'': [https://github.com/deepaklorkhatri007 Deepak Khatri]<br>
+
''Github'': [https://github.com/lorforlinux Deepak Khatri]<br>
''School'': [http://www.nsit.ac.in/ Netaji Subhas Univerity of Technology (NSUT) formely NSIT ]<br>
+
''School'': [http://www.nsut.ac.in/ Netaji Subhas Univerity of Technology (NSUT) formerly NSIT ]<br>
 
''Country'': India <br>
 
''Country'': India <br>
 
''Primary language(s)'': Hindi,English<br>
 
''Primary language(s)'': Hindi,English<br>
 
''Typical work hours'': 9AM - 7PM IST<br>
 
''Typical work hours'': 9AM - 7PM IST<br>
''Previous GSoC participation'': I participated in GSoC2019 but i was not selected for the project. The project was to make a jekyll website for AIMA organization, Discussion on the project can be found [https://github.com/aimacode/aima-exercises/issues/36 here] and the prototype i made can be found [https://deepaklorkhatri007.github.io/aima-exercise-prototype/ here]. From the GSoC2019 I learnt the importance of communication.
+
''Previous GSoC participation'': I participated in GSoC2019 but I was not selected for the project. The project was to make a Jekyll website for the AIMA organization, Discussion on the project can be found [at https://github.com/aimacode/aima-exercises/issues/36 here] and the prototype I made can be found [https://lorforlinux.github.io/aima-exercise-prototype/ here]. From the GSoC2019 I learnt the importance of communication.
  
 
==About your project==
 
==About your project==
Line 38: Line 38:
 
In 10-20 sentences, what are you making, for whom, why and with what technologies (programming languages, etc.)? (We are looking for open-source SOFTWARE submissions.)
 
In 10-20 sentences, what are you making, for whom, why and with what technologies (programming languages, etc.)? (We are looking for open-source SOFTWARE submissions.)
 
-->
 
-->
==== Making P8 and P9 header compatible: ====
+
==== Enabling overlay compatibility: ====
The idea of this project is to make the same user-space examples work with both BeagleBone Black and AI, using the same references to drivers for peripherals assigned to the same pins between Black and AI. Main things to do for achieving that are assigning the same pin names and same aliases for both the boards. Changes will be done in the file am5729-beaglebone.dts of BeagleBoard-DeviceTrees repo.
+
The BeagleBone boards use U-Boot as their Tertiary Program Loader (TPL). U-boot is responsible for loading the Linux kernel, Flattened Device Tree (FDT), Initial Ram File System (initramfs) into DRAM. U-Boot controls the boot time MUX_MODE for the GPIOs, symlinks for the peripherals and other hardware-specific device configurations by loading specific FDT. We can control the configuration(s) by updating the FDT for the hardware we want to support. We can enable the device compatibility in this case Cape compatibility using the boot-time device tree overlays. Overlays for most of the capes are available from the [https://github.com/beagleboard/bb.org-overlays/ bb.org-overlays] repo. A major task for achieving cape compatibility will be creating device tree overlays and loading at boot time. For loading the required driver for the hardware at boot time we have to edit uEnv.txt file. We can export the required overlays at boot time and the hardware will be compatible as soon as the board boots up. Most capes use an EEPROM for storing hardware related information about the CAPE and all of the individual pin configuration details can be imported out of the EEPROM, which makes things way better to handle.
 +
 
 +
Device tree overlays are a very important part of the main idea of this project which is to make the same user-space examples work with both BeagleBone Black and AI. the same references will be used in the drivers for peripherals assigned to the same pins between Black and AI. Main things to do for achieving that are assigning the same pin names and same aliases for both the boards.
 +
 
 +
For making the cape compatible, the device tree overlays code will be added to [https://github.com/beagleboard/bb.org-overlays/ bb.org-overlays] repo and changes will be made in the file [https://github.com/beagleboard/BeagleBoard-DeviceTrees/blob/v4.19.x-ti/src/arm/am5729-beagleboneai.dts am5729-beaglebone.dts] and other related files to BeagleBoard-DeviceTrees repo for base pin naming and MUX_MODE selection upon which overlays will sit and will be able to use the properties assigned in [https://github.com/beagleboard/BeagleBoard-DeviceTrees/blob/v4.19.x-ti/src/arm/am5729-beagleboneai.dts am5729-beaglebone.dts] device-tree source.
  
 
# For making the boards pin to pin compatible as in pin names, a new node will be created called cape-universal {...} which will hold child nodes like P8_03{...} for pin name assignment. Included the code for through pull request [https://github.com/beagleboard/BeagleBoard-DeviceTrees/pulls?q=is%3Apr+is%3Aclosed #13].
 
# For making the boards pin to pin compatible as in pin names, a new node will be created called cape-universal {...} which will hold child nodes like P8_03{...} for pin name assignment. Included the code for through pull request [https://github.com/beagleboard/BeagleBoard-DeviceTrees/pulls?q=is%3Apr+is%3Aclosed #13].
# Setting up the same default pin configuration in pin muxing nodes of board device tree files is required which will be achieved using nodes that use DRA7XX_CORE_IOPAD() functions along with pinctrl-single driver. I have included the required code through pull requests [https://github.com/beagleboard/BeagleBoard-DeviceTrees/pulls?q=is%3Apr+is%3Aclosed #8 #9 #10].  
+
# Setting up the same default pin configuration in pin muxing nodes of board device tree files is required which will be achieved using nodes that use DRA7XX_CORE_IOPAD() functions along with the pinctrl-single driver. I have included the required code through pull requests [https://github.com/beagleboard/BeagleBoard-DeviceTrees/pulls?q=is%3Apr+is%3Aclosed #8 #9 #10].  
# We also require to assign the same aliases which is the easiest part after achieving the above goals. We need some assignments under aliases {...} nodes similar to what we have in the BeagleBone Black device tree file. We might also want to use symlinks for the peripherals as discussed with rcn over pull requests [https://github.com/beagleboard/BeagleBoard-DeviceTrees/pulls?q=is%3Apr+is%3Aclosed #11 #12].
+
# I will also assign symlinks for the peripherals as discussed with rcn over pull requests [https://github.com/beagleboard/BeagleBoard-DeviceTrees/pulls?q=is%3Apr+is%3Aclosed #11 #12].I have already assigned some of the symlinks for currently active peripheral devices of BBB through the pull request [https://github.com/beagleboard/BeagleBoard-DeviceTrees/pulls?q=is%3Apr+is%3Aclosed #14]. We might also require to assign the same aliases for peripherals in the device tree which is the easiest part after achieving the above goals. We need some assignments under aliases {...} nodes similar to what we have in the BeagleBone Black device tree file.
 +
 
 +
The file am335x-bone-common-univ.dtsi for BeagleBone Black and am335x-pocketbeagle.dts provides all the information for pin muxing and pin naming. The project will enable us to use serial ports and userspace I2C/spidev. In device trees, the aliases node can be seen as a quick lookup table, an index of another node. We can use find_node_by_aliases() function  to find a node by its alias. Interface buses like I2C, SPI, UART, CAN, etc will be aliases according to the [https://elinux.org/Beagleboard:BeagleBone_cape_interface_spec BeagleBone cape interface spec]. All the aliases defined in the device tree can be found in /sys/firmware/devicetree/base/aliases as files containing the full name/path for the peripheral device. For GPIOs, examples would work using pin names under libgpiod.
 +
 
 +
Pin MUX_MODE selection, pin naming and aliasing of P8 and P9 headers of BeagleBone AI will enable us to use different peripherals like GPIO, I2C, UART, SPI, qQEP, CAN, etc. [https://elinux.org/Beagleboard:BeagleBone_cape_interface_spec BeagleBone cape interface spec] shows further details on the active bus data of BeagleBone Black and BeagleBone AI. For the cape specific bus interface, the [https://docs.google.com/spreadsheets/d/1fE-AsDZvJ-bBwzNBj1_sPDrutvEvsmARqFwvbw_HkrE/edit#gid=1518010293 BeagleBone Cape Header Pins] file gives us all the required information like which pins are used and also details on MUX_MODE are also provided there.
 +
 
 +
==== Enabling userspace and end-user compatibility ====
 +
Looking at the symlink theory of operation with udev we see that for allowing userspace programs to use the devices with a custom name Symlinks allow us to define names/location of a peripheral. It’s very much like creating an alias for the peripheral but we can use this in userspace and it can be richer in information, for example, let’s look at this new symlink I created for the uart1 and submitted through pull request [https://github.com/beagleboard/BeagleBoard-DeviceTrees/pull/14 #14].
  
 +
<pre>
 +
&uart1 {
 +
          status = "okay";
 +
          pinctrl-names = "default";
 +
          pinctrl-0 = <>;
 +
          symlink = "bone-uart1";
 +
};
 +
</pre>
  
After testing we may require to create new device tree sources include (dtsi) files. The file [https://github.com/beagleboard/linux/blob/4.14/arch/arm/boot/dts/am335x-bone-common-univ.dtsiam 335x-bone-common-univ.dtsi] for BeagleBone Black and [https://github.com/beagleboard/BeagleBoard-DeviceTrees/blob/v4.19.x-ti/src/arm/am335x-pocketbeagle.dts am335x-pocketbeagle.dts] provides all the information for pinmuxing and pin naming. The project will enable us to use serial ports and user space I2C/spidev. In device trees, the aliases node can be seen as a quick lookup table, an index of another node. We can use find_node_by_aliases() function  to find a node by its alias. Aliases provided by the device trees would match for both the boards. Interface buses like I2C, SPI, UART, CAN will be aliases according to the [https://elinux.org/Beagleboard:BeagleBone_cape_interface_spec BeagleBone cape interface spec]. All the aliases defined in the device tree can be found in /sys/firmware/devicetree/base/aliases as files containing the full name/path for the peripheral device. For GPIOs, examples would work using pin names under libgpiod.
+
In this node, we assign the value of “bone-uart1” to the symlink property which we can call from userspace. Device tree creates an index of all the symlinks we define, In the device tree directory like for the SPI device for which we already have symlinks assigned in the current device tree.
  
==== Cape compatibility: ====
+
When we look inside the /sys/firmware/devicetree/ of our BeagleBone we see all the folders created by the device tree. For SPI of BBB we see these folders.
 +
* ./sys/firmware/devicetree/base/ocp/spi@481a0000/channel@0/symlink
 +
* ./sys/firmware/devicetree/base/ocp/spi@481a0000/channel@1/symlink
 +
* ./sys/firmware/devicetree/base/ocp/spi@48030000/channel@0/symlink
 +
* ./sys/firmware/devicetree/base/ocp/spi@48030000/channel@1/symlink
  
Pin muxing, pin naming and aliasing of P8 and P9 headers of BeagleBone AI will enable us to use different peripherals like I2C, SPI, UART, CAN, ADC, PWM/TIMER etc on the exact pin required by the cape. [https://elinux.org/Beagleboard:BeagleBone_cape_interface_spec BeagleBone cape interface spec] shows all the details on that. We have many peripherals available to use on AM5729 SoC but with different MUX_MODExx than AM3358. First let's see an example for '''/dev/bone/i2c/1''' specs for which are :
+
These indexed folders can be searched and viewed through user space programs for example when we look in the [https://github.com/rcn-ee/repos/blob/master/bb-customizations/suite/stretch/debian/10-of-symlink.rules 10-of-symlink.rules] we see it uses these indexed folders for creating new devices under /dev. Looking at the code, first, we see ATTR{device/of_node/symlink} !=””  which checks if there are symlinks available. Then we create a variable for that symlink using ENV{OF_SYMLINK} and if it’s not empty and we have a device name we add it to the SYMLINK environment variable and we also add the systemd to TAG. In the end, we add an alias for the device using ENV{SYSTEMD_ALIAS}+="/dev/%E{OF_SYMLINK}".This way we can use the peripheral using the name assigned in the device tree through symlinks.
 +
 
 +
<pre>
 +
 +
ATTR{device/of_node/symlink}!="", \
 +
          ENV{OF_SYMLINK}="%s{device/of_node/symlink}"
 +
 +
ENV{OF_SYMLINK}!="", ENV{DEVNAME}!="", \
 +
          SYMLINK+="%E{OF_SYMLINK}", \
 +
          TAG+="systemd", ENV{SYSTEMD_ALIAS}+="/dev/%E{OF_SYMLINK}"
 +
</pre>
 +
 
 +
 
 +
We have many peripherals available to use on AM5729 SoC but with different MUX_MODExx than AM3358. First let's see an example for '''/dev/bone/i2c/1''' specs for which are :
  
 
<pre>
 
<pre>
Line 79: Line 115:
  
 
</pre>
 
</pre>
 
For making the capes entirely compatible. I will have to include the code for pin-muxing names, pin naming and aliases. I am working on some of that at the moment. Also, the code requires testing on the real hardware and that part will be done only during the GSoC coding period.
 
  
 
==== Software required and Programming Languages: ====
 
==== Software required and Programming Languages: ====
Line 87: Line 121:
  
 
==== Hardware required: ====
 
==== Hardware required: ====
# [https://www.element14.com/community/docs/DOC-84108 BeagleBone Black].
+
# [https://www.element14.com/community/docs/DOC-84108 BeagleBone Black]. (ordered Black Wireless)
# [https://www.digikey.com/product-detail/en/seeed-technology-co-ltd/102110362/1597-102110362-ND/10492208 BeagleBone AI].
+
# [https://www.digikey.com/product-detail/en/seeed-technology-co-ltd/102110362/1597-102110362-ND/10492208 BeagleBone AI]. (ordered)
 
# BeagleBone capes:
 
# BeagleBone capes:
## [https://beagleboard.org/static/images/capes/600px/BeagleBoneLoadCapeA2_Top.png Load Cape].
+
## [https://beagleboard.org/static/images/capes/600px/BeagleBoneLoadCapeA2_Top.png Load Cape]. (ordered)
## [https://beagleboard.org/static/images/capes/600px/BeagleBoneMotorCapeA2_Top.png Motor Cape].
+
## [https://beagleboard.org/static/images/capes/600px/BeagleBoneMotorCapeA2_Top.png Motor Cape]. (ordered)
## [https://beagleboard.org/static/images/capes/600px/BeagleBoneRelayCapeA2_Top.png Relay Cape].
+
## [https://beagleboard.org/static/images/capes/600px/BeagleBoneRelayCapeA2_Top.png Relay Cape]. (ordered)
 
## [https://beagleboard.org/static/images/capes/600px/roboticscape-top-angle3.jpg Robotics Cape].
 
## [https://beagleboard.org/static/images/capes/600px/roboticscape-top-angle3.jpg Robotics Cape].
## [https://beagleboard.org/static/images/capes/600px/BeagleBoneServoCapeA2_Top.png Servo Cape].
+
## [https://beagleboard.org/static/images/capes/600px/BeagleBoneServoCapeA2_Top.png Servo Cape]. (ordered)
## [https://4dsystems.com.au/4dcape-43 4.3"Display Cape].
+
## [https://beagleboard.org/static/images/capes/250px/BeagleBoneCommsCapeA2_Top.png Comms cape]. (ordered)
 +
## [https://4dsystems.com.au/4dcape-43 4.3"Display Cape]. (ordered)
 
## [https://4dsystems.com.au/gen4-4dcape-70ct-clb 7.0" Primary gen4 Display CAPE].
 
## [https://4dsystems.com.au/gen4-4dcape-70ct-clb 7.0" Primary gen4 Display CAPE].
 
# Additional hardware for using capes:
 
# Additional hardware for using capes:
 
## JST SH Jumper [https://www.sparkfun.com/products/10359 4 Wire] and [https://www.sparkfun.com/products/10361 6 Wire].  
 
## JST SH Jumper [https://www.sparkfun.com/products/10359 4 Wire] and [https://www.sparkfun.com/products/10361 6 Wire].  
## Grove Universal 4 Pin to Beaglebone® 6 Pin Female.
+
## [https://www.seeedstudio.com/Grove-Universal-4-Pin-to-Beagleboner-Blue-6-Pin-Female-JST-SH-Conversion-Cable-10-pcs-pack.html Grove Universal 4 Pin to Beaglebone® 6 Pin Female]. (ordered)
## Grove Universal 4 Pin to Beaglebone® Blue 4 Pin Female.
+
## [https://www.seeedstudio.com/Grove-Universal-4-Pin-to-Beagleboner-Blue-4-Pin-Female-JST-SH-Conversion-Cable-10-pcs-pack.html Grove Universal 4 Pin to Beaglebone® Blue 4 Pin Female]. (ordered)
## Servo motor.
+
## [https://www.digikey.com/product-detail/en/900-00005/900-00005-ND/361277?WT.mc_id=IQ_7595_G_pla361277&wt.srch=1&wt.medium=cpc&WT.srch=1&gclid=CJz-qdC9n9ICFRO4wAodOjYLuQ Servo motor]. (ordered)
## DC Motor.
+
## [https://www.sparkfun.com/products/13302 DC Motor].
## Groove Modules.
+
## Groove Modules:
### Grove - Servo
+
### [https://www.seeedstudio.com/Grove-Servo.html Grove - Servo].
### Grove - Vibration Motor
+
### [https://www.seeedstudio.com/Grove-Vibration-Motor.html Grove - Vibration Motor].
### Grove - Line Finder v1.1
+
### [https://www.seeedstudio.com/Grove-Line-Finder-v1-1.html Grove - Line Finder v1.1].
### Grove - I2C Color Sensor V2
+
### [https://www.seeedstudio.com/Grove-I2C-Color-Sensor-V2.html Grove - I2C Color Sensor V2].
### Grove - Rotary Angle Sensor
+
### [https://www.seeedstudio.com/Grove-Rotary-Angle-Sensor.html Grove - Rotary Angle Sensor].
### Grove - Adjustable PIR Motion Sensor
+
### [https://www.seeedstudio.com/Grove-Adjustable-PIR-Motion-Sensor.html Grove - Adjustable PIR Motion Sensor].
### Grove - 6-Position DIP Switch
+
### [https://www.seeedstudio.com/Grove-6-Position-DIP-Switch.html Grove - 6-Position DIP Switch].
### Grove - 16x2 LCD (White on Blue)
+
### [https://www.seeedstudio.com/Grove-16x2-LCD-White-on-Blue.html Grove - 16x2 LCD (White on Blue)].
### Grove - Speaker
+
### [https://www.seeedstudio.com/Grove-Speaker-p-1445.html Grove - Speaker].
### Grove - Buzzer
+
### [https://www.seeedstudio.com/Grove-Buzzer.html Grove - Buzzer].
### Grove - GPS Module
+
### [https://www.seeedstudio.com/Grove-GPS-Module.html Grove - GPS Module]. (ordered)
### Grove - Digital Light Sensor - TSL2561
+
### [https://www.seeedstudio.com/Grove-Digital-Light-Sensor-TSL2561.html Grove - Digital Light Sensor - TSL2561].
### Grove - Temperature Humidity Sensor (High-Accuracy & Mini)
+
### [https://www.seeedstudio.com/Grove-Temperature-Humidity-Sensor-High-Accuracy-Mini-p-1921.html Grove - Temperature Humidity Sensor (High-Accuracy & Mini)].
## FTDI Serial TTL-232 USB Cable
+
# [https://www.adafruit.com/product/70 FTDI Serial TTL-232 USB Cable]. (ordered)
 +
# [https://www.adafruit.com/product/1203 Barcode reader]. (ordered)
 
# Must have lab tools like:
 
# Must have lab tools like:
## Solder, flux and soldering iron.
+
## Solder, flux, and soldering iron.
 
## Screwdriver set.
 
## Screwdriver set.
 
## Tweezers and pliers.
 
## Tweezers and pliers.
Line 130: Line 166:
 
{| class="wikitable"
 
{| class="wikitable"
  
| Apr 27 || Pre-work || Community Bonding Period and discussion on the project and resources available.  
+
| May 4 || Pre-work || Community Bonding Period and discussion on the project and resources available.  
 
|-
 
|-
| May 18 || Pre-work complete || Coding officially begins!
+
| June 1 || Pre-work complete || Coding officially begins!
 
* All the boards and additional hardware will be available to me at this period of time and I should have set up my BeagleBone Black and Ai boards i.e flashing up to date Linux image and Testing user-led blink code :)  
 
* All the boards and additional hardware will be available to me at this period of time and I should have set up my BeagleBone Black and Ai boards i.e flashing up to date Linux image and Testing user-led blink code :)  
 
* Initial checks for hardware like motors and other peripheral devices will be completed and all the soldering related work will be done.
 
* Initial checks for hardware like motors and other peripheral devices will be completed and all the soldering related work will be done.
 
* A detailed spreadsheet will be created if not already available for cape pin mapping and referencing for further use during BeagleBone AI software development ease.
 
* A detailed spreadsheet will be created if not already available for cape pin mapping and referencing for further use during BeagleBone AI software development ease.
 
|-
 
|-
| May 25 || Milestone #1 ||  
+
| June 8 || Milestone #1 ||  
 
* Introductory YouTube video.
 
* Introductory YouTube video.
 
* Running cape examples and user space examples on BeagleBone Black. This will allow me to get more info on the process of setting up the software and hardware of the cape for future reference.
 
* Running cape examples and user space examples on BeagleBone Black. This will allow me to get more info on the process of setting up the software and hardware of the cape for future reference.
 
|-
 
|-
| June 1 || Milestone #2 ||  
+
| June 15 || Milestone #2 ||  
 
* Cleaning up the code in [https://github.com/jadonk/beagle-tester beagle-tester] and creating new examples.  
 
* Cleaning up the code in [https://github.com/jadonk/beagle-tester beagle-tester] and creating new examples.  
 
* Testing everything on BeagleBone Black.
 
* Testing everything on BeagleBone Black.
 
|-
 
|-
| June 8 || Milestone #3 ||
+
| June 22 || Milestone #3 ||
 
* Finalizing the compatibility of the header pins of the BeagleBone AI with the BeagleBone Black. Code submitted through pull requests [https://github.com/beagleboard/BeagleBoard-DeviceTrees/pulls?q=is%3Apr+is%3Aclosed #8 - #13] will be tested on the BeagleBone AI.
 
* Finalizing the compatibility of the header pins of the BeagleBone AI with the BeagleBone Black. Code submitted through pull requests [https://github.com/beagleboard/BeagleBoard-DeviceTrees/pulls?q=is%3Apr+is%3Aclosed #8 - #13] will be tested on the BeagleBone AI.
 
* Detailed discussion with the mentor on the work done till now.
 
* Detailed discussion with the mentor on the work done till now.
 
|-
 
|-
| June 15 - 19 18:00 UTC || Milestone #4 <br> (Phase 1 Evaluation) ||  
+
| June 29 - July 3 18:00 UTC || Milestone #4 <br> (Phase 1 Evaluation) ||  
 
* Testing the pin control using libgpiod.
 
* Testing the pin control using libgpiod.
 
* Running already available examples that demonstrate the proper working of pin control using libgpiod.
 
* Running already available examples that demonstrate the proper working of pin control using libgpiod.
 
* Finalizing everything done till now and submitting the Phase 1 report for evaluation.
 
* Finalizing everything done till now and submitting the Phase 1 report for evaluation.
 
|-
 
|-
| June 22 || Milestone #5 ||
+
| July 10 || Milestone #5 ||
 
* Testing user space examples with BeagleBone AI.
 
* Testing user space examples with BeagleBone AI.
 
* Taking notes and feedback from my mentor on the quality of code.
 
* Taking notes and feedback from my mentor on the quality of code.
 
|-
 
|-
| June 29 || Milestone #6 ||
+
| July 17 || Milestone #6 ||
 
* Initial setup for using capes with BeagleBone AI. Everything will be already available to me as the process is already complete for BeagleBone Black.
 
* Initial setup for using capes with BeagleBone AI. Everything will be already available to me as the process is already complete for BeagleBone Black.
 
* Making the required fixes for running the userspace examples on BeagleBone AI.
 
* Making the required fixes for running the userspace examples on BeagleBone AI.
Line 167: Line 203:
 
# [https://beagleboard.org/static/images/capes/600px/BeagleBoneRelayCapeA2_Top.png Relay Cape].
 
# [https://beagleboard.org/static/images/capes/600px/BeagleBoneRelayCapeA2_Top.png Relay Cape].
 
|-
 
|-
| July 6 || Milestone #7 ||
+
| July 24 || Milestone #7 ||
 
* Finalizing the device tree code and driver code.
 
* Finalizing the device tree code and driver code.
 
* Testing the Robotics Cape on [https://beagleboard.org/static/images/capes/600px/roboticscape-top-angle3.jpg BeagleBone AI] using newly created device tree and already available cape examples.
 
* Testing the Robotics Cape on [https://beagleboard.org/static/images/capes/600px/roboticscape-top-angle3.jpg BeagleBone AI] using newly created device tree and already available cape examples.
 
* Detailed discussion on the work done till now.
 
* Detailed discussion on the work done till now.
 
|-
 
|-
| July 13 -17 18:00 UTC || Milestone #8 <br> (Phase 2 Evaluation) ||
+
| July 27 - 31 18:00 UTC || Milestone #8 <br> (Phase 2 Evaluation) ||
 
* Fixing the code and making required changes for cape compatibility.
 
* Fixing the code and making required changes for cape compatibility.
 
* Documenting everything and submitting the Phase 2 report for evaluation.
 
* Documenting everything and submitting the Phase 2 report for evaluation.
 
|-
 
|-
| July 20 || Milestone #9 ||
+
| August 7 || Milestone #9 ||
 
* Testing following capes :
 
* Testing following capes :
 
# [https://4dsystems.com.au/4dcape-43 4.3"Display Cape]
 
# [https://4dsystems.com.au/4dcape-43 4.3"Display Cape]
Line 183: Line 219:
 
* Taking notes and feedback from my mentor on the quality of code.
 
* Taking notes and feedback from my mentor on the quality of code.
 
|-
 
|-
| July 27 || Milestone #10 ||
+
| August 14 || Milestone #10 ||
 
* Testing the [https://beagleboard.org/static/images/capes/600px/BeagleBoneRelayCapeA2_Top.png Relay Cape].
 
* Testing the [https://beagleboard.org/static/images/capes/600px/BeagleBoneRelayCapeA2_Top.png Relay Cape].
 
* Completing the documentation.
 
* Completing the documentation.
 
* Taking feedback from my mentor.
 
* Taking feedback from my mentor.
 
|-
 
|-
| August 3 || Milestone #11 ||  
+
| August 21 || Milestone #11 ||  
 
* Completion YouTube video
 
* Completion YouTube video
 
|-
 
|-
| August 10 - 17 18:00 UTC || Final week || Students submit their final work product and their final mentor evaluation
+
| August 24 - 31 18:00 UTC || Final week || Students submit their final work product and their final mentor evaluation
 
|-
 
|-
| August 17 - 24 18:00 UTC || End of competition || Mentors submit final student evaluations
+
| August 31 - September 24 18:00 UTC || End of competition || Mentors submit final student evaluations
 
|}
 
|}
 
<!--
 
<!--
Line 246: Line 282:
 
                                                                                                                                                                                   - Set_ on #beagle
 
                                                                                                                                                                                   - Set_ on #beagle
  
 +
<!--
 
===Suggestions===
 
===Suggestions===
 
Is there anything else we should have asked you?
 
Is there anything else we should have asked you?
 +
-->

Latest revision as of 05:07, 23 February 2024


Cape compatibility layer for BeagleBone Black and BeagleBone AI

Student: Deepak Khatri (lorforlinux)
Mentors: Jason Kridner
Code: https://github.com/deepaklorkhatri007/linux/tree/4.14, TODO: Update to various trees and closer to mainline
Wiki: https://elinux.org/BeagleBoard/GSoC/2020Proposal/DeepakKhatri
GSoC: https://summerofcode.withgoogle.com/projects/#5125259251941376

Status

This project is currently just a proposal.

Proposal

Completed all the requirements listed on the ideas page. the code for the cross-compilation task can be found here submitted through the pull request #130.

About you

IRC: lorforlinux
Github: Deepak Khatri
School: Netaji Subhas Univerity of Technology (NSUT) formerly NSIT
Country: India
Primary language(s): Hindi,English
Typical work hours: 9AM - 7PM IST
Previous GSoC participation: I participated in GSoC2019 but I was not selected for the project. The project was to make a Jekyll website for the AIMA organization, Discussion on the project can be found [at https://github.com/aimacode/aima-exercises/issues/36 here] and the prototype I made can be found here. From the GSoC2019 I learnt the importance of communication.

About your project

Project name: Cape compatibility layer for BeagleBone Black and BeagleBone AI

Description

Enabling overlay compatibility:

The BeagleBone boards use U-Boot as their Tertiary Program Loader (TPL). U-boot is responsible for loading the Linux kernel, Flattened Device Tree (FDT), Initial Ram File System (initramfs) into DRAM. U-Boot controls the boot time MUX_MODE for the GPIOs, symlinks for the peripherals and other hardware-specific device configurations by loading specific FDT. We can control the configuration(s) by updating the FDT for the hardware we want to support. We can enable the device compatibility in this case Cape compatibility using the boot-time device tree overlays. Overlays for most of the capes are available from the bb.org-overlays repo. A major task for achieving cape compatibility will be creating device tree overlays and loading at boot time. For loading the required driver for the hardware at boot time we have to edit uEnv.txt file. We can export the required overlays at boot time and the hardware will be compatible as soon as the board boots up. Most capes use an EEPROM for storing hardware related information about the CAPE and all of the individual pin configuration details can be imported out of the EEPROM, which makes things way better to handle.

Device tree overlays are a very important part of the main idea of this project which is to make the same user-space examples work with both BeagleBone Black and AI. the same references will be used in the drivers for peripherals assigned to the same pins between Black and AI. Main things to do for achieving that are assigning the same pin names and same aliases for both the boards.

For making the cape compatible, the device tree overlays code will be added to bb.org-overlays repo and changes will be made in the file am5729-beaglebone.dts and other related files to BeagleBoard-DeviceTrees repo for base pin naming and MUX_MODE selection upon which overlays will sit and will be able to use the properties assigned in am5729-beaglebone.dts device-tree source.

  1. For making the boards pin to pin compatible as in pin names, a new node will be created called cape-universal {...} which will hold child nodes like P8_03{...} for pin name assignment. Included the code for through pull request #13.
  2. Setting up the same default pin configuration in pin muxing nodes of board device tree files is required which will be achieved using nodes that use DRA7XX_CORE_IOPAD() functions along with the pinctrl-single driver. I have included the required code through pull requests #8 #9 #10.
  3. I will also assign symlinks for the peripherals as discussed with rcn over pull requests #11 #12.I have already assigned some of the symlinks for currently active peripheral devices of BBB through the pull request #14. We might also require to assign the same aliases for peripherals in the device tree which is the easiest part after achieving the above goals. We need some assignments under aliases {...} nodes similar to what we have in the BeagleBone Black device tree file.

The file am335x-bone-common-univ.dtsi for BeagleBone Black and am335x-pocketbeagle.dts provides all the information for pin muxing and pin naming. The project will enable us to use serial ports and userspace I2C/spidev. In device trees, the aliases node can be seen as a quick lookup table, an index of another node. We can use find_node_by_aliases() function to find a node by its alias. Interface buses like I2C, SPI, UART, CAN, etc will be aliases according to the BeagleBone cape interface spec. All the aliases defined in the device tree can be found in /sys/firmware/devicetree/base/aliases as files containing the full name/path for the peripheral device. For GPIOs, examples would work using pin names under libgpiod.

Pin MUX_MODE selection, pin naming and aliasing of P8 and P9 headers of BeagleBone AI will enable us to use different peripherals like GPIO, I2C, UART, SPI, qQEP, CAN, etc. BeagleBone cape interface spec shows further details on the active bus data of BeagleBone Black and BeagleBone AI. For the cape specific bus interface, the BeagleBone Cape Header Pins file gives us all the required information like which pins are used and also details on MUX_MODE are also provided there.

Enabling userspace and end-user compatibility

Looking at the symlink theory of operation with udev we see that for allowing userspace programs to use the devices with a custom name Symlinks allow us to define names/location of a peripheral. It’s very much like creating an alias for the peripheral but we can use this in userspace and it can be richer in information, for example, let’s look at this new symlink I created for the uart1 and submitted through pull request #14.

&uart1 {
           status = "okay";
           pinctrl-names = "default";
           pinctrl-0 = <>;
           symlink = "bone-uart1";
};

In this node, we assign the value of “bone-uart1” to the symlink property which we can call from userspace. Device tree creates an index of all the symlinks we define, In the device tree directory like for the SPI device for which we already have symlinks assigned in the current device tree.

When we look inside the /sys/firmware/devicetree/ of our BeagleBone we see all the folders created by the device tree. For SPI of BBB we see these folders.

  • ./sys/firmware/devicetree/base/ocp/spi@481a0000/channel@0/symlink
  • ./sys/firmware/devicetree/base/ocp/spi@481a0000/channel@1/symlink
  • ./sys/firmware/devicetree/base/ocp/spi@48030000/channel@0/symlink
  • ./sys/firmware/devicetree/base/ocp/spi@48030000/channel@1/symlink

These indexed folders can be searched and viewed through user space programs for example when we look in the 10-of-symlink.rules we see it uses these indexed folders for creating new devices under /dev. Looking at the code, first, we see ATTR{device/of_node/symlink} !=”” which checks if there are symlinks available. Then we create a variable for that symlink using ENV{OF_SYMLINK} and if it’s not empty and we have a device name we add it to the SYMLINK environment variable and we also add the systemd to TAG. In the end, we add an alias for the device using ENV{SYSTEMD_ALIAS}+="/dev/%E{OF_SYMLINK}".This way we can use the peripheral using the name assigned in the device tree through symlinks.

 
ATTR{device/of_node/symlink}!="", \
           ENV{OF_SYMLINK}="%s{device/of_node/symlink}"
 
ENV{OF_SYMLINK}!="", ENV{DEVNAME}!="", \
           SYMLINK+="%E{OF_SYMLINK}", \
           TAG+="systemd", ENV{SYSTEMD_ALIAS}+="/dev/%E{OF_SYMLINK}"


We have many peripherals available to use on AM5729 SoC but with different MUX_MODExx than AM3358. First let's see an example for /dev/bone/i2c/1 specs for which are :


AM3358 I2C1
AM5729 I2C5

    P9.17 - SCL
    P9.18 - SDA

Let's see this code from my pull requests #8 #9 #10 in BeagleBoard-DeviceTrees repo. It is for the I2C peripiral on AM5729 based BeagleBone AI. The pin P9.17 has 2 GPIO pins of SoC attached to it and the code configures the pin to use the 2nd GPIO in MUX_MODE10 that enables the I2C on that pin. You see all that information and more insde the System Reference Manual for BeagleBone AI, info on P9.17 can be cound here.


P9_17_i2c_pin: pinmux_P9_17_i2c_pin { pinctrl-single,pins = <
		DRA7XX_CORE_IOPAD(0x36B8, PIN_OUTPUT_PULLUP | INPUT_EN | MUX_MODE10) >; };

Looking on the code for AM3358 for the same P9.17 pin on BeagleBone Black which can be found here. We see that it is using the MUX_MODE2 and only one GPIO pin of SoC is attached to this header pin.


P9_17_i2c_pin: pinmux_P9_17_i2c_pin { pinctrl-single,pins = <
		AM33XX_IOPAD(0x095c, PIN_OUTPUT_PULLUP | INPUT_EN | MUX_MODE2) >; };	/* spi0_cs0.i2c1_scl */

Software required and Programming Languages:

The project requires the use of the device tree compiler (dtc) for compiling the device tree source (ex. *.dts, *.dtsi) files. The c programming language will be used for kernel-level programming and the gcc compiler along with other build tools will be used for compiling the C source code (*.c).

Hardware required:

  1. BeagleBone Black. (ordered Black Wireless)
  2. BeagleBone AI. (ordered)
  3. BeagleBone capes:
    1. Load Cape. (ordered)
    2. Motor Cape. (ordered)
    3. Relay Cape. (ordered)
    4. Robotics Cape.
    5. Servo Cape. (ordered)
    6. Comms cape. (ordered)
    7. 4.3"Display Cape. (ordered)
    8. 7.0" Primary gen4 Display CAPE.
  4. Additional hardware for using capes:
    1. JST SH Jumper 4 Wire and 6 Wire.
    2. Grove Universal 4 Pin to Beaglebone® 6 Pin Female. (ordered)
    3. Grove Universal 4 Pin to Beaglebone® Blue 4 Pin Female. (ordered)
    4. Servo motor. (ordered)
    5. DC Motor.
    6. Groove Modules:
      1. Grove - Servo.
      2. Grove - Vibration Motor.
      3. Grove - Line Finder v1.1.
      4. Grove - I2C Color Sensor V2.
      5. Grove - Rotary Angle Sensor.
      6. Grove - Adjustable PIR Motion Sensor.
      7. Grove - 6-Position DIP Switch.
      8. Grove - 16x2 LCD (White on Blue).
      9. Grove - Speaker.
      10. Grove - Buzzer.
      11. Grove - GPS Module. (ordered)
      12. Grove - Digital Light Sensor - TSL2561.
      13. Grove - Temperature Humidity Sensor (High-Accuracy & Mini).
  5. FTDI Serial TTL-232 USB Cable. (ordered)
  6. Barcode reader. (ordered)
  7. Must have lab tools like:
    1. Solder, flux, and soldering iron.
    2. Screwdriver set.
    3. Tweezers and pliers.

Timeline

May 4 Pre-work Community Bonding Period and discussion on the project and resources available.
June 1 Pre-work complete Coding officially begins!
  • All the boards and additional hardware will be available to me at this period of time and I should have set up my BeagleBone Black and Ai boards i.e flashing up to date Linux image and Testing user-led blink code :)
  • Initial checks for hardware like motors and other peripheral devices will be completed and all the soldering related work will be done.
  • A detailed spreadsheet will be created if not already available for cape pin mapping and referencing for further use during BeagleBone AI software development ease.
June 8 Milestone #1
  • Introductory YouTube video.
  • Running cape examples and user space examples on BeagleBone Black. This will allow me to get more info on the process of setting up the software and hardware of the cape for future reference.
June 15 Milestone #2
  • Cleaning up the code in beagle-tester and creating new examples.
  • Testing everything on BeagleBone Black.
June 22 Milestone #3
  • Finalizing the compatibility of the header pins of the BeagleBone AI with the BeagleBone Black. Code submitted through pull requests #8 - #13 will be tested on the BeagleBone AI.
  • Detailed discussion with the mentor on the work done till now.
June 29 - July 3 18:00 UTC Milestone #4
(Phase 1 Evaluation)
  • Testing the pin control using libgpiod.
  • Running already available examples that demonstrate the proper working of pin control using libgpiod.
  • Finalizing everything done till now and submitting the Phase 1 report for evaluation.
July 10 Milestone #5
  • Testing user space examples with BeagleBone AI.
  • Taking notes and feedback from my mentor on the quality of code.
July 17 Milestone #6
  • Initial setup for using capes with BeagleBone AI. Everything will be already available to me as the process is already complete for BeagleBone Black.
  • Making the required fixes for running the userspace examples on BeagleBone AI.
  • Testing following capes :
  1. Servo Cape
  2. Motor Cape
  3. Load Cape
  4. Relay Cape.
July 24 Milestone #7
  • Finalizing the device tree code and driver code.
  • Testing the Robotics Cape on BeagleBone AI using newly created device tree and already available cape examples.
  • Detailed discussion on the work done till now.
July 27 - 31 18:00 UTC Milestone #8
(Phase 2 Evaluation)
  • Fixing the code and making required changes for cape compatibility.
  • Documenting everything and submitting the Phase 2 report for evaluation.
August 7 Milestone #9
  • Testing following capes :
  1. 4.3"Display Cape
  2. 7.0" Primary gen4 Display CAPE
  • Code cleaning and proper commenting if not done already.
  • Taking notes and feedback from my mentor on the quality of code.
August 14 Milestone #10
  • Testing the Relay Cape.
  • Completing the documentation.
  • Taking feedback from my mentor.
August 21 Milestone #11
  • Completion YouTube video
August 24 - 31 18:00 UTC Final week Students submit their final work product and their final mentor evaluation
August 31 - September 24 18:00 UTC End of competition Mentors submit final student evaluations

Experience and approach

I have a good understanding of C, C++, and python. I have done an internship on Embedded Electronics using BeagleBoneBlack. I completed this project called "Mausam national" during my internship. Mausam national is an air quality cum multiple gases ppm level acquisition system. The interesting part of the project is that it can connect to the internet and fetch the air quality data from my university's pollution center that they provide for everyone to use. we used that data for the calibration of the MQ sensors on-board.

I was one of the quarter-finalists in IICDC2017 and during that period I worked with ARM cortex M4 based MSP432. I participated in Electronics Maker contest '17 there I presented a low-cost biopotential amplifier based on TL074 and won Ti's C2000 DSP for the project. I have worked on both hardware and software-based projects, hardware projects can be found on my youtube channel here and software projects can be found on my GitHub here.

Contingency

I believe that if I get stuck on my project and my mentor isn’t around, I will use the resources that are available to me. Some of those information portals are listed below.

  1. Derek Molly's beagle bone guide provides all the information needed for getting up and running with my beagle.
  2. Content on e-ALE.org is very useful for information that ranges from tutorials and walkthroughs to the level of very advanced stuff.
  3. BeagleBone cookbook from Mark A. Yoder & Jason Kridner is the best source for test projects during the prototyping period.
  4. The technical reference manuals provided by TI on am3358 and am5729 are the best source for getting the insights on the SoC used in Black and Ai.

Benefit

I believe that the project is very important for the adoption of the BeagleBone AI. It will bring support for BeagleBone Black capes on BeagleBone AI and also for the execution of same user space examples written for BeagleBone black.
                                                                                                                                                                               - Deepak Khatri aka lorforlinux

Quotes from BeagleBone community member(s):

Me, personally, I would find this very interesting. I love add-ons, Capes, sensors, and actuators. Making an Upward Working Cape would be successful for many people looking to use the AI. Now, easy? I do not know. It is like upward mobility in life. Instead of making things updated, one makes the old work w/ the new. That is a success.
                                                                                                                                                                                  - Set_ on #beagle