Add Flow Control and Buffering to Serial Routines
A feature of the compiler is the powerful #use rs232() library that has added transmit buffering, receive buffering, and flow control. While the API for the serial library remains unchanged ( getc(), putc(), printf() ), existing code using this API allows for buffering and flow control by simply modifying the #use rs232() parameters. A user may specify:
* size of transmit buffer
* size of receive buffer
* interrupt usage or no interrupt usage
* pin for CTS and pin for RTS
Click through to: https://www.ccsinfo.com/Version5
to review a usage example of the #use rs232() and additional details on each new usage. Additional configurations and control options are also available.
Notifications From the Serial Library on Data Reception
The compiler provides an extremely flexibly serial library; it has the ability to use the hardware peripheral or bit bang the pins, to control and monitor flow control, to specify parity, to use a one wire bus, and more. One feature it has is the ability to specify a receive buffer, and the library will automatically use the receive interrupt to buffer incoming characters. Here is an example of creating a stream called STREAM_UART1 on the UART1 hardware peripheral with a 16 byte receive buffer:
#use rs232(UART1, baud=9600, receive_buffer=16, stream=STREAM_UART1)
Essentially the stream works like a file handle that can be used with C standard I/O functions like fputc, fgetc, etc. Using the stream created above, here is a simple loop that echoes data received on the UART back to the UART:
while (kbhit(STREAM_UART1))
{
fputc(fgetc(STREAM_UART1), STREAM_UART1);
}
This example shows the flexibility of the #use rs232() library provided by CCS. The 'receive_buffer' option creates an interrupt on the UART receive to buffer incoming characters and kbhit() and fgetc() accesses that buffer, but if the 'receive_buffer' was removed from the #use rs232(), then kbhit() and fgetc() would instead check for any received data being held by the UART.
The 'receive_buffer' example as shown above has no way of notifying the users software that data is available, except by polling the receive buffer status with kbhit(). The 5.095 version of the CCS C Compiler adds a new option called 'callback' that allows the user to specify a function to be called when the receive buffer goes from empty to not empty. This could be used to mark a semaphore or enable a routine to start parsing data in the receive buffer. Here is an example of adding this new option:
#use rs232(UART1, baud=9600, receive_buffer=16, stream=STREAM_UART1, \
callback=Uart1OnRx)
As stated earlier, this example will call the 'Uart1OnRx' function whenever the receive buffer goes from empty to not empty. Here is how the earlier echo example can be changed to use an RTOS with a semaphore to mark when the receive buffer is ready:
#use rtos(timer=0)
int uart_sem = 0;
static void Uart1OnRx(void) {
rtos_signal(uart_sem);
}
#task(rate=10ms)
static void Uart1Task(void) {
for(;;) {
rtos_wait(uart_sem);
while(kbhit(STREAM_UART1)) {
fputc(fgetc(STREAM_UART1), STREAM_UART1);
}
}
}
Alternatively, a function for parsing data in the receive buffer can be queued for execution with the timeouts library:
#include <timeouts.c>
void Uart1OnxTimeout(void* pArgs) {
while(kbhit(STREAM_UART1)) {
putc(getc(STREAM_UART1), STREAM_UART1);
}
}
static void Uart1OnRx(void) {
TimeoutsAdd(Uart1OnxTimeout, NULL, 0);
}
The #USE RS232 (and I2C for that matter) is in effect for GETC, PUTC, PRINTF and KBHIT functions encountered until another #USE RS232 is found.
The #USE RS232 is not an executable line. It works much like a #DEFINE. The following is an example program to read from one port (A) and echo the data to both the first port (A) and a second port (B).
#USE RS232(BAUD=9600, XMIT=PIN_B0, RCV=PIN_B1)
void put_to_a( char c ) {
put(c);
}
char get_from_a( ) {
return(getc());
}
#USE RS232(BAUD=9600, XMIT=PIN_B2,RCV=PIN_B3)
void put_to_b( char b ) {
putc(c);
}
main() {
char c;
put_to_a("Online\n\r");
put_to_b("Online\n\r");
while(TRUE) {
c=get_from_a();
put_to_b(c);
put_to_a(c);
}
}
The following will do the same thing but is more readable and is the recommended method:
#USE RS232(BAUD=9600, XMIT=PIN_B0, RCV=PIN_B1, STREAM=COM_A)
#USE RS232(BAUD=9600, XMIT=PIN_B2, RCV=PIN_B3, STREAM=COM_B)
main() {
char c;
fprintf(COM_A,"Online\n\r");
fprintf(COM_B,"Online\n\r");
while(TRUE) {
c = fgetc(COM_A);
fputc(c, COM_A);
fputc(c, COM_B);
}
}
