Enhancements

A better implementation would use a single gpioset process that continuously pulses the trigger GPIO at the required intervals, while a separate gpiomon process continuously monitors the echo GPIO and calculates the distances without needing to restart the gpioset command each time. This would avoid the “device or resource busy” errors and provide a more reliable measurement of distances. This is quite possible, but would need to synchronise the two processes to achieve full throughput, which is a bit more complex to implement in a single command line. It would likely require some form of inter-process communication (e.g., using named pipes or shared memory) to coordinate the timing between the trigger and echo measurements.

Line Abstractions

The GPIO library lets developers access GPIO lines on Linux systems. Its abstractions include line settings, line configurations and request configurations. The Figure below shows the relationships between these abstractions.

Figure 1: GPIO Library Abstractions

The diagram simplifies the names, specifically by omitting the gpiod_ prefix. It also elides the argument types for brevity. The library’s documentation provides the full details. Nevertheless, it shows that “line requests” sit at the centre of the abstraction hierarchy. A line request is a collection of line settings, which in turn are collections of line configurations. Edge-event buffers load edge events from the kernel via line requests.

Notice that edge events carry a nanosecond timestamp. This is the time at which the kernel detected the edge. The kernel’s GPIO module uses the system clock to timestamp the event. There may be some latency between the actual edge and the timestamp, but it is likely negligible for ECHO pulse measurements, which are on the order of microseconds.

Scanning for Chips

GPIO “chips” represent the GPIO controller hardware. You open a chip using its character device file, e.g. /dev/gpiochip0. But this implies that you know the chip’s device path; otherwise, scan for chips.

Fortunately, the C standard library provides a function to scan directories. The standard scandir() function reads the contents of a directory and returns a list of directory entries. You can use this function to scan the /dev directory for GPIO chip device files. It takes a filter function to select only the entries that match the desired pattern, such as gpiochip*. The following code snippet demonstrates how to scan the /dev directory, or any specified directory, for GPIO chip device files and return their paths.

ssize_t scan_dir_for_gpiochip_paths(const char *dir, char ***paths) {
  /*
   * Filter closure for scandir to find GPIO chip devices. This lambda-like
   * function will be called for each entry in the directory, and it will return
   * 1 if the entry is a GPIO chip device, and 0 otherwise. The function will
   * use gpiod_is_gpiochip_device to check if the entry is a GPIO chip device,
   * and it will also filter out symlinks to avoid false positives. Note that
   * this also means that GPIO chip devices that are symlinks will be ignored,
   * but this is a reasonable trade-off.
   *
   * This is a GNU-compiler extension that allows us to define a function inside
   * another function, and it can capture variables from the enclosing function.
   * In this case, it captures the dir variable from the enclosing
   * scan_dir_for_gpiochip_paths function, which is used to construct the full
   * path of the entry for the gpiod_is_gpiochip_device check. This allows the
   * scan operation to avoid having to pass the dir variable as an argument to
   * the filter function, and it keeps the code more concise and easier to read.
   * However, this is not standard C, and it may not be supported by all
   * compilers, so it should be used with caution if portability is a concern.
   */
  int gpiochip_device_filter(const struct dirent *entry) {
    char *path;
    if (dir_entry_path(dir, entry, &path) < 0) {
      return 0;
    }
    struct stat st;
    if (lstat(path, &st) < 0 || S_ISLNK(st.st_mode)) {
      free(path);
      return 0;
    }
    const int rc = gpiod_is_gpiochip_device(path);
    free(path);
    return rc;
  }
  struct dirent **entries;
  ssize_t num_entries = scandir(dir, &entries, gpiochip_device_filter, NULL);
  if (num_entries < 0) {
    return num_entries;
  }

  /*
   * Create an array of strings to store the paths of found GPIO chip devices.
   * The caller is responsible for freeing this array using free_gpiochip_paths.
   * The caller should use the returned number of found GPIO chip devices to
   * determine how many paths are in the array. If an error occurs while
   * creating the array of paths, the function will free any allocated memory
   * and return -1.
   */
  char **found = malloc((num_entries + 1) * sizeof(char *));
  if (!found) {
    free_dir_entries(entries, num_entries);
    return -1;
  }
  ssize_t num_found = 0;
  for (ssize_t i = 0; i < num_entries; i++) {
    char *path;
    if (dir_entry_path(dir, entries[i], &path) < 0) {
      free_gpiochip_paths(found, num_found);
      free_dir_entries(entries, num_entries);
      return -1;
    }
    found[num_found++] = path;
  }
  free_dir_entries(entries, num_entries);

  /*
   * Null-terminate the array of found paths. This is not strictly necessary,
   * but it can be useful for debugging and for certain use cases where the
   * caller may want to iterate over the array of paths without knowing the
   * number of paths in advance. The caller should still use the returned number
   * of found GPIO chip devices to determine how many paths are in the array,
   * and should not rely on the null-termination to determine the end of the
   * array. If the caller does not want the null-termination, it can simply
   * ignore the last element of the array.
   */
  found[num_found] = NULL;
  if (paths) {
    *paths = found;
  } else {
    free_gpiochip_paths(found, num_found);
  }
  return num_found;
}

You will notice some missing pieces in the code snippet above. The dir_entry_path() function constructs the full path of a directory entry by concatenating the directory path and the entry name. The free_dir_entries() function frees the memory allocated for the directory entries returned by scandir(). The free_gpiochip_paths() function frees the memory allocated for the array of paths returned by scan_dir_for_gpiochip_paths(). These functions are not shown here, but they are straightforward to implement.

Edge Event Generator Pattern

The GPIO library provides a way to read edge events from GPIO lines, but it requires some setup and configuration. Reading edges, rising and falling, requires a pattern that is not immediately obvious.

A GPIO edge buffer has a limited capacity. Given a GPIO line request, a buffer read operation will return a number of events up to the buffer’s capacity. What happens if the request accumulates more events than the buffer can hold? After processing the first batch of events, the buffer needs refilling. The event processor repeats the refill until either (1) the process has seen all the available events, or (2) some error occurs.

struct gpio_edge_event_generator {
  struct gpiod_line_request *request;     /*!< The GPIO line request to read edge events from. */
  struct gpiod_edge_event_buffer *buffer; /*!< The buffer used to store edge events read from the request. */
  size_t max_events;                      /*!< The maximum number of edge events to generate. */
  int num_events;                         /*!< The number of edge events generated. */
  unsigned long index;                    /*!< The current index in the edge event buffer. */
};

void gpio_edge_event_generator_init(struct gpio_edge_event_generator *generator /* generator to initialise */,
                                    struct gpiod_line_request *request /* request to read edge events from */,
                                    struct gpiod_edge_event_buffer *buffer /* buffer to store edge events */,
                                    size_t max_events /* maximum number of edge events to generate */) {
  generator->request = request;
  generator->buffer = buffer;
  generator->max_events = max_events;
  generator->num_events = 0;
  generator->index = 0;
}

int gpio_edge_event_generator_next(struct gpio_edge_event_generator *generator, struct gpiod_edge_event **event) {
  if (!generator || !event) {
    return -1;
  }
  if (generator->index >= generator->num_events) {
    if (generator->max_events == 0) {
      return 0;
    }
    const size_t capacity = gpiod_edge_event_buffer_get_capacity(generator->buffer);
    const size_t max_events = generator->max_events < capacity ? generator->max_events : capacity;
    if (max_events == 0) {
      return 0;
    }
    generator->num_events = gpiod_line_request_read_edge_events(generator->request, generator->buffer, max_events);
    if (generator->num_events <= 0) {
      return generator->num_events;
    }
    generator->index = 0;
    generator->max_events -= (size_t)generator->num_events;
  }
  *event = gpiod_edge_event_buffer_get_event(generator->buffer, generator->index);
  if (!*event) {
    return -1;
  }
  generator->index++;
  return 1;
}

Printing Pulse Widths to Standard Output

Print pulse widths to standard output:

hc-sr04 --echo GPIO8 --trig GPIO11

Sending Readings to Redis Stream

Send readings to Redis Stream hc-sr04 on localhost:

hc-sr04 --echo GPIO8 --trig GPIO11 --host 127.0.0.1

With explicit Redis port and stream max length:

hc-sr04 --echo GPIO8 --trig GPIO11 --host 127.0.0.1 --port 6379 --maxlen 1000

Read the stream in another terminal:

redis-cli XREAD BLOCK 0 STREAMS hc-sr04 $

Each stream entry includes:

• pulse_width_ns field whose value encodes, in decimal, the ECHO pulse width in nanoseconds.

The program emits pulse width, not distance. This is by design. Translation of pulse width to distance depends on temperature and humidity, which are not known to the program.