modm API documentation
Input/Output Streams


class  modm::IODevice
class  modm::IODeviceObjectWrapper< Device, behavior >
class  modm::IODeviceWrapper< Device, behavior >
class  modm::IOStream


enum  modm::IOBuffer { DiscardIfFull, BlockIfFull }
IOStreammodm::flush (IOStream &ios)
IOStreammodm::endl (IOStream &ios)
IOStreammodm::bin (IOStream &ios)
 set the output mode to binary style
IOStreammodm::hex (IOStream &ios)
 set the output mode to hexadecimal style
IOStreammodm::ascii (IOStream &ios)
 set the output mode to ASCII style
IOStreammodm::black (IOStream &ios)
 Set the foreground colour on ANSI terminals.
IOStreammodm::red (IOStream &ios)
IOStreammodm::green (IOStream &ios)
IOStreammodm::yellow (IOStream &ios)
IOStreammodm::blue (IOStream &ios)
IOStreammodm::magenta (IOStream &ios)
IOStreammodm::cyan (IOStream &ios)
IOStreammodm::white (IOStream &ios)

Detailed Description

lbuild module: modm:io

The modm::IOStream class contains efficient formatting that supports both C++ std::basic_ostream-like formatting via operator << as well as implementing printf via the modm:printf module.

modm::IOStream stream(device);
stream << "format number 8: " << uint8_t(8) << " or as signed -100: " << int8_t(-100);
stream << modm::endl;
stream.printf("format number 8: %u or as signed -100: %d", 8, -100);
AVR supported features All expensive features including printf are disabled by default to reduce firmware size! Please check the options.
modm::endl does NOT implicitly flush! Flushing is extremely expensive on embedded systems, therefore modm::endl does not implicitly flush the stream. Please call modm::flush explicitly.

Redirecting IOStreams

The modm::IODeviceWrapper transforms any peripheral device that provides static write() and read() functions into an IODevice.

You have to decide what happens when the device buffer is full and you cannot write to it at the moment. There are two options:

  1. busy wait until the buffer is free, or
  2. discard the bytes that cannot be written.

Option 1 has the advantage, that none of your data will be lost, however, busy-waiting can take a long time and can mess up your program timings. There is also a high risk of deadlock, when writing to a IODevice inside of an interrupt and then busy-waiting forever because the IODevice requires interrupts itself to send out the data.

It is therefore highly recommended to use option 2, where surplus data will be discarded. You should increase the IODevice buffer size, if you experience missing data from your connection. This behavior is also deadlock safe when called from inside another interrupt, and your program timing is minimally affected (essentially only coping data into the buffer).

There is no default template argument, so that you hopefully make a conscious decision and be aware of this behavior.


// configure a UART
using Uart = Uart0;
// wrap it into an IODevice
// use this device to print a message
// or create a IOStream and use the stream to print something
modm::IOStream stream(device);
stream << " World!";

Module Options

modm:io:with_long_long: Support for 64-bit integer formatting

Generated with: no in [yes, no]

modm:io:with_float: Support for floating point formatting

On AVRs floating point values can be printed, however, the formatting cannot be specified and all values are printed as scientific-notation exponential floating point

Generated with: no in [yes, no]

modm:io:with_printf: Support for printf-style formatting

Generated with: no in [yes, no]

Enumeration Type Documentation

enum modm::IOBuffer

The preferred behavior when the IODevice buffer is full

Function Documentation

IOStream& modm::flush ( IOStream ios)

Flushes the output stream. This manipulator simply calls the stream's flush() member function.