SerialChecker is an Arduino based class for the easy handling of serial messages. SerialChecker can be used to check incoming messages
More...

#include <SerialChecker.h>

Public Member Functions
	SerialChecker ()
	Constructs the object. Dynamically creates a char array to hold message buffers. Assigns the the default arduino serial port.

	SerialChecker (uint16_t msgMaxLen, HardwareSerial &HSerial, uint32_t baudrate)
	Constructs the object. As above but lets user choose serial port and baudrate. More...

	~SerialChecker ()
	Destroys the object and frees the memory used by message buffer.

void	init ()
	This is functionally the same as Serial.begin(baudrate);.

void	disableACKNAK ()
	Disables the use of Acknowledge and Naknowledge messages. This really only disables the use of NAK messages. The user must choose to send an ACK with sendACK() command.

void	enableACKNAK ()
	Enables the use of Acknowledge and Naknowledge messages. If an invalid message is received then a NAK is returned to the sender. This uses the default ACK and NAK chars, 'A' and 'N'. NAKs get sent when a message does not start with the start char, if use of STX is required, see enableSTX(). NAKs also get sent if the message is below the minimum length set by setMsgMinLen(). The default for that is two chars. NAKs are also sent if a message is received with an invalid checksum, if enableChecksum() is used.

void	enableACKNAK (char ACK, char NAK)
	Enables the use of Acknowledge and Naknowledge messages. If an invalid message is received then a NAK is returned to the sender. Here, the ACK and NAK chars are chosen by the user. More...

void	disableChecksum ()
	Disables the checking of checksums.

void	enableChecksum ()
	Enables the checking of checksums. When messages are received, the last char before the ETX char must be a checksum char as calculated by the algorithm given in calcChecksum(char* rawMessage).

void	setChecksumType (checksumTypeEnum checksumType)
	Sets the checksum type. More...

void	enableSTX (bool requireSTX)
	Enables the use of and STX char at the start of a received message. If requireSTX == false, presence of an STX char in the received message array will reset the start of the message to the next char. This is useful in case the message received consists of some garbled chars followed by a valid message. If requireSTX == true, then messages will only be valid if an STX char is received. The message is then parsed from that point on. In this case, subsequent STX chars are counted the same as any other message chars and do not reset the start index of the received message. This uses the default STX char which is '$'. More...

void	enableSTX (bool requireSTX, char STX)
	As above but allows the user to set a new STX char. The ascii char set does contain both an STX and ETX symbol but these are not human readable so serial monitors such as that used by the arduino IDE will not display them. This can make debugging harder. The default STX char is '$'. On the other hand, if enableSTX is used while requireSTX is false AND a checksum is used, if the checksum produced happens to be the STX symbol, then the message can not be successfully received since the checksum will be interpreted as an STX char, and the message receive process reset. If checksums and start characters are both required, ensure that requireSTX flag is set to true. More...

void	disableSTX ()
	Disables the use of the STX char at the start of messages. Disabled by default. See enableSTX() for more details.

void	setETX (char ETX)
	Sets the ETX char to be used. Serial data is received and the message buffer is filled until the ETX char is received. By default the ETX char is ' ' (newline character). This can be changed at runtime. More...

uint8_t	check ()
	Call this function as often as you like to check for new messages. Valid messages cause the function to return the length of received message. This is also available by calling getMsgLen(). If no message, or an incomplete message is received, tt transfers the partial message (any message not terminated by an ETX char) from the arduino's serial buffer to this class's message buffer and returns a 0. More...

char *	getMsg ()
	Gets the contents of the message buffer. The message buffer is updated if new chars are received by check(). More...

char *	getMsg (uint8_t startIndex)
	Gets the message starting at index startIndex. More...

uint8_t	getMsgLen ()
	Gets the length of the message in the message buffer. More...

void	setMsgMinLen (uint8_t msgMinLen)
	Sets the valid message minimum length. Received messages that are shorter than this will be discarded and check() will return a 0. More...

void	setMsgMaxLen (uint8_t msgMaxLen)
	Sets the valid message maximum length. Received messages that are longer than this will be discarded and check() will return a 0. More...

bool	contains (char *snippet, uint8_t startIndex)
	Check to see if the received message contains a char array starting at startIndex. With this function the user can check to see what type of message has been sent. More...

bool	contains (const char *snippet)
	Check to see if the received message contains a char array. With this function the user can check to see what type of message has been sent. More...

char	calcChecksum (char *rawMessage, int len)
	Calculates a checksum of the rawMessage array of length len using which ever algorithm is set to be used by the setChecksumType() function. There are currently two options. More...

char	calcChecksum (char *rawMessage)
	Calculates the checksum of the null terminated rawMessage array. I can't remember where I got this algorithm from but it produces a checksum char in the human readable asciii charset range of which there are 128 possibilities. Whilst this will not guarantee an error free message, it will hugely reduce the chances of getting a message with an error in it that matches the checksum. More...

char	chksmSpellmanMPS (char *rawMessage, int len)
	Calculates a checksum that is compatible with the Spellman MPS range of high voltage power supplies as detailed here. More...

char	chksmSpellmanMPS (char *rawMessage)
	Calculates a checksum that is compatible with the Spellman MPS range of high voltage power supplies as detailed here. More...

char	chksm8bitAllReadableChars (char *rawMessage, int len)
	Calculates a checksum where the resultant char is in the range of chars that are printable by the arduino IDE. That is 33: '!' to 126: '~'. More...

char	chksm8bitAllReadableChars (char *rawMessage)
	Calculates a checksum where the resultant char is in the range of chars that are printable by the arduino IDE. That is 33: '!' to 126: '~'. More...

float	toFloat (uint8_t startIndex)
	Converts the message in the message buffer starting at startIndex to a float. More...

float	toFloat ()
	Converts the message in the message buffer to a float. More...

uint8_t	toInt8 (uint8_t startIndex)
	Converts the message buffer (starting at startIndex) to an int8_t. This works for both unsigned and signed ints as long as the container it is loaded in to is of the correct type. More...

uint8_t	toInt8 ()
	Converts the message buffer to an int8_t. This works for both unsigned and signed ints as long as the container it is loaded in to is of the correct type. More...

uint16_t	toInt16 (uint8_t startIndex)
	Converts the message buffer (starting at startIndex) to an int16_t. This works for both unsigned and signed ints as long as the container it is loaded in to is of the correct type. More...

uint16_t	toInt16 ()
	Converts the message buffer to an int16_t. This works for both unsigned and signed ints as long as the container it is loaded in to is of the correct type. More...

uint32_t	toInt32 (uint8_t startIndex)
	Converts the message buffer (starting at startIndex) to an int32_t. This works for both unsigned and signed ints as long as the container it is loaded in to is of the correct type. More...

uint32_t	toInt32 ()
	Converts the message buffer to an int32_t. This works for both unsigned and signed ints as long as the container it is loaded in to is of the correct type. More...

void	sendACK ()
	Sends an ACK char followed by the ETX char.

void	sendNAK ()
	Sends an NAK char followed by the ETX char.

void	print (char *message)
	Same as Serial's .print method. More...

void	print (char c)
	Same as Serial's .print method. More...

void	print (uint8_t n)
	Same as Serial's .print method. More...

void	print (uint16_t n)
	Same as Serial's .print method. More...

void	print (uint32_t n)
	Same as Serial's .print method. More...

void	print (int8_t n)
	Same as Serial's .print method. More...

void	print (int16_t n)
	Same as Serial's .print method. More...

void	print (int32_t n)
	Same as Serial's .print method. More...

void	print (float n)
	Same as Serial's .print method. More...

void	print (double n)
	Same as Serial's .print method. More...

void	println (char *message)
	Same as Serial's .println method. More...

void	println (char c)
	Same as Serial's .println method. More...

void	println (uint8_t n)
	Same as Serial's .println method. More...

void	println (uint16_t n)
	Same as Serial's .println method. More...

void	println (uint32_t n)
	Same as Serial's .println method. More...

void	println (int8_t n)
	Same as Serial's .println method. More...

void	println (int16_t n)
	Same as Serial's .println method. More...

void	println (int32_t n)
	Same as Serial's .println method. More...

void	println (float n)
	Same as Serial's .println method. More...

void	println (double n)
	Same as Serial's .println method. More...

Detailed Description

SerialChecker is an Arduino based class for the easy handling of serial messages. SerialChecker can be used to check incoming messages

Constructor & Destructor Documentation

◆ SerialChecker()

SerialChecker::SerialChecker	(	uint16_t	msgMaxLen,
		HardwareSerial &	HSerial,
		uint32_t	baudrate
	)

Constructs the object. As above but lets user choose serial port and baudrate.

Parameters

[in]	msgMaxLen	The message maximum length
	HSerial	The serial port. Can be Serial, Serial1, Serial2, Serial3 for an Arduino Mega (Atmega 2560).
[in]	baudrate	The baudrate

Member Function Documentation

◆ calcChecksum() [1/2]

char SerialChecker::calcChecksum	(	char *	rawMessage,
		int	len
	)

Calculates a checksum of the rawMessage array of length len using which ever algorithm is set to be used by the setChecksumType() function. There are currently two options.

Spellman MPS: Simple checksum algorithm that produces 64 possible chars. This is as defined in the Spellman MPS Digital Interface manual, designed for use with their MPS power supplies.
8 bit printable chars: This is also a simple checksum which is calculated by summing over all the chars in the message and then mapping the sum to the ascii chars which are printable by the arduino IDE. This is chosen for easier debugging and provides 94 unique checksums. A limitation of both of these methods is that they are not dependent on the order of the chars in the message and only consider the total sum. They also don't produce very many checksums so the chances of two flipped bits due to noise causing valid checksum to still be produced is higher than 1/100. Having said that, these algorithms have been successfully used in a physics research lab for years without noticeable errors.

Use this function to generate a checksum of a return message.

Parameters

	rawMessage	The message to be sent that needs a checksum.
[in]	len	The length of the message

Returns: The checksum char.

◆ calcChecksum() [2/2]

char SerialChecker::calcChecksum ( char * rawMessage )

Calculates the checksum of the null terminated rawMessage array. I can't remember where I got this algorithm from but it produces a checksum char in the human readable asciii charset range of which there are 128 possibilities. Whilst this will not guarantee an error free message, it will hugely reduce the chances of getting a message with an error in it that matches the checksum.

Use this function to generate a checksum of a return message.

Parameters

rawMessage The message to be sent that needs a checksum.

Returns: The checksum char.

◆ check()

uint8_t SerialChecker::check ( )

Call this function as often as you like to check for new messages. Valid messages cause the function to return the length of received message. This is also available by calling getMsgLen(). If no message, or an incomplete message is received, tt transfers the partial message (any message not terminated by an ETX char) from the arduino's serial buffer to this class's message buffer and returns a 0.

If the message is too long or below the minimum length, it returns a 0 and deletes the message.

If enableSTX(false) is used, a start STX char is not required, but if one is received, any previous received chars will be delected. This is useful to discard partial or garbled messages. If enableSTX(true) is used, a received message must begin with an STX char. Subsequent STX chars in this case will be counted as valid message body chars. it restarts the message if a it If an incomplete message is sitting in the serial buffer, this function will append it to this class's message buffer. Once an ETX end char is received (default is newline '
' char), the message is checked This is the main function.

By default, the class does not use checksums but if enableChecksum() is used, the char preceding the ETX char must be a checksum char. A local checksum is calculated from the rest of the message and compared with the received checksum. If valid, the message length is returned, else a 0.

If enableACKNAK() is used, the check function will send back NAK chars in the event that the message received is not valid based on the above explained conditions. It is left to the user to send back ACK messages if they are needed using sendACK(). For example, a message might be received that sets a parameter. It might not make sense to send this back to the other device but sending an ACK char would notify the device that its message was received and successfully implemented. On the other hand, sendNAK() can be used if the received set parameter is out of the allowed set range for example.

Returns: A uint8_t value is returned representing the length of the message received, excluding the STX start char if used, the checksum char if used, or the ETX end char.

◆ chksm8bitAllReadableChars() [1/2]

char SerialChecker::chksm8bitAllReadableChars	(	char *	rawMessage,
		int	len
	)

Calculates a checksum where the resultant char is in the range of chars that are printable by the arduino IDE. That is 33: '!' to 126: '~'.

Parameters

	rawMessage	The raw message
[in]	len	The length of the message

Returns: the calculated checksum char

◆ chksm8bitAllReadableChars() [2/2]

char SerialChecker::chksm8bitAllReadableChars ( char * rawMessage )

Calculates a checksum where the resultant char is in the range of chars that are printable by the arduino IDE. That is 33: '!' to 126: '~'.

Parameters

rawMessage The raw message

Returns: the calculated checksum char

◆ chksmSpellmanMPS() [1/2]

char SerialChecker::chksmSpellmanMPS	(	char *	rawMessage,
		int	len
	)

Calculates a checksum that is compatible with the Spellman MPS range of high voltage power supplies as detailed here.

Parameters

	rawMessage	The raw message
[in]	len	The length of the message

Returns: the calculated checksum char

◆ chksmSpellmanMPS() [2/2]

char SerialChecker::chksmSpellmanMPS ( char * rawMessage )

Calculates a checksum that is compatible with the Spellman MPS range of high voltage power supplies as detailed here.

Parameters

rawMessage The raw message

Returns: the calculated checksum char

◆ contains() [1/2]

bool SerialChecker::contains	(	char *	snippet,
		uint8_t	startIndex
	)

Check to see if the received message contains a char array starting at startIndex. With this function the user can check to see what type of message has been sent.

Parameters

[in] snippet The snippet char array to be compared.

Returns: Returns true if the snippet test char array is present and false if not.

◆ contains() [2/2]

bool SerialChecker::contains ( const char * snippet )

Check to see if the received message contains a char array. With this function the user can check to see what type of message has been sent.

Parameters

[in] snippet The snippet char array to be compared.

Returns: Returns true if the snippet test char array is present and false if not.

◆ enableACKNAK()

void SerialChecker::enableACKNAK	(	char	ACK,
		char	NAK
	)

Enables the use of Acknowledge and Naknowledge messages. If an invalid message is received then a NAK is returned to the sender. Here, the ACK and NAK chars are chosen by the user.

Parameters

[in]	ACK	The acknowledgement char to be sent by sendACK().
[in]	NAK	The naknowledgement char to be sent on receipt of invalid message or when sendNAK() is called.

◆ enableSTX() [1/2]

void SerialChecker::enableSTX ( bool requireSTX )

Enables the use of and STX char at the start of a received message. If requireSTX == false, presence of an STX char in the received message array will reset the start of the message to the next char. This is useful in case the message received consists of some garbled chars followed by a valid message. If requireSTX == true, then messages will only be valid if an STX char is received. The message is then parsed from that point on. In this case, subsequent STX chars are counted the same as any other message chars and do not reset the start index of the received message. This uses the default STX char which is '$'.

Parameters

[in] requireSTX A flag to enforce the use of starting a message with the STX symbol. If true, messages must start with STX. If false, messages can optionally use STX at the start. If an STX is found part way through the message though, the preceding chars will be discarded.

◆ enableSTX() [2/2]

void SerialChecker::enableSTX	(	bool	requireSTX,
		char	STX
	)

As above but allows the user to set a new STX char. The ascii char set does contain both an STX and ETX symbol but these are not human readable so serial monitors such as that used by the arduino IDE will not display them. This can make debugging harder. The default STX char is '$'. On the other hand, if enableSTX is used while requireSTX is false AND a checksum is used, if the checksum produced happens to be the STX symbol, then the message can not be successfully received since the checksum will be interpreted as an STX char, and the message receive process reset. If checksums and start characters are both required, ensure that requireSTX flag is set to true.

Parameters

[in]	requireSTX	A flag to enforce the use of starting a message with the STX symbol. If true, messages must start with STX. If false, messages can optionally use STX at the start. If an STX is found part way through the message though, the preceding chars will be discarded.
[in]	STX	The STX char to be used. Default is '$'.

◆ getMsg() [1/2]

char * SerialChecker::getMsg ( )

Gets the contents of the message buffer. The message buffer is updated if new chars are received by check().

Returns: The message buffer which is null terminated.

◆ getMsg() [2/2]

char * SerialChecker::getMsg ( uint8_t startIndex )

Gets the message starting at index startIndex.

Parameters

[in] startIndex The start index

Returns: The null terminated message starting at index startIndex.

◆ getMsgLen()

uint8_t SerialChecker::getMsgLen ( )

Gets the length of the message in the message buffer.

Returns: The message length.

◆ print() [1/10]

void SerialChecker::print ( char * message )

Same as Serial's .print method.

Parameters

message The c style string message

◆ print() [2/10]

void SerialChecker::print ( char c )

Same as Serial's .print method.

Parameters

[in] c The char to print

◆ print() [3/10]

void SerialChecker::print ( uint8_t n )

Same as Serial's .print method.

Parameters

[in] n The uint8_t to print

◆ print() [4/10]

void SerialChecker::print ( uint16_t n )

Same as Serial's .print method.

Parameters

[in] n The uint16_t to print

◆ print() [5/10]

void SerialChecker::print ( uint32_t n )

Same as Serial's .print method.

Parameters

[in] n The uint32_t to print

◆ print() [6/10]

void SerialChecker::print ( int8_t n )

Same as Serial's .print method.

Parameters

[in] n The int8_t to print

◆ print() [7/10]

void SerialChecker::print ( int16_t n )

Same as Serial's .print method.

Parameters

[in] n The int16_t to print

◆ print() [8/10]

void SerialChecker::print ( int32_t n )

Same as Serial's .print method.

Parameters

[in] n The int32_t to print

◆ print() [9/10]

void SerialChecker::print ( float n )

Same as Serial's .print method.

Parameters

[in] n The float to print

◆ print() [10/10]

void SerialChecker::print ( double n )

Same as Serial's .print method.

Parameters

[in] n The float to print