2.2.1 Callback arguments

Above the callbacks just delivered one floating point value. However, often more than one sample or more complex data are transmitted:

• Complex data: do not put loads of arguments into the callback but define a struct. For example an ADC might deliver all 4 channels at once:

  class ADmulti {
  
          struct ADCSample {
              float ch1;
              float ch2;
              float ch3;
              float ch4;
          };
  
          ...
          virtual void hasSample(ADCSample& sample) = 0;
          ...
  };
  

  Depending on your application, you might consider the values not useful individually and therefore prefer a std::tuple.

• Arrays: Use arrays which contain the length of the arrays: either std::array, std::vector, etc or const arrays and then references to these so that the callback knows the length. For example the LIDAR callback uses a reference to a const length array:

  /**
   * Callback interface which needs to be implemented by the user.
   **/
  struct DataInterface {
          virtual void newScanAvail(
                  float rpm, 
                  A1LidarData (&)[A1Lidar::nDistance]) = 0;
  };
  

  Here A1Lidar::nDistance is a constant-expression giving the fixed array length, and (&)[A1Lidar::nDistance] a reference to a constant-length array which containing A1LidarData stucts. If you’re going to use types that hard to key-in often, typedef them.

In terms of memory management:

1. Low sampling rate complex data structures: allocate as a local variable. It can be a simple type or a struct. See dataReady() in: https://github.com/berndporr/LSM9DS1_RaspberryPi_CPP_Library/blob/master/LSM9DS1.cpp.

2. High sampling rate buffers: allocate memory on the heap in the constructor or in the private section of the class as a const length array and pass on a reference. See getData() in https://github.com/berndporr/rplidar_rpi.

2.3.1 Video camera capture (openCV)

while(running) {
    cv::Mat cap;
    videoCapture.read(cap);
    sceneCallback->nextScene(cap);
}

2.3.2 Audio (ALSA)

The standard framework for audio is alsa: https://github.com/alsa-project.

ALSA is packet based with a read command returning a chunk ("buffer") of audio and write emitting one. There are calls to set the sample format, sample rate, buffer size and so forth.

First, the parameters are requested and the driver can modify or reject them:

/* Signed 16-bit little-endian format */
  snd_pcm_hw_params_set_format(handle, params,
                               SND_PCM_FORMAT_S16_LE);

  /* One channel (mono) */
  snd_pcm_hw_params_set_channels(handle, params, 1);

  /* 44100 bits/second sampling rate (CD quality) */
  val = 44100;
  snd_pcm_hw_params_set_rate_near(handle, params,
                                  &val, &dir);

Then playing sound is done in an endless loop were a read() or write() command is issued. Both are blocking so that they guarantee event timing of audio both way.

 while (running) {
   if ((err = snd_pcm_readi (handle, buffer, buffer_frames)) != buffer_frames) {
     if (errCallback) errCallback->hasError();
   }
   if (sampleCallback) sampleCallback->hasData(buffer);
 }

For a full coding example “aplay” and “arecord” are a good start. Both can be found here: https://github.com/alsa-project.

2.3.3 Bluetooth

Bluetooth has also blocking I/O so that one can wait for incoming packets on a socket:

void run() {
        doRun = 1;
        while (doRun) {
                recv(btsocket, recvbuffer, sizeof(recvbuffer), 0);
                hasData(recvbuffer);
        }
};

Here the recv command blocks until new data has arrived.

2.3.4 General purpose I/O (GPIO)

GPIO pins are not just simple digital ports but they can be used to turn non-blocking I/O into blocking I/O, or in other words: events! SPI and I2C are only blocking for their read/write operations but they don’t know when new data is available at a sensor so one needs to connect the DATA-READY output of a sensor to a GPIO port which then feeds into blocking I/O.

gpiod_line_request_output(pinRed, "example1", 0);

gpiod_line_set_value(pinRed, 1);

int ret =
   gpiod_line_request_rising_edge_events(pinSwitch, "Consumer1");

void worker() {
    while (running) {
        constexpr struct timespec ts = { 1, 0 };
        gpiod_line_event_wait(pinSwitch, &ts);
        struct gpiod_line_event event;
        gpiod_line_event_read(pinSwitch, &event);
        event_callback();
    }
}

    gpiod_line_release(pinRed);

    gpiod_chip_close(chip);

2.3.5 SPI

SPI is a protocol which usually transmits and receives at the same time. Its calls are blocking for the duration of receive and transmit but cannot be used for event based processing. If an SPI device is used events should be transmitted via an additional GPIO line. Even though data might not be used it needs to be matched up, because the same clock is used to send and collect the data signal (it is isochronous). So if you send 8 bytes the hardware receives 8 bytes at the same time.

Transfer to/from SPI is best managed by the low level access to /dev. Open the SPI device with the standard open() function:

int fd = open( "/dev/spidev0.0", O_RDWR);

Then set the SPI mode (see table 2.1):

int ret = ioctl(fd, SPI_IOC_WR_MODE, &mode);

as explained, for example, here: https://www.analog.com/en/analog-dialogue/articles/introduction-to-spi-interface.html.

Because SPI is isochronous, read() and write() can’t be used to transmit and receive data. Instead, the simultaneous read and write is performed using an ioctl() to do the communication. Populate this struct:

struct spi_ioc_transfer tr {
  .tx_buf = (unsigned long)tx1,
  .rx_buf = (unsigned long)rx1,
  .len = ARRAY_SIZE(tx1),
  .delay_usecs = delay,
  .speed_hz = speed,
  .bits_per_word = 8,
};

which points to two character buffers “tx” and “rx” with the same length ¹ .

Reading and simultaneous writing then happens via this ioctrl() function call:

int ret = ioctl(fd, SPI_IOC_MESSAGE(1), &tr);

Sometimes the SPI protocol of a chip is so odd that even the raw I/O via /dev won’t work and you need to write your own bit banging interface, for example done here for the ADC on the alphabot: https://github.com/berndporr/alphabot/blob/main/alphabot.cpp#L58. This is obviously far from ideal as it might require usleep() commands so that acquisition needs to be run in a separate thread (the alphabot indeed uses a timer callback in a separate thread).

Overall the SPI protocol is often device dependent and calls for experimentation to get it to work. On some ADCs the SPI clock is also the conversion clock and a longer lasting clock signal sequence is required, making it necessary to transmit dummy bytes in addition to the payload.

As a general recommendation do not use SAR converters which use the SPI data clock also as acquisition clock as they are often not compatible with the standard SPI transfers via /dev. Use sensors or ADCs which have their own clock signal.

2.3.6 I2C

I2C is a protocol which either receives or transmits. Its I/O operations are blocking but only for the duration of receive or transmit. Use an additional GPIO pin for events for example for a data-ready event.

The I2C bus has two signal lines (SDA & SDL) which must be pulled up by resistors. Every I2C device has an address on the bus. You can scan a bus with i2cdetect (part of the i2c-tools package):

root@raspberrypi:/home/pi# i2cdetect -y 1
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:                         -- -- -- -- -- -- -- -- 
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- 1e -- 
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
50: -- -- -- -- -- -- -- -- 58 -- -- -- -- -- -- -- 
60: -- -- -- -- -- -- -- -- -- -- -- 6b -- -- -- -- 
70: -- -- -- -- -- -- -- --                         
root@raspberrypi:/home/pi# 

In this case there are 3 I2C devices on the I2C bus at addresses 1E, 58 and 6B and need to be specified when accessing the I2C device.

char buf[2];
int file = open("/dev/i2c-2",O_RDWR);
int addr = 0x58;
ioctl(file, I2C_SLAVE, addr);
write(file, buf, 1)
read(file, buf, 2)

unsigned 2c_readWord(uint8_t reg)
{
	uint8_t tmp[2];
	tmp[0] = reg;
	write(fd_i2c,&tmp,1);
        read(fd_i2c, tmp, 2);
        return (((unsigned)(tmp[0])) << 8) | ((unsigned)(tmp[1]));
}

void i2c_writeWord(uint8_t reg, unsigned data)
{
	uint8_t tmp[3];
	tmp[0] = reg;
	tmp[1] = (char)((data & 0xff00) >> 8);
	tmp[2] = (char)(data & 0x00ff);
	write(fd_i2c,&tmp,3);
}

2.3.7 Access to hardware via special devices in /sys

Some sensors are directly available via the sys filesystem in human readable format. For example

cat /sys/class/thermal/thermal_zone0/temp

gives you the temperature of the CPU.

2.3.8 Accessing physical memory locations (danger!)

Don’t. In case you really need to access registers you can also access memory directly. This should only be used as a last resort. For example, setting the clock for the AD converter requires turning a GPIO pin into a clock output pin. This is not yet supported by the drivers so we need to program registers on the RPI.

• Linux uses virtual addresses so that a pointer won’t point to a physical memory location. It points to three page tables with an offset.

• Special device /dev/mem allows access to physical memory.

• The command mmap provides a pointer to a physical address by opening /dev/mem.

• Example:

  int *addr;
  if ((fd = open("/dev/mem", O_RDWR|O_SYNC)) < 0 ) {
      printf("Error opening file. \n");
      close(fd);
      return (-1);
  }
  addr = (int *)mmap(0, num*STRUCT_PAGE_SIZE, PROT_READ, MAP_PRIVATE,
              fd, 0x0000620000000000);
  printf("addr: %p \n",addr);
  printf("addr: %d \n",*addr);
  

• Use this with care! It’s dangerous if not used properly.

3.3.1 Creating threads

In C++ a worker is a method within a class:

uthread = std::thread(&MyClassWithAThread::run, this);

where MyClassWithAThread is a class containing the function “run”:

class MyClassWithAThread {
        void run() {
                // ... hard work is done here
                doCallback(result); // hand the result over
        }
}

Note that the & signifies a functor, a method prototype. Instead of using functors you can also use a lambda function to call a method in the instance:

uthread = std::thread([this](){run();});

3.3.2 Lifetime of a thread

Threads terminate simply once the worker has finished its job. To tell the client that a thread has finished you can use a callback to trigger an event.

Sometimes it’s important to wait for the termination of the thread, for example when your whole program is terminating or when you stop an endless loop in a thread. To wait for the termination of the thread use the “join()” method:

        void stop() {
                uthread.join();
        }

In a realtime system join is most likely only needed when shutting down the program.

3.3.3 Running/stopping workers with endless loops

Threads with endless loops are often used in conjunction with blocking I/O which provide the timing:

void run() {
       running = true;
       while (running) {
              read(buffer); // blocking
              doCallback(buffer); // hand data to client
       }
}

Note the flag running which is controlled by the main program and is set to zero to terminate the thread:

        void stop() {
                running = false; // <----- HERE!!
                uthread.join();
        }

Note that join() is a blocking operation and needs to be used with care not to lock up the main program. You probably only need it when your program is terminating. See https://github.com/berndporr/rpi_AD7705_daq for an example.

If your program creates and joins several threads while executing, with care you might be able to design your program to allow an end-of-life thread to carry on tidying up in the background after you stop it by setting running = false;. In this case only need execute join() to be sure that the thread has finished. Joining a terminated thread is OK (the call just returns immediately) but you absolutely must not join a thread more than once, nor delete a thread until you’ve joined it.

3.3.4 Timing within threads

Threads are perfect to create timing without using sleep commands with the help of blocking I/O. Blocking I/O puts a thread to sleep and is woken up after new data has arrived or has been written to a device. Blocking I/O won’t consume any CPU power and is perfect to tell the kernel that it can execute other threads in the meantime.

void run() {
       running = 1;
       while (running) {
              read(buffer); // blocking
              doCallback(buffer); // hand data to client
       }
}

int flags = fcntl(fd, F_GETFL, 0);
fcntl(fd, F_SETFL, flags | O_NONBLOCK);

FD_ZERO(&rdset);
FD_SET(fd,&rdset);
struct timeval timeout;
timeout.tv_sec = 0;
timeout.tv_usec = 500000;
int ret = select(fd+1,&rdset,NULL,NULL,&timeout);
if (ret < 0) return ret;
// non-blocking I/O read
ret = read(fd,buffer,bytes_per_sample * n_chan);

4.2.1 Events from widgets

In contrast to our low level callback mechanism using interfaces, Qt rather directly calls methods in classes. The problem is that function pointers cannot be directly used as a class has instance pointers to its local data. So a method of a class needs to be combined with the instance pointer. The Qt method “connect” does exactly that:

connect(button, &QPushButton::clicked,
        this, &Window::reset);

The QPushButton instance button has a method called clicked() which is called whenever the user clicks on the button. This is then forwarded to the method reset() in the application Widget.

4.2.2 Plotting realtime data arriving via a callback

The general idea is to store the real-time samples from a callback in a buffer and trigger a screen refresh at a lower rate. For example, we may choose to replot the samples in the buffer every 40 ms because that fast enough for the user, whereas plotting the whole buffer every sample would be too CPU-intensive.

A callback addSample() is called in real-time whenever a sample has arrived:

void Window::addSample( float v ) {
    // add the new input to the plot
    std::move( yData, yData + plotDataSize - 1, yData+1 );
    yData[0] = v;
}

which stores the sample v in the shift buffer yData.

Then the screen refresh (which is slow) is done at a lower and unreliable rate:

void Window::timerEvent( QTimerEvent * )
{
    curve->setSamples(xData, yData, plotDataSize);
    plot->replot();
    thermo->setValue( yData[0] );
    update();
}

update() in the timer event-handler generates a paint event and Qt then invokes the repaint handler “as soon as possible” (which is to say, not in real-time) to repaint the canvas of the widget:

void ScopeWindow::paintEvent(QPaintEvent *) {
        QPainter paint( this );

        paint.drawLine( ... )
}

Note that neither the timer nor the update() function is called in a reliable way but whenever Qt chooses to do it. So Qt timers cannot be used to sample data but should only be used for screen refresh and other non-time-critical reasons.

5.3.1 Creating a Topic

Participant.create_topic is used to associate the topic with the data structure which will be passed to that topic’s subscribers. The example program calls it like this:

topic_ = participant_->create_topic("HelloWorldTopic",
                                    "HelloWorldMsg",
                                    TOPIC_QOS_DEFAULT);

5.3.2 Creating a Publisher and a Writer

Message senders and receivers are created by a factory class, Publisher. An instance of this class is required before any writers can be created. The Participant can build Publishers for us using its create_datawriter method. In the example program, it looks like this:

publisher_ = participant_->create_publisher(PUBLISHER_QOS_DEFAULT,
                                            nullptr);

and with that Publisher, we can create a DataWriter

writer_ = publisher_->create_datawriter(topic_,
                                        DATAWRITER_QOS_DEFAULT,
                                        &listener_);

5.3.3 Specifying the Writer’s callback function

listener_, the third argument to the create_datawriter method above, is an object implementing the callback interface spefied by the DataWriterListener class, specifically, the on_publication_matched method. In the example, the private class PubListener provides this functionality. When a subscriber registers to receive messages on the topic, this is the object which will be informed. As this is a minimalistic example, all that listener_ does is to maintain a thread-safe (“atomic”) integer which counts the number of subscribers as they connect and disconnect, and prints messages to the console as they do so. Refer to the source code in the example to see how it works.

5.3.4 Sending messages

Having packaged this all in a class we can finally implement the method which publishes a message. The code in the example sends the HelloWorldMsg referenced by hello if any listners are subscribed. If there is none, it immediately returns false; otherwise it sends the message then returns true.

class HelloWorldPublisher
{
    // ... the initialisation decribed above ... then
    
    //!Send a publication
    bool publish(HelloWorldMsg& hello)
    {
        if (listener_.matched_ > 0)
        {
            writer_->write(&hello);
            return true;
        }
        return false;
    }
}

6.4.1 Web servers (http/https)

• NGINX: Easy to configure but very flexible web server. Pronounced “Engine-X”.

• Apache: Hard to configure but safe option

• lighttpd: Smaller web server with a small memory footprint. Pronounced “lighty”.

Note that it’s possible to run different web servers at the same time where they then act as proxies for a central web server visible to the outside world. In particular nginx makes it very easy to achieve this.

6.4.2 FastCGI

FastCGI (see Fig 6.1) is written in C++ and generates the entire content of the http/https request. In particular here we generate JSON packets which can then be processed by client JavaScripts and vice versa. For realtime applications JSON transmission is perfect because the client-side JavaScript can request and receive JSON packages

A fast CGI program is a UNIX commandline program which communicates with the web server (nginx, Apache, …) via a UNIX socket which in turn is a pseudo file located in a temporary directory for example /tmp/sensorsocket.

The web server then maps certain http/https requests to this socket. An example configuration for nginx looks like this:

       location /sensor/ {
          include        fastcgi_params;
          fastcgi_pass   unix:/tmp/sensorsocket;
        }

If the user does a request via the URL www.mywebpage.com/sensor/ then nginx contacts the fastcgi program via this socket. The fastcgi program then needs to return the content. Internally this will be a C++ callback inside of the fastcgi program.

The C++ fastcgi API https://github.com/berndporr/fastcgi_json_cpp_api is wrapper around the quite cryptic fastcgi C library and we discuss its callback handlers now.

6.4.3 Server \(\to \) client

The fastCGI callback expects a JSON string (application/json) with the data transmitted form the server to the client. Use the jsoncpp library (standard debian/Ubuntu package) to create JSON.

class JSONcallback : public JSONCGIHandler::GETCallback {
public:
/**
* Gets the data and sends it to the webserver.
* The callback creates two JSON entries. One with the
* timestamp and an array of sensor readings.
**/
virtual std::string getJSONString() {
  Json::Value root;
  root["epoch"] = (long)time(NULL);
  Json::Value values;
  for(int i = 0; i < datasink->values.size(); i++) {
    values[i] = datasink->values[i];
  }
  root["values"]  = values;
  Json::StreamWriterBuilder builder;
  const std::string json_file = Json::writeString(builder, root);
  return json_file;
};

6.4.4 Client \(\to \) server: POST

Like in any GUI the client can press a button and create an event. Here, the server then receives the JSON data as a callback called “postArg”:

virtual void postString(std::string postArg) {
  const auto rawJsonLength = static_cast<int>(postArg.length());
  JSONCPP_STRING err;
  Json::Value root;
  Json::CharReaderBuilder builder;
  const std::unique_ptr<Json::CharReader> reader(builder.newCharReader());
  reader->parse(postArg.c_str(), postArg.c_str() + rawJsonLength, &root, &err)
  // do something with root
}

where root is a std::map.