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:
Thu Jan 20 11:57:32 2011 +0000
Revision:
12:8c7394e2ae7f
Parent:
11:a93a62eeeb9d
1.12 See ChangeLog

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AjK 12:8c7394e2ae7f 1 #ifdef COMPILE_EXAMPLE_CODE_MODSERIAL_MODDMA
AjK 12:8c7394e2ae7f 2
AjK 12:8c7394e2ae7f 3 /*
AjK 12:8c7394e2ae7f 4 * To run this test program, link p9 to p10 so the Serial loops
AjK 12:8c7394e2ae7f 5 * back and receives characters it sends.
AjK 12:8c7394e2ae7f 6 */
AjK 12:8c7394e2ae7f 7
AjK 12:8c7394e2ae7f 8 #include "mbed.h"
AjK 12:8c7394e2ae7f 9
AjK 12:8c7394e2ae7f 10 /* Note, this example requires that you also import into the Mbed
AjK 12:8c7394e2ae7f 11 compiler the MODDMA project as well as MODSERIAL
AjK 12:8c7394e2ae7f 12 http://mbed.org/users/AjK/libraries/MODDMA/latest
AjK 12:8c7394e2ae7f 13 MODDMA.h MUST come before MODSERIAL.h */
AjK 12:8c7394e2ae7f 14 #include "MODDMA.h" // <--- Declare first
AjK 12:8c7394e2ae7f 15 #include "MODSERIAL.h" // Flollowed by MODSERIAL
AjK 12:8c7394e2ae7f 16
AjK 12:8c7394e2ae7f 17 DigitalOut led1(LED1);
AjK 12:8c7394e2ae7f 18 DigitalOut led2(LED2);
AjK 12:8c7394e2ae7f 19 DigitalOut led3(LED3);
AjK 12:8c7394e2ae7f 20 DigitalOut led4(LED4);
AjK 12:8c7394e2ae7f 21
AjK 12:8c7394e2ae7f 22 MODSERIAL pc(USBTX, USBRX);
AjK 12:8c7394e2ae7f 23
AjK 12:8c7394e2ae7f 24 /*
AjK 12:8c7394e2ae7f 25 * As experiement, you can define MODSERIAL as show here and see what
AjK 12:8c7394e2ae7f 26 * effects it has on the LEDs.
AjK 12:8c7394e2ae7f 27 *
AjK 12:8c7394e2ae7f 28 * MODSERIAL uart(TX_PIN, RX_PIN, 512);
AjK 12:8c7394e2ae7f 29 * With this, the 512 characters sent can straight into the buffer
AjK 12:8c7394e2ae7f 30 * vary quickly. This means LED1 is only on briefly as the TX buffer
AjK 12:8c7394e2ae7f 31 * fills.
AjK 12:8c7394e2ae7f 32 *
AjK 12:8c7394e2ae7f 33 * MODSERIAL uart(TX_PIN, RX_PIN, 32);
AjK 12:8c7394e2ae7f 34 * With this, the buffer is smaller than the default 256 bytes and
AjK 12:8c7394e2ae7f 35 * therefore LED1 stays on much longer while the system waits for
AjK 12:8c7394e2ae7f 36 * room in the TX buffer.
AjK 12:8c7394e2ae7f 37 */
AjK 12:8c7394e2ae7f 38 MODSERIAL uart(TX_PIN, RX_PIN);
AjK 12:8c7394e2ae7f 39
AjK 12:8c7394e2ae7f 40 MODDMA dma;
AjK 12:8c7394e2ae7f 41
AjK 12:8c7394e2ae7f 42 // This function is called when a character goes from the TX buffer
AjK 12:8c7394e2ae7f 43 // to the Uart THR FIFO register.
AjK 12:8c7394e2ae7f 44 void txCallback(void) {
AjK 12:8c7394e2ae7f 45 led2 = !led2;
AjK 12:8c7394e2ae7f 46 }
AjK 12:8c7394e2ae7f 47
AjK 12:8c7394e2ae7f 48 // This function is called when TX buffer goes empty
AjK 12:8c7394e2ae7f 49 void txEmpty(void) {
AjK 12:8c7394e2ae7f 50 led2 = 0;
AjK 12:8c7394e2ae7f 51 pc.puts(" Done. ");
AjK 12:8c7394e2ae7f 52 }
AjK 12:8c7394e2ae7f 53
AjK 12:8c7394e2ae7f 54 void dmaComplete(void) {
AjK 12:8c7394e2ae7f 55 led1 = 1;
AjK 12:8c7394e2ae7f 56 }
AjK 12:8c7394e2ae7f 57
AjK 12:8c7394e2ae7f 58 // This function is called when a character goes into the RX buffer.
AjK 12:8c7394e2ae7f 59 void rxCallback(void) {
AjK 12:8c7394e2ae7f 60 led3 = !led3;
AjK 12:8c7394e2ae7f 61 pc.putc(uart.getc());
AjK 12:8c7394e2ae7f 62 }
AjK 12:8c7394e2ae7f 63
AjK 12:8c7394e2ae7f 64 int main() {
AjK 12:8c7394e2ae7f 65 char s1[] = " *DMA* *DMA* *DMA* *DMA* *DMA* *DMA* *DMA* ";
AjK 12:8c7394e2ae7f 66 int c = 'A';
AjK 12:8c7394e2ae7f 67
AjK 12:8c7394e2ae7f 68 // Tell MODSERIAL where the MODDMA controller is.
AjK 12:8c7394e2ae7f 69 pc.MODDMA( &dma );
AjK 12:8c7394e2ae7f 70
AjK 12:8c7394e2ae7f 71 // Ensure the baud rate for the PC "USB" serial is much
AjK 12:8c7394e2ae7f 72 // higher than "uart" baud rate below.
AjK 12:8c7394e2ae7f 73 pc.baud( PC_BAUD );
AjK 12:8c7394e2ae7f 74
AjK 12:8c7394e2ae7f 75 // Use a deliberatly slow baud to fill up the TX buffer
AjK 12:8c7394e2ae7f 76 uart.baud(1200);
AjK 12:8c7394e2ae7f 77
AjK 12:8c7394e2ae7f 78 uart.attach( &txCallback, MODSERIAL::TxIrq );
AjK 12:8c7394e2ae7f 79 uart.attach( &rxCallback, MODSERIAL::RxIrq );
AjK 12:8c7394e2ae7f 80 uart.attach( &txEmpty, MODSERIAL::TxEmpty );
AjK 12:8c7394e2ae7f 81
AjK 12:8c7394e2ae7f 82 // Loop sending characters. We send 512
AjK 12:8c7394e2ae7f 83 // which is twice the default TX/RX buffer size.
AjK 12:8c7394e2ae7f 84
AjK 12:8c7394e2ae7f 85 led1 = 0;
AjK 12:8c7394e2ae7f 86
AjK 12:8c7394e2ae7f 87 // Send the buffer s using DMA channel 7
AjK 12:8c7394e2ae7f 88 pc.attach_dmaSendComplete( &dmaComplete );
AjK 12:8c7394e2ae7f 89 pc.dmaSend( s1, sizeof(s1), MODDMA::Channel_7 );
AjK 12:8c7394e2ae7f 90
AjK 12:8c7394e2ae7f 91 for (int loop = 0; loop < 512; loop++) {
AjK 12:8c7394e2ae7f 92 uart.printf("%c", c);
AjK 12:8c7394e2ae7f 93 c++;
AjK 12:8c7394e2ae7f 94 if (c > 'Z') c = 'A';
AjK 12:8c7394e2ae7f 95 }
AjK 12:8c7394e2ae7f 96
AjK 12:8c7394e2ae7f 97 led1 = 0; // Show the end of sending by switching off LED1.
AjK 12:8c7394e2ae7f 98
AjK 12:8c7394e2ae7f 99 // End program. Flash LED4. Notice how LED 2 and 3 continue
AjK 12:8c7394e2ae7f 100 // to flash for a short period while the interrupt system
AjK 12:8c7394e2ae7f 101 // continues to send the characters left in the TX buffer.
AjK 12:8c7394e2ae7f 102
AjK 12:8c7394e2ae7f 103 while(1) {
AjK 12:8c7394e2ae7f 104 led4 = !led4;
AjK 12:8c7394e2ae7f 105 wait(0.25);
AjK 12:8c7394e2ae7f 106 }
AjK 12:8c7394e2ae7f 107 }
AjK 12:8c7394e2ae7f 108
AjK 12:8c7394e2ae7f 109 /*
AjK 12:8c7394e2ae7f 110 * Notes. Here is the sort of output you can expect on your PC/Mac/Linux host
AjK 12:8c7394e2ae7f 111 * machine that is connected to the "pc" USB serial port.
AjK 12:8c7394e2ae7f 112 *
AjK 12:8c7394e2ae7f 113 * *DMA* *DMA* *DMA* *DMA* *DMA* *DMA* *DMA* ABCDEFGHIJKLMNOPQRSTUVWXYZABCDE
AjK 12:8c7394e2ae7f 114 * FGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZA
AjK 12:8c7394e2ae7f 115 * BCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVW
AjK 12:8c7394e2ae7f 116 * XYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRS
AjK 12:8c7394e2ae7f 117 * TUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNO
AjK 12:8c7394e2ae7f 118 * PQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJK
AjK 12:8c7394e2ae7f 119 * LMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFG
AjK 12:8c7394e2ae7f 120 * HIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQ Done. R
AjK 12:8c7394e2ae7f 121 *
AjK 12:8c7394e2ae7f 122 * Note how the DMA blocks the TX buffer sending under standard interrupt control.
AjK 12:8c7394e2ae7f 123 * Not until the DMA transfer is complete will "normal" buffered TX sending resume.
AjK 12:8c7394e2ae7f 124 *
AjK 12:8c7394e2ae7f 125 * Of interest is that last "R" character after the system has said "Done."
AjK 12:8c7394e2ae7f 126 * This comes from the fact that the TxEmpty callback is made when the TX buffer
AjK 12:8c7394e2ae7f 127 * becomes empty. MODSERIAL makes use of the fact that the Uarts built into the
AjK 12:8c7394e2ae7f 128 * LPC17xx device use a 16 byte FIFO on both RX and TX channels. This means that
AjK 12:8c7394e2ae7f 129 * when the TxEmpty callback is made, the TX buffer is empty, but that just means
AjK 12:8c7394e2ae7f 130 * the "last few characters" were written to the TX FIFO. So although the TX
AjK 12:8c7394e2ae7f 131 * buffer has gone empty, the Uart's transmit system is still sending any remaining
AjK 12:8c7394e2ae7f 132 * characters from it's TX FIFO. If you want to be truely sure all the characters
AjK 12:8c7394e2ae7f 133 * you have sent have left the Mbed then call txIsBusy(); This function will
AjK 12:8c7394e2ae7f 134 * return true if characters are still being sent. If it returns false after
AjK 12:8c7394e2ae7f 135 * the Tx buffer is empty then all your characters have been sent.
AjK 12:8c7394e2ae7f 136 *
AjK 12:8c7394e2ae7f 137 * In a similar way, when characters are received into the RX FIFO, the entire
AjK 12:8c7394e2ae7f 138 * FIFO contents is moved to the RX buffer, assuming there is room left in the
AjK 12:8c7394e2ae7f 139 * RX buffer. If there is not, any remaining characters are left in the RX FIFO
AjK 12:8c7394e2ae7f 140 * and will be moved to the RX buffer on the next interrupt or when the running
AjK 12:8c7394e2ae7f 141 * program removes a character(s) from the RX buffer with the getc() method.
AjK 12:8c7394e2ae7f 142 */
AjK 12:8c7394e2ae7f 143
AjK 12:8c7394e2ae7f 144 #endif