# serial_hardware3

UART hardware control for USART 3

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

Description

    USART3 hardware control.
                 Routines for sending and receiving through the second [E]USART3.

Sources

    Based on the serial_hardware2.jal library by Stef Mientki.

Notes

    - See also the notes in serial_hardware library.
             Tested for baudrates from 1200 baud to 115200 baud.
           - 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_TX2_RC3 and pin_RX3_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_TX3_direction is pin_TX3_RC2_direction
                 alias  pin_RX3_direction is pin_RX3_RC1_direction

Dependencies

- usart3_common

## Summary

### Global variables/contants

- `var bit return_value = FALSE`

### Procedures

- `serial_hw3_data'put(byte in data)`
- `serial_hw3_enable()`
- `serial_hw3_data_raw'put(byte in data)`
- `serial_hw3_init()`
- `serial_hw3_write_word(word in data)`
- `serial_hw3_disable()`
- `serial_hw3_write(byte in data)`

### Functions

- `serial_hw3_read(byte out data) return bit`
- `serial_hw3_data_available() return bit`
- `serial_hw3_data'get() return byte`
- `serial_hw3_data_ready() return bit`
- `serial_hw3_data_raw'get() return byte`

Private

- `_serial_hw3_read(byte out data) return bit`

## API details

### Global variables/contants

- `var bit return_value = FALSE`

  No documentation found

### Procedures

- `serial_hw3_data'put(byte in data)`

      Title:     Transmit byte
      Arguments: Data (byte) to be transmitted
      Returns:   (nothing)
      Notes:     This pseudo variable allows a language construct like
      serial_hw3_data =
      to transmit a byte to the seial port

- `serial_hw3_enable()`

      Title:     Enable USART3
      Arguments: (none)
      Returns:   (nothing)
      Title:     Re-enable USART after use of serial_hw3_disable()

- `serial_hw3_data_raw'put(byte in data)`

      These are real raw procedures, declared as pseudo variables
      the user is totally responsible for testing the transmit/receive
      flag before using these functions

- `serial_hw3_init()`

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

- `serial_hw3_write_word(word in data)`

      Title:     Transmit word
      Arguments: Data (word) to transmit
      Returns:   (nothing)
      Notes:     Send word as 2 bytes, Most Significant Byte first.
      See also serial_hw_write()

- `serial_hw3_disable()`

      Title:     Disable USART3
      Arguments: (none)
      Returns:   (nothing)
      Notes:     Allows pins to be used (temporary) for other purposes.
      USART can be enabled again by calling serial_hw3_enable()

- `serial_hw3_write(byte in data)`

      Title:     Transmit character
      Arguments: Data (byte) to transmit
      Returns:   (nothing)
      Notes:     Hardware transmit buffer must be empty, wait if necessary

### Functions

- `serial_hw3_read(byte out data) return bit`

      Title:     Receive byte
      Arguments: (none)
      Returns:   bit:
        TRUE data available
        FALSE no data available

- `serial_hw3_data_available() return bit`

      generic (pic-independent) variable to check if a byte is received

- `serial_hw3_data'get() return byte`

      Title:     Receive byte
      Arguments: (none)
      Returns:   Data (byte) received
      Notes:     This pseudo variable allows a language construct like
      databyte = serial_hw3_data
      to receive a byte from the serial port into variable 'databyte'

- `serial_hw3_data_ready() return bit`

      generic (pic-independent) variable to check if transmit buffer is empty

- `serial_hw3_data_raw'get() return byte`

  No documentation found

Private

- `_serial_hw3_read(byte out data) return bit`

      Title:     Receive byte
      Arguments: (none)
      Returns:   bit:
        TRUE data available
        FALSE no data available
      Notes:     Using this inline function for serial_hw_data'get saves a stack level
      With overrun error the USART is reset (error(?)byte is returned!)

## Related samples

Here are the list of samples which use this library:

18f16q40 | 18f16q40_serial_hardware3.jal
18f47q43 | 18f47q43_serial_hardware3.jal