BeagleBoard.org BeagleBone Relay Cape#
Relay Cape, as the name suggests, is a simple Cape with relays on it. It contains four relays, each of which can be operated independently from the BeagleBone.
Note
The following describes how to use the device tree overlay under development. The description may not be suitable for those using older firmware.
Installation#
No special configuration is required. When you plug the Relay Cape into your BeagleBoard, it will automatically be recognized by the Cape Universal function.
You can check to see if the Relay Cape is recognized with the following command.
ls /proc/device-tree/chosen/overlay
A list of currently loaded device tree overlays is displayed here. If you see BBORG_RELAY-00A2.kernel in this list, it has been loaded correctly.
If it is not loaded correctly, you can also load it directly by adding the following to the U-Boot options (which can be reflected by changing the file /boot/uEnv.txt) to reflect the text below.
uboot_overlay_addr0=BBORG_RELAY-00A2.dtbo
Usage#
ls /sys/class/leds
The directory “relay1”, for instance, exists in the following directory. The LEDs can be controlled by modifying the files in its directory.
echo 1 > relay1/brightness
This allows you to adjust the brightness; entering 1 for brightness turns it ON while entering 0 turns it OFF.
The four relays can be changed individually by changing the number after “relay” in /sys/class/leds/relay.
Code to Get Started#
Currently, using sysfs in .c files, libgpiod-dev/gpiod in .c files, and python3 files with the Relay Cape work well!
For instance, a kernel that I found to work is kernel: 5.10.140-ti-r52
Another idea, an image I found that works is BeagleBoard.org Debian Bullseye Minimal Image 2022-11-01
There are newer images and kernels if you want to update and there are older ones in case you would like to go back in time to use older kernels and images for the Relay Cape. Please remember that older firmware will work differently on the BeagleBone Black or other related am335x SBC.
C Source with File Descriptors#
You can name this file GPIO.c and use gcc to handle compiling the source into a binary like so:
gcc GPIO.c -o GPIO
/*
This is an example of programming GPIO from C using the sysfs interface on
a BeagleBone Black/BeagleBone Black Wireless or other am335x board with the Relay Cape.
Use the Relay Cape attached to the BeagleBone Black for a change in seconds and then exit with CTRL-C.
The original source can be found here by Mr. Tranter: https://github.com/tranter/blogs/blob/master/gpio/part5/demo1.c
Jeff Tranter <jtranter@ics.com>
and...Seth. I changed the source a bit to fit the BeagleBone Black and Relay Cape while using sysfs.
*/
#include <errno.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
int main()
{
// Export the desired pin by writing to /sys/class/leds/relay1/brightness
int fd = open("/sys/class/leds/relay1/brightness", O_WRONLY);
if (fd == -1) {
perror("Unable to open /sys/class/leds/relay1/brightness");
exit(1);
}
fd = open("/sys/class/leds/relay1/brightness", O_WRONLY);
if (fd == -1) {
perror("Unable to open /sys/class/leds/relay1/brightness");
exit(1);
}
// Toggle LED 50 ms on, 50ms off, 100 times (10 seconds)
for (int i = 0; i < 100; i++) {
if (write(fd, "1", 1) != 1) {
perror("Error writing to /sys/class/leds/relay1/brightness");
exit(1);
}
usleep(50000);
if (write(fd, "0", 1) != 1) {
perror("Error writing to /sys/class/leds/relay1/brightness");
exit(1);
}
usleep(50000);
}
close(fd);
// And exit
return 0;
}
C Source with LibGPIOd-dev and File Descriptors#
Also…if you are looking to dive into the new interface, libgpiod-dev/gpiod.h, here is another form of source that can toggle the same GPIO listed from the file descriptor.
One thing to note: sudo apt install cmake
mkdir GPIOd && cd GPIOd
nano LibGPIO.c
add the below source into the file LibGPIO.c
/*
Simple gpiod example of toggling a LED connected to a gpio line from
the BeagleBone Black Wireless and Relay Cape.
Exits with or without CTRL-C.
*/
// This source can be found here: https://github.com/tranter/blogs/blob/master/gpio/part9/example.c
// It has been changed by me, Seth, to handle the RelayCape and BBBW Linux based SiP SBC.
// kernel: 5.10.140-ti-r52
// image : BeagleBoard.org Debian Bullseye Minimal Image 2022-11-01
// type gpioinfo and look for this line: line 20: "P9_41B" "relay1" output active-high [used]
// That line shows us the info. we need to make an educated decision on what fd we will use, i.e. relay1.
// We will also need to locate which chipname is being utilized. For instance: gpiochip0 - 32 lines:
// #include <linux/gpio.h>
#include <gpiod.h>
#include <stdio.h>
#include <unistd.h>
int main(int argc, char **argv)
{
const char *chipname = "gpiochip0";
struct gpiod_chip *chip;
struct gpiod_line *lineLED;
int i, ret;
// Open GPIO chip
chip = gpiod_chip_open_by_name(chipname);
if (!chip) {
perror("Open chip failed\n");
return 1;
}
// Open GPIO lines
lineLED = gpiod_chip_get_line(chip, 20);
if (!lineLED) {
perror("Get line failed\n");
return 1;
}
// Open LED lines for output
ret = gpiod_line_request_output(lineLED, "relay1", 0);
if (ret < 0) {
perror("Request line as output failed\n");
return 1;
}
// Blink a LED
i = 0;
while (true) {
ret = gpiod_line_set_value(lineLED, (i & 1) != 0);
if (ret < 0) {
perror("Set line output failed\n");
return 1;
}
usleep(1000000);
i++;
}
// Release lines and chip
gpiod_line_release(lineLED);
gpiod_chip_close(chip);
return 0;
}
mkdir build && touch CMakeLists.txt
In CMakeLists.txt, add these values and text via nano or your favorite editor!
cmake_minimum_required(VERSION 3.22)
project(gpiod LANGUAGES C)
add_executable(LibGPIO LibGPIO.c)
target_link_libraries(LibGPIO gpiod)
cd build && cmake ..
make
./LibGPIO
These are a few examples on how to use the RelayCape and am335x supported BeagleBone Black Wireless/BeagleBone Black SBCs.