serial_hw_int_cts

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

Author Rob Hamerling, Copyright © 2008..2015, all rights reserved.
Adapted-by Joep Suijs
Compiler 2.4q3

Description

Serial communications for first or only 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_hw_init()                          -- initialize communications
.
  - serial_send_byte(byte out )         -- send byte
                                              -- returns the transmitted byte
  - serial_hw_read(byte out ) return bit  -- receive byte
                                              -- returns TRUE with data,
                                              -- FALSE when no data available
  - serial_hw_write(byte in )           -- send byte (wait if queue full)
.
  - serial_hw_data =                    -- send byte, wait if queue full
.
  - serial_hw_tx_buffer_free()                -- get free bytes in transmit buffer
                                              -- returns number of free bytes
.
  -  = serial_hw_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_hw_baudrate = 115200      -- line speed must be declared (no default)
.
     const bit serial_overflow_discard = TRUE  -- 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 serial_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 (= default).
   If not defined, the following values are used:
.
     const   SERIAL_XMTBUFSIZE  = 32         -- size of transmit buffer
     const   SERIAL_RCVBUFSIZE  = 64         -- size of receive buffer
     const   SERIAL_DELTA       = 17         -- spare space receive buffer
                                             -- if possible keep SERIAL_DELTA = 17!
.
   When the physical locations of pin_TX and pin_RX are configurable for a specific
   PIC, the device file will probably contain names like pin_TX_RB2 and pin_RX_RB1
   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_TX            is  pin_TX_RB2
        alias  pin_RX            is  pin_RX_RB1
        alias  pin_TX_direction  is  pin_TX_RB2_direction
        alias  pin_RX_direction  is  pin_RX_RB1_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_TX and pin_RX are selected automatically
          - direction settings of these pins are taken care of by the library
.
4. Call serial_hw_init() to initialize serial communications.


Notes

Background information:
.
The PIC ports use positive logic: '1' is positive voltage, '0' is ground.
.
In the RS232 standard:
- Negative voltage ('mark') means OFF for control signals, and
  indicates 1 (one) for data signals (start-, data-, stop-bits).
- Positive voltage ('space') means ON for control signals and
  0 (zero) for start-, data- and stop-bits.
- Signal levels: 'mark' = -3V to -15V,  'space' = +3V to +15V
.
Between PIC and RS232 normally an interface chip is used, such as a
Maxim/Dallas MAX232 or MAX202. These are not only voltage level CONverters
but also signal INverters. You should be aware of the following:
- The inversion of PIC data-in and data-out by the MAX2x2 is required
  to convert data-, start- and stop-bits to/from the corresponding
  RS232 polarity. So nothing special has to be done in the program
  because the USART of the PIC uses 'inverted' signal levels!
- For CTS the inversion by the MAX2x2 is NOT desired.
  Therefore the program has to use inverted signalling for CTS:
  'FALSE' is used for CTS ON and 'TRUE' for CTS OFF!
  As a reminder for this 'inverted' logic the signal is called
  serial_ctsinv (serial_ctsinv = TRUE means CTS is FALSE!).
.
Remember also: RxD of RS232-plug connects to TX of PIC via MAX2x2
               TxD of RS232-plug connects to RX of PIC via MAX2x2
.
Additional remarks:
 - The selection of the CTS pin above is an example, any other pin
   which is configurable for output can be used.
 - Do not touch the following interrupt bits: TXIE, RCIE, PEIE and GIE


Dependencies


Summary

Global variables/contants

Procedures

Private

Functions


API details

Global variables/contants

Procedures

  • serial_init()

    Deprecated
    

  • serial_hw_data'put(byte in data)

    Put byte in transmit buffer as pseudo variable
    

  • serial_hw_init()

    Title:     Initialize first or only serial port
    Arguments: (none)
    Returns:   (nothing)
    
    

  • serial_hw_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 serial_send_byte() compatible with
    the procedure in the serial_hardware library.
     Spins when byte cannot be put in transmit buffer
    (buffer full condition).
    
    

Private

Functions

  • serial_hw_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_hw_data'get() return byte

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

  • serial_receive_byte(byte out data) return bit

    Deprecated function -------------------
    

  • serial_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 'serial_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_hw_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.
    
    


Related samples

Here are the list of samples which use this library:

16f648a16f648a_serial_hw_int_cts.jal
16f72316f723_serial_hw_int_cts.jal
16f7316f73_serial_hw_int_cts.jal
16f87716f877_serial_hw_int_cts.jal
16f877a16f877a_serial_hw_int_cts.jal
16f877a16f877a_glcd_t6963.jal
16f8816f88_serial_hw_int_cts.jal
16f8816f88_serial_hw_int_cts_echo.jal
18f14k5018f14k50_serial_hw_int_cts.jal
18f245018f2450_serial_hw_int_cts.jal
18f24k2018f24k20_charlie_lolshield_ticker1.jal
18f252018f2520_serial_hw_int_cts.jal
18f255018f2550_serial_hw_int_cts.jal
18f258518f2585_canid4_serial_adapter.jal
18f258518f2585_can_serial_adapter.jal
18f25k2218f25k22_serial_speed_converter.jal
18f262018f2620_serial_hw_int_cts.jal
18f45218f452_serial_hw_int_cts.jal
18f455018f4550_serial_hw_int_cts.jal
18f462018f4620_serial_hw_int_cts.jal
18f631018f6310_serial_speed_converter.jal
18f67j5018f67j50_serial_hw_int_cts.jal