TagValueRemoteConnector Class Reference

#include <RemoteConnector.h>

Public Member Functions
	TagValueRemoteConnector (uint8_t remoteNo=0)
void	initialise (TagValueTransport *transport, CombinedMessageProcessor *processor, const ConnectorLocalInfo *localInfoPgm, uint8_t remoteNo)
void	setAuthManager (AuthenticationManager *mgr)
void	setCommsNotificationCallback (CommsCallbackFn callback)
bool	isTransportAvailable ()
void	provideAuthentication (const char *auth)
bool	isTransportConnected ()
void	encodeJoin ()
void	encodeCustomTagValMessage (uint16_t msgType, void(*msgWriter)(TagValueTransport *, void *), void *)
void	encodeCustomBinaryMessage (uint16_t msgType, uint16_t len, void(*msgWriter)(TagValueTransport *, void *, size_t), void *data=nullptr)
void	encodeDialogMsg (uint8_t mode, uint8_t btn1, uint8_t btn2, const char *hdrPgm, const char *buffer)
void	encodeBootstrap (bool isComplete)
void	encodeHeartbeat (HeartbeatMode restartConnection)
void	encodeAnalogItem (int parentId, AnalogMenuItem *item)
void	encodeSubMenu (int parentId, SubMenuItem *item)
void	encodeBooleanMenu (int parentId, BooleanMenuItem *item)
void	encodeEnumMenu (int parentId, EnumMenuItem *item)
void	encodeActionMenu (int parentId, ActionMenuItem *item)
void	encodeFloatMenu (int parentId, FloatMenuItem *item)
void	encodeRuntimeMenuItem (int parentId, RuntimeMenuItem *item)
void	encodeMultiEditMenu (int parentId, RuntimeMenuItem *item)
void	encodeLargeNumberMenuItem (int parentId, EditableLargeNumberMenuItem *item)
void	encodeChangeValue (MenuItem *theItem)
void	encodeAcknowledgement (uint32_t correlation, AckResponseStatus status)
void	encodeColorMenuItem (int id, Rgb32MenuItem *pItem)
void	encodeScrollMenuItem (int id, ScrollChoiceMenuItem *pItem)
void	tick ()
void	pairingRequest (const char *name, const char *uuid)
void	initiateBootstrap ()
uint8_t	getRemoteNo () const
const char *	getRemoteName ()
uint8_t	getRemoteMajorVer () const
uint8_t	getRemoteMinorVer () const
ApiPlatform	getRemotePlatform ()
bool	isConnected ()
void	setRemoteName (const char *name)
void	setRemoteConnected (uint8_t major, uint8_t minor, ApiPlatform platform)
void	commsNotify (uint16_t commsEventType)
void	close ()
bool	isAuthenticated ()
AuthenticationManager *	getAuthManager ()
void	setHeartbeatTimeout (uint16_t milli)

Detailed Description

The remote connector is what we would normally interact with when dealing with a remote. It provides functionality at the message processing level, for sending messages and processing incoming ones.

Constructor & Destructor Documentation

TagValueRemoteConnector()

TagValueRemoteConnector::TagValueRemoteConnector ( uint8_t  remoteNo = 0 )

explicit

Construct an instance

Parameters

remoteNo

the index of this connector, 0 based.

Member Function Documentation

initialise()

void TagValueRemoteConnector::initialise	(	TagValueTransport *	transport,
		CombinedMessageProcessor *	processor,
		const ConnectorLocalInfo *	localInfoPgm,
		uint8_t	remoteNo = 0
	)

Initialises the connector with a specific transport that can send and recevie data, a message processor that can process incoming message, the remote number that should be used and it's name.

Parameters

transport	a class that implements TagValueTransport for sending and receving data.
processor	a linked list of processors that can process incoming messages.
localInfoPgm	the name and UUID of this local device (in program memory where available).
remoteNo	remote number, optional and defaults to 0

setCommsNotificationCallback()

void TagValueRemoteConnector::setCommsNotificationCallback ( CommsCallbackFn  callback )

inline

If you want to be informed of communication events for this remote, pass a function that takes a CommunicationInfo structure as its parameter.

isTransportAvailable()

bool TagValueRemoteConnector::isTransportAvailable ( )

inline

Indicates if the underlying transport is functionality

isTransportConnected()

bool TagValueRemoteConnector::isTransportConnected ( )

inline

Indicates if the underlying transport is connected.

encodeJoin()

void TagValueRemoteConnector::encodeJoin

(

)

Encode a join message onto the wire, giving local name

Parameters

localName

the name to send in the join message

encodeCustomTagValMessage()

void TagValueRemoteConnector::encodeCustomTagValMessage	(	uint16_t	msgType,
		void(*)(TagValueTransport *, void *)	msgWriter,
		void *
	)

Encode a custom message onto the wire in the TagVal protocol, provide the message type and a function that sets the fields you wish to send. This works by you providing the type of message and a function that will set all the fields by calling transport's add field methods. Once that method returns the message will be completed and sent on the wire. Where myData can be a pointer to any data you need to provide, it allows you to get data into the lambda without enabling captures.

// first we define out custom message, we'd define any custom fields the same way.
#define MSG_CUSTOM msgFieldToWord('Z','Z')
 
// then we call the function to send the message, it wraps up the message for us.
myConnector.encodeCustomTagValMessage(MSG_CUSTOM, [](TagValueTransport* transport, void* myData) {
    transport.writeField(FIELD_BUFFER, "12345");
    transport.writeFieldInt(FIELD_VERSION, 123);
    transport.writeFieldLong(FIELD_HB_MILLISEC, 2039349L);
}, myData);

encodeCustomBinaryMessage()

void TagValueRemoteConnector::encodeCustomBinaryMessage	(	uint16_t	msgType,
		uint16_t	len,
		void(*)(TagValueTransport *, void *, size_t)	msgWriter,
		void *	data = nullptr
	)

Encode a binary message onto the wire using your own format, note that the other end must be able to process this type of message. Embed Control UI will not understand such custom messages. This works by you providing the type of message and a function that will set all the binary data direct to the transport using the write function. The myData parameter allows you to pass data into the lambda with enabling capture.

// first we define out custom message, we'd define any custom fields the same way.
#define MSG_CUSTOM msgFieldToWord('Z','Z')
 
// then we call the function to send the message, it wraps up the message for us.
myConnector.encodeCustomBinaryMessage(MSG_CUSTOM, len, [](TagValueTransport* transport, void* myData, size_t len) {
    transport.writeChar(binDataByte);
}, myData);

encodeDialogMsg()

void TagValueRemoteConnector::encodeDialogMsg	(	uint8_t	mode,
		uint8_t	btn1,
		uint8_t	btn2,
		const char *	hdrPgm,
		const char *	buffer
	)

Encodes a dialog message that the UI can use to render / remove a dialog from the display.

Parameters

mode	either 'S'how, 'H'ide or 'A'ction
btn1	the status of the first button
btn2	the status of the second button
hdrPgm	the header of the dialog (progrma memory)
buffer	the additional text

encodeBootstrap()

void TagValueRemoteConnector::encodeBootstrap

(

bool

isComplete

)

Encode a bootstrap message indicating we are sending state

Parameters

isComplete

true - end of boot sequence.

encodeHeartbeat()

void TagValueRemoteConnector::encodeHeartbeat

(

HeartbeatMode

restartConnection

)

Encodes a heartbeat message onto the transport

Parameters

restartConnection

indicates that the connection is to restart.

encodeAnalogItem()

void TagValueRemoteConnector::encodeAnalogItem	(	int	parentId,
		AnalogMenuItem *	item
	)

Encodes a bootstrap for an Analog menu item, this gives all needed state to the remote.

Parameters

parentId	the parent menu
item	the item to be bootstrapped.

encodeSubMenu()

void TagValueRemoteConnector::encodeSubMenu	(	int	parentId,
		SubMenuItem *	item
	)

Encodes a bootstrap for a Sub menu item, this gives all needed state to the remote.

Parameters

parentId	the parent menu
item	the item to be bootstrapped.

encodeBooleanMenu()

void TagValueRemoteConnector::encodeBooleanMenu	(	int	parentId,
		BooleanMenuItem *	item
	)

Encodes a bootstrap for a boolean menu item, this gives all needed state to the remote.

Parameters

parentId	the parent menu
item	the item to be bootstrapped.

encodeEnumMenu()

void TagValueRemoteConnector::encodeEnumMenu	(	int	parentId,
		EnumMenuItem *	item
	)

Encodes a bootstrap for an enum menu item, this gives all needed state to the remote.

Parameters

parentId	the parent menu
item	the item to be bootstrapped.

encodeActionMenu()

void TagValueRemoteConnector::encodeActionMenu	(	int	parentId,
		ActionMenuItem *	item
	)

Encodes a bootstrap for an action menu item, this gives all needed state to the remote.

Parameters

parentId	the parent menu
item	the item to be bootstrapped.

encodeFloatMenu()

void TagValueRemoteConnector::encodeFloatMenu	(	int	parentId,
		FloatMenuItem *	item
	)

Encodes a bootstrap for a float menu item, this gives all needed state to the remote.

Parameters

parentId	the parent menu
item	the item to be bootstrapped.

encodeRuntimeMenuItem()

void TagValueRemoteConnector::encodeRuntimeMenuItem	(	int	parentId,
		RuntimeMenuItem *	item
	)

Encodes a bootstrap for a runtime list menu item, this gives all needed state to the remote.

Parameters

parentId	the parent menu
item	the item to be bootstrapped.

encodeMultiEditMenu()

void TagValueRemoteConnector::encodeMultiEditMenu	(	int	parentId,
		RuntimeMenuItem *	item
	)

Encodes a bootstrap for a multiEdit runtime menu item, this gives all needed state to the remote.

Parameters

parentId	the parent menu
item	the item to be bootstrapped.

encodeLargeNumberMenuItem()

void TagValueRemoteConnector::encodeLargeNumberMenuItem	(	int	parentId,
		EditableLargeNumberMenuItem *	item
	)

Encodes a large number type (a specialisation of multiedit) as a boot command

Parameters

parentId	the parent menu
item	the item to be bootstrapped.

encodeChangeValue()

void TagValueRemoteConnector::encodeChangeValue

(

MenuItem *

theItem

)

Encodes a value change message to be sent to the remote. The embedded device always sends absolute changes out.

Parameters

parentId	the parent menu
theItem	the item to be bootstrapped.

encodeAcknowledgement()

void TagValueRemoteConnector::encodeAcknowledgement	(	uint32_t	correlation,
		AckResponseStatus	status
	)

Encodes an acknowledgement back to the other side to indicate the success or failure of an operation.

Parameters

correlation	the ID to returned to the other side, or 0.
status	the status to be returned.

encodeColorMenuItem()

void TagValueRemoteConnector::encodeColorMenuItem	(	int	id,
		Rgb32MenuItem *	pItem
	)

Encodes a color RGB to the remote as a boot command.

Parameters

id	the parent ID
pItem	the item to be transferred

encodeScrollMenuItem()

void TagValueRemoteConnector::encodeScrollMenuItem	(	int	id,
		ScrollChoiceMenuItem *	pItem
	)

Encodes a scroll choice to the remote as a boot command

Parameters

id	parent id
pItem	the item to be sent

tick()

void TagValueRemoteConnector::tick

(

)

Called frequently to perform all functions, this is arranged interally by registering a taskManager task.

pairingRequest()

void TagValueRemoteConnector::pairingRequest	(	const char *	name,
		const char *	uuid
	)

Puts the system into pairing mode, If the system is in pairing mode already the display is updated. This will present a dialog on the renderer if there is one and the connection will be allowed only when the user selects to pair on the local device.

Parameters

name	the name of the remote device
uuid	the UUID to go with the name

initiateBootstrap()

void TagValueRemoteConnector::initiateBootstrap

(

)

Called internally to start a bootstrap on new connections

getRemoteNo()

uint8_t TagValueRemoteConnector::getRemoteNo ( ) const

inline

Returns the remoteNo (or remote number) for this remote

getRemoteName()

const char* TagValueRemoteConnector::getRemoteName ( )

inline

Returns the remote name for this connection. The name of the other side

getRemoteMajorVer()

uint8_t TagValueRemoteConnector::getRemoteMajorVer ( ) const

inline

returns the major version of the other party API

getRemoteMinorVer()

uint8_t TagValueRemoteConnector::getRemoteMinorVer ( ) const

inline

Returns the minor version of the other party API

getRemotePlatform()

ApiPlatform TagValueRemoteConnector::getRemotePlatform ( )

inline

Returns the platform of the other party.

isConnected()

bool TagValueRemoteConnector::isConnected ( )

inline

Indicates if we are currently connected. Different to transport level connection as this includes checking for heartbeats.

setRemoteName()

void TagValueRemoteConnector::setRemoteName

(

const char *

name

)

Sets the remote name, usually only used by the message processor.

setRemoteConnected()

void TagValueRemoteConnector::setRemoteConnected	(	uint8_t	major,
		uint8_t	minor,
		ApiPlatform	platform
	)

Sets the remote connection state, again only used by message processor.

commsNotify()

void TagValueRemoteConnector::commsNotify

(

uint16_t

commsEventType

)

Notify any listeners of a communication event on this remote, usually used by message processors to indicate an issue

Parameters

commsEventType

an error usually defined in RemoteConnector.h

close()

void TagValueRemoteConnector::close

(

)

close the connection

isAuthenticated()

bool TagValueRemoteConnector::isAuthenticated ( )

inline

indicates if the connection is yet authenicated

---

The documentation for this class was generated from the following files:

• src/RemoteConnector.h
• src/RemoteConnector.cpp