serial_hw3_int_cts

Interrupt driven buffered serial interface for USART3 with flow control.

Author Rob Jansen Copyright © 2021..2021, all rights reserved.
Adapted-by
Compiler 2.5r5

Description

Serial communications for the third USART:
  - receive and transmit data transfer is interrupt driven
  - receive and transmit data transfer is buffered (circular buffers)
  - provides automatic CTS flow control with spare free space for FiFo buffer
.
This library supports:
  - Data format: 8 bits data, 1 start-bit, 1 stop bit
  - Acceptable baud rate depends on the oscillator frequency
    (see BAUD RATES tables in the datasheet).
  - Interrupt bits used: TXIE, RCIE, PEIE and GIE.
.
Available procedures/functions for application programs:
  - serial_hw3_init()                         -- initialise communications
  - serial_send3_byte(byte out )        -- send byte
                                              -- returns the transmitted byte
  - serial_hw3_read(byte out ) return bit  -- receive byte
                                              -- returns TRUE with data,
                                              -- FALSE when no data available
  - serial_hw3_write(byte in )          -- send byte (wait if queue full)
  - serial_hw3_data =                   -- send byte, wait if queue full
  - serial_hw3_tx_buffer_free()               -- get free bytes in transmit buffer
                                              -- returns number of free bytes
  -  = serial_hw3_data                  -- receive byte, wait if queue empty
.
Directions for use of this library in application programs (in this sequence):
1. Declare the following constants:
     const  serial_hw3_baudrate = 115200        -- line speed must be declared (no default)
     const bit serial3_overflow_discard = FALSE -- Transmit buffer overflow:
                                                -- -) FALSE: wait for free space (blocking)
                                                -- -) TRUE: discard data (non-blocking)
                                                -- This flag may be dynamically changed
                                                -- but must then be declared as 'var bit'


Sources

Based on the serial_hw_int_cts2.jal library by Rob Hamerling.


Notes

See serial_hw_int_cts library for background information.


Dependencies


Summary

Global variables/contants

Procedures

Private

Functions


API details

Global variables/contants

Procedures

  • serial_hw3_data'put(byte in data)

    Put byte in transmit buffer as pseudo variable
    

  • serial_hw3_init()

    Title:     Initialize second serial port
    Arguments: (none)
    Returns:   (nothing)
    
    

  • serial_hw3_write(byte in data)

    Title:     Put a single byte in transmit buffer
    Arguments: Data (byte) to transmit
    Returns    (nothing)
    Notes:     - This is a variant of serial2_send_byte() compatible with
    the procedure in the serial_hardware3 library.
     Spins when byte cannot be put in transmit buffer
    (buffer full condition).
    
    

Private

Functions

  • serial_hw3_read(byte out data) return bit

    Title:     Return byte (if any) from circular receive buffer of USART
    Arguments: received byte (if any)
    Returns:   - TRUE  when byte returned
     FALSE if no byte available
    Notes:     Sets CTS high when receive buffer has more than 
    bytes free space after delivering byte to caller.
    
    

  • serial_hw3_data_available() return bit

    generic function to check if a byte is received
    

  • serial_hw3_data_ready() return bit

    generic function to check if transmit buffer is empty
    

  • serial_hw3_tx_buffer_free() return byte

    Title:     Get free space in transmit buffer
    Arguments: (none)
    Returns:   Number of free bytes in transmit buffer
    Notes:     - Useful to check in advance if a string will fit in the buffer
    or if transmitting the string will block.
     Never returns zero. If "1" is returned, regard buffer as full.
    
    

  • serial3_send_byte(byte in data) return byte

    Title:     Put a single byte in transmit buffer
    Arguments: Data (byte) to transmit
    Returns:   transmitted byte (or 0x00 when data discarded)
    Notes:     - Activates transmit interrupt handler when data buffered
     When buffer full act as indicated in 'serial3_overflow_discard'
    * TRUE:  discard data (and return 0x00 as data byte)
    * FALSE: wait for free buffer space
    (returns only after data has been stored in buffer)
    
    

  • serial_hw3_data'get() return byte

    Return next byte from receive buffer as pseudo variable
    Spin as long as no data available (buffer empty)
    


Related samples

Here are the list of samples which use this library:

18f16q4018f16q40_serial_hw3_int_cts.jal
18f47q4318f47q43_serial_hw3_int_cts.jal