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 12:8c7394e2ae7f 1 /*
AjK 12:8c7394e2ae7f 2 Copyright (c) 2011 Andy Kirkham
AjK 12:8c7394e2ae7f 3
AjK 12:8c7394e2ae7f 4 Permission is hereby granted, free of charge, to any person obtaining a copy
AjK 12:8c7394e2ae7f 5 of this software and associated documentation files (the "Software"), to deal
AjK 12:8c7394e2ae7f 6 in the Software without restriction, including without limitation the rights
AjK 12:8c7394e2ae7f 7 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
AjK 12:8c7394e2ae7f 8 copies of the Software, and to permit persons to whom the Software is
AjK 12:8c7394e2ae7f 9 furnished to do so, subject to the following conditions:
AjK 12:8c7394e2ae7f 10
AjK 12:8c7394e2ae7f 11 The above copyright notice and this permission notice shall be included in
AjK 12:8c7394e2ae7f 12 all copies or substantial portions of the Software.
AjK 12:8c7394e2ae7f 13
AjK 12:8c7394e2ae7f 20 THE SOFTWARE.
AjK 12:8c7394e2ae7f 21
AjK 12:8c7394e2ae7f 22 @file example2.cpp
AjK 12:8c7394e2ae7f 23 @purpose Demos a simple messaging system.
AjK 12:8c7394e2ae7f 24 @version see ChangeLog.c
AjK 12:8c7394e2ae7f 25 @date Jan 2011
AjK 12:8c7394e2ae7f 26 @author Andy Kirkham
AjK 12:8c7394e2ae7f 27 */
AjK 12:8c7394e2ae7f 28
AjK 12:8c7394e2ae7f 29 /*
AjK 12:8c7394e2ae7f 30 This example demostrates a simple "messaging" system. You can use it with
AjK 12:8c7394e2ae7f 31 a terminal program to test it out or write a cusom C#/C++/VB/etc program
AjK 13:70bb7c1769fa 32 to read and write messages to or from the Mbed. The default baud rate in
AjK 12:8c7394e2ae7f 33 this example is 115200.
AjK 12:8c7394e2ae7f 34
AjK 12:8c7394e2ae7f 35 In this example, the LEDs are controlled and pins p21 to p24 are set as
AjK 12:8c7394e2ae7f 36 InterruptIn and send messages out when their value changes.
AjK 12:8c7394e2ae7f 37
AjK 12:8c7394e2ae7f 38 To use, hook up the MBed USB and open your fav terminal. All messages
AjK 12:8c7394e2ae7f 39 end with the \n character, don't forget to hit carriage return!.
AjK 12:8c7394e2ae7f 40 As an example:-
AjK 12:8c7394e2ae7f 41
AjK 12:8c7394e2ae7f 42 to switch on LED1 send LED1:1\n, off is LED1:0\n and toggle is LED1:2\n
AjK 12:8c7394e2ae7f 43 to switch on LED2 send LED2:1\n, off is LED2:0\n and toggle is LED2:2\n
AjK 12:8c7394e2ae7f 44 to switch on LED3 send LED3:1\n, off is LED3:0\n and toggle is LED3:2\n
AjK 12:8c7394e2ae7f 45 to switch on LED4 send LED4:1\n, off is LED4:0\n and toggle is LED4:2\n
AjK 12:8c7394e2ae7f 46
AjK 12:8c7394e2ae7f 47 When a pin change on p21 to p24 happens, a message is sent. As an example
AjK 12:8c7394e2ae7f 48 when p21 goes low PIN21:0\n is sent, when goes high PIN21:1\n is sent.
AjK 12:8c7394e2ae7f 49
AjK 12:8c7394e2ae7f 50 Note, the InterruptIn pins p21 to p24 are setup to have pullups. This means
AjK 12:8c7394e2ae7f 51 they are high. To activate them use a wire to short the pin to 0volts.
AjK 12:8c7394e2ae7f 52
AjK 12:8c7394e2ae7f 53 If you find that p21 to p24 sent a lot of on/off/on/off then it's probably
AjK 12:8c7394e2ae7f 54 due to "bounce". If you are connecting a mechanical switch to a pin you
AjK 12:8c7394e2ae7f 55 may prefer to use the PinDetect library rather than using InterruptIn.
AjK 12:8c7394e2ae7f 56 @see http://mbed.org/users/AjK/libraries/PinDetect/latest
AjK 12:8c7394e2ae7f 57
AjK 13:70bb7c1769fa 58 One point you may notice. Incoming messages are processed via main()'s
AjK 13:70bb7c1769fa 59 while(1) loop whereas pin changes have their messages directly sent.
AjK 13:70bb7c1769fa 60 The reason for this is when MODSERIAL makes callbacks to your application
AjK 13:70bb7c1769fa 61 it is in "interrupt context". And one thing you want to avoid is spending
AjK 13:70bb7c1769fa 62 lots of CPU time in that context. So, the callback moves the message from
AjK 13:70bb7c1769fa 63 the input buffer to a local holding buffer and it then sets a bool flag
AjK 13:70bb7c1769fa 64 which tells main()'s while(1) loop to process that buffer. This means the
AjK 13:70bb7c1769fa 65 time spent doing the real incoming message handing is within your program
AjK 13:70bb7c1769fa 66 and not within MODSERIAL's interrupt context. So you may ask, why not do
AjK 13:70bb7c1769fa 67 the same for out going messages? Well, because MODSERIAL output buffers
AjK 13:70bb7c1769fa 68 all your sent content then sending chars is very fast. MODSERIAL handles
AjK 13:70bb7c1769fa 69 all the nitty gritty bits for you. You can just send. This example uses
AjK 13:70bb7c1769fa 70 puts() to send the message. If you can, always try and use sprintf()+puts()
AjK 13:70bb7c1769fa 71 rathe than printf(), printf() is known to often screw things up when used
AjK 13:70bb7c1769fa 72 within an interrupt context. Better still, just use puts() and do away
AjK 13:70bb7c1769fa 73 with any of the crappy ?printf() calls if possible. But I found the code
AjK 13:70bb7c1769fa 74 below to work fine even at 115200baud.
AjK 13:70bb7c1769fa 75
AjK 12:8c7394e2ae7f 76 */
AjK 12:8c7394e2ae7f 77
AjK 12:8c7394e2ae7f 78
AjK 12:8c7394e2ae7f 79 #ifdef COMPILE_EXAMPLE1_CODE_MODSERIAL
AjK 12:8c7394e2ae7f 80
AjK 12:8c7394e2ae7f 81 #include "mbed.h"
AjK 12:8c7394e2ae7f 82 #include "MODSERIAL.h"
AjK 12:8c7394e2ae7f 83
AjK 12:8c7394e2ae7f 84 #define MESSAGE_BUFFER_SIZE 32
AjK 12:8c7394e2ae7f 85
AjK 12:8c7394e2ae7f 86 DigitalOut led1(LED1);
AjK 12:8c7394e2ae7f 87 DigitalOut led2(LED2);
AjK 12:8c7394e2ae7f 88 DigitalOut led3(LED3);
AjK 12:8c7394e2ae7f 89 DigitalOut led4(LED4);
AjK 12:8c7394e2ae7f 90
AjK 12:8c7394e2ae7f 91 InterruptIn P21(p21);
AjK 12:8c7394e2ae7f 92 InterruptIn P22(p22);
AjK 12:8c7394e2ae7f 93 InterruptIn P23(p23);
AjK 12:8c7394e2ae7f 94 InterruptIn P24(p24);
AjK 12:8c7394e2ae7f 95
AjK 12:8c7394e2ae7f 96 MODSERIAL messageSystem(USBTX, USBRX);
AjK 13:70bb7c1769fa 97
AjK 12:8c7394e2ae7f 98 char messageBufferIncoming[MESSAGE_BUFFER_SIZE];
AjK 12:8c7394e2ae7f 99 char messageBufferOutgoing[MESSAGE_BUFFER_SIZE];
AjK 12:8c7394e2ae7f 100 bool messageReceived;
AjK 12:8c7394e2ae7f 101
AjK 18:21ef26402365 102 void messageReceive(MODSERIAL_IRQ_INFO *q) {
AjK 18:21ef26402365 103 MODSERIAL *sys = q->serial;
AjK 18:21ef26402365 104 sys->move(messageBufferIncoming, MESSAGE_BUFFER_SIZE);
AjK 12:8c7394e2ae7f 105 messageReceived = true;
AjK 18:21ef26402365 106 return 0;
AjK 12:8c7394e2ae7f 107 }
AjK 12:8c7394e2ae7f 108
AjK 12:8c7394e2ae7f 109 void messageProcess(void) {
AjK 12:8c7394e2ae7f 110 if (!strncmp(messageBufferIncoming, "LED1:1", sizeof("LED1:1")-1)) led1 = 1;
AjK 12:8c7394e2ae7f 111 else if (!strncmp(messageBufferIncoming, "LED1:0", sizeof("LED1:0")-1)) led1 = 0;
AjK 12:8c7394e2ae7f 112 else if (!strncmp(messageBufferIncoming, "LED1:2", sizeof("LED1:2")-1)) led1 = !led1;
AjK 12:8c7394e2ae7f 113
AjK 12:8c7394e2ae7f 114 else if (!strncmp(messageBufferIncoming, "LED2:1", sizeof("LED2:1")-1)) led2 = 1;
AjK 12:8c7394e2ae7f 115 else if (!strncmp(messageBufferIncoming, "LED2:0", sizeof("LED2:0")-1)) led2 = 0;
AjK 12:8c7394e2ae7f 116 else if (!strncmp(messageBufferIncoming, "LED2:2", sizeof("LED2:2")-1)) led2 = !led2;
AjK 12:8c7394e2ae7f 117
AjK 12:8c7394e2ae7f 118 else if (!strncmp(messageBufferIncoming, "LED3:1", sizeof("LED3:1")-1)) led3 = 1;
AjK 12:8c7394e2ae7f 119 else if (!strncmp(messageBufferIncoming, "LED3:0", sizeof("LED3:0")-1)) led3 = 0;
AjK 12:8c7394e2ae7f 120 else if (!strncmp(messageBufferIncoming, "LED3:2", sizeof("LED3:2")-1)) led3 = !led3;
AjK 12:8c7394e2ae7f 121
AjK 12:8c7394e2ae7f 122 else if (!strncmp(messageBufferIncoming, "LED4:1", sizeof("LED4:1")-1)) led4 = 1;
AjK 12:8c7394e2ae7f 123 else if (!strncmp(messageBufferIncoming, "LED4:0", sizeof("LED4:0")-1)) led4 = 0;
AjK 12:8c7394e2ae7f 124 else if (!strncmp(messageBufferIncoming, "LED4:2", sizeof("LED4:2")-1)) led4 = !led4;
AjK 12:8c7394e2ae7f 125
AjK 12:8c7394e2ae7f 126 messageReceived = false;
AjK 12:8c7394e2ae7f 127 }
AjK 12:8c7394e2ae7f 128
AjK 13:70bb7c1769fa 129 #define PIN_MESSAGE_SEND(x,y) \
AjK 13:70bb7c1769fa 130 sprintf(messageBufferOutgoing,"PIN%02d:%d\n",x,y);\
AjK 13:70bb7c1769fa 131 messageSystem.puts(messageBufferOutgoing);
AjK 12:8c7394e2ae7f 132
AjK 12:8c7394e2ae7f 133 void pin21Rise(void) { PIN_MESSAGE_SEND(21, 1); }
AjK 12:8c7394e2ae7f 134 void pin21Fall(void) { PIN_MESSAGE_SEND(21, 0); }
AjK 12:8c7394e2ae7f 135 void pin22Rise(void) { PIN_MESSAGE_SEND(22, 1); }
AjK 12:8c7394e2ae7f 136 void pin22Fall(void) { PIN_MESSAGE_SEND(22, 0); }
AjK 12:8c7394e2ae7f 137 void pin23Rise(void) { PIN_MESSAGE_SEND(23, 1); }
AjK 12:8c7394e2ae7f 138 void pin23Fall(void) { PIN_MESSAGE_SEND(23, 0); }
AjK 12:8c7394e2ae7f 139 void pin24Rise(void) { PIN_MESSAGE_SEND(24, 1); }
AjK 12:8c7394e2ae7f 140 void pin24Fall(void) { PIN_MESSAGE_SEND(24, 0); }
AjK 12:8c7394e2ae7f 141
AjK 12:8c7394e2ae7f 142 int main() {
AjK 12:8c7394e2ae7f 143
AjK 12:8c7394e2ae7f 144 messageReceived = false;
AjK 12:8c7394e2ae7f 145 messageSystem.baud(115200);
AjK 12:8c7394e2ae7f 146 messageSystem.attach(&messageReceive, MODSERIAL::RxAutoDetect);
AjK 15:a1d9e745d71e 147 messageSystem.autoDetectChar('\n');
AjK 12:8c7394e2ae7f 148
AjK 12:8c7394e2ae7f 149 // Enable pullup resistors on pins.
AjK 12:8c7394e2ae7f 150 P21.mode(PullUp); P22.mode(PullUp); P23.mode(PullUp); P24.mode(PullUp);
AjK 12:8c7394e2ae7f 151
AjK 12:8c7394e2ae7f 152 // Fix Mbed library bug, see http://mbed.org/forum/bugs-suggestions/topic/1498
AjK 12:8c7394e2ae7f 153 LPC_GPIOINT->IO2IntClr = (1UL << 5) | (1UL << 4) | (1UL << 3) | (1UL << 2);
AjK 12:8c7394e2ae7f 154
AjK 13:70bb7c1769fa 155 // Attach InterruptIn pin callbacks.
AjK 12:8c7394e2ae7f 156 P21.rise(&pin21Rise); P21.fall(&pin21Fall);
AjK 12:8c7394e2ae7f 157 P22.rise(&pin22Rise); P22.fall(&pin22Fall);
AjK 12:8c7394e2ae7f 158 P23.rise(&pin23Rise); P23.fall(&pin23Fall);
AjK 12:8c7394e2ae7f 159 P24.rise(&pin24Rise); P24.fall(&pin24Fall);
AjK 12:8c7394e2ae7f 160
AjK 12:8c7394e2ae7f 161 while(1) {
AjK 12:8c7394e2ae7f 162 // Process incoming messages.
AjK 12:8c7394e2ae7f 163 if (messageReceived) messageProcess();
AjK 12:8c7394e2ae7f 164 }
AjK 12:8c7394e2ae7f 165 }
AjK 12:8c7394e2ae7f 166
AjK 12:8c7394e2ae7f 167 #endif