BeagleBoard/GSoC/2019Proposal/clickboard-support-under-greybus

Clickboard Support Under Greybus

MikroElektronika Click boards

• bringing in Click Board Support via Manifests using Greybus Simulator, instead of device tree overlays
• modify the Greybus drivers and provide an userspace simulator based on GBSIM (Greybus Simulator)
• Create example manifests for several MikroElectronika click boards and provide documentation for creating and loading Greybus Simulator Manifest files.

Student: Vaishnav M A
Mentors: Jason Kridner
Code: https://github.com/vaishnav98/gbsim
https://github.com/beagleboard/linux
Wiki: https://elinux.org/BeagleBoard/GSoC/2019Proposal/clickboard-support-under-greybus
GSoC: Not Yet Submitted

Status

This project aims to bring in Click board support starting from Greybus Simulator, I was able to install the Greybus Simulator on:

Linux beaglebone 4.1.38-bone24

BeagleBoard.org Debian Image 2018-10-07

During the installation I was facing some issues and was able to fix it by making simple changes to the Greybus Simulator Sources here : https://github.com/vaishnav98/gbsim/commit/aaf23e23dcaba53dbe9518f4a10318fde8cff293

Currently I am trying to fix the errors occurring while installing the greybus simulator and its dependencies on:

Linux beaglebone 4.14.71-ti-r80

This project is currently in the proposal stage.

Proposal

The Hello World Application was Cross-Compiled(and tested using QEMU Emulator) and Pull Request #127 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,C,C++,Linux,Python,UI Design,PCB Design,HTML/CSS Hardware Skills : Circuit Prototyping and Soldering,HomeBrewing PCBs. Previous GSoC participation: 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. I had successfully completed the project : Fixing Bugs in BoneScript and Improve BeagleBone UI during GSoC 2018

About my project

Project name : Clickboard Support Under Greybus

Description

Click boards are a flagship hardware product line of MikroElektronika with over 600 add-on boards ranging from wireless connectivity clicks to Human Machine Interface clicks for interfacing with peripheral sensors or transceivers. Most of the Click boards use the common protocols like SPI,I2C or UART to communicate with the Beaglebone and thus the support for them now is accomplished via device tree overlays via the bb.org-overlays repository. This requires /boot/uEnv.txt to be modified to load the drivers at boot, requiring at least one reboot to enable the support in a potentially error-prone way, as modifying that file could prevent the image from booting. This makes the interfacing of the Click Boards with Pocketbeagle a tedious task and it would be better if there was a possibility of adding hot-plugging support for the click boards which would make the interfacing a lot easier.

The Greybus Simulator is a tool which simulates an AP Bridge, SVC, and an arbitrary set of Ara modules plugged into Greybus. Greybus already provides most of the interfaces used on click boards and utilizes manifest files to enumerate hardware at run-time. By using the simulator, similar functionality should be possible to achieve for these existing buses, rather than via true hot-swapping hardware.

Greybus

Greybus System

The Greybus specification provides device discovery and description at runtime, network routing and housekeeping, and class and bridged PHY protocols, which devices use to talk to each other and to the processors. The following figure gives a glimpse of how various parts of the kernel interact with the Greybus subsystem.

The Greybus core implements the supervisory controller (SVC) protocol, which is used by the application processor (AP — the CPUs running Linux) to communicate to the SVC. The SVC represents an entity within the Greybus network that configures and controls the Greybus (UniPro) network, mostly based on the instructions from the AP. All module insertion and removal events are first reported to the SVC, which in turn informs the AP about them using the SVC protocol. The AP is responsible for administrating the Greybus network via the SVC.

During module initialization (after the module is detected on Greybus, here in our case the simulator emulates the device connection), the Greybus core parses the module's manifest, which describes the capabilities of the module and creates devices within the kernel to represent it.

Greybus Manifest Files

Example Greybus Manifest File

When a module is connected to the Greybus network, the AP starts enumerating its interfaces over CPort0. The AP fetches a block of data from the interfaces, called the interface manifest. The manifest is a data structure containing the manifest header along with a set of descriptors. The manifest allows the AP to learn about the capabilities of the interface and creates devices within the kernel to represent the interface.

Following is a simple example of a raw manifest file that represents an interface that supports a single audio bundle. The manifest file is converted into a binary blob using the Manifesto library.A minimal manifest file contains the manifest-header , interface-descriptor,string-descriptors,bundle-descriptor, function-descriptors(I2C,SPI,UART,GPIO,..) and c-port descriptors.

The Manifesto library is a simple tool to generate a Greybus manifest blob from a Python ConfigParser-style input file, when using with the Greybus Simulator it's possible to hot plug/unplug modules by simply copying or removing a conformant manifest blob file in the /path/to/hotplug-module directory

Greybus Simulator

The Greybus Simulator is a tool which simulates an AP Bridge, SVC, and an arbitrary set of modules plugged into Greybus. Greybus Simulator successfully runs on the beaglebone backend( Linux beaglebone 4.1.38-bone24), it is possible to hot plug/unplug modules by simply copying or removing a conformant manifest blob file in the /path/to/hotplug-module directory. Thus we can enable Click Board Support via Greybus Simulator by writing suitable Manifests according to the Clickboard Specifications, creating and copying the respective Manifest blobs to the /path/to/hotplug-module directory. Thus we can bring in click board support in a more convenient way without requiring a reboot each time when a new click is added as required when loading a device tree overlay for the click board.For writing the manifest i am planning to use the available Device Tree Overlays as reference to get a clear idea about the interfaces used by each click board.

Overview

Currently the support for Click Boards are provided via device tree overlays requiring at least one reboot to enable the support in a potentially error-prone way. The primary aim of this project is to provide an userspace greybus simulator(similar to GBSIM) to bring in support for the Click Boards through Greybus Manifest files and writing the manifest files corresponding to different Click Boards. I am planning to start from the Greybus Simulator sources fix the issues that occur while installation in recent kernels and then try to bring in support for a single Click Board first and then prepare the manifest files and provide support for more click boards.I also plan to develop a Command Line utility to make it easier for the end user to load the manifest for corresponding click board, by using the CLI, the user can easily load/unload the click boards with simple commands like:

insclick oledc
rmclick oledc 

I am planning to add and test the greybus simulator based support for the following click boards:

• SPI OLED C Click
• SPI OLED B Click
• MicroSD Click
• MPU 9DOF Click
• Weather Click
• ETH Click
• RTC Click
• GNSSS 4 Click
• Ultrasonic Click
• Waveform Generator Click
• Temperature and Humidity Click

Timeline

I am planning to work on fixing the Greybus Simulator issues and then try to demonstrate a simple example for the click board support via GBSIM before proceeding to adding support for other click boards.

Prior to Coding Period

I will use this time to go through the entire codebase of Greybus Simulator, try to understand the Greybus specifications, the structure of the GBSIM Manifest files and the Manifest file generator. I will also try to use this period to fix the compilation/installation issues with GBSIM on Linux beaglebone 4.14.71-ti-r80(and recent kernel versions).

Community Bonding Period: May 6 - May 26

• Prepare the introduction video and start a blog to document the project progress.
• Start discussions in the community channels and ask feedback/suggestions about the project
• Testing and getting familiarized with the hardware
• Make changes to some of the goals according to mentors’ opinion
• Fix timings for periodic meeting with mentors
• Discuss about Documentation Guidelines to be Followed

Week 1: May 27 - June 2

• Work on fixing the issues with GreyBus Simulator
• Try to bring in support for SPI based OLED C Click through Greybus Simulator( write the required Manifest and fix issues with corresponding drivers).

Week 2: June 3 - June 10

• Prepare Documentation for writing manifests for other click boards with similar(SPI) interface.
• Bring support for SPI based OLED B click
• Bring support for SPI based microSD click

Week 3: April 11 - June 17

• Try to bring in support for I2C based MPU 9DOF click through Greybus Simulator( write the required Manifest and fix issues with corresponding drivers)
• Prepare Documentation for installation and making use of Greybus based Click board support.
• Prepare Documentation for writing manifests for other click boards with similar(I2C) interface.

Week 4: June 17 - June 24

• Bring support for SPI based microSD click(write the corresponding Manifest and testing)
• Bring support for I2C based Weather click with suitable demonstration examples
• Prepare test/demonstration videos for added click boards support via greybus simulator

At the end of Phase I, I will be able to deliver : working Click Board support through greybus simulator for SPI based (OLED C click, OLED B click,microSD Click) and I2C based(MPU 9DOF click) click boards.

Week 5: June 25 - July 01

• complete previous weeks work if any
• ask for community feedback for finished work and make suggested changes
• add support for the SPI based ETH Click with suitable demonstration examples
• add support for the SPI based ETH WIZ Click

Week 6: July 01 - July 08

• add support for I2C based RTC Click with suitable demonstration examples
• add support for SPI based RTC 5 Click

Week 7: June 09 - July 16

• add support for I2C based Temp and Humidity Click with suitable demonstration examples
• add support for SPI based waveform Generator Click with suitable demonstration examples

Week 8: July 16 - July 22

• prepare test/demonstration videos for click board support added after phase I
• Testing and documenting the work done until now and fixing any issues
• ask for community feedback for finished work and make suggested changes

By the end of Phase II, I will be able to Deliver manifests and click board support for ETH Click, ETH WIZ Click, RTC Click, RTC 5 Click, Temp and Humidity Click, Waveform Generator Click along with proper documentation

Week 9: July 23 - July 29

• add support for UART based GNSS 4 Click with suitable examples
• add support for UART based GNSS 5 Click(with pps) and provide suitable examples
• add support for UART based Ultrasonic 2 Click and provide suitable examples

Week 10: July 30 - Aug 6

• develop the Python-based Command Line utility which can be used to load the manifests
• bundle documentation for each click board added with the CLI so that the user can infer details about clicks directly from CLI
• prepare demonstration video for CLI and ask for community feedback regarding the project
• testing out the project for different OS Image and Kernel versions and reporting the status

Week 11 and 12: Aug 7 - Aug 23

• these two weeks are reserved as buffer time for finishing pending work from previous weeks
• bundle all the manifests in a single repo and add detailed installation and development instructions
• Improve the CLI Tool as per feedback from mentors and community
• Prepare final documentation/Wiki for the project
• Prepare the final video

Experience and approach

I am a Third year undergraduate pursuing Electronics and Communication Engineering, I have enough experience working with BeagleBone and other Embedded Linux based boards. I have successfully completed GSoC 2018 under Beagleboard.org Foundation : Fixing Bugs in BoneScript and Improve BeagleBone UI I have also some experience in Linux Kernel Module development and cross-compiling which will be useful for the project. I have tried to go through the Greybus Simulator sources and have a basic understanding of the project.

pxt-beaglebone – Makecode Beaglebone a Makecode Blocks editor for Beaglebone Boards

My Works(all uploaded on my Github Repository):

Contingency

If I get stuck and if my mentor isn’t around , I’ll try to search the internet for similar issues and try to solve the 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, IRC and mailing lists, I will try to proceed my work by focussing on documenting the finished work and creating demonstration videos.

Approach

I don't have any other commitments during my vacation, so I can devote about 7-9 hours a day, i.e. 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

MikroElektronika Click boards are a wonderful piece of hardware which can be used for interfacing with peripheral sensors or transceivers. There are over 600 add-on click boards from wireless connectivity clicks to Human Machine Interface clicks which could take PocketBeagle projects to the next level. Unfortunately, the current method of adding support for click boards through device tree overlays require /boot/uEnv.txt to be modified to load the drivers at boot, requiring at least one reboot to enable the support in a potentially error-prone way thus making it a tedious task. However, through the Greybus simulator which offers most of the interfaces used by click boards, hardware enumeration can be performed by utilizing manifest files (i.e. just by copying a manifest blob to the simulator hot-plug directory) thus achieving similar functionality for these existing buses, rather than via true hot-swapping hardware. The progress in this project can also help in adding support for various Click modules to TechLab Cape. Some of comments mentioning the importance of this project are given below:
Mentor Jason Kridner on Beagleboard-GSoC google groups in the project ideas introduction mail

 I'm really thinking there is a lot of fun around Greybus to have. By using the simulator, similar functionality should be possible to achieve for these existing buses, rather than via true hot-swapping hardware.

in https://lwn.net/Articles/715955/

As Project Ara is discontinued now, it would be quite interesting to find new targets (like the Internet of Things) for the Greybus subsystem and adapt Greybus to support them.