Beagleboard GSoC '19: Clickboard Support Under Greybus
This is a Google Summer of Code 2019 project under BeagleBoard.org Foundation aimed at :
- setting up Greybus Simulator and bringing support for MikroElektronika Clickboards through Greybus
- writing Greybus manifests for different Mikroelektronika Clickboards and provide a straightforward way for adding support for new Click boards
Code : GBSIM , manfiesto & insclick/rmclick Utilities , Mikrobus Kernel Driver
Mentors : Jason Kridner, Ravi Kumar Prasad
GSoC Project Page : https://summerofcode.withgoogle.com/projects/#5996499987595264
Project Blog : https://vaishnav98.github.io/GSoC19/
Project Final Video : https://youtu.be/RWBzyHNetOE
Project Intro Video : https://www.youtube.com/watch?v=QtzHhAFE0SE
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.
This project aims to bring in partial hotplug support for click boards through the Greybus Subsytem. Click Board support through Greybus uses the Greybus Simulator to simulate the AP(Application Processor) bridge and other endpoints required for greybus, once the Greybus Simulator(gbsim) is setup then simply copying a conformant manifest blob to the hotplug-module directory of the gbsim will create virtual interfaces/buses(SPI/I2C/UART/GPIO) corresponding to the manifest with the required device drivers loaded. The Greybus Simulator also takes care of the routing of the transfers from the greybus virtual interfaces/buses to the corresponding physical interfaces on the beaglebone thus enabling support for a Click board connected to a mikrobus socket on the board.
The insclick
/rmclick
command line utilities help in loading/unloading clicks by handling things like copying the correct manifest blob, setting the pinmux and device instantiation.Thus insclick/rmclick utilities along with a Greybus Simulator(gbsim) instance makes click board support as easy as :
sudo insclick oledc(clickname) p1(portname) : for loading the OLED C click on the mikrobus port 1
sudo rmsclick oledc(clickname) p1(portname) : for unloading the OLED C click from the mikrobus port 1
Project Status
GBSIM Features | Supported Clicks | User Experience |
---|---|---|
Fix Issues with GBSIM | OLED C Click | insclick/rmclick utilities |
GBSIM Install and start Scripts | MPU 9DOF Click | Examples for each supported click, Techlab Cape Examples |
GBSIM Instance for each mikrobus port | Weather Click | Makecode Integration |
OLEDB Click | ||
MicroSD Click | ||
ETH Click | ||
RTC6 Click | ||
Temp&Humidity Click | ||
Waveform Click | ||
GNSS Click | ||
Ultrasonic 2 Click | ||
Completed | Hardware Not available | Not Completed |
The project has three main components :
-
Greybus Simulator(gbsim)
: A tool which simulates an AP Bridge, SVC, and an arbitrary set of modules plugged into Greybus. -
manifesto, insclick/rmclick utilities
: these utilities are used to create greybus manifest blobs, loading and removing the click boards on mikrobus port -
mikrobus kernel driver
: the mikrobus kernel driver is used to instantiate devices with additional platform data(interrupts,display properties) on the mikrobus.
The instructions for installing and setting up each of the components are given below:
For installing and setting up the Greybus Simulator(GBSIM), Greybus Kernel driver should be available, the Greybus Kernel Module is available on BeagleBone Linux Kernel Versions greater than 4.14.108-ti-r106
, if you have an older version, please update the kernel. The details of the image used for testing are:
debian@beaglebone:~$ uname -a
Linux beaglebone 4.14.108-ti-r106 #1 SMP PREEMPT Fri May 24 22:12:34 UTC 2019 armv7l GNU/Linux
debian@beaglebone:~$ cat /etc/dogtag
BeagleBoard.org Debian Image 2018-10-07
If you are using an older kernel version and(or) if greybus kernel drivers are not available, then update the kernel using the following commands:
cd /opt/scripts/tools/
git pull
sudo ./update_kernel.sh
sudo reboot
For installing gbsim
, other required dependencies and setting up gbsim
as a service :
git clone https://github.com/vaishnav98/gbsim.git
cd gbsim
sudo sh installgbsim.sh
For installing the gbsim
project and required dependencies manually without the install script follow the instructions here
Load up the Greybus Simulator corresponding to all the available Mikrobus Ports and the required modules manually, just run:
sudo startgbsim
For starting for single Mikrobus port, the parameters corresponding to the Port (SPI/I2C bus details) should be passed to gbsim:
sudo gbsim -g GBSIMID -h HOTPLUGDIR -c CSNO -s SPIBUS -i I2CADAPTER
-
GBSIMID
: Unique Integer ID for GBSIM -
HOTPLUGDIR
: GBSIM Hotplug Modules Directory -
CSNO
: Mikrobus Port SPI Chip Select No. -
SPIBUS
: Mikrobus Port SPI Bus No. -
I2C ADAPTER
: Mikrobus Port I2C Adapter Number
The manifesto
utility is used to create greybus manifest blobs(.mnfb) from greybus manifest(.mnfs) files,The insclick
/rmclick
command line utilities help in loading/unloading clicks by handling things like copying the correct manifest blob, setting the pinmux and device instantiation on the Mikrobus.
For installing the utilities, generating the reuqired manifest blobs and adding the insclick/rmclick CLI to path :
git clone https://github.com/vaishnav98/manifesto.git
cd manifesto
sudo sh install.sh
For creating a manifest blob(.mnfb) from a manifest file(.mnfs) :
manifesto -o /path/to/output.mnfb /path/to/input.mnfs
For loading a click to a mikrobus port through greybus (when gbsim is running & mikrobus kernel driver is installed):
sudo insclick rtc6 (clickname) p1 (portname :p1 ,p2 ,p3 ,p4)
The rmclick utility/command can be used to remove/free the Greybus Interface and Unload the Click, the rmclick usage is:
sudo rmclick rtc6 (clickname) p1 (portname :p1 ,p2 ,p3 ,p4)
The mikrobus kernel module is a simple driver to instantiate the devices with additional platform data (like interrupts..) on the mikrobus port, for installing the mikrobus driver(requires the Kernel Headers to be installed, will be already installed if gbsim was installed using the install script) :
git clone https://github.com/vaishnav98/mikrobus_device.git
cd mikrobus_device
(next command requires the Kernel Headers to be installed : (sudo apt-get install linux-headers-`uname -r`)
make all install
sudo modprobe mikrobus_spi_device name=devicename busno=spibusno csno=spi_cs max_speed=SPI_speed_hz irq_gpio=irqgpiono
sudo modprobe mikrobus_i2c_device custom(bool) name=devicename busno=i2cbusno address=devicei2caddress irq_gpio=irqgpiono
Once the Greybus Simulator(gbsim) and the required utilities are installed and set up, the steps for trying out different clicks are:
The gbsim instance for each mikrobus port on the platform can be started using:
sudo startgbsim
For loading a click to a mikrobus port via gbsim:
sudo insclick rtc6 (clickname) p1 (portname :p1 ,p2 ,p3 ,p4)
Here the argument portname
corresponds to the slot in which the click is connected , the PocketBeagle Mikrobus position 1 and Beaglebone Mikrobus Cape Position 1 corresponds to p1, the PocketBeagle Mikrobus position 2 and Beaglebone Mikrobus Cape Position 2 corresponds to p2, p3 and p4 corresponds to the slots 3 and 4 in the Beaglebone Mikrobus Cape, For more information on Mikrobus ports on the beaglebone see : Mikrobus Ports on BeagleBone Boards . The argument clickname
corresponds to the click name, for example, rtc6 weather, etc.
The rmclick utility/command can be used to remove/free the Greybus Interface and Unload the Click, the rmclick usage is:
sudo rmclick rtc6 (clickname) p1 (portname :p1 ,p2 ,p3 ,p4)
-
Note
: Users may need to disable HDMI Audio and Video for freeing the Mikorbus port pins used by HDMI, See U-Boot_Disable_on-board_devices
Adding support for new click board normally requires the addition of the click data under clicks.json and creating a new manifest(only for simple SPI based clicks), some example entries for SPI and I2C based clicks are explained below :
Adding support for simple I2C clicks which has no interrupts or other platform data requirements requires only the addition of the corresponding entry under clicks.json
. An example entry for the RTC 6 Click based on the MCP79410 I2C RTC is shown below:
"rtc6": {
"type": "i2c",
"class": "ordinary",
"driver": "mcp7941x",
"address": "0x6f",
"info": [
"RTC 6 Click",
"Use Command : sudo hwclock -r --rtc /dev/rtc1 to display the RTC Date and Time",
"use cat /sys/class/rtc/rtc1/date to get the RTC Date",
"use cat /sys/class/rtc/rtc1/time to get the RTC Time",
"use cat /sys/class/rtc/rtc1/since_epoch to get the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT)"
]
}
Here the key for the entry is the name of the click rtc6
, this name will be available with the insclick/rmclick commands.The other entries are:
-
type
: corresponds to the type of bus the click uses (currently SPI/I2C) -
class
: corresponds to whether the click requires additional platform data or not , in this case class->ordinary , the available options are : oridnary/platform/display -
driver
: corresponds to the name of linux driver available for the click device -
address
: corresponds to the I2C address of the device -
info
: this section contains the helping information for the user to get started with the Click Board , the helper string array can have any length and each array element will be displayed in new line when invoking the insclick command
Adding support for simple SPI clicks which has no interrupts or other platform data requirements requires only the addition of the corresponding entry under clicks.json
and creation of a greybus manifest file for the device. An example entry for the MicroSD Click is shown below:
"microSD": {
"type": "spi",
"class": "ordinary",
"info": [
"microSD Click",
"usage information"
]
},
Here the key for the entry is the name of the click microSD
, this name will be available with the insclick/rmclick commands.The other entries are:
-
type
: corresponds to the type of bus the click uses (currently SPI/I2C) -
class
: corresponds to whether the click requires additional platform data or not , in this case class->ordinary , the available options are : oridnary/platform/display -
info
: this section contains the helping information for the user to get started with the Click Board , the helper string array can have any length and each array element will be displayed in new line when invoking the insclick command
The example manifest for a microSD click is as shown below
;
; Simple SPI Interface Manifest
;
; Copyright 2015 Google Inc.
; Copyright 2015 Linaro Ltd.
;
; Provided under the three clause BSD license found in the LICENSE file.
;
[manifest-header]
version-major = 0
version-minor = 1
[interface-descriptor]
vendor-string-id = 1
product-string-id = 2
; Interface vendor string (id can't be 0)
[string-descriptor 1]
string = MikroElektronika
; Driver Name string (id can't be 0)
[string-descriptor 2]
string = mmc_spi
; Control cport and bundle are optional.
; - Control cport's id must be 0 and its bundle number must be 0.
; - No other bundle or control cport may use these values.
; - Class and protocol of bundle and cport must be marked as 0x00.
;
;Control protocol on CPort 0
[cport-descriptor 0]
bundle = 0
protocol = 0x00
;Control protocol Bundle 0
[bundle-descriptor 0]
class = 0
; SPI protocol on CPort 1
[cport-descriptor 1]
bundle = 1
protocol = 0x0b
; Bundle 1
[bundle-descriptor 1]
class = 0x0a
For adding support for new SPI clicks without additional platform data , a new manifest needs to be made from the above template where the string-decriptor 2
property should match the device driver corresponding to the clickboard (here mmc_spi corresponds to the driver for the microSD click), the newly created manifests should be saved under the manifests/ directory where the name of the manifest file should be same as the click name.To know more about greybus manifests see : Greybus Manifests
Adding support for SPI based display clicks requires only the additon of a corresponding entry under clicks.json
, currently the display clicks supported by the fbtft driver is supported through this method. An example entry for the OLED Click based on the SSD1306 driver is shown below:
"oledb": {
"type": "spi",
"class": "display",
"driver": "fb_ssd1306",
"width": "96",
"height": "39",
"speed": "6000000",
"buswidth": "8",
"fps": "40",
"info": [
"OLEDB Click",
"blinking cursor will be diplayed on the screen if setup was successful",
"use sudo fbi -T 1 -a NameofImage to display an image",
"use sudo screen /dev/tty1 to enter a conole on the OLED Screen",
"echo text | sudo tee /dev/vcs1 (or /dev/tty1) to display some text on the display"
]
}
Here the key for the entry is the name of the click oledb
, this name will be available with the insclick/rmclick commands.The other entries are:
-
type
: corresponds to the type of bus the click uses (currently SPI/I2C) -
class
: corresponds to the class of the click, in this case class->display , the available options are : oridnary/platform/display -
driver
: corresponds to the name of linux driver available for the click device -
width
: width of the display -
height
: height of the display -
speed
: SPI Bus Speed (Hz) -
buswdith
: number of bits width -
fps
: Frame Per Second -
info
: this section contains the helping information for the user to get started with the Click
Adding support for I2C based clicks with additional platform data requires only the additon of a corresponding entry under clicks.json
, currently the clicks with interrupt requirements is supported through this method, for adding support for clicks with additonal platform_data, the mikrobus_i2c driver needs to be modified. An example entry for the MPU9DOF Click based on the MPU9150 driver is shown below:
"mpu9dof": {
"type": "i2c",
"class": "platform",
"driver": "mpu9150",
"address": "0x68",
"info": [
"MPU9DOF Click",
"Use Command : cat /sys/bus/iio/devices/iio\\:device1/in_accel_x_raw to display the x-direction raw acceleration",
"use cat /sys/bus/iio/devices/iio\\:device1/in_accel_y_raw to display the y-direction raw acceleration",
"use cat /sys/bus/iio/devices/iio\\:device1/in_accel_z_raw to display the z-direction raw acceleration",
"use cat /sys/bus/iio/devices/iio\\:device1/in_anglvel_x_raw to display the x-direction raw angular velocity",
"use cat /sys/bus/iio/devices/iio\\:device1/in_anglvel_y_raw to display the y-direction raw angular velocity",
"use cat /sys/bus/iio/devices/iio\\:device1/in_anglvel_z_raw to display the z-direction raw angular velocity",
"use cat /sys/bus/iio/devices/iio\\:device1/in_temp_raw to display the raw tmeperature reading"
]
}
Here the key for the entry is the name of the click mpu9dof
, this name will be available with the insclick/rmclick commands.The other entries are:
-
type
: corresponds to the type of bus the click uses (currently SPI/I2C) -
class
: corresponds to the class of the click, in this case class->platform as additonal platform data is required , the available options are : oridnary/platform/display -
driver
: corresponds to the name of linux driver available for the click device -
address
: corresponds to the I2C address of the device -
info
: this section contains the helping information for the user to get started with the Click
Adding support for SPI based clicks with additional platform data requires only the additon of a corresponding entry under clicks.json
, currently the clicks with interrupt requirements is supported through this method, for adding support for clicks with additonal platform_data, the mikrobus_spi driver needs to be modified. An example entry for the ETH Click based on the enc28j60 driver is shown below:
"eth": {
"type": "spi",
"class": "platform",
"driver": "enc28j60",
"speed": "16000000",
"info": [
"ETH Click",
"usage information"
]
}
Here the key for the entry is the name of the click eth
, this name will be available with the insclick/rmclick commands.The other entries are:
-
type
: corresponds to the type of bus the click uses (currently SPI/I2C) -
class
: corresponds to the class of the click, in this case class->platform as additonal platform data is required, the available options are : oridnary/platform/display -
driver
: corresponds to the name of linux driver available for the click device -
speed
: corresponds to the SPI Bus Speed (Hz) -
info
: this section contains the helping information for the user to get started with the Click
The insclick
and rmclick
utilities make it easier for users to try out clickboards with linux kernel driver support easily from the userspace for making it easier for trying out click board suppport, insclick/rmclick
methods has been added to bonescript which has the following template :
var b = require('bonescript);
b.insclick(clickname,port, insclickcallback);
function insclickcallback(err,data) {
}
b.rmclick(clickname,port, rmclickcallback);
function rmclickcallback(err,data) {
}
The version of bonescript with the following changes can be tried out by :
sudo npm install --unsafe-perm -g vaishnav98/bonescript
Makecode Beaglebone is a Beta version blocks based experimental code editor for Beaglebone boards which uses bonescript RPC server running on the board to interact with the board ( the simulator only versions of the editor can be tried out on the browser here). The insclick/rmclick
blocks for Beaglebone Makecode has been added to support click boards:
Once the click is loaded, then operations on the device can be performed by simple file read/write operations,
sudo npm install -g pxt
git clone https://github.com/vaishnav98/pxt-beaglebone.git
cd pxt-beaglebone
npm install
pxt serve
- GBSIM Exit Issue : The Greybus Simulator when interrupted does not exit cleanly (GBSIM ISSUE #3)
- Two Clicks both of the display category or platform category will not work together, currently separate kernel modules like fbtft_device and mikrobus_device are used to instantiate the devices with additional platform data which can handle only a single device at a time
- Beaglebone Black Mikrobus Cape Port 4 does not work for SPI Clicks, these ports has GPIOs as SPI_CS and thus requires a separate device tree overlay for the corresponding spidev entries to appear.
I would like to thank all the Mentors and Org Admins under BeagleBoard.org Foundation, specially Jason Kridner for the continued support and guidance to improve the project.I would also like to thank Matt Porter(mdp), Christopher Friedt(cfriedt) and Greg KH from the community for their suggestions and support.This project has been a wonderful learning experience for me, some of the goals of the project has not been achieved completely and I hope to contribute to achieve those goals after GSoC.Also would like to thank Google for putting up such a wonderful opportunity for students.
- Project Proposal
- Weekly Project Report Thread
- Greybus Dev Mailing List Thread
- GBSIM Techlab Cape Examples
- Beaglebone Makecode
- Beaglebone Makecode Clickboards +Techlab Cape Examples Demonstration Video
- GBSIM Techlab Cape Examples Demonstration Video
- PocketBeagle I2C Click Demonstration Video
- Beaglebone Black I2C Click Demonstration Video
- IRC nickname: vaishnav98_ (#beagle-gsoc, #beagle)