serial_hw2_int_cts

serial_hw2_int_cts.jal. Interrupt driven buffered serial interface with flow control.

Author Rob Hamerling, Copyright © 2008..2020, all rights reserved.
Adapted-by Karl "Kiste" Seitz, Rob Jansen
Compiler 2.5r4

Description

Serial communications for the second 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_hw2_init()                         -- initialise communications
.
  - serial_send2_byte(byte out )        -- send byte
                                              -- returns the transmitted byte
  - serial_hw2_read(byte out ) return bit  -- receive byte
                                              -- returns TRUE with data,
                                              -- FALSE when no data available
  - serial_hw2_write(byte in )          -- send byte (wait if queue full)
.
  - serial_hw2_data =                   -- send byte, wait if queue full
.
  - serial_hw2_tx_buffer_free()               -- get free bytes in transmit buffer
                                              -- returns number of free bytes
.
  -  = serial_hw2_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_hw2_baudrate = 115200     -- line speed must be declared (no default)
.
     const bit serial2_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'
.
                                             -- Receive buffer overflow data is
                                             -- prevented by CTS flow control, provided
                                             -- the sender has flow control enabled.
                                             -- Otherwise data discarded without notification!
.
   and an alias:
.
     alias serial2_ctsinv  is  pin_B4        -- Incoming data flow control signal
                                             -- Optional, if no CTS flow control needed
                                             -- no dummy needs to be declared.
.
   And optionally you could define one or more of the constants below.
   You should do so if you want different values than shown (= defaults).
   If not defined, the following values are used:
.
     const   SERIAL2_XMTBUFSIZE  = 32        -- size of transmit buffer
     const   SERIAL2_RCVBUFSIZE  = 64        -- size of receive buffer
     const   SERIAL2_DELTA       = 17        -- spare space receive buffer
                                             -- if possible keep SERIAL2_DELTA = 17!
.
   When the physical locations of pin_TX2 and pin_RX2 are configurable for a specific
   PIC, the device file will probably contain names like pin_TX2_RC2 and pin_RX2_RC1
   and another pair with other pin suffixes.
   Depending for which pair of pins the USART is configured aliases
   without suffixes have to be specified, like:
        alias  pin_TX2            is  pin_TX2_RC2
        alias  pin_RX2            is  pin_RX2_RC1
        alias  pin_TX2_direction  is  pin_TX2_RC2_direction
        alias  pin_RX2_direction  is  pin_RX2_RC1_direction
.
2. Include this library.
.
and somewhere before actually using serial communications:
.
3. Prepare pins
      pin_B4_direction = OUTPUT              -- incoming data flow control
   Notes: - pin_TX2 and pin_RX2 are selected automatically
          - direction settings of these pins are taken care of by the library
.
4. Call serial_hw2_init() to initialize serial communications.


Notes

See serial_hw_int_cts library


Dependencies


Summary

Global variables/contants

Procedures

Private

Functions


API details

Global variables/contants

Procedures

  • serial_hw2_data'put(byte in data)

    Put byte in transmit buffer as pseudo variable
    

  • serial_hw2_init()

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

  • serial_hw2_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_hardware2 library.
     Spins when byte cannot be put in transmit buffer
    (buffer full condition).
    
    

Private

Functions

  • serial_hw2_data_ready() return bit

    generic function to check if transmit buffer is empty
    

  • serial2_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 'serial2_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_hw2_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.
    
    

  • serial_hw2_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_hw2_data_available() return bit

    generic function to check if a byte is received
    

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

16f1532516f15325_bluetooth_hc05_master.jal
16f1532516f15325_bluetooth_hc06_slave.jal
16f1801516f18015_serial_speed_converter.jal
16f1917616f19176_esp8266_tcp_server.jal
16f1917616f19176_esp8266_web_server_led.jal
16f1917616f19176_serial_hw2_int_cts.jal
16f1917616f19176_esp8266_connect.jal
16f1917616f19176_esp8266_web_server.jal
16f1917616f19176_esp8266_tcp_server_led.jal
16f1917616f19176_dfplayer.jal
16f1917616f19176_esp8266_web_client.jal
16f194716f1947_serial_hw2_int_cts.jal
18f25k2218f25k22_serial_speed_converter.jal
18f26k4218f26k42_serial_hw2_int_cts.jal
18f47q4318f47q43_serial_hw2_int_cts.jal
18f631018f6310_serial_speed_converter.jal
18f672218f6722_serial_hw2_int_cts.jal