This is the latest (main) BeagleBoard documentation. If you are looking for stable releases, use the drop-down menu on the bottom-left and select the desired version.

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.

../../_images/BeagleBoneRelayCapeA2-400x274.png

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 Cape into your BeagleBoard, it is automatically 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 /boot/uEnv.txt).

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, and entering 0 for 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 BBB 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 BBB 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 BBB 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

  1. mkdir GPIOd && cd GPIOd

  2. nano LibGPIO.c

  3. 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;
}
  1. mkdir build && touch CMakeLists.txt

  2. In CMakeLists.txt, add these values and text

cmake_minimum_required(VERSION 3.22)

project(gpiod LANGUAGES C)

add_executable(LibGPIO LibGPIO.c)

target_link_libraries(LibGPIO gpiod)
  1. cd build && cmake ..

  2. make

  3. ./LibGPIO

These are a few examples on how to use the RelayCape and am335x supported BBBW/BBB SBCs.