Testing the serial port

To get to know how to access serial devices I decided to write some simple test code. I connected an Arduino board to the UART1 port of BeagleBone Black as seen here.

Wiring Arduino and BBB


To enable the UART1 port I opened /etc/default/capemgr in vim and added the following line to the bottom:

vim /etc/default/capemgr
# Options to pass to capemgr

enable uart ports on wheezy

To enable the UART1 port I opened /boot/uEnv.txt in vim and added the following line to the bottom:

vim /boot/uEnv.txt
##Enable UART ports

So tail gives the following:

##enable Generic eMMC Flasher:
##make sure, these tools are installed: dosfstools rsync

##Enable UART ports


Communicating through uart

I then wrote some Arduino code which sends 5000 messages to the UART port. On the BB I read the messages using the termios API (see man termios ) and write each message with a tag (time, date) to a file. Currently, everything works fine, but I think if there should arise any issues in terms of performance making the file writing and port reading asynchronously (possibly also using IO interrupts via SIGIO?) should give the whole process more performance.

The code can be found in my GSoC preparation repo


How to wire the Arduino to the BBB for testing purposes
Testing the serial port

Project Outline no.2

It’s been a while since I published my first project outline here. I talked to the project mentor, Michael Welling, and he was able to answer my questions related to the project goals. Using the PRUs is a bit oversized, there is no need at all for that. What I will try instead is to configure the UART driver so that he writes input data into a file. That file will be used as log file and can be accessed through the UI.

Did I say UI? Yeah, the last project outline didn’t show that. But a UI is definitively a part of the project and will ease the usage of the program. That way, people with a chronic command-line-phobia will also like to use the serial terminal server.

So what is this about now? Well, there is a UI, probably a web interface, provided by the BeagleBone. This interface will be accessed by a PC and allow the user to access and manage serial devices connected via UART to the board. As you can imagine, there will be something like a middleware needed to connect the web interface to the serial ports. Additionally, all I/O will be logged and will be accessible through the interface.

I created the following component diagrams which show the scope for each stage of the project. I divided it into 3 stages. Stage 1 will be the one which I will definitively implement during GSoC. It includes basic functionality and fulfills the project’s goals. Stage 2 extends the scope and could also fit into the 12 week timeline, depending on my progress with Stage 1. in contrast, Stage 3 will probably be difficult to implement completely during the summer as it introduces a set of extra features which will consume much time to implement. Note that each stage will be divided into several milestones.

stage 1

Basic functionality designed to be extended easily

I payed attention to hide implementation details behind interfaces which allow for easy access, use and extension of single components. I want to make it easier to both include new serial devices (I2C, SPI, etc.) as well as including new features into the terminal server or UI (e.g. see Stage 3).

Features introduced in this stage:

  • set up serial UART connections through UI
  • edit baud rate, parity bit
  • send messages to devices
  • read current messages from devices
  • log input for each UART device along with a timestamp in a file
  • packaging everything into an image (not exactly a feature, but also a goal)

I am still looking for what’s the best solution to connect the terminal server with the client, but probably it would make sense to include Stage 2 which adds an HTML interface:

Stage 2

Expose HTTP interface to clients/network

This basically prepares the project for Stage 3. As pretty much everything can use HTTP interfaces, it makes sense to me to add this interface to the web server. Client applications now also have the option to use the HTTP interface and thus will not need any dependencies to the serial management.

Additional features introduced with this stage:

  • HTTP interface exposed to the network

Stage 3

More features

Additional features introduced with this stage:

  • automation rules (e.g. automatically send a mail when an event occurs)
  • tunneling to interconnect serial devices
  • pattern matching
  • upload log to external server/host pc
  • hexadecimal viewer

These functions are regarded as “stretch goals”. I might be able to implement some parts during the summer, but most of it will probably wait until past GSoC. As I really like these ideas I have also personal interest in implementing them even after GSoC ends, so stay tuned.
I also created a draft which showed how the architecture would look like if I implemented an additional server ( / socket) in C. That server would be responsible for all features introduced with Stage 2 and Stage 3. Yet, that would nearly double the complexity of the project. Using C for the web server means that there are in fact two web servers running: One to provide a backend to the web interface and the other one for tunneling and the automation rules stuff. Note that here we would also need an API which would allow other servers to access our server.. To my mind, if you really need something like this you could use the C-Library within your solution, but for the GSoC project it will make much more sense to just use the web server for all this stuff. Plus, it fits better into the timeline as I’m faster with JavaScript.

Past Stage 3 we can include more serial interfaces like I mentioned before. Due to the HTTP interface, also IoT applications can build up on this project or we can use the C-Library to access serial devices without going through the hassle of using device nodes. Adding a cape to turn the BeagleBone physically into a serial terminal server and including it into the library can be another task.

I guess some of the library functionality already exists inside of other projects out there, I will see if I find something useful. Same applies to the web server component.

Project Outline no.2

How does UART work under the hood?

This is a short summary about how UART works as the serial terminal server project focuses on UART devices. First of all, UART means Universal Asynchronous Receiver Transmitter. This tells us that receiving and transmitting data all happens without a clock.

The protocol

When the UART is idle the output is HIGH. So when there is no data transmitted you will always read HIGH from the UART pins. Then, when a signal is transmitted, the pin is pulled down to LOW to indicate that data is transmitted. This is our start bit. Then we can transmit 8 data bits followed by a stop bit. Its value is HIGH. In total, there are 10bits which are sent in one package. Also note that transmitted values are passed less significant bit first.

In order to read the transmitted data you need to know the baud rate as UART is baud rate based. Transmitter and receiver use the baud rate for synchronization: Having a baud rate of 9600 corresponds to 9600 bits per second. As one package consists of 10 bits we thus receive 960 data bytes per second (or 960 packages per second). For one message, we thus have 1042µs. If we divide this number by 10, we know that one bit takes 104.2µs This timing can now be used to decode each message transmitted via UART.

Let’s look at an example: With a baud rate of 115200 we have 1/115200 = 8.68µs per bit. If we transfer the number 0x03 which is 0b00000011 in binary we get the following time chart:

.........X  XXXXXXX                 XXXX......
   HIGH  X  X     X                 X
         X  X     X                 X
         X  X     X                 X
         X  X     X                 X
         X  X     X                 X
         X  X     X                 X
   LOW   X  X     X                 X
*idle* start 1  1  0  0  0  0  0  0  end *idle*
       bit                           bit

In reality

When it comes to communication between two micro controllers you have also pay attention to exact timing. If data transmitted is off too much from the specified baud rate you won’t be able to read the message. If you have a 2MHz oscillator (FOSC) and transmit messages using high speed you surely have already seen the formula

FOSC / (16*(SPBRG + 1))

Here, SPBRG is a value saved in the corresponding register which ultimately determines which baud rate is used. With SPBRG=51in the current example we get a baud rate of 9615.38 out of the formula above. So our controller is off by 15.38 bits per second, the amount of error is 0.16%. Of course, you want this error to be as small as possible.

Error detection

If you like to have a parity bit you can reduce the 8 data bits to 7 data bits and use the MSB as parity bit. That way, you can notice one bit errors.

After all, UART is a technology which is existing now for a long time. You won’t get a very large transfer rate but there are still many devices which use this protocol as it is duplex, asynchronous and easy to integrate.

How does UART work under the hood?

Project Draft No.1

After chatting on IRC with some other students I was able to better understand the Serial Terminal Server project, its goals, requirements and complexity. I think that I’m definitively going to apply for that project, so I ordered a BeagleBone Black now. Since I have no experience with BeagleBone, RaspberryPi and similar boards I think that exploring the BeagleBone Black before starting to code is a good idea. I already thought of some solutions, one of them is shown in the sketch below which involves the PRUs for buffering I/O data. I checked out the BegleScope project from ZeekHuge which also uses the PRUs for buffering, so that might help me in getting some ideas. A slightly different solution I came up with was to use DMA to transfer data from the PRUs (or maybe directly from the UART pins) into the I/O buffer. Yet, this attempt seems to cause people some headaches, as some have already tried it and did not succeed. I will focus for now on using the PRUs along with RPMsg for communication with the A8 and let the PRUs write the buffers.

First architecture draft

Open questions on which I will focus on now are:

  • How will communication between the two PRUs happen?
  • Is there a better solution than passing commands through all instances or can we make calls directly to the UART device?
  • How can multiple UART devices be monitored without loosing inputs?
  • Is the driver really the right instance to copy the PRUs buffer to the sd card or should this task be done by another instance?
  • Is there another solution which does not rely on the PRUs?

When talking to ZeekHuge it turned out that it should be possible to reuse and modify some of his code in order to buffer UART I/O. In the days to come I will check out more of his code and explore how to write drivers, how to write code for the PRUs and how to deploy everything so that it’s easy to set up.

Project Draft No.1