Base socket-level interface to the ESP. More...

#include <ESPComm.h>

Collaboration diagram for ESPComm:

Public Types
enum	Error { OK = 0, CANNOT_OPEN_SOCKET_PORT, TIMEOUT_ACCEPT_CLIENT, CANNOT_ACCEPT_CLIENT, PORT_NOT_OPEN, TIMEOUT_CONNECTING, CANNOT_CONNECT }
	Errors. More...

enum	EspStream { UNKNOWN = 0, RESULT = 0201, OUTPUT = 0202, EXCEPTION = 0203, LOG = 0204, SET_PROMPT = 0205, STATE_VEC = 0206, STATUS = 0207, PROMPT = 0200 }
	the ESP virtual streams More...

enum	EspState { ES_UNKNOWN, ES_IDLE, ES_LOADING, ES_READY, ES_FILTERING, ES_PAUSED, ES_FILTERING_ERR, ES_PROCESSING, ES_PROCESS_FAILED, ES_PROCESSED, ES_UNLOADING }

Public Member Functions
	ESPComm (Str name, const int serverSocketPort, Logger &logger, size_t readBufferSize=1024)
	Constructor for when the LRAUV is to act as the server in the socket communication. More...

	ESPComm (Str name, const char *espServerAddr, const int espServerPort, Logger &logger, size_t readBufferSize=1024)
	Constructor for when the remote ESP acts as the server in the socket communication. More...

	~ESPComm ()
	Destructor. More...

ESPComm &	open ()
	Starts the server on the given port. More...

ESPComm &	acceptClient (int timeoutMillis=0)
	Client connection accept with timeout (0 by default) More...

Str	getPeerAddress ()
	Gets the address of peer connected to the client socket. More...

ESPComm &	connectAsClient ()
	Can be called when hasEspServerAddressAndPort is true. More...

ESPComm &	connectAsClient (int timeoutMillis)
	Similar to connectAsClient() but with timeout. More...

ESPComm &	setEspServerAddressAndPort (Str espServerAddr, const int espServerPort)
	Sets the address and port of the ESP server. More...

bool	hasEspServerAddressAndPort ()
	Do we already know the address and port where the ESP is/will be running as server? More...

Str	showEspServerAddressAndPort ()
	log helper: "address:port" string with the espServerAddr_ and espServerPort fields. More...

ESPComm &	submitAbort ()
	Issues command to request the ESP to interrupt the thread associated with this client. More...

bool	isClientConnected ()
	is a client connected? More...

ESPComm &	close ()
	Closes underlying sockets. More...

virtual bool	isReadable ()

virtual bool	eof ()

virtual bool	isWritable ()

const char *	streamName (EspStream stream)

const char *	espStateName (EspState espState)

EspState	espStateFromReportedString (const char *str)

void	setEspLogFile (const char *path, bool onlyLog=true)
	Received lines from the ESP are reported in the given file. More...

int	readLine (char buffer, size_t bufferSize, EspStream stream=0)
	Reads a line (non-blocking) from the ESP. More...

EspState	getEspState ()

EspStream	getCurrentStream ()

Str *	getLastResult ()
	Gets the last result received from the ESP. More...

Str *	getLastException ()
	Gets the last exception received from the ESP. More...

int	sendLine (const char *buffer, size_t bufferSize=0xFFFFFFFF)
	Sends a single line to the ESP. More...

Str	escape (const char *buffer, size_t bufferSize=0xFFFFFFFF)
	Debugging utility: returns a readable version of contents received from the ESP. More...

ESPComm::Error	getError ()
	get last error More...

bool	hasError ()

const char *	errorString ()

void	setDebug (bool debugOn)

Private Member Functions
	ESPComm (const ESPComm &old)

int	sendLineAux (Socket socket, const char buffer, size_t bufferSize=0xFFFFFFFF)

void	logDebug (Str msg)

void	logError (Str msg)

Private Attributes
Str	name_

int	serverSocketPort_

SocketServer *	socketServer_

Str	espServerAddr_

int	espServerPort_

Socket *	socketClient_

LineReader *	lineReader_

size_t	readBufferSize_

EspStream	currentStream_

Str	lastResult_

bool	lastResultComplete_

Str	lastException_

bool	lastExceptionComplete_

EspState	espState_

ESPComm::Error	lastError_

Logger	logger_

std::ofstream *	espLogFile_

bool	onlyLog_

bool	debug_

Detailed Description

Base socket-level interface to the ESP.

Besides communication establishment, provides basic operations (readLine, sendLine) to support implementation of the actual ESP component.

Member Enumeration Documentation

enum ESPComm::Error

Errors.

Enumerator
OK
CANNOT_OPEN_SOCKET_PORT
TIMEOUT_ACCEPT_CLIENT
CANNOT_ACCEPT_CLIENT
PORT_NOT_OPEN
TIMEOUT_CONNECTING
CANNOT_CONNECT

enum ESPComm::EspState

Enumerator
ES_UNKNOWN
ES_IDLE
ES_LOADING
ES_READY
ES_FILTERING
ES_PAUSED
ES_FILTERING_ERR
ES_PROCESSING
ES_PROCESS_FAILED
ES_PROCESSED
ES_UNLOADING

enum ESPComm::EspStream

the ESP virtual streams

Enumerator
UNKNOWN
RESULT
OUTPUT
EXCEPTION
LOG
SET_PROMPT
STATE_VEC
STATUS
PROMPT

Constructor & Destructor Documentation

ESPComm::ESPComm	(	Str	name,
		const int	serverSocketPort,
		Logger &	logger,
		size_t	readBufferSize = `1024`
	)

Constructor for when the LRAUV is to act as the server in the socket communication.

Parameters

name	String to identify this instance as an ESP client
serverSocketPort	The local port for the server socket
logger	Logger
readBufferSize	Passed to LineReader; 1024 by default

ESPComm::ESPComm	(	Str	name,
		const char *	espServerAddr,
		const int	espServerPort,
		Logger &	logger,
		size_t	readBufferSize = `1024`
	)

Constructor for when the remote ESP acts as the server in the socket communication.

Parameters

name	String to identify this instance as an ESP client
espServerAddr	ESP address
espServerPort	ESP port
logger	Logger
readBufferSize	Passed to LineReader; 1024 by default

ESPComm::~ESPComm ( )

Destructor.

References close(), isReadable(), and setEspLogFile().

ESPComm::ESPComm ( const ESPComm & old )

private

Member Function Documentation

ESPComm & ESPComm::acceptClient ( int timeoutMillis = 0 )

Client connection accept with timeout (0 by default)

References SocketServer::accept(), CANNOT_ACCEPT_CLIENT, Socket::close(), Str::cStr(), debug_, escape(), espServerAddr_, espServerPort_, Socket::getDescriptor(), SocketException::getErrno(), lastError_, lineReader_, logDebug(), name_, OK, readBufferSize_, Socket::sendall(), serverSocketPort_, socketClient_, socketServer_, and TIMEOUT_ACCEPT_CLIENT.

Referenced by main(), and ESPComponent::waitForESPConnection().

ESPComm & ESPComm::close ( void )

Closes underlying sockets.

References Socket::close(), lastError_, lineReader_, PORT_NOT_OPEN, socketClient_, and socketServer_.

Referenced by open(), ESPComponent::start(), ESPComponent::stop(), ESPComponent::uninitialize(), and ~ESPComm().

ESPComm & ESPComm::connectAsClient ( )

Can be called when hasEspServerAddressAndPort is true.

References CANNOT_CONNECT, Str::cStr(), debug_, espServerAddr_, espServerPort_, Socket::getDescriptor(), lastError_, lineReader_, logDebug(), name_, OK, readBufferSize_, Socket::sendall(), and socketClient_.

Referenced by open(), and ESPComponent::starting().

ESPComm & ESPComm::connectAsClient ( int timeoutMillis )

Similar to connectAsClient() but with timeout.

Uses constructor SocketClient( const char* host, int port, int timeoutMillis ). See SocketClient.h for relevant documentation.

getError() will be ESPComm::TIMEOUT_CONNECTING if there's a connection refused error or there's a timeout connecting.

Parameters

timeoutMillis Timeout in millis. A value of 100 or more has worked well according to testing with client on testhyssim and server on bufflehead.

References CANNOT_CONNECT, Str::cStr(), debug_, espServerAddr_, espServerPort_, Socket::getDescriptor(), SocketException::getErrno(), lastError_, lineReader_, logDebug(), name_, OK, readBufferSize_, Socket::sendall(), socketClient_, and TIMEOUT_CONNECTING.

virtual bool ESPComm::eof ( )

inlinevirtual

References isReadable().

const char * ESPComm::errorString ( )

References CANNOT_ACCEPT_CLIENT, CANNOT_CONNECT, CANNOT_OPEN_SOCKET_PORT, lastError_, OK, PORT_NOT_OPEN, TIMEOUT_ACCEPT_CLIENT, and TIMEOUT_CONNECTING.

Referenced by ESPComponent::openServerSocket().

Str ESPComm::escape	(	const char *	buffer,
		size_t	bufferSize = `0xFFFFFFFF`
	)

Debugging utility: returns a readable version of contents received from the ESP.

Parameters

buffer	string
bufferSize	size of buffer; if unspecified, strlen is used to determine the size

Returns: readable version of contents received from the ESP

Referenced by acceptClient(), ESPClient::checkCmdCompleteTimeout(), ESPClient::checkCmdResultTimeout(), ESPClient::consumeResult(), ESPComponent::getLine(), ESPClient::getLine(), ESPClient::handleException(), ESPClient::issueCommand(), readLine(), sendLineAux(), and ESPComponent::starting().

EspState ESPComm::espStateFromReportedString ( const char * str )

inline

References Syslog::ERROR, ES_FILTERING, ES_FILTERING_ERR, ES_IDLE, ES_LOADING, ES_PAUSED, ES_PROCESS_FAILED, ES_PROCESSED, ES_PROCESSING, ES_READY, ES_UNKNOWN, ES_UNLOADING, logger_, and Logger::syslog().

Referenced by readLine().

const char* ESPComm::espStateName ( EspState espState )

inline

References ES_FILTERING, ES_FILTERING_ERR, ES_IDLE, ES_LOADING, ES_PAUSED, ES_PROCESS_FAILED, ES_PROCESSED, ES_PROCESSING, ES_READY, ES_UNKNOWN, and ES_UNLOADING.

Referenced by readLine().

EspStream ESPComm::getCurrentStream ( )

inline

References currentStream_.

Referenced by ESPClient::advanceInteraction().

ESPComm::Error ESPComm::getError ( )

inline

get last error

References lastError_.

Referenced by main(), ESPComponent::starting(), and ESPComponent::waitForESPConnection().

EspState ESPComm::getEspState ( )

inline

References espState_.

Referenced by ESPClient::advanceInteraction(), and readLine().

Str * ESPComm::getLastException ( )

Gets the last exception received from the ESP.

Returns: 0 if no exception at all has been received or if a previous exception has already been reported. Otherwise the complete last exception. Note: caller is responsible for releasing (delete'ing) the returned object.

References lastException_, and lastExceptionComplete_.

Referenced by ESPClient::getLine().

Str * ESPComm::getLastResult ( )

Gets the last result received from the ESP.

Returns: result string; 0 if no result at all has yet been received or if a previous result has already been reported. Otherwise the complete last result. Note: caller is responsible for releasing (delete'ing) the returned object.

References lastResult_, and lastResultComplete_.

Referenced by ESPClient::getLine().

Str ESPComm::getPeerAddress ( )

Gets the address of peer connected to the client socket.

This is used to switch server/client roles once the ESP connects to the vehicle.

References debug_, Socket::getDescriptor(), logDebug(), and socketClient_.

Referenced by ESPComponent::starting().

bool ESPComm::hasError ( )

inline

References lastError_, and OK.

Referenced by main(), ESPComponent::openServerSocket(), ESPComponent::starting(), and ESPComponent::waitForESPConnection().

bool ESPComm::hasEspServerAddressAndPort ( )

inline

Do we already know the address and port where the ESP is/will be running as server?

References espServerAddr_, espServerPort_, and Str::length().

Referenced by ESPComponent::starting().

bool ESPComm::isClientConnected ( )

inline

is a client connected?

References socketClient_.

Referenced by ESPComponent::starting().

virtual bool ESPComm::isReadable ( void )

inlinevirtual

References socketClient_.

Referenced by eof(), open(), ESPComponent::start(), ESPComponent::stop(), and ~ESPComm().

virtual bool ESPComm::isWritable ( void )

inlinevirtual

References socketClient_.

void ESPComm::logDebug ( Str msg )

private

References Syslog::DEBUG, logger_, and Logger::syslog().

Referenced by acceptClient(), connectAsClient(), getPeerAddress(), open(), readLine(), sendLineAux(), setEspLogFile(), and submitAbort().

void ESPComm::logError ( Str msg )

private

References Syslog::ERROR, logger_, and Logger::syslog().

Referenced by readLine().

ESPComm & ESPComm::open ( )

Starts the server on the given port.

References CANNOT_OPEN_SOCKET_PORT, close(), connectAsClient(), debug_, isReadable(), lastError_, logDebug(), OK, serverSocketPort_, and socketServer_.

Referenced by main(), and ESPComponent::openServerSocket().

int ESPComm::readLine	(	char *	buffer,
		size_t	bufferSize,
		EspStream *	stream = `0`
	)

Reads a line (non-blocking) from the ESP.

Parameters

buffer	output buffer
bufferSize	size of output buffer
stream	If not null, associated stream is stored here

Returns: See LineReader::readLine for documentation

References Str::cStr(), currentStream_, debug_, escape(), espLogFile_, espState_, espStateFromReportedString(), espStateName(), EXCEPTION, getEspState(), lastException_, lastExceptionComplete_, lastResult_, lastResultComplete_, Str::length(), lineReader_, LOG, logDebug(), logError(), onlyLog_, LineReader::readLine(), RESULT, STATUS, streamName(), and UNKNOWN.

Referenced by ESPComponent::getLine(), and ESPClient::getLine().

int ESPComm::sendLine	(	const char *	buffer,
		size_t	bufferSize = `0xFFFFFFFF`
	)

Sends a single line to the ESP.

The given string may omit the trailing '
'. The string is encoded as expected by the ESP. This "encoding" is simply the insertion of a NUL character before the '
'. The encoded string is sent out using Socket::sendall.

Parameters

buffer	string
bufferSize	size of buffer; if unspecified, strlen is used to determine the size

Returns: The value returned by the internal call to Socket::sendall

References sendLineAux(), and socketClient_.

Referenced by ESPClient::issueCommand().

int ESPComm::sendLineAux	(	Socket *	socket,
		const char *	buffer,
		size_t	bufferSize = `0xFFFFFFFF`
	)

private

References debug_, escape(), logDebug(), and Socket::sendall().

Referenced by sendLine(), and submitAbort().

void ESPComm::setDebug ( bool debugOn )

inline

References debug_.

Referenced by ESPComponent::createESPComm(), and main().

void ESPComm::setEspLogFile	(	const char *	path,
		bool	onlyLog = `true`
	)

Received lines from the ESP are reported in the given file.

Any previous file specified with this method is first closed.

Parameters

path	Path to output file. Can be 0 to cause any previously specified file to be closed.
onlyLog	true to only report <log> lines; true by default.

References debug_, espLogFile_, logDebug(), Timestamp::Now(), onlyLog_, and Timestamp::toString().

Referenced by ESPComponent::espReady(), main(), and ~ESPComm().

ESPComm & ESPComm::setEspServerAddressAndPort	(	Str	espServerAddr,
		const int	espServerPort
	)

Sets the address and port of the ESP server.

This information can be used for later connection as a client, in particular for the submitAbort call.

This method called after being connected with the vehicle as server once we know the peer address (from the socket connection) and the port, which is explicitly reported by the ESP in a first line in the connection.

Parameters