-
Notifications
You must be signed in to change notification settings - Fork 29
Software Description
You may want to skip this chapter if you do not want (and need) to know these details (with a possible exception for the sections on HardwareSerialRS485, HardwareSerialRS485_configuration and RS485CommandResponse).
Preamble: This project makes extensive use of template classes. The use of templates allows for a high degree of code configuration options that are resolved at compile time, leading to improved code performance. Template parameters are used in this project to enhance functionality through supplied helper classes, as well as for various configurable parameters, such as buffer sizes, buffer overrun policy, RS485 enable wirings, etc.
Another design choice is that header files contains the code for both class definition and class implementation. The majority of method implementations are given as in-line code in the class definition. However, also the implementation of non in-line methods as well as the static class variables is given in the header files. This class implementation code is activated, under #ifdef preprocessor control, when the header files are included from the almost empty class implementation files (see e.g. HardwareSerialRS485.cpp).
The following sections describe the files and classes that are part of the HardwareSerialRS485 library. All described files are located under the folder HardwareSerialRS485/src unless indicated otherwise.
This header file serves as a library wrapper and #includes all other needed header files. This header also checks for potential conflict with the classical HardwareSerial header file from the Arduino project. The header file should be included before the Arduino.h header is included (whether directly, or indirectly by another included header file). To avoid conflicts, the inclusion of this header file inhibits the loading of the classical HardwareSerial header file from the Arduino project.
This header file, which is #included by the HardwareSerialRS485 header file, specifies the implementation details and options of the Serial objects. This file can be tailored to user requirements. However, the user is advised to copy this file to a user specific location in his project folder. (For more detail on tailoring the RS485 configuration, please see the section Configuration and serial object definition below).
This header file contains the rewritten HardwareSerial class. This class is backward compatible with the classical HardwareSerial class provided in the Arduino project in release V1.05 and up (tested up to V1.6.5). This is a template class, which by default does not provide additional functionality. Extensions are activated by passing helper class specifications through the template parameters. This particular choice was made such that the class stays lean and efficient in case no additional functionality is required.
This header file contains the helper class RS485serial, which can be passed by a template parameter to the HardwareSerialRS485 class to provide the RS485 capabilities. The RS485Serial class is itself implemented as a template class and takes as a parameter the TRxControl class (also included in this header file), which specifies the wiring of the RS485 enable lines to the Atmega/Arduino.
This header file provides a diagnostics tracer function which keeps track of the most recent internal state changes. This facility is used for debugging and is inactive by default. Tracing can be activated by defining the macro RS485configuration_useTRACE (either in the HardwareSerialRS485_configuration.h or in boards.txt).
When tracing is activated, a trace history dump will be included in the output of the diagnostics() method.
This header file contains the helper class MessageFilter, which can be passed by a template parameter to the HardwareSerialRS485 class to provide message filtering capabilities. The MessageFilter class is itself implemented as a template class and takes as a parameter an MFP class (two versions included in this header file), which specifies the message filtering protocol.
This header file contains the MessageReader class, a client level message reader. The MessageReader class, which also does message recognition and filtering, is implemented as a sub-class of the MessageFilter class. Furthermore, this class will properly flag the user when a complete message is available without the overhead of blocking for a finite time to ascertain that no new characters have arrived (as is done by the Stream class).
The header file USARTdef.h provides ‘normalized’ definitions of the USART parameters for USARTn (where n=0 … 3). The code generates for each available USART a dedicated state-less parameter class. These USART classes are used for the T__USART template parameter of the HardwareSerialRS485_Enabled template class.
This header file provides template functions for type independent bit manipulation functions. This is a general purpose library that may serve various purposes also outside the HardwareSerialRS485 context. (Arduino project/community).
This header file provides a simple wrapper class SerialUSBSwitch to support the demo sketch in the Leonardo or Micro environment. This class facilitate switching between RS485 via the USART and USB serial via the Serial_ class (as defined in USBAPI.h).
The example demo sketch RS485CommandResponse allows for switching between various communication modes and implements some rudimentary commands for echo and information printing. Some diagnostic facilities are provided.
This sketch makes further use of an (embedded) ApplicationControl class, which maintains the settings for the communication mode and provides various functions.
To support the demo sketch in the Leonardo or Micro environment, this sketch also makes use of the SerialUSBSwitch class described above. Note that the usage of the SerialUSBSwitch class is only required if you would like to switch dynamically between two communication channels.
Due to the implementation of the USART parameters as a static class that is passed by a template parameter to the HardwareSerialRS485 class, the HardwareSerialRS485 class handles only one USART per template instance. In case more than one Serial object is required for systems with more than one USART, each Serial object will need its own instance of the template class. While for single USART devices the template based solution will lead to efficient and compact code (as many addresses can be resolved at compile time), for devices with several USART there could be a code size penalty (however, there is no execution speed overhead). This issue will be further investigated (and if needed improved) in a future release.
Examples: