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:-

/media/uploads/mbedofficial/serial_interfaces.png

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"
2
3  Serial pc(USBTX, USBRX); // tx, rx
4 
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
4 
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"
2
3  #define MODSERIAL_DEFAULT_RX_BUFFER_SIZE 512
4  #define MODSERIAL_DEFAULT_TX_BUFFER_SIZE 1024 
5  #include "MODSERIAL.h"
6
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"
3
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"
3
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
4 
5  int main() {
6
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     }
11
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
4 
5  int main() {
6      int result;
7
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     }
11
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.baud(9600);
    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.



Committer:
AjK
Date:
Sat Nov 20 16:54:05 2010 +0000
Revision:
0:eb2522b41db8
Child:
2:b936b4acbd92
1.0

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AjK 0:eb2522b41db8 1 /*
AjK 0:eb2522b41db8 2 Copyright (c) 2010 Andy Kirkham
AjK 0:eb2522b41db8 3
AjK 0:eb2522b41db8 4 Permission is hereby granted, free of charge, to any person obtaining a copy
AjK 0:eb2522b41db8 5 of this software and associated documentation files (the "Software"), to deal
AjK 0:eb2522b41db8 6 in the Software without restriction, including without limitation the rights
AjK 0:eb2522b41db8 7 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
AjK 0:eb2522b41db8 8 copies of the Software, and to permit persons to whom the Software is
AjK 0:eb2522b41db8 9 furnished to do so, subject to the following conditions:
AjK 0:eb2522b41db8 10
AjK 0:eb2522b41db8 11 The above copyright notice and this permission notice shall be included in
AjK 0:eb2522b41db8 12 all copies or substantial portions of the Software.
AjK 0:eb2522b41db8 13
AjK 0:eb2522b41db8 14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
AjK 0:eb2522b41db8 15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
AjK 0:eb2522b41db8 16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AjK 0:eb2522b41db8 17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
AjK 0:eb2522b41db8 18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
AjK 0:eb2522b41db8 19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
AjK 0:eb2522b41db8 20 THE SOFTWARE.
AjK 0:eb2522b41db8 21 */
AjK 0:eb2522b41db8 22
AjK 0:eb2522b41db8 23 #include "MODSERIAL.h"
AjK 0:eb2522b41db8 24 #include "MACROS.h"
AjK 0:eb2522b41db8 25
AjK 0:eb2522b41db8 26 namespace AjK {
AjK 0:eb2522b41db8 27
AjK 0:eb2522b41db8 28 MODSERIAL::MODSERIAL(PinName tx, PinName rx, const char *name) : Serial(tx, rx, name)
AjK 0:eb2522b41db8 29 {
AjK 0:eb2522b41db8 30 init(MODSERIAL_DEFAULT_TX_BUFFER_SIZE, MODSERIAL_DEFAULT_RX_BUFFER_SIZE);
AjK 0:eb2522b41db8 31 }
AjK 0:eb2522b41db8 32
AjK 0:eb2522b41db8 33 MODSERIAL::MODSERIAL(PinName tx, PinName rx, int bufferSize, const char *name) : Serial(tx, rx, name)
AjK 0:eb2522b41db8 34 {
AjK 0:eb2522b41db8 35 init(bufferSize, bufferSize);
AjK 0:eb2522b41db8 36 }
AjK 0:eb2522b41db8 37
AjK 0:eb2522b41db8 38 MODSERIAL::MODSERIAL(PinName tx, PinName rx, int txSize, int rxSize, const char *name) : Serial(tx, rx, name)
AjK 0:eb2522b41db8 39 {
AjK 0:eb2522b41db8 40 init(txSize, rxSize);
AjK 0:eb2522b41db8 41 }
AjK 0:eb2522b41db8 42
AjK 0:eb2522b41db8 43 MODSERIAL::~MODSERIAL()
AjK 0:eb2522b41db8 44 {
AjK 0:eb2522b41db8 45 disableIrq();
AjK 0:eb2522b41db8 46 if (buffer[0] != NULL) free((char *)buffer[0]);
AjK 0:eb2522b41db8 47 if (buffer[1] != NULL) free((char *)buffer[1]);
AjK 0:eb2522b41db8 48 }
AjK 0:eb2522b41db8 49
AjK 0:eb2522b41db8 50 bool
AjK 0:eb2522b41db8 51 MODSERIAL::txBufferFull(void)
AjK 0:eb2522b41db8 52 {
AjK 0:eb2522b41db8 53 return MODSERIAL_TX_BUFFER_FULL;
AjK 0:eb2522b41db8 54 }
AjK 0:eb2522b41db8 55
AjK 0:eb2522b41db8 56 bool
AjK 0:eb2522b41db8 57 MODSERIAL::rxBufferFull(void)
AjK 0:eb2522b41db8 58 {
AjK 0:eb2522b41db8 59 return MODSERIAL_RX_BUFFER_FULL;
AjK 0:eb2522b41db8 60 }
AjK 0:eb2522b41db8 61
AjK 0:eb2522b41db8 62 bool
AjK 0:eb2522b41db8 63 MODSERIAL::txBufferEmpty(void)
AjK 0:eb2522b41db8 64 {
AjK 0:eb2522b41db8 65 return MODSERIAL_TX_BUFFER_EMPTY;
AjK 0:eb2522b41db8 66 }
AjK 0:eb2522b41db8 67
AjK 0:eb2522b41db8 68 bool
AjK 0:eb2522b41db8 69 MODSERIAL::rxBufferEmpty(void)
AjK 0:eb2522b41db8 70 {
AjK 0:eb2522b41db8 71 return MODSERIAL_RX_BUFFER_EMPTY;
AjK 0:eb2522b41db8 72 }
AjK 0:eb2522b41db8 73
AjK 0:eb2522b41db8 74 void
AjK 0:eb2522b41db8 75 MODSERIAL::disableIrq(void)
AjK 0:eb2522b41db8 76 {
AjK 0:eb2522b41db8 77 switch(_uidx) {
AjK 0:eb2522b41db8 78 case 0: NVIC_DisableIRQ(UART0_IRQn); break;
AjK 0:eb2522b41db8 79 case 1: NVIC_DisableIRQ(UART1_IRQn); break;
AjK 0:eb2522b41db8 80 case 2: NVIC_DisableIRQ(UART2_IRQn); break;
AjK 0:eb2522b41db8 81 case 3: NVIC_DisableIRQ(UART3_IRQn); break;
AjK 0:eb2522b41db8 82 }
AjK 0:eb2522b41db8 83 }
AjK 0:eb2522b41db8 84
AjK 0:eb2522b41db8 85 void
AjK 0:eb2522b41db8 86 MODSERIAL::enableIrq(void)
AjK 0:eb2522b41db8 87 {
AjK 0:eb2522b41db8 88 switch(_uidx) {
AjK 0:eb2522b41db8 89 case 0: NVIC_EnableIRQ(UART0_IRQn); break;
AjK 0:eb2522b41db8 90 case 1: NVIC_EnableIRQ(UART1_IRQn); break;
AjK 0:eb2522b41db8 91 case 2: NVIC_EnableIRQ(UART2_IRQn); break;
AjK 0:eb2522b41db8 92 case 3: NVIC_EnableIRQ(UART3_IRQn); break;
AjK 0:eb2522b41db8 93 }
AjK 0:eb2522b41db8 94 }
AjK 0:eb2522b41db8 95
AjK 0:eb2522b41db8 96 }; // namespace AjK ends