libconio

Console IO C-library for STM32 and MSP430G2553 MCUs

1. Introduction

“libconio” is part of “libemb“. It provides a simple to use API for writing text to a console. Currently the console is the first USART on the STM32 or USCI_A UART on the MSP430. The library is not HW dependend since the HW part is provided by “libserial“. Thus, this library is dependend on “libserial” form the “libemb” project.

For detailed building instructions see instructions for “libemb

2. Hardware Setup

No special hardware setup is required. Just connect the RX/TX (and GND) lines of your USB to serial converter to the corresponding lines of your MCU so you could see output of “libconio” or provide some input to it (since by default “libconio” uses the serial line as device).

Note: When using the TI Launchpad, “/dev/ttyACM0″ could be used as serial port at 9600 Bauds, but RX/TX must be crossed on the jumper bridge of the Launchpad.

3. Including libconio Headers

To use “libconio” functionality add the following include to your sources:

#include <libemb/conio/conio.h>

Since “libconio” needs some device for in-/output, you also need to setup the serial line of your MCU by using “libserial” (see the corresponding HOWTO for details), and thus need to include that header too:

#include <libemb/serial/serial.h>

4. Linking libconio Library

To link against “libconio”, add the following to your linker options:

-lconio

And for serial line support via “libserial” add the following:

-lserial

5. Initializing the Hardware

For “libconio”, no hardware initialization is needed. But the serial line used by “libconio” has to be initialized. This could be easily done by using “libserial’s” init functionality:

serial_init(38400);

Again, for more datails on “libserial” see the corresponding HOWTO.

For printing out data through the underlaying hardware (by default the serial line), the following methods are available:

Method Description
cio_printc Print a single character
cio_print Print a string
cio_printi Print an integer
cio_printb Print an integer in its binary representation (e.g. 010111)
cio_printf Tiny implementaion of printf

To print a single character to the device in blocking mode, use “cio_printc”:

cio_printc('A'); // prints A

To print a null terminated string use “cio_print”:

cio_print((char *)"This is a String"); // print This is ....

For printing an integer, “cio_printi” could be used:

int i;
i = 42;
cio_printi(i);	// prints 42

If you like to print an integer in its binary representation use “cio_printb”:

int i;
i = 42;
cio_printb(i, 8); 	// prints 00101010

Note: the second parameter for “cio_printb” is the number of bits to print.

To print acording to a given format string (like printf), use “cio_printf”:

s = "test";
c = 'X';
i = -12345;
u =  12345;
l = -1234567890;
n =  1234567890;
x = 0xABCD;

cio_printf("String        %s\n\r", s); // prints test
cio_printf("Char          %c\n\r", c); // prints X
cio_printf("Integer       %i\n\r", i); // prints -12345
cio_printf("Unsigned      %u\n\r", u); // prints 12345
cio_printf("Long          %l\n\r", l); // prints -1234567890
cio_printf("Unsigned loNg %n\n\r", n); // prints 1234567890
cio_printf("Hex           %x\n\r", x); // prints ABCD

Note: “cio_printf” supports the following format patterns:

Type Format
String %s
Char %c
Integer %i
Unsigned %u
Long %l
Unsigned long %n
Hex %x

Specifying the number of digits for numbers is not supported!

7. Read Data

For reading data in form the underlaying hardware (by default the serial line), the following mehtods are available:

Method Description
cio_getc Read in a single character (blocking)

To wait until a single character is received through the input device use “cio_getc”:

char c = cio_getc();

8. Use it With a Custom Device

If you don’t want to use the default serial line device as provided by “libserial”, support for a different device could be provided easily by writing a custom implementation of the methods “cio_printc” and “cio_getc”. Instead of then linking “libconio” with “cio_serio.o”, use your own implementation.

Leave a Reply

You must be logged in to post a comment.