Serial Object Definitions

Due to the complex structure of the HardwareSerialRS485 template class, the specifications of the derived HardwareSerialRS485_<n> classes and Serial<n> objects are given by C preprocessor macros. Through this mechanism, declaration and implementation of the HardwareSerialRS485 classes and objects can be made consistent without having to modify multiple locations.

The header file utility/HardwareSerialRS485_configuration.h provides the definitions for the HardwareSerialRS485 classes associated with the potential hardware USART devices. For a HardwareSerialRS485_<n> class to be created, both a RS485configuration_HardwareSerialRS485<n> definition and a USART<n> device should exists.

To further ease the tailoring, the definitions are cascaded as shown here

#define RS485configuration_TRxBufferParameters 6, 6, ' '
#define RS485configuration_TRxControl TRxControl< 'B', 2, 3 >
#define RS485configuration_RS485helper RS485serial< RS485configuration_TRxControl >
#define RS485configuration_MessageFilterParameters MFP< '{', '}' >
#define RS485configuration_MessageFilter MessageFilter< RS485configuration_MessageFilterParameters >
#define RS485configuration_HardwareSerialRS485_0 HardwareSerialRS485< USART0, RS485configuration_TRxBufferParameters, RS485configuration_RS485helper, RS485configuration_MessageFilter >
#define RS485configuration_HardwareSerialRS485_1` HardwareSerialRS485< USART1, RS485configuration_TRxBufferParameters, RS485configuration_RS485helper, RS485configuration_MessageFilter >
// no default definition is given for RS485configuration_HardwareSerialRS485_2
// no default definition is given for RS485configuration_HardwareSerialRS485_3
//

These definitions reflect the default values provided by the header file HardwareSerialRS485_configuration.h. Additional code for testing if a definition already exists are, for clarity, omitted from the above extract.

In the following a short description and options for the various definitions are given.

• RS485configuration_TRxBufferParameters 6, 6, ' '

  defines, in three comma separated fields, the Tx (transmit) and Rx (receive) buffer sizes and the Rx-buffer overrun indicator.

  • the buffer sizes are specified in powers of 2, i.e. a value 6 specifies a buffersize of (1<<6) or 64 bytes;
  • the buffer overrun indicator specifies the character to be entered in the Rx buffer when the buffer is full and incoming characters will have to be dropped. A space character indicates no overrun indicator.

  Default definition. . . . . . : 6, 6, ' ' // Buffer size (Tx & Rx): 64, no Rx-buffer overrun signalling

  Alternative example . . .: 5, 7,'$' // Buffer size: 32 (Tx) and 128 (Rx), Rx overrun marked by a '$' sign.

• RS485configuration_TRxControl TRxControl< 'B', 2, 3 >

  defines the class that implements the control of the RS485 enable lines.

  This is likely the only definition that you should adapt (although not in the HarwareSerialRS485.h file) to reflect how the RS485 enable pins are connected in your hardware implementation.

  Unless in special cases where a user defined class is needed, you should use the TRxControl template class. This template class is specialized with three parameters that give the port (by character), the TxE port number (aka DE) and the RxE* port number (aka RE*).

  Example: if the hardware connects output pin B2 to the TxE input and output pin B3 to the RxE* input, you should specify TRxControl< 'B', 2, 3 >.

  Important the parameters refer to hardware port numbers and do not use the Arduino pin naming convention. Also note that the mapping of pin numbers to port number is different from the Atmega328P/Arduino-Uno and the Atmega32u4/Arduino-Leonardo/Micro.

  For efficiency this class only handles hardware configurations where the two enable pins of the RS485 transceiver are controlled by the same port register. In case this restriction does not match your hardware reality, you have to adapt the TRxControl class.

  The following definition is given as an example (and serves as default).

  Default definition. . . . . . : TRxControl< 'B', 2, 3 >

  Alternative example . . . : TheSuperDuperTRxControlClassYouWillWriteSomeday< D3, D4 >

• RS485configuration_RS485helper RS485serial< RS485configuration_TRxControl >

  defines the helper class to provide RS485 capabilities. You can define RS485configuration_RS485helper without a value to create HardwareSerialRS485 classes without RS485 capabilities.

• RS485configuration_MessageFilterParameters MFP< '{', '}' >

  defines the MessageFilterParameter class used by the message filter. Note that this definition is also used by the message reader as default MessageFilterParameter. You are advised to use the MFP template class which takes two parameters: the SOM (start of message) and EOM (end of message).

  Default definition. . . . . . : MFP< '{', '}' > // message filtering based on '{' and '}' message delimiting characters

  Alternative example . . . : MFP< 0x01, 0x04 > // alternative example: message filtering based on control characters SOH: Start of header (^A), and EOT: end of transmission (^D)

• RS485configuration_MessageFilter MessageFilter< RS485configuration_MessageFilterParameters >

  defines the message filter class used by the HardwareSerialRS485 classes. If RS485configuration_MessageFilter is defined without a value, then the HardwareSerialRS485 classes will have no filtering capabilities.

• RS485configuration_HardwareSerialRS485_0 HardwareSerialRS485< USART0, RS485configuration_TRxBufferParameters, RS485configuration_RS485helper, RS485configuration_MessageFilter >

  defines a standard HardwareSerialRS485_0 class and associated Serial0 object.

• RS485configuration_HardwareSerialRS485_1 HardwareSerialRS485< USART1, RS485configuration_TRxBufferParameters, RS485configuration_RS485helper, RS485configuration_MessageFilter >

  defines a standard HardwareSerialRS485_1 class and associated Serial1 object.

  Note that HardwareSerialRS485_1 is the defined class on Atmega32u4 processors (Leonardo/Micro)

• RS485configuration_HardwareSerialRS485_2

  there is no default definition for this class. If the user would like to define this class (on a device where USART2 exists) he will have to provide this definition.

• RS485configuration_HardwareSerialRS485_3

  there is no default definition for this class. If the user would like to define this class (on a device where USART3 exists) he will have to provide this definition.

• next: User Adaptations