Bug fix release

Dependents:   AntiTheftGPS XbeeReceive XbeeSend Superball_Ball2 ... more

MODSERIAL is an easy to use library that extends Serial to add fully buffered input and output.

The features of MODSERIAL include:-


Connecting up the MODSERIAL module

The starting point for using MODSERIAL is the Mbed's own handbook for Serial library object. MODSERIAL inherits Serial and adds extensions for buffering. So getting started is easy. Follow the Mbed instructions for Serial to get setup. Here's a reproduction of Serial's simple code starter:-

1  #include "mbed.h"
3  Serial pc(USBTX, USBRX); // tx, rx
5  int main() {
6      pc.printf("Hello World!");
7      while(1) {
8          pc.putc(pc.getc() + 1);
9      }
10 }

All we need to do to use MODSERIAL is to add a #include and alter one line thus:-

1  #include "mbed.h"
2  #include "MODSERIAL.h"
3  MODSERIAL pc(USBTX, USBRX); // tx, rx
5  int main() {
6      pc.printf("Hello World!");
7      while(1) {
8          pc.putc(pc.getc() + 1);
9      }
10 }

As we can see, all we have done is add the header at line 2 and changed line 3 to specify the use of MODSERIAL in replacement for Serial. The default settings for MODSERIAL are that both the TX and RX buffers are assigned 256 bytes each of storage space. This storage space is acquired from the heap using malloc.

The default buffer assignment can be manipulated in three ways. First is the compile time setting which alters the default parameters used when creating a MODSERIAL object. This is done thus:-

1  #include "mbed.h"
5  #include "MODSERIAL.h"
7  MODSERIAL pc(USBTX, USBRX); // tx, rx
8  ...

By defining the two #defines before the #include "MODSERIAL.h" alters the defaults MODSERIAL uses to create it's buffers.

The second method is the run-time version. To get TX at 1024 and RX buffer at 512 as above during run-time initialisation, alter the constructor thus:-

1  #include "mbed.h"
2  #include "MODSERIAL.h"
4  // Make TX buffer 1024bytes and RX buffer use 512bytes.
5  MODSERIAL pc(USBTX, USBRX, 1024, 512); // tx, rx
6  ...

If you supply only one numeric value, as shown below, both TX and RX will have the same buffer sizes assigned to them:-

1  #include "mbed.h"
2  #include "MODSERIAL.h"
4  // Make both TX and RX use a 512byte buffer.
5  MODSERIAL pc(USBTX, USBRX, 512); // tx, rx
6  ...

The third method is reassigning a new buffer while the program is running. This allows the program to grow and shrink either buffer as required. However, there are caveats to do this as will be shown below.

First, expanding the buffer involves increasing the buffer size. This is fairly straight forward and is accomplished thus:-

1  #include "mbed.h"
2  #include "MODSERIAL.h"
3  MODSERIAL pc(USBTX, USBRX); // tx, rx
5  int main() {
7      // Increase the TX buffer from the default 256bytes to 1024bytes.
8      if (pc.txBufferSetSize(1024) != MODSERIAL::Ok) {
9         error("Failed to allocate memory for new buffer");
10     }
12     pc.printf("Hello World!");
13     while(1) {
14         pc.putc(pc.getc() + 1);
15     }
16 }

As can be seen, growing the buffer is fairly straight forward. However, how it is done should be understood by the user. First, a new buffer allocation is made using malloc. Once acquired the current buffer is checked for contents. If the current buffer is not empty it is copied to the new buffer so the old buffer contents is maintained after resizing. The last step is then to free() the old memory buffer.

The buffer can also be contracted to a smaller length buffer. Here's the code:-

1  #include "mbed.h"
2  #include "MODSERIAL.h"
3  MODSERIAL pc(USBTX, USBRX); // tx, rx
5  int main() {
6      int result;
8      // Decrease the TX buffer from the default 256bytes to 32bytes.
9      result = pc.txBufferSetSize(32);
10     if (result != MODSERIAL::Ok) {
11         switch(result) {
12             case MODSERIAL::BufferOversize: 
13                 error("Contents too big to fit into new allocation");
14                 break;
15             case MODSERIAL::NoMemory: 
16                 error("Not enough memory for new allocation");
17                 break;
18         }
19     }
12     pc.printf("Hello World!");
13     while(1) {
14         pc.putc(pc.getc() + 1);
15     }
16 }

Since buffer resizing involves the copying over of any existing old buffer contents the possibility exists that the current buffer contains more bytes than will fit into the new requested buffer. In these conditions the user must handle the return value of the resize functions. If the contents are of no concern then calling txBufferFlush() to empty of the contents before resizing.

MODSERIAL Interrupts

Users of Serial will be familar with the fact that you can attach functions or methods to TxIrq or RxIrq. This attachment of callbacks allows users to have Interrupt Service Routines (ISR) for both the TX and RX channel of the Uart. MODSERIAL uses both of these callbacks to maintain it's buffers and so are not available to users. However, MODSERIAL does contain five potential callbacks the user can use. These are:-

  • TxIrq - This callback is used to inform the user's program that a character was transferred from the TX buffer to the Uart's TX THR FIFO.
  • RxIrq - This callback is used to inform the user's program that a character was transferred from the Uart's RX FIFO RBR to the RX buffer.
  • RxOvIrq - This callback is used to inform the user's program that a character in the Uart's RX FIFO RBR failed to transfer to the RX buffer because the RX buffer was full. The failed byte is availble via xxGetLastChar() methods.
  • TxOvIrq - As RX overflow above
  • TxEmpty - This callback is made when the last byte in the TX buffer is transferred to the Uart's TX THR FIFO. It informs the user's program that the TX buffer has become empty. However, it does not mean transmission is complete. See the example1.cpp example for more information.

Delineating "packets"

Many devices send information on RS232 interfaces in distinct "packets". As an example of this is NMEA information sent by many GPS modules. Each NMEA sentence is delineated by a '\n' newline character. Each sentence can be of vary length depending upon the information being sent, however, all are seperated by a '\n' newline. Detecting this if very simple with MODSERIAL. Here's an example:-

#include "mbed.h"
#include "MODSERIAL.h"

// Connect the TX of the GPS module to p10 RX input
MODSERIAL gps(NC, p10);

bool newline_detected = false;

// Called everytime a new character goes into
// the RX buffer. Test that character for \n
// Note, rxGetLastChar() gets the last char that
// we received but it does NOT remove it from
// the RX buffer.
void rxCallback(MODSERIAL_IRQ_INFO *q) {
    MODSERIAL *serial = q->serial;
    if ( serial->rxGetLastChar() == '\n') {
    	newline_detected = true;

int main() {
    gps.attach(&rxCallback, MODSERIAL::RxIrq);

    // Wait here until we detect the \n going into the buffer.
    while (! newline_detected ) ;    
    // When we get here the RX buffer now contains a NMEA sentence.
    // ...


Note, the txGetLastChar() and rxGetLastChar() methods only return the last character but they do not remove that character from the associated buffer.

If this is your first time using MODSERIAL or would just like to test it out then see the example.cpp that comes with the library.

Tue Jan 08 18:01:03 2013 +0000
See ChangeLog.c

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AjK 1:b7e435fbfe8e 1 /* $Id:$
AjK 2:b936b4acbd92 2
AjK 25:ae0408ebdd68 3 1.25 8th January 2013
AjK 25:ae0408ebdd68 4
AjK 25:ae0408ebdd68 5 * Bring back into line with MBed libraries.
AjK 25:ae0408ebdd68 6 * Credits:
AjK 25:ae0408ebdd68 7 Erik Olieman : http://mbed.org/users/Sissors/code/MODSERIAL/rev/3ba4341d74d6
AjK 25:ae0408ebdd68 8 Erik Olieman : http://mbed.org/users/Sissors/code/MODSERIAL/rev/a469aa702bab
AjK 25:ae0408ebdd68 9
AjK 25:ae0408ebdd68 10
AjK 24:9c456e647a8f 11 1.24 6th Dec 2012
AjK 25:ae0408ebdd68 12
AjK 25:ae0408ebdd68 13 * Beta release for new Mbed library.
AjK 24:9c456e647a8f 14
AjK 23:5c45c21f36b7 15 1.23 25th July 2012
AjK 23:5c45c21f36b7 16
AjK 23:5c45c21f36b7 17 * LPC1768 code as was. This release includes "alpha" support for the LPC11U24
AjK 23:5c45c21f36b7 18
AjK 22:c11ea36f17f9 19 1.22 19th April 2012
AjK 22:c11ea36f17f9 20
AjK 22:c11ea36f17f9 21 * http://mbed.org/forum/bugs-suggestions/topic/2936/
AjK 22:c11ea36f17f9 22 * Bug fix, protect important buffer pointers from IRQ corruption.
AjK 25:ae0408ebdd68 23 * Credits:
AjK 22:c11ea36f17f9 24 Anthony Wieser http://mbed.org/users/WieserSoftwareLtd/ for the fix.
AjK 22:c11ea36f17f9 25 BlazeX http://mbed.org/users/BlazeX/ for the alert that a fix was needed!
AjK 22:c11ea36f17f9 26
AjK 21:af2af4c61c2f 27 1.21 10 May 2011
AjK 21:af2af4c61c2f 28
AjK 21:af2af4c61c2f 29 * http://mbed.org/forum/mbed/topic/2264
AjK 21:af2af4c61c2f 30
AjK 20:59c74aaedda2 31 1.20 26 April 2011
AjK 20:59c74aaedda2 32
AjK 20:59c74aaedda2 33 * Bug fix, not blocking on transmit
AjK 20:59c74aaedda2 34 by Erik Petrich, http://mbed.org/forum/bugs-suggestions/topic/2200
AjK 20:59c74aaedda2 35
AjK 20:59c74aaedda2 36 1.19 20 April 2011
AjK 20:59c74aaedda2 37
AjK 20:59c74aaedda2 38 * Fixed some doxygen comment bugs.
AjK 20:59c74aaedda2 39
AjK 18:21ef26402365 40 1.18 20 April 2011
AjK 18:21ef26402365 41
AjK 18:21ef26402365 42 * All callbacks now use MODSERIAL_callback (rather than Mbed's FunctionPointer[1] type)
AjK 18:21ef26402365 43 to store and invoke it's callbacks. This allows MODSERIAL to pass a parameter
AjK 18:21ef26402365 44 to callbacks. The function prototype is now void func(MODSERIAL_IRQ_INFO *q).
AjK 18:21ef26402365 45 * Callbacks now pass a pointer to a MODSERIAL_IRQ_INFO class type.
AjK 18:21ef26402365 46 This class holds a pointer to the MODSERIAL object that invoked the callback
AjK 18:21ef26402365 47 thus freeing callbacks need to use the global variable of the original
AjK 18:21ef26402365 48 MODSERIAL instance.
AjK 18:21ef26402365 49 * MODSERIAL_IRQ_INFO also declares public functions that are protected within MODSERIAL
AjK 18:21ef26402365 50 thus allowing certain functions to be restricted to callback context only.
AjK 18:21ef26402365 51 * New function MODSERIAL_IRQ_INFO::rxDiscardLastChar() allows an rxCallback function
AjK 18:21ef26402365 52 to remove the character that was just placed into the RX buffer.
AjK 18:21ef26402365 53
AjK 18:21ef26402365 54 [1] http://mbed.org/users/AjK/libraries/FPointer/latest/docs/
AjK 18:21ef26402365 55
AjK 17:6c9b57c14868 56 1.17 08/Mar/2011
AjK 17:6c9b57c14868 57 Fixed a memory leak in the DMA code.
AjK 17:6c9b57c14868 58
AjK 16:8b1dbf4cce4e 59 1.16 - 12 Feb 2011
AjK 16:8b1dbf4cce4e 60
AjK 16:8b1dbf4cce4e 61 * Missed one, doh!
AjK 16:8b1dbf4cce4e 62
AjK 15:a1d9e745d71e 63 1.15 - 12 Feb 2011
AjK 15:a1d9e745d71e 64
AjK 15:a1d9e745d71e 65 * Fixed some typos.
AjK 15:a1d9e745d71e 66
AjK 14:3c3b87617bfe 67 1.14 - 7 Feb 2011
AjK 14:3c3b87617bfe 68
AjK 14:3c3b87617bfe 69 * Fixed a bug in __putc() that caused the output buffer pointer to
AjK 14:3c3b87617bfe 70 become corrupted.
AjK 14:3c3b87617bfe 71
AjK 13:70bb7c1769fa 72 1.13 - 20/01/2011
AjK 13:70bb7c1769fa 73
AjK 13:70bb7c1769fa 74 * Added extra documentation.
AjK 13:70bb7c1769fa 75 * Fixed some typos.
AjK 13:70bb7c1769fa 76
AjK 12:8c7394e2ae7f 77 1.12 - 20/01/2011
AjK 12:8c7394e2ae7f 78
AjK 12:8c7394e2ae7f 79 * Added new "autoDetectChar()" function. To use:-
AjK 12:8c7394e2ae7f 80 1st: Add a callback to invoke when the char is detected:-
AjK 12:8c7394e2ae7f 81 .attach(&detectedChar, MODSERIAL::RxAutoDetect);
AjK 12:8c7394e2ae7f 82 2nd: Send the char to detect.
AjK 12:8c7394e2ae7f 83 .autoDectectChar('\n');
AjK 12:8c7394e2ae7f 84 Whenever that char goes into the RX buffer your callback will be invoked.
AjK 12:8c7394e2ae7f 85 Added example2.cpp to demo a simple messaging system using this auto feature.
AjK 12:8c7394e2ae7f 86
AjK 12:8c7394e2ae7f 87
AjK 11:a93a62eeeb9d 88 1.11 - 23/11/2010
AjK 11:a93a62eeeb9d 89
AjK 11:a93a62eeeb9d 90 * Fixed a minor issue with 1.10 missed an alteration of name change.
AjK 11:a93a62eeeb9d 91
AjK 10:725fe81aa9ff 92 1.10 - 23/11/2010
AjK 10:725fe81aa9ff 93
AjK 18:21ef26402365 94 * Rename the DMA callback from attach_dma_complete() to attach_dmaSendComplete()
AjK 10:725fe81aa9ff 95
AjK 9:b3cdae80e7a9 96 1.9 - 23/11/2010
AjK 9:b3cdae80e7a9 97
AjK 9:b3cdae80e7a9 98 * Added support for DMA sending of characters. Required is
AjK 9:b3cdae80e7a9 99 the MODDMA library module:-
AjK 9:b3cdae80e7a9 100 http://mbed.org/users/AjK/libraries/MODDMA/latest
AjK 9:b3cdae80e7a9 101 See example_dma.cpp for more information.
AjK 9:b3cdae80e7a9 102
AjK 8:775f860e94d3 103 1.8 - 22/11/2010
AjK 8:775f860e94d3 104
AjK 8:775f860e94d3 105 * Added code so that if a buffer is set to zero length then
AjK 8:775f860e94d3 106 MODSERIAL defaults to just using the FIFO for that stream
AjK 8:775f860e94d3 107 thus making the library "fall back" to teh same operation
AjK 8:775f860e94d3 108 that the Mbed Serial library performs.
AjK 8:775f860e94d3 109 * Removed dmaSend() function that should have been removed
AjK 8:775f860e94d3 110 at 1.7
AjK 8:775f860e94d3 111
AjK 7:ffa4a7cb7f8d 112 1.7 - 21/11/2010
AjK 7:ffa4a7cb7f8d 113
AjK 7:ffa4a7cb7f8d 114 * Remove the DMA enum from MODSERIAL.h as it's not currently
AjK 7:ffa4a7cb7f8d 115 ready for release.
AjK 7:ffa4a7cb7f8d 116 * Added page doxygen comments.
AjK 7:ffa4a7cb7f8d 117
AjK 6:c8f77fe1cc10 118 1.6 - 21/11/2010
AjK 6:c8f77fe1cc10 119
AjK 6:c8f77fe1cc10 120 * Version 1.5 solved a blocking problem on putc() when called
AjK 6:c8f77fe1cc10 121 from another ISR. However, isr_tx() invokes a callback of it's
AjK 6:c8f77fe1cc10 122 own when a byte is tranferred from TX buffer to TX FIFO. User
AjK 6:c8f77fe1cc10 123 programs may interpret that as an IRQ callback. That's an ISR
AjK 6:c8f77fe1cc10 124 call from within an existing ISR which is not good. So the
AjK 6:c8f77fe1cc10 125 TxIrq callback from isr_tx is now conditional. It will only
AjK 6:c8f77fe1cc10 126 be called when isr_tx() is actually within it's own ISR and
AjK 6:c8f77fe1cc10 127 not when called from alternate ISR handlers.
AjK 6:c8f77fe1cc10 128
AjK 5:8365c4cf8f33 129 1.5 - 21/11/2010
AjK 5:8365c4cf8f33 130
AjK 5:8365c4cf8f33 131 * Calling putc() (or any derived function that uses it like
AjK 5:8365c4cf8f33 132 printf()) while inside an interrupt service routine can
AjK 5:8365c4cf8f33 133 cause the system to lock up if the TX buffer is full. This
AjK 5:8365c4cf8f33 134 is because bytes are only transferred from the TX buffer to
AjK 5:8365c4cf8f33 135 the TX FIFO via the TX ISR. If we are, say in an RX ISR already,
AjK 5:8365c4cf8f33 136 then the TX ISR will never trigger. The TX buffer stays full and
AjK 5:8365c4cf8f33 137 there is never space to putc() the byte. So, while putc() blocks
AjK 5:8365c4cf8f33 138 waiting for space it calls isr_tx() to ensure if TX FIFO space
AjK 5:8365c4cf8f33 139 becomes available it will move bytes from the TX buffer to TX
AjK 5:8365c4cf8f33 140 FIFO thus removing the blocking condition within putc().
AjK 5:8365c4cf8f33 141
AjK 4:28de979b77cf 142 1.4 - 21/11/2010
AjK 4:28de979b77cf 143
AjK 4:28de979b77cf 144 * Removed all the new DMA code. I wish mbed.org had proper SVN
AjK 4:28de979b77cf 145 versioning, I'm use to working in HEAD and BRANCHES after I've
AjK 4:28de979b77cf 146 released a project. Getting bug reports in current releases
AjK 4:28de979b77cf 147 while trying to dev new code is hard to manage without source
AjK 4:28de979b77cf 148 control of some type!
AjK 4:28de979b77cf 149
AjK 2:b936b4acbd92 150 1.3 - 21/11/2010
AjK 2:b936b4acbd92 151
AjK 2:b936b4acbd92 152 * Fixed a macro problem with txIsBusy()
AjK 2:b936b4acbd92 153 * Started adding code to use "block data" sending using DMA
AjK 3:0f10f536456e 154 * Removed #include "IOMACROS.h"
AjK 1:b7e435fbfe8e 155
AjK 2:b936b4acbd92 156 1.2 - 21/11/2010
AjK 2:b936b4acbd92 157
AjK 2:b936b4acbd92 158 * Removed unsed variables from flushBuffer()
AjK 2:b936b4acbd92 159 * Fixed a bug where both RX AND TX fifos are cleared/reset
AjK 2:b936b4acbd92 160 when just TX OR RX should be cleared.
AjK 2:b936b4acbd92 161 * Fixed a bug that cleared IIR when in fact it should be left
AjK 2:b936b4acbd92 162 alone so that any pending interrupt after flush is handled.
AjK 2:b936b4acbd92 163 * Merged setBase() into init() as it wasn't required anywhere else.
AjK 2:b936b4acbd92 164 * Changed init() to enforce _uidx is set by Serial to define the _base
AjK 2:b936b4acbd92 165 address of the Uart in use.
AjK 2:b936b4acbd92 166
AjK 1:b7e435fbfe8e 167 1.1 - 20/11/2010
AjK 1:b7e435fbfe8e 168
AjK 1:b7e435fbfe8e 169 * Added this file
AjK 1:b7e435fbfe8e 170 * Removed cruft from GETC.cpp
AjK 1:b7e435fbfe8e 171 * "teh" should be "the", why do my fingers do that?
AjK 1:b7e435fbfe8e 172
AjK 1:b7e435fbfe8e 173 1.0 - 20/11/2010
AjK 1:b7e435fbfe8e 174
AjK 1:b7e435fbfe8e 175 * First release.
AjK 1:b7e435fbfe8e 176
AjK 1:b7e435fbfe8e 177 */