The Tinyserial library

a tiny serial I/O library for Arduino boards

The Tinyserial library is a space-saving alternative to the Arduino software distribution's libraries for reading and writing characters and strings to the USART0 serial port on the Atmel ATmega168 and ATmega328p MCUs found on Arduino Diecimilla and Duemilanove boards.

While the Arduino software distribution's libraries provide interrupt-driven serial I/O with far more features and support more MCUs, the Tinyserial library provides only the most basic polling-based serial I/O. However, the Tinyserial library uses far less Flash and SRAM, thereby giving you room to implement larger and more complicated applications on your boards.

The Tinyserial library respects the GNU libc ABI, so you can call into it from C and C++ programs.

When should I consider using the Tinyserial library?

Specific consideration: When to use standard Arduino libraries: When to use the Tinyserial library:
Concurrency: If your program must perform other processing while waiting for user input, or while bytes are passing back in forth over the serial port, use the standard Arduino libraries, as they are interrupt-drivern. If it is OK if your program does nothing while waiting for user input or other serial I/O, then consider using Tinyserial.
Storing immutable data in Flash to save SRAM: If you want to store immutable data structures other than strings in Flash in order to save SRAM, use the standard Arduino Libraries. If you simply want to store immutable strings in Flash in order to save SRAM, then consider using Tinyserial.
Hardware support: If you are using an MCU other than the Atmel ATmega168 or -328p, you may still be able to use Tinyserial. However, if your MCU has more than one USART and you need to use more than one, you should use the standard Arduino Libraries as Tinyserial supports only one. If you are using an Arduino Diecimilla or Duemilanove, consider using the Tinyserial library.

How tiny is tiny?

Hello World programs built using the Tinyserial library consume an order of magnitude less Flash and SRAM than functionally equivalent Hello World programs built with the Arduino-0017 software distribution makefiles and libraries.

.text size
(Flash)
.data + .bss size
(SRAM)
Arduino-0017 Hello World (string in SRAM) 4358 bytes 196 bytes
Arduino-0017 Hello World (string in Flash) 4420 bytes 197 bytes
Tinyserial Hello World (string in SRAM) 244 bytes 16 bytes
Tinyserial Hello World (string in Flash) 260 bytes 0 bytes

The Hello World programs and Makefiles used for this comparison are included in the Tinyserial distribution.

Building the Tinyserial library

Follow these steps to build the Tinyserial library. These instructions should work on both Windows and UNIX-like platforms. These instructions describe how to build on the command line. You do not need the Arduino integrated development environment UI.

  1. First, you'll need to download and install the Arduino software distribution. Although the Tinyserial library does not depend on any of the libraries contained in this distribution, it does use some of the headers and avr-gcc tools. See http://arduino.cc.
  2. Put the directories containing the avr-gcc tool binaries into your PATH environment variable. In the arduno-0017 distribution, there were two directories:
  3. Make sure your Arduino software distribution has an avrdude.conf file. My Windows distribution of arduino-0017 did not; I had to download the GNU/Linux version of the arduino-0017 distribution and copy it from there.
  4. Modify the configuration.mk file provided in the Tinyserial distribution. See the instructions in that file.
  5. Type make to build the Tinyserial library and its test programs.

Building and deploying your own programs

The tinyserial.h file contains documentation on how to use all of the Tinyserial library functions. tinyserial.h and libtinyserial.a reside in the Lib directory after you have built the library.

See the test programs for further examples on how to use the Tinyserial library. Adapt their Makefiles for your own purposes.

Use "make upload" to load programs into flash. I usually press the reset button on my Arduino board the instant before I hit enter on the make upload command. The timing is tricky - sometimes I get a "the programmer is not responding" error. Keep trying; it can take several tries for make upload to work.

Tinyserial library API

This excerpt from tinyserial.h explains the Tinyserial library API. You can do character and string I/O on USART0 (the first serial port). If you like, you can save SRAM by storing your constant strings in Flash and printing them directly to the serial port. There is no need to first copy them to a buffer in SRAM.
// Call this function first to configure USART0.
// Example:  ts_init(TS_CONFIG_16MHZ_9600BAUD, TS_MODE_WRITEONLY);
void ts_init(unsigned int, unsigned char);

// Call this function to write single characters to USART0.
// Example:  ts_putc('x');
void ts_putc(unsigned char);

// Call this function to read singles characters from USART0.  Use the
// parameter to control whether the program should echo the characters
// it reads back to the USART0 or not.
// Example: char byte = ts_getc(TS_ECHO_ON);
char ts_getc(unsigned char);

// Call this function to write C strings stored in SRAM to USART0.
// Example:  ts_puts("Hello World!");
void ts_puts(char *);

// Call this function to read C strings from USART0.
// Example:
// #define INPUT_LENGTH 16
// char buffer[INPUT_LENGTH + 1];
// unsigned int length;
// length = ts_gets(buffer, INPUT_LENGTH, TS_ECHO_ON);
// buffer[length] = '\0';
unsigned int ts_gets(char *, unsigned int, unsigned char);

// Call this function to write C strings stored in Flash to USART0.
// Example:
// char thestr[] __attribute((__progmem__)) = THEDATA;
// ts_putsf(thestr);
void ts_putsf(char *);

A Hello World program using the Tinyserial library:

#include <avr/io.h>

#include "tinyserial.h"

int
main(void) {

  ts_init(TS_CONFIG_16MHZ_9600BAUD, TS_MODE_WRITEONLY);
  
  while (1) {
    ts_puts("Hello world!\r\n");
  }

  return 0;
}

Feedback and bug reports

Please send feedback and bug reports to Tim Fraser at tfraser@alum.wpi.edu.

Download

The Tinyserial library is Free software available under the GNU Lesser General Public License (LGPL). Tinyserial source distribution:


Tim Fraser's homepage at the WPI alumni site