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.

Real-Time I/O

Sometimes, when BeagleBone Black interacts with the physical world, it needs to respond in a timely manner. For example, your robot has just detected that one of the driving motors needs to turn a bit faster. Systems that can respond quickly to a real event are known as real-time systems. There are two broad categories of real-time systems: soft and hard.

In a soft real-time system, the real-time requirements should be met most of the time, where most depends on the system. A video playback system is a good example. The goal might be to display 60 frames per second, but it doesn’t matter much if you miss a frame now and then. In a 100 percent hard real-time system, you can never fail to respond in time. Think of an airbag deployment system on a car. You can’t even be 50 ms late.

Systems running Linux generally can’t do 100 percent hard real-time processing, because Linux gets in the way. However, the Bone has an ARM processor running Linux and two additional 32-bit programmable real-time units (PRUs Ti AM33XX PRUSSv2) available to do real-time processing. Although the PRUs can achieve 100 percent hard real-time, they take some effort to use.

This chapter shows several ways to do real-time input/output (I/O), starting with the effortless, yet slower JavaScript and moving up with increasing speed (and effort) to using the PRUs.

Note

In this chapter, as in the others, we assume that you are logged in as debian (as indicated by the bone$ prompt). This gives you quick access to the general-purpose input/output (GPIO) ports but you may have to use sudo some times.

I/O with JavaScript

Problem

You want to read an input pin and write it to the output as quickly as possible with JavaScript.

Solution

Reading the Status of a Pushbutton or Magnetic Switch (Passive On/Off Sensor) shows how to read a pushbutton switch and Toggling an External LED controls an external LED. This recipe combines the two to read the switch and turn on the LED in response to it. To make this recipe, you will need:

• Breadboard and jumper wires

• Pushbutton switch

• 220R resistor

• LED

Wire up the pushbutton and LED as shown in Diagram for wiring a pushbutton and LED with the LED attached to P9_14.

Fig. 289 Diagram for wiring a pushbutton and LED with the LED attached to P9_14

The code in Monitoring a pushbutton (pushLED.js) reads GPIO port P9_42, which is attached to the pushbutton, and turns on the LED attached to P9_12 when the button is pushed.

Listing 59 Monitoring a pushbutton (pushLED.py)

#!/usr/bin/env python
# ////////////////////////////////////////
# //	pushLED.py
# //	Blinks an LED attached to P9_12 when the button at P9_42 is pressed
# //	Wiring:
# //	Setup:
# //	See:
# ////////////////////////////////////////
import time
import os

ms = 50   # Read time in ms

LED="50"   # Look up P9.14 using gpioinfo | grep -e chip -e P9.14.  chip 1, line 18 maps to 50
button="7" # P9_42 mapps to 7

GPIOPATH="/sys/class/gpio/"

# Make sure LED is exported
if (not os.path.exists(GPIOPATH+"gpio"+LED)):
    f = open(GPIOPATH+"export", "w")
    f.write(LED)
    f.close()

# Make it an output pin
f = open(GPIOPATH+"gpio"+LED+"/direction", "w")
f.write("out")
f.close()

# Make sure button is exported
if (not os.path.exists(GPIOPATH+"gpio"+button)):
    f = open(GPIOPATH+"export", "w")
    f.write(button)
    f.close()

# Make it an output pin
f = open(GPIOPATH+"gpio"+button+"/direction", "w")
f.write("in")
f.close()

# Read every ms
fin  = open(GPIOPATH+"gpio"+button+"/value", "r")
fout = open(GPIOPATH+"gpio"+LED+"/value", "w")

while True:
    fin.seek(0)
    fout.seek(0)
    fout.write(fin.read())
    time.sleep(ms/1000)

pushLED.py

Listing 60 Monitoring a pushbutton (pushLED.js)

#!/usr/bin/env node
////////////////////////////////////////
//	pushLED.js
//	Blinks an LED attached to P9_12 when the button at P9_42 is pressed
//	Wiring:
//	Setup:
//	See:
////////////////////////////////////////
const fs = require("fs");

const ms = 500   // Read time in ms

const LED="50";   // Look up P9.14 using gpioinfo | grep -e chip -e P9.14.  chip 1, line 18 maps to 50
const button="7"; // P9_42 mapps to 7

GPIOPATH="/sys/class/gpio/";

// Make sure LED is exported
if(!fs.existsSync(GPIOPATH+"gpio"+LED)) {
    fs.writeFileSync(GPIOPATH+"export", LED);
}
// Make it an output pin
fs.writeFileSync(GPIOPATH+"gpio"+LED+"/direction", "out");

// Make sure button is exported
if(!fs.existsSync(GPIOPATH+"gpio"+button)) {
    fs.writeFileSync(GPIOPATH+"export", button);
}
// Make it an input pin
fs.writeFileSync(GPIOPATH+"gpio"+button+"/direction", "in");

// Read every ms
setInterval(flashLED, ms);

function flashLED() {
    var data = fs.readFileSync(GPIOPATH+"gpio"+button+"/value").slice(0, -1);
    console.log('data = ' + data);
    fs.writeFileSync(GPIOPATH+"gpio"+LED+"/value", data);
 }

pushLED.js

Add the code to a file named pushLED.js and run it by using the following commands:

bone$ chmod *x pushLED.js
bone$ ./pushLED.js
data = 0
data = 0
data = 1
data = 1
^C

Press ^C (Ctrl-C) to stop the code.

I/O with C

Problem

You want to use the C language to process inputs in real time, or Python/JavaScript isn’t fast enough.

Solution

I/O with JavaScript shows how to control an LED with a pushbutton using JavaScript. This recipe accomplishes the same thing using C. It does it in the same way, opening the correct /sys/class/gpio files and reading an writing them.

Wire up the pushbutton and LED as shown in Diagram for wiring a pushbutton and LED with the LED attached to P9_14. Then add the code in Code for reading a switch and blinking an LED (pushLED.c) to a file named pushLED.c.

Listing 61 Code for reading a switch and blinking an LED (pushLED.c)

////////////////////////////////////////
//	blinkLED.c
//	Blinks the P9_14 pin based on the P9_42 pin
//	Wiring:
//	Setup:
//	See:
////////////////////////////////////////
#include <stdio.h>
#include <string.h>
#include <unistd.h>
#define MAXSTR 100

int main() {
  FILE *fpbutton, *fpLED;
  char LED[] = "50";   // Look up P9.14 using gpioinfo | grep -e chip -e P9.14.  chip 1, line 18 maps to 50
  char button[] = "7"; // Look up P9.42 using gpioinfo | grep -e chip -e P9.42.  chip 0, line 7 maps to 7
  char GPIOPATH[] = "/sys/class/gpio";
  char path[MAXSTR] = "";

  // Make sure LED is exported
  snprintf(path, MAXSTR, "%s%s%s", GPIOPATH, "/gpio", LED);
  if (!access(path, F_OK) == 0) {
    snprintf(path, MAXSTR, "%s%s", GPIOPATH, "/export");
    fpLED = fopen(path, "w");
    fprintf(fpLED, "%s", LED);
    fclose(fpLED);
  }
 
  // Make it an output LED
  snprintf(path, MAXSTR, "%s%s%s%s", GPIOPATH, "/gpio", LED, "/direction");
  fpLED = fopen(path, "w");
  fprintf(fpLED, "out");
  fclose(fpLED);

  // Make sure bbuttonutton is exported
  snprintf(path, MAXSTR, "%s%s%s", GPIOPATH, "/gpio", button);
  if (!access(path, F_OK) == 0) {
    snprintf(path, MAXSTR, "%s%s", GPIOPATH, "/export");
    fpbutton = fopen(path, "w");
    fprintf(fpbutton, "%s", button);
    fclose(fpbutton);
  }
 
  // Make it an input button
  snprintf(path, MAXSTR, "%s%s%s%s", GPIOPATH, "/gpio", button, "/direction");
  fpbutton = fopen(path, "w");
  fprintf(fpbutton, "in");
  fclose(fpbutton);

  // I don't know why I can open the LED outside the loop and use fseek before
  //  each read, but I can't do the same for the button.  It appears it needs
  //  to be opened every time.
  snprintf(path, MAXSTR, "%s%s%s%s", GPIOPATH, "/gpio", LED,    "/value");
  fpLED    = fopen(path, "w");
  
  char state = '0';

  while (1) {
    snprintf(path, MAXSTR, "%s%s%s%s", GPIOPATH, "/gpio", button, "/value");
    fpbutton = fopen(path, "r");
    fseek(fpLED, 0L, SEEK_SET);
    fscanf(fpbutton, "%c", &state);
    printf("state: %c\n", state);
    fprintf(fpLED, "%c", state);
    fclose(fpbutton);
    usleep(250000);   // sleep time in microseconds
  }
}

pushLED.c

Compile and run the code:

bone$ gcc -o pushLED pushLED.c
bone$ ./pushLED
state: 1
state: 1
state: 0
state: 0
state: 0
state: 1
^C

The code responds quickly to the pushbutton. If you need more speed, comment-out the printf() and the sleep().

I/O with devmem2

Problem

Your C code isn’t responding fast enough to the input signal. You want to read the GPIO registers directly.

Solution

The solution is to use a simple utility called devmem2, with which you can read and write registers from the command line.

Warning

This solution is much more involved than the previous ones. You need to understand binary and hex numbers and be able to read the AM335x Technical Reference Manual.

First, download and install devmem2:

bone$ wget http://free-electrons.com/pub/mirror/devmem2.c
bone$ gcc -o devmem2 devmem2.c
bone$ sudo mv devmem2 /usr/bin

This solution will read a pushbutton attached to P9_42 and flash an LED attached to P9_13. Note that this is a change from the previous solutions that makes the code used here much simpler. Wire up your Bone as shown in Diagram for wiring a pushbutton and LED with the LED attached to P9_13.

Fig. 290 Diagram for wiring a pushbutton and LED with the LED attached to P9_13

Now, flash the LED attached to P9_13 using the Linux sysfs interface (Controlling GPIOs by Using SYSFS Entries). To do this, first look up which GPIO number P9_13 is attached to by referring to Mapping from header pin to internal GPIO number. Finding P9_13 at GPIO 31, export GPIO 31 and make it an output:

bone$ cd cd /sys/class/gpio/
bone$ echo 31 > export
bone$ cd gpio31
bone$ echo out > direction
bone$ echo 1 > value
bone$ echo 0 > value

The LED will turn on when 1 is echoed into value and off when 0 is echoed.

Now that you know the LED is working, look up its memory address. This is where things get very detailed. First, download the AM335x Technical Reference Manual. Look up GPIO0 in the Memory Map chapter (sensors). Table 2-2 indicates that GPIO0 starts at address 0x44E0_7000. Then go to Section 25.4.1, “GPIO Registers.” This shows that GPIO_DATAIN has an offset of 0x138, GPIO_CLEARDATAOUT has an offset of 0x190, and GPIO_SETDATAOUT has an offset of 0x194.

This means you read from address 0x44E0_7000 * 0x138 = 0x44E0_7138 to see the status of the LED:

bone$ sudo devmem2 0x44E07138
/dev/mem opened.
Memory mapped at address 0xb6f8e000.
Value at address 0x44E07138 (0xb6f8e138): 0xC000C404

The returned value 0xC000C404 (1100 0000 0000 0000 1100 0100 0000 0100 in binary) has bit 31 set to 1, which means the LED is on. Turn the LED off by writing 0x80000000 (1000 0000 0000 0000 0000 0000 0000 0000 binary) to the GPIO_CLEARDATA register at 0x44E0_7000 * 0x190 = 0x44E0_7190:

bone$ sudo devmem2 0x44E07190 w 0x80000000
/dev/mem opened.
Memory mapped at address 0xb6fd7000.
Value at address 0x44E07190 (0xb6fd7190): 0x80000000
Written 0x80000000; readback 0x0

The LED is now off.

You read the pushbutton switch in a similar way. Mapping from header pin to internal GPIO number says P9_42 is GPIO 7, which means bit 7 is the state of P9_42. The devmem2 in this example reads 0x0, which means all bits are 0, including GPIO 7. Section 25.4.1 of the Technical Reference Manual instructs you to use offset 0x13C to read GPIO_DATAOUT. Push the pushbutton and run devmem2:

bone$ sudo devmem2 0x44e07138
/dev/mem opened.
Memory mapped at address 0xb6fe2000.
Value at address 0x44E07138 (0xb6fe2138): 0x4000C484

Here, bit 7 is set in 0x4000C484, showing the button is pushed.

This is much more tedious than the previous methods, but it’s what’s necessary if you need to minimize the time to read an input. I/O with C and mmap() shows how to read and write these addresses from C.

I/O with C and mmap()

Problem

Your C code isn’t responding fast enough to the input signal.

Solution

In smaller processors that aren’t running an operating system, you can read and write a given memory address directly from C. With Linux running on Bone, many of the memory locations are hardware protected, so you can’t accidentally access them directly.

This recipe shows how to use mmap() (memory map) to map the GPIO registers to an array in C. Then all you need t o do is access the array to read and write the registers.

Warning

This solution is much more involved than the previous ones. You need to understand binary and hex numbers and be able to read the AM335x Technical Reference Manual.

This solution will read a pushbutton attached to P9_42 and flash an LED attached to P9_13. Note that this is a change from the previous solutions that makes the code used here much simpler.

Tip

See I/O with devmem2 for details on mapping the GPIO numbers to memory addresses.

Add the code in Memory address definitions (pushLEDmmap.h) to a file named pushLEDmmap.h.

Listing 62 Memory address definitions (pushLEDmmap.h)

// From: http://stackoverflow.com/questions/13124271/driving-beaglebone-gpio
// -through-dev-mem
// user contributions licensed under cc by-sa 3.0 with attribution required
// http://creativecommons.org/licenses/by-sa/3.0/
// http://blog.stackoverflow.com/2009/06/attribution-required/
// Author: madscientist159 (http://stackoverflow.com/users/3000377/madscientist159)

#ifndef _BEAGLEBONE_GPIO_H_
#define _BEAGLEBONE_GPIO_H_

#define GPIO0_START_ADDR 0x44e07000
#define GPIO0_END_ADDR   0x44e08000
#define GPIO0_SIZE (GPIO0_END_ADDR - GPIO0_START_ADDR)

#define GPIO1_START_ADDR 0x4804C000
#define GPIO1_END_ADDR   0x4804D000
#define GPIO1_SIZE (GPIO1_END_ADDR - GPIO1_START_ADDR)

#define GPIO2_START_ADDR 0x41A4C000
#define GPIO2_END_ADDR   0x41A4D000
#define GPIO2_SIZE (GPIO2_END_ADDR - GPIO2_START_ADDR)

#define GPIO3_START_ADDR 0x41A4E000
#define GPIO3_END_ADDR   0x41A4F000
#define GPIO3_SIZE (GPIO3_END_ADDR - GPIO3_START_ADDR)

#define GPIO_DATAIN 0x138
#define GPIO_SETDATAOUT 0x194
#define GPIO_CLEARDATAOUT 0x190

#define GPIO_03  (1<<3)
#define GPIO_07  (1<<7)
#define GPIO_31  (1<<31)
#define GPIO_60  (1<<28)
#endif

pushLEDmmap.h

Add the code in Code for directly reading memory addresses (pushLEDmmap.c) to a file named pushLEDmmap.c.

Listing 63 Code for directly reading memory addresses (pushLEDmmap.c)

// From: http://stackoverflow.com/questions/13124271/driving-beaglebone-gpio
// -through-dev-mem
// user contributions licensed under cc by-sa 3.0 with attribution required
// http://creativecommons.org/licenses/by-sa/3.0/
// http://blog.stackoverflow.com/2009/06/attribution-required/
// Author: madscientist159 (http://stackoverflow.com/users/3000377/madscientist159)
//
// Read one gpio pin and write it out to another using mmap.
// Be sure to set -O3 when compiling.
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <fcntl.h> 
#include <signal.h>    // Defines signal-handling functions (i.e. trap Ctrl-C)
#include "pushLEDmmap.h"

// Global variables
int keepgoing = 1;    // Set to 0 when Ctrl-c is pressed

// Callback called when SIGINT is sent to the process (Ctrl-C)
void signal_handler(int sig) {
    printf( "\nCtrl-C pressed, cleaning up and exiting...\n" );
	keepgoing = 0;
}

int main(int argc, char *argv[]) {
    volatile void *gpio_addr;
    volatile unsigned int *gpio_datain;
    volatile unsigned int *gpio_setdataout_addr;
    volatile unsigned int *gpio_cleardataout_addr;

    // Set the signal callback for Ctrl-C
    signal(SIGINT, signal_handler);

    int fd = open("/dev/mem", O_RDWR);

    printf("Mapping %X - %X (size: %X)\n", GPIO0_START_ADDR, GPIO0_END_ADDR, 
                                           GPIO0_SIZE);

    gpio_addr = mmap(0, GPIO0_SIZE, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 
                        GPIO0_START_ADDR);

    gpio_datain            = gpio_addr + GPIO_DATAIN;
    gpio_setdataout_addr   = gpio_addr + GPIO_SETDATAOUT;
    gpio_cleardataout_addr = gpio_addr + GPIO_CLEARDATAOUT;

    if(gpio_addr == MAP_FAILED) {
        printf("Unable to map GPIO\n");
        exit(1);
    }
    printf("GPIO mapped to %p\n", gpio_addr);
    printf("GPIO SETDATAOUTADDR mapped to %p\n", gpio_setdataout_addr);
    printf("GPIO CLEARDATAOUT mapped to %p\n", gpio_cleardataout_addr);

    printf("Start copying GPIO_07 to GPIO_31\n");
    while(keepgoing) {
    	if(*gpio_datain & GPIO_07) {
            *gpio_setdataout_addr= GPIO_31;
    	} else {
            *gpio_cleardataout_addr = GPIO_31;
    	}
        //usleep(1);
    }

    munmap((void *)gpio_addr, GPIO0_SIZE);
    close(fd);
    return 0;
}

pushLEDmmap.c

Now, compile and run the code:

bone$ gcc -O3 pushLEDmmap.c -o pushLEDmmap
bone$ sudo ./pushLEDmmap
Mapping 44E07000 - 44E08000 (size: 1000)
GPIO mapped to 0xb6fac000
GPIO SETDATAOUTADDR mapped to 0xb6fac194
GPIO CLEARDATAOUT mapped to 0xb6fac190
Start copying GPIO_07 to GPIO_31
^C
Ctrl-C pressed, cleaning up and exiting...

The code is in a tight while loop that checks the status of GPIO 7 and copies it to GPIO 31.

Tighter Delay Bounds with the PREEMPT_RT Kernel

Problem

You want to run real-time processes on the Beagle, but the OS is slowing things down.

Solution

The Kernel can be compiled with PREEMPT_RT enabled which reduces the delay from when a thread is scheduled to when it runs.

Switching to a PREEMPT_RT kernel is rather easy, but be sure to follow the steps in the Discussion to see how much the latencies are reduced.

• First see which kernel you are running:

bone$ uname -a
Linux breadboard-home 5.10.120-ti-r47 #1bullseye SMP PREEMPT Tue Jul 12 18:59:38 UTC 2022 armv7l GNU/Linux

I’m running a 5.10 kernel. Remember the whole string, 5.10.120-ti-r47, for later.

• Go to kernel update and look for 5.10.

Fig. 291 The regular and RT kernels

In The regular and RT kernels you see the reular kernel on top and the RT below.

• We want the RT one.

bone$ sudo apt update
bone$ sudo apt install bbb.io-kernel-5.10-ti-rt-am335x

Note

Use the am57xx if you are using the BeagleBoard AI or AI64.

• Before rebooting, edit /boot/uEnv.txt to start with:

#Docs: http://elinux.org/Beagleboard:U-boot_partitioning_layout_2.0

# uname_r=5.10.120-ti-r47
uname_r=5.10.120-ti-rt-r47
#uuid=
#dtb=

uname_r tells the boot loader which kernel to boot. Here we’ve commented out the regular kernel and left in the RT kernel. Next time you boot you’ll be running the RT kernel. Don’t reboot just yet. Let’s gather some latency data first.

Bootlin’s preempt_rt workshop looks like a good workshop on PREEMPT RT. Their slides say:

• One way to implement a multi-task Real-Time Operating System is to have a preemptible system

• Any task can be interrupted at any point so that higher priority tasks can run

• Userspace preemption already exists in Linux

• The Linux Kernel also supports real-time scheduling policies

• However, code that runs in kernel mode isn’t fully preemptible

• The Preempt-RT patch aims at making all code running in kernel mode preemptible

The workshop goes into many details on how to get real-time performance on Linux. Checkout their slides and labs. Though you can skip the first lab since we present a simpler way to get the RT kernel running.

Cyclictest

cyclictest is one tool for measuring the latency from when a thread is schduled and when it runs. The code/rt directory in the git repo has some scripts for gathering latency data and plotting it. Here’s how to run the scripts.

• First look in rt/install.sh to see what to install.

Listing 64 rt/install.sh

sudo apt install rt-tests
# You can run gnuplot on the host
sudo apt install gnuplot

rt/install.sh

• Open up another window and start something that will create a load on the Bone, then run the following:

bone$ time sudo ./hist.gen > nort.hist

hist.gen shows what’s being run. It defaults to 100,000 loops, so it takes a while. The data is saved in nort.hist, which stands for no RT histogram.

Listing 65 hist.gen

#!/bin/sh
# This code is from Julia Cartwright julia@kernel.org

cyclictest -m -S -p 90 -h 400 -l "${1:-100000}"

rt/hist.gen

Note

If you get an error:

Unable to change scheduling policy! Probably missing capabilities, either run as root or increase RLIMIT_RTPRIO limits

try running ./setup.sh. If that doesn’t work try:

bone$ sudo bash
bone# ulimit -r unlimited
bone# ./hist.gen > nort.hist
bone# exit

• Now you are ready to reboot into the RT kernel and run the test again.

bone$ reboot

• After rebooting:

bone$ uname -a
Linux breadboard-home 5.10.120-ti-rt-r47 #1bullseye SMP PREEMPT RT Tue Jul 12 18:59:38 UTC 2022 armv7l GNU/Linux

Congratulations you are running the RT kernel.

Note

If the Beagle appears to be running (the LEDs are flashing) but you are having trouble connecting via ssh 192.168.7.2, you can try connecting using the approach shown in Viewing and Debugging the Kernel and u-boot Messages at Boot Time.

Now run the script again (note it’s being saved in rt.hist this time.)

bone$ time sudo ./hist.gen > rt.hist

Note

At this point yoou can edit /boot/uEnt.txt to boot the non RT kernel and reboot.

Now it’s time to plot the results.

bone$ gnuplot hist.plt

This will generate the file cyclictest.png which contains your plot. It should look like:

Fig. 292 Histogram of Non-RT and RT kernels running cyclictest

Notice the NON-RT data have much longer latenices. They may not happen often (fewer than 10 times in each bin), but they are occurring and may be enough to miss a real-time deadline.

The PREEMPT-RT times are all under a 150s.

I/O with simpPRU

Problem

You require better timing than running C on the ARM can give you.

Solution

The AM335x processor on the Bone has an ARM processor that is running Linux, but it also has two 32-bit PRUs that are available for processing I/O. It takes a fair amount of understanding to program the PRU. Fortunately, simpPRU is an intuitive language for PRU which compiles down to PRU C. This solution shows how to use it.

Background

simpPRU