Chris Heydrick: Serial Hobbyist

If you do any searching for Cairo or GTK+ tutorials, you’ll eventually wind up on zetcode.com. I’d be content with only a fraction of this guy’s talent for explaining difficult subject matters with such brevity and clarity. It’s not coincidence that much of my code style matches his.

That said, his GTK+ and Cairo tutorials are a bit out of date. The migration from GTK+2 to GTK+3 was pretty dramatic. There is no longer an “expose-event” signal to trigger redrawing of a window. It’s been replaced by “draw”, and the prototype for the callback changed, too. I’ve been meaning to learn Cairo now that GTK+ is completely in bed with it, so I thought I’d tackle porting the fill and stroke example on zetcode.com to be GTK+3 compatible.

/* This is a GTK+3 ported version of the Basic Drawing
 * fill and stroke Cairo tutorial at zetcode.com
 * http://zetcode.com/tutorials/cairographicstutorial/basicdrawing/
 */

#include <stdio.h>
#include <stdlib.h>
#include <cairo.h>
#include <gtk/gtk.h>
#include <math.h>

gboolean on_draw_event (GtkWidget *widget, cairo_t *cr, gpointer user_data)
{
 /* http://stackoverflow.com/questions/8722084/using-cairo-with-gtk3 */

 cr = gdk_cairo_create(gtk_widget_get_window(widget));

 int width, height;
 gtk_window_get_size(GTK_WINDOW(widget), &width, &height);
 cairo_set_line_width(cr, 9);

 cairo_set_source_rgb(cr, 0.69, 0.19, 0);
 cairo_arc(cr, width/2, height/2, (width < height ? width : height) / 2 - 10, 0, 2 * M_PI);
 cairo_stroke_preserve(cr);

 cairo_set_source_rgb(cr, 0.3, 0.4, 0.6);
 cairo_fill(cr);

 cairo_destroy(cr);

 return FALSE;
}

int main (int argc, char *argv[])
{
 GtkWidget *window;

 gtk_init(&argc, &argv);

 window = gtk_window_new(GTK_WINDOW_TOPLEVEL);

 g_signal_connect(G_OBJECT(window), "draw", G_CALLBACK(on_draw_event), NULL);
 g_signal_connect(G_OBJECT(window), "destroy", G_CALLBACK(gtk_main_quit), NULL);

 gtk_window_set_position(GTK_WINDOW(window), GTK_WIN_POS_CENTER);
 gtk_window_set_default_size(GTK_WINDOW(window), 200, 150);

 gtk_widget_set_app_paintable(window, TRUE);
 gtk_widget_show_all(window);

 gtk_main();

 return 0;
}

No big deal here, only three changes required.

1) Change the signal connection

g_signal_connect(G_OBJECT(window), "expose-event", G_CALLBACK(on_expose_event), NULL);

to

g_signal_connect(G_OBJECT(window), "draw", G_CALLBACK(on_draw_event), NULL);

because there is no “expose-event” signal anymore.

2) Change the event callback prototype

on_expose_event (GtkWidget *widget, GdkEventExpose *event, gpointer data)

to

on_draw_event(GtkWidget *widget, cairo_t *cr, gpointer data)

and note that the names on_draw_event and on_expose_event are arbitrary. It’s common in most examples to name them as such.

3) In the draw event callback change

cr = gdk_cairo_create (widget->window);

to

cr = gdk_cairo_create(gtk_widget_get_window(widget));

because the window member is considered private now. You need to use the function gtk_widget_get_window() to get a pointer to the window.

I really want to get a grip on Cairo since it’s the new way forward in Gnome development. Porting the zetcode.com examples might help start me out.

I stumbled across this: http://stackoverflow.com/questions/7276797/reading-from-an-arduino-tty-with-file?rq=1

I’d very much like to subscribe to that guy’s newsletter.

Preface: Part 1 covered the sketch the Arduino will run for this example, and part 2 covered the resources and other people’s code I used to make sure everything works as expected. In part 3 I’m going to go through a small program that does exactly what I want: read serial data from the Arduino. Part 4 is here.

Part 3: Reading

I’ve had a tough time writing this part. One of the hardest lessons I’ve had to learn over the past few years of learning C is that there is never one way to do something, and of the multiple ways to do something there is often never one clear better way to do it.

My Arduino is sending “Hello World” once every second to my PC via a serial connection, and I want to read this and print it out on the PC. Should I write my program to wait until 12 characters are read? Should I wait until one second goes by and write whatever was in the buffer? Should I open the port to be blocking or non-blocking? Canonical or non-canonical?

There is no right answer, so I went with what I could make work in a sensible way. Since my data is always going to be 12 characters long, and it’s always going to come in at once per second, I decided to stick with something similar to Tod Kurt’s example with the exception that instead of looking for the newline character, I’ll use the VMIN control to get exactly 12 (or however many) characters from the serial buffer. IMPORTANT: This means that read() function will block (pause) until all 12 characters are received!

Here’s the program:

#include <stdio.h>
#include <stdlib.h>
#include <ioctl.h>
#include <fcntl.h>
#include <termios.h>

/* My Arduino is on /dev/ttyACM0 */
char *portname = "/dev/ttyACM"
char buf[256];

int main(int argc, char *argv[])
{
 int fd;

/* Open the file descriptor in non-blocking mode */
 fd = open(portname, O_RDWR | O_NOCTTY);

/* Set up the control structure */
 struct termios toptions;

 /* Get currently set options for the tty */
 tcgetattr(fd, &amp;amp;toptions);

/* Set custom options */

/* 9600 baud */
 cfsetispeed(&amp;amp;toptions, B9600);
 cfsetospeed(&amp;amp;toptions, B9600);
 /* 8 bits, no parity, no stop bits */
 toptions.c_cflag &= ~PARENB;
 toptions.c_cflag &= ~CSTOPB;
 toptions.c_cflag &= ~CSIZE;
 toptions.c_cflag |= CS8;
 /* no hardware flow control */
 toptions.c_cflag &= ~CRTSCTS;
 /* enable receiver, ignore status lines */
 toptions.c_cflag |= CREAD | CLOCAL;
 /* disable input/output flow control, disable restart chars */
 toptions.c_iflag &= ~(IXON | IXOFF | IXANY);
 /* disable canonical input, disable echo,
 disable visually erase chars,
 disable terminal-generated signals */
 toptions.c_lflag &= ~(ICANON | ECHO | ECHOE | ISIG);
 /* disable output processing */
 toptions.c_oflag &= ~OPOST;

/* wait for 12 characters to come in before read returns */
/* WARNING! THIS CAUSES THE read() TO BLOCK UNTIL ALL */
/* CHARACTERS HAVE COME IN! */
 toptions.c_cc[VMIN] = 12;
 /* no minimum time to wait before read returns */
 toptions.c_cc[VTIME] = 0;

/* commit the options */
 tcsetattr(fd, TCSANOW, &amp;amp;toptions);

/* Wait for the Arduino to reset */
 usleep(1000*1000);
 /* Flush anything already in the serial buffer */
 tcflush(fd, TCIFLUSH);
 /* read up to 128 bytes from the fd */
 int n = read(fd, buf, 128);

/* print how many bytes read */
 printf("%i bytes got read...\n", n);
 /* print what's in the buffer */
 printf("Buffer contains...\n%s\n", buf);

return 0;
}

It’s not that interesting to look at. I’ll try to explain it best I can – there are several key things that I’m shaky on that require further experimentation.

First up is declaring the headers, and a few constants, like the port name and the buffer I’ll be reading into. I picked 256 as the buffer size for no particular reason other than it’s bigger than I need.

#include <stdio.h>
#include <stdlib.h>
#include <sys/ioctl.h>
#include <fcntl.h>
#include <termios.h>

/* My Arduino is on /dev/ttyACM0 */
char *portname = "/dev/ttyACM0";
char buf[256];

In main() I declare an integer ‘fd’ to be the file descriptor that open() returns on the next line.

int fd;

/* Open the file descriptor in non-blocking mode */
 fd = open(portname, O_RDWR | O_NOCTTY);

I mentioned before that some things were still unknown to me. In Tod Kurt’s example he uses open() with one more option – O_NDELAY – which opens the port in non-blocking mode. I had some complications with this, so I removed it and magically my complications went away. Several iterations of this program ago I found that using non-blocking mode meant that read() wouldn’t wait until data was in the buffer to return, but instead of read() returning 0 it was returning -1. This wound up being because my Arduino was busy rebooting (which is does when you open the port) while read() was running. I added some delay and it worked fine, but then I couldn’t reconcile the implications of a non-blocking port and non-canonical input. I’ve been oscillating between thinking I had a grip on it and being completely confused, so I’ll tackle it another day.

Next is setting up the serial communications to our particular way of doing things. Terminal options are held in a termios structure, and it’s typical after declaring the structure (although not entirely necessary, I think) to then set it to the currently set options of the port.

/* Set up the control structure */
 struct termios toptions;

 /* Get currently set options for the tty */
 tcgetattr(fd, &toptions);

So now we have the structure toptions set to what currently is set on the tty port. The terminal command stty can show you what a port is set to, so I assume tcgetattr() does something similar and plugs it into the toptions structure.

The next part here is basically the same as Tod Kurt’s example, but it’s all pretty typical – the Unix programming book I’m referencing has something similar in the examples where you want the data coming at you in non-canonical raw mode. The comments explain what each line does. Some flags are grouped together for brevity – they don’t need to be like that (and they COULD all be lumped together).

/* 9600 baud */
 cfsetispeed(&toptions, B9600);
 cfsetospeed(&toptions, B9600);
 /* 8 bits, no parity, no stop bits */
 toptions.c_cflag &= ~PARENB;
 toptions.c_cflag &= ~CSTOPB;
 toptions.c_cflag &= ~CSIZE;
 toptions.c_cflag |= CS8;
 /* no hardware flow control */
 toptions.c_cflag &= ~CRTSCTS;
 /* enable receiver, ignore status lines */
 toptions.c_cflag |= CREAD | CLOCAL;
 /* disable input/output flow control, disable restart chars */
 toptions.c_iflag &= ~(IXON | IXOFF | IXANY);
 /* disable canonical input, disable echo,
 disable visually erase chars,
 disable terminal-generated signals */
 toptions.c_lflag &= ~(ICANON | ECHO | ECHOE | ISIG);
 /* disable output processing */
 toptions.c_oflag &= ~OPOST;

This was the first time I’d really had to set/unset options using bitwise operators (in a non-tutorial setting). It’s important to remember that it’s there for your convenience, and not meant to annoy. An alternative approach would be to have the termios structure have every individual option exist as a variable set to 0 or 1 in the structure, but for the sake of size and brevity (and because C doesn’t have a true bool type perhaps) it was done such that in the termios structure c_iflag, c_oflag, c_cflag, and c_lflag are all unsigned integers, and each of the 16 bits of the unsigned int represent a different option that can be set. Wikipedia helps explain what the & | and ~ do for us here.

VMIN and VTIME are important in non-canonical processing of serial data. There’s a fantastic explanation of how to best utilize them here, but we can take it in this example to mean that read() will wait for 12 characters to come in before returning.

/* wait for 24 characters to come in before read returns */
 toptions.c_cc[VMIN] = 24;
 /* no minimum time to wait before read returns */
 toptions.c_cc[VTIME] = 0;

So at this point the bits are set, but the serial driver doesn’t know it, so call tcsetattr().

/* commit the options */
 tcsetattr(fd, TCSANOW, &toptions);

All that setting happens nearly instantly after open() is called. It’s not very obvious, but when open is called a signal is sent via the serial port that the Arduino interprets as “reboot now”. There is a way around it on the Arduino end, but it’s easy enough to simply use usleep() to wait a bit before calling read().

/* Wait for the Arduino to reset */
 usleep(1000*1000);
 /* Flush anything already in the serial buffer */
 tcflush(fd, TCIFLUSH);
 /* read up to 128 bytes from the fd */
 int n = read(fd, buf, 128);

/* print how many bytes read */
 printf("%i bytes got read...\n", n);
 /* print what's in the buffer */
 printf("Buffer contains...\n%s\n", buf);

The last bits of code do the waiting for reboot, flushes what’s still in the serial buffer, reads into the buffer declared (obeying the VMIN rules already defined) and prints out what was received. If VMIN is changed from 12 to 24 you get “Hello World” twice. This makes sense so all is well.

So there is a minimal but functional example of reading serial data from an Arduino. Here are my remaining questions I want to answer someday.

1) Is tcgetattr() really necessary? What if I memset() the structure to 0 and only set what I want?

2) How much of what I set is really necessary? I’m only reading data so should I care about ECHO, ECHOE, or ISIG?

3) Why does Tod’s example work when using a non-blocking port, but mine doesn’t?

4) What’s the point of using a non-blocking port with non-canonical communication?

Some of these questions likely have very complicated answers. I know that there are functions for intelligently knowing when a serial port is ready (which would help with question 3 and 4). Question 1 and 2 simply require experimenting (which requires time).

Part 4 will take longer to come. I want to use what I’ve learned here to do something interesting with serial communication. I have a good project in mind, and I’m shooting for results and a writeup by mid-July. In the meantime I’m going to start learning about socket programming.

EDIT: Part 4 is here.

Edit: Part 3 and Part 4 of the writeup.

Preface: In Part 1 I covered the Arduino sketch that will output serial data to read on the PC it’s connected to. Next I’ll go over the resources I used to learn about terminal programming, and the only example I could find online of communicating with an Arduino in C.

Part 2: Information Resources

Serial communication in a Unix environment is handled through the terminal interface. This really threw me for a loop when I started researching this because I had figured reading and writing to a serial port would have its own separate set of functions unique to serial port interfacing. The “terminal” is the command line, right?

Well, it’s complicated. My keyboard is a device that sends characters into the computer to be interpreted and acted on. So is a printer. So is a modem. So is a device hooked up to the serial port (which at one time could be a printer/modem/keyboard/mouse). When you think about the long history you can forgive that the terminal interface became a bit of a catch-all over the years. The terminal I/O chapter of Advanced Programming in the Unix Environment starts off with “The handling of terminal I/O is a messy area, regardless of the operating system”.

Comforting, right?

My point is this – doing a search for how to read/write serial port data is going to give you a ton of results, and most aren’t going to be even remotely relevant to reading serial data from an Arduino.

There is one exception – Tod Kurt’s blog has an excellent write-up and fantastic example program for reading and writing serial data to/from an Arduino. The only “problem” with it is that it’s very flexible, uses command line toggles to get information, and has lots of code dedicated to parsing the info passed from the command line. What I’m saying is that it’s a great, flexible program and a wonderful example, but it’s super hard to tease out the important bits for someone new to terminal programming (like me). That being said, it’s exactly what you need to make sure you can compile to verify that it’s possible to use the terminal I/O API yourself.

Download the example program and compile it…

>>gcc arduino-serial.c -o arduino-serial

then run it, passing parameters that make sense for the sketch the Arduino is running…

>>./arduino-serial -b 9800 -p /dev/ttyACM0 -d 1500 -r

The passed parameters “-b 9800” means 9800 baud (which we defined in the sketch), “-p /dev/ttyACM0” sets the serial port to /dev/ttyACM0 (might be different for you), “-d 1500” means wait 1.5 seconds, and “-r” means read the serial data.

I’ll go into this more in the next part, but the delay is important. It provides a brief moment for the Arduino to reboot and start sending data.

If all goes well you should see the output “read: Hello World”. If the compile fails, it means you’ll have to figure out what libraries are missing on your machine. I don’t recall having to do anything special on mine (Ubuntu 12.04).

I recommend reading through the program Tod wrote. If you’re familiar enough with C and Unix programming it might be enough of an explanation for how to read/write serial data to an Arduino. The only reason it wasn’t enough for me is that I had a hard time seeing past all the code to parse the command line parameters, and didn’t know what all of the structures in the initialization function were doing.

Here are two other resources I’ve been using while learning about serial communication:

Serial Programming Guide for POSIX Operating Systems

Serial HOWTO

In part 3 I’ll go through writing (and explaining) a small program that uses the bare minimum to read “hello world” from the Arduino.

EDIT: Part 2, Part 3, and Part 4 of the writeup.

Preface: I bought an Arduino a few months ago. Many of the projects I want to tackle require that the Arduino send data to a computer through the serial link. There is a simple way of doing this in Python and Processing, but since I’m neck deep learning Unix programming in C I figured I should stick with it. This 4 (or 5) part guide will be the tutorial I wish I had come across a month ago.

Part 1: The Sketch

Before tackling reading serial data from an Arduino, you have to get the Arduino to output serial data. This guide will be assuming the following sketch is running on the Arduino.

void setup()

{

Serial.begin(9600);

}

void loop()

{

Serial.print("Hello World\n");

delay(1000);

}

It’s pretty simple. Once per second the string “Hello World” will be sent to the PC via the serial connection. Upload the sketch and verify that it’s working through the Serial Monitor tool in the Arduino IDE.

I recommend doing two more sanity checks.

First is to make sure you know what serial port the Arduino is on. In Linux it’s going to be something like /dev/ttyACM0 or /dev/ttyUSB0. Mine is the former. If you can successfully load the sketch then the Arduino IDE knows the right serial port, and the name is on the bottom right of the sketch window.

Second is to make sure that you can see the serial data in something other than the Arduino serial monitor. There is a neat tool called GNU Screen that can do this easily. My Arduino is attached to serial port /dev/ttyACM0 and the sketch is set to run at 9600 baud, so at the terminal I can type:

>>screen /dev/ttyACM0 9600

and I can see something similar (but not exactly identical) to the Arduino serial monitor. To exit screen type “ctrl-a \” without the quotes.

In part 2 I’ll cover compiling and using (what I believe is) the only example online of talking to an Arduino in C. It’s a robust program, but is very “general use” and confusing for someone like me that’s still getting a grip on Unix programming. I’m going to cover it because if you can get it to compile and then work we can write a simpler program that does the one thing we need it to do.

Some initial testing with setting up serial communication flummoxed me. I decided to work up a tool to give me a hand.

https://github.com/cheydrick/ssanity

Any evening you get to use the ternary operator is a good one, right? ssanity runs through all the macros in termios.h (almost all them… working on it) and checks to see if those flags are set in the termios structure. It’s not super complex – just a lot of this…

t->c_iflag & ICRNL ? printf("ICRNL: Set\n") : printf("ICRNL: Unset\n");

…over and over again. ICRNL is a flag that can be set, and that line will print out whether or not it is. I considered simply not having anything print out if it was unset, but I wanted to be more verbose.

So, now that I have a useful tool worked up I can likely make more effective attempts later this week! I’m having a good time. “Advanced Programming in the UNIX Environment” by Stevens and Rago is an absolute delight to read. I wish I had picked it up years ago. Its best feature is that it actually comes clean when something is complicated. It’s refreshing to know when something is supposed to be hard!

I’ve missed using Git in my day-to-day programming. It’s a wonderful way of focusing your attention to how your program is organized when more than one file is in play.

ssanity will need another pass for cleaning up and commenting, and I’m considering adding a few more things to check for the sake of completeness (despite the fact I won’t use them in my particular project). Ah – I need to remember to incorporate a makefile, too.

I really want to get a grip on serial communication. Step one is to set up something to read from or send to. I had hoped that it would be similar to how web servers worked – I can set up a web server on my local PC and then connect to it on the same PC. Very convenient for testing. I can’t find a way to set up a software process that emulates a serial port for me to send/receive data with. Lucky for me I have an Arduino Uno.

Here’s the Arduino sketch:

void setup() {
 // initialize the digital pin as an output.
 // Pin 13 has an LED connected on most Arduino boards:
 pinMode(13, OUTPUT);
 Serial.begin(9600);
 }

void loop() {
 digitalWrite(13, HIGH); // set the LED on
 Serial.println("Hello World");
 delay(1000); // wait for a second
 digitalWrite(13, LOW); // set the LED off
 delay(1000); // wait for a second
 }

This sketch blinks an LED on the Arduino breakout board and outputs serial data. I included the blinking as a way to confirm the chip is doing something. I hadn’t realized there’s an LED that blinks when it sends serial data so it wasn’t super necessary to do it myself. That’s ok.

Cool, so I uploaded the program to the chip and confirmed with the built in serial monitor that it’s outputting something. Now I want to see if I can “connect” to it (or “monitor”, not sure what the correct term is here) using some other program. I found a forum post that mentioned using a program called screen to do this. In the terminal I type:

>>screen /dev/ttyACM0 9600

And I do indeed get “Hello World” printed once every two seconds. The problem is that there  doesn’t seem to be a way to exit screen. Another search later and I popped open another terminal session and typed:

>>screen -ls

which told me the name of the screen session open, and I stopped it using:

>> screen -X -S 21044.pts-0.chris-Ubuntu1204 quit

I’m not sure what that did, exactly, but it worked.

My mission this morning is accomplished. I now have a device that outputs serial communication, and I should be able to now experiment with receiving that data. Once I get that working I’ll move on to sending data. The end goal is to send information over the serial line to the Arduino to control the program running on the chip itself.