Collaboration diagram for MyTransport:

Detailed Description

API declaration for MyTransport.

Transport-related log messages, format: [!]SYSTEM:[SUB SYSTEM:]MESSAGE

[!] Exclamation mark is prepended in case of error
SYSTEM:
- TSM: messages emitted by the transport state machine
- TSF: messages emitted by transport support functions
SUB SYSTEMS:
- Transport state machine (TSM)
  - TSM:INIT from stInit Initialize transport and radio
  - TSM:FPAR from stParent Find parent
  - TSM:ID from stID Check/request node ID, if dynamic node ID set
  - TSM:UPL from stUplink Verify uplink connection by pinging GW
  - TSM:READY from stReady Transport is ready and fully operational
  - TSM:FAIL from stFailure Failure in transport link or transport HW
- Transport support function (TSF)
  - TSF:CKU from transportCheckUplink(), checks connection to GW
  - TSF:SID from transportAssignNodeID(), assigns node ID
  - TSF:PNG from transportPingNode(), pings a node
  - TSF:WUR from transportWaitUntilReady(), waits until transport is ready
  - TSF:CRT from transportClearRoutingTable(), clears routing table stored in EEPROM
  - TSF:LRT from transportLoadRoutingTable(), loads RAM routing table from EEPROM (only GW/repeaters)
  - TSF:SRT from transportSaveRoutingTable(), saves RAM routing table to EEPROM (only GW/repeaters)
  - TSF:MSG from transportProcessMessage(), processes incoming message
  - TSF:SAN from transportInvokeSanityCheck(), calls transport-specific sanity check
  - TSF:RTE from transportRouteMessage(), sends message
  - TSF:SND from transportSendRoute(), sends message if transport is ready (exposed)
  - TSF:TDI from transportDisable()
  - TSF:TRI from transportReInitialise()
  - TSF:SIR from transportSignalReport()

Transport debug log messages:

E	SYS	SUB	Message	Comment
	TSM	INIT		Transition to stInit state
	TSM	INIT	STATID=%d	Node ID is static
	TSM	INIT	TSP OK	Transport device configured and fully operational
	TSM	INIT	TSP PSM	Transport passive mode set
	TSM	INIT	GW MODE	Node is set up as GW, thus omitting ID and findParent states
!	TSM	INIT	TSP FAIL	Transport device initialization failed
	TSM	FPAR		Transition to stParent state
	TSM	FPAR	STATP=%d	Static parent set, skip finding parent
	TSM	FPAR	OK	Parent node identified
!	TSM	FPAR	NO REPLY	No potential parents replied to find parent request
!	TSM	FPAR	FAIL	Finding parent failed
	TSM	ID		Transition to stID state
	TSM	ID	OK,ID=%d	Node ID is valid
	TSM	ID	REQ	Request node ID from controller
!	TSM	ID	FAIL,ID=%d	ID verification failed, ID invalid, no ID received from controller
	TSM	UPL		Transition to stUplink state
	TSM	UPL	OK	Uplink OK, GW returned ping
	TSF	UPL	DGWC,O=%d,N=%d	Uplink check revealed changed network topology, old distance (O), new distance (N)
!	TSM	UPL	FAIL	Uplink check failed, i.e. GW could not be pinged
	TSM	READY	SRT	Save routing table
	TSM	READY	ID=%d,PAR=%d,DIS=%d	Transition to stReady Transport ready, node ID (ID), parent node ID (PAR), distance to GW (DIS)
!	TSM	READY	UPL FAIL,SNP	Too many failed uplink transmissions, search new parent
!	TSM	READY	FAIL,STATP	Too many failed uplink transmissions, static parent enforced
	TSM	FAIL	CNT=%d	Transition to stFailure state, consecutive failure counter (CNT)
	TSM	FAIL	DIS	Disable transport
	TSM	FAIL	RE-INIT	Attempt to re-initialize transport
	TSF	CKU	OK	Uplink OK
	TSF	CKU	OK,FCTRL	Uplink OK, flood control prevents pinging GW in too short intervals
	TSF	CKU	DGWC,O=%d,N=%d	Uplink check revealed changed network topology, old distance (O), new distance (N)
	TSF	CKU	FAIL	No reply received when checking uplink
	TSF	SID	OK,ID=%d	Node ID assigned
!	TSF	SID	FAIL,ID=%d	Assigned ID is invalid
	TSF	PNG	SEND,TO=%d	Send ping to destination (TO)
	TSF	WUR	MS=%lu	Wait until transport ready, timeout (MS)
	TSF	MSG	ECHO REQ	ECHO message requested
	TSF	MSG	ECHO	ECHO message, do not proceed but forward to callback
	TSF	MSG	FPAR RES,ID=%d,D=%d	Response to find parent received from node (ID) with distance (D) to GW
	TSF	MSG	FPAR PREF FOUND	Preferred parent found, i.e. parent defined via MY_PARENT_NODE_ID
	TSF	MSG	FPAR OK,ID=%d,D=%d	Find parent response from node (ID) is valid, distance (D) to GW
	TSF	MSG	FPAR INACTIVE	Find parent response received, but no find parent request active, skip response
	TSF	MSG	FPAR REQ,ID=%d	Find parent request from node (ID)
	TSF	MSG	PINGED,ID=%d,HP=%d	Node pinged by node (ID) with (HP) hops
	TSF	MSG	PONG RECV,HP=%d	Pinged node replied with (HP) hops
	TSF	MSG	BC	Broadcast message received
	TSF	MSG	GWL OK	Link to GW ok
	TSF	MSG	FWD BC MSG	Controlled broadcast message forwarding
	TSF	MSG	RCV CB	Hand over message to receive() callback function
	TSF	MSG	REL MSG	Relay message
	TSF	MSG	REL PxNG,HP=%d	Relay PING/PONG message, increment hop counter (HP)
!	TSF	MSG	SIGN VERIFY FAIL	Signing verification failed
!	TSF	MSG	REL MSG,NORP	Node received a message for relaying, but node is not a repeater, message skipped
!	TSF	MSG	SIGN FAIL	Signing message failed
!	TSF	MSG	GWL FAIL	GW uplink failed
!	TSF	MSG	ID TK INVALID	Token for ID request invalid
	TSF	SAN	OK	Sanity check passed
!	TSF	SAN	FAIL	Sanity check failed, attempt to re-initialize radio
	TSF	CRT	OK	Clearing routing table successful
	TSF	LRT	OK	Loading routing table successful
	TSF	SRT	OK	Saving routing table successful
!	TSF	RTE	FPAR ACTIVE	Finding parent active, message not sent
!	TSF	RTE	DST %d UNKNOWN	Routing for destination (DST) unknown, send message to parent
	TSF	RTE	N2N OK	Node-to-node communication succeeded
!	TSF	RTE	N2N FAIL	Node-to-node communication failed, handing over to parent for re-routing
	TSF	RRT	ROUTE N=%d,R=%d	Routing table, messages to node (N) are routed via node (R)
!	TSF	SND	TNR	Transport not ready, message cannot be sent
	TSF	TDI	TSL	Set transport to sleep
	TSF	TDI	TPD	Power down transport
	TSF	TRI	TRI	Reinitialise transport
	TSF	TRI	TSB	Set transport to standby
	TSF	SIR	CMD=d,VAL=d	Get signal report

Incoming / outgoing messages:

See here for more detail on the format and definitions.

Receiving a message

TSF:MSG:READ,sender-last-destination,s=%d,c=%d,t=%d,pt=%d,l=%d,sg=%d:%s

Sending a message

[!/?]TSF:MSG:SEND,sender-last-next-destination,s=%d,c=%d,t=%d,pt=%d,l=%d,sg=%d,ft=%d,st=%s:%s

Prepended char:

none=sending OK
!=error sending
?=sending status unknown Message fields:
s=sensor ID
c=command
t=msg type
pt=payload type
l=length
sg=signing flag
ft=failed uplink transmission counter
st=send status, OK=success, NACK=no radio ACK received

Classes
struct	transportConfig_t
	Node configuration. More...

struct	transportState_t
	SM state. More...

struct	transportSM_t
	Status variables and SM state. More...

struct	routingTable_t
	RAM routing table. More...

Macros
#define	MY_TRANSPORT_MAX_TX_FAILURES (5u)
	search for a new parent node after this many transmission failures, lower threshold for non-repeating nodes More...

#define	MY_TRANSPORT_MAX_TSM_FAILURES (7u)
	Max. number of consecutive TSM failure state entries (3bits)

#define	MY_TRANSPORT_TIMEOUT_FAILURE_STATE_MS (10*1000ul)
	Duration failure state (in ms)

#define	MY_TRANSPORT_TIMEOUT_EXT_FAILURE_STATE_MS (60*1000ul)
	Duration extended failure state (in ms)

#define	MY_TRANSPORT_STATE_TIMEOUT_MS (2*1000ul)
	general state timeout (in ms)

#define	MY_TRANSPORT_CHKUPL_INTERVAL_MS (10*1000ul)
	Interval to re-check uplink (in ms)

#define	MY_TRANSPORT_STATE_RETRIES (3u)
	retries before switching to FAILURE

#define	AUTO (255u)
	ID 255 is reserved.

#define	BROADCAST_ADDRESS (255u)
	broadcasts are addressed to ID 255

#define	DISTANCE_INVALID (255u)
	invalid distance when searching for parent

#define	MAX_HOPS (254u)
	maximal number of hops for ping/pong

#define	INVALID_HOPS (255u)
	invalid hops

#define	MAX_SUBSEQ_MSGS (5u)
	Maximum number of subsequently processed messages in FIFO (to prevent transport deadlock if HW issue)

#define	UPLINK_QUALITY_WEIGHT (0.05f)
	UPLINK_QUALITY_WEIGHT.

#define	_autoFindParent (bool)(MY_PARENT_NODE_ID == AUTO)
	returns true if static parent id is undefined

#define	isValidDistance(_distance) (bool)(_distance!=DISTANCE_INVALID)
	returns true if distance is valid

#define	isValidParent(_parent) (bool)(_parent != AUTO)
	returns true if parent is valid

#define	transportInternalToRSSI(__value) ((int16_t)__value >> 4)
	Convert internal RSSI to RSSI.

#define	transportRSSItoInternal(__value) ((transportRSSI_t)__value << 4)
	Convert RSSI to internal RSSI.

Typedefs
typedef void(*	transportCallback_t) (void)
	Callback type.

typedef int16_t	transportRSSI_t
	Datatype for internal RSSI storage. More...

Functions
void	stInitTransition (void)
	Initialize SM variables and transport HW.

void	stInitUpdate (void)
	Initialize transport.

void	stParentTransition (void)
	Find parent.

void	stParentUpdate (void)
	Verify find parent responses.

void	stIDTransition (void)
	Send ID request.

void	stIDUpdate (void)
	Verify ID response and GW link.

void	stUplinkTransition (void)
	Send uplink ping request.

void	stUplinkUpdate (void)
	Verify uplink response.

void	stReadyTransition (void)
	Set transport OK.

void	stReadyUpdate (void)
	Monitor transport link.

void	stFailureTransition (void)
	Transport failure and power down radio.

void	stFailureUpdate (void)
	Re-initialize transport after timeout.

void	transportSwitchSM (transportState_t &newState)
	Switch SM state. More...

void	transportUpdateSM (void)
	Update SM state.

uint32_t	transportTimeInState (void)
	Request time in current SM state. More...

void	transportInvokeSanityCheck (void)
	Call transport driver sanity check.

void	transportProcessFIFO (void)
	Process all pending messages in RX FIFO.

void	transportProcessMessage (void)
	Receive message from RX FIFO and process.

bool	transportAssignNodeID (const uint8_t newNodeId)
	Assign node ID. More...

bool	transportWait (const uint32_t waitingMS, const uint8_t cmd, const uint8_t msgType)
	Wait and process messages for a defined amount of time until specified message received. More...

uint8_t	transportPingNode (const uint8_t targetId)
	Ping node. More...

bool	transportRouteMessage (MyMessage &message)
	Send and route message according to destination. More...

bool	transportSendRoute (MyMessage &message)
	Send and route message according to destination with transport state check. More...

bool	transportSendWrite (const uint8_t to, MyMessage &message)
	Send message to recipient. More...

bool	transportCheckUplink (const bool force=false)
	Check uplink to GW, includes flooding control. More...

bool	transportWaitUntilReady (const uint32_t waitingMS=0)
	Wait until transport is ready. More...

void	transportInitialise (void)
	Initialize transport and SM.

void	transportProcess (void)
	Process FIFO msg and update SM.

bool	isTransportReady (void)
	Flag transport ready. More...

bool	isTransportSearchingParent (void)
	Flag searching parent ongoing. More...

bool	isTransportExtendedFailure (void)
	Flag TSM extended failure. More...

bool	isMessageReceived (void)
	Flag valid message received. More...

void	resetMessageReceived (void)
	Reset message received flag.

void	transportClearRoutingTable (void)
	Clear routing table.

uint32_t	transportGetHeartbeat (void)
	Return heart beat. More...

void	transportLoadRoutingTable (void)
	Load routing table from EEPROM to RAM. Only for GW devices with enough RAM, i.e. ESP8266, RPI Sensebender GW, etc. Atmega328 has only limited amount of RAM.

void	transportSaveRoutingTable (void)
	Save routing table to EEPROM.

void	transportSetRoute (const uint8_t node, const uint8_t route)
	Update routing table. More...

uint8_t	transportGetRoute (const uint8_t node)
	Load route to node. More...

void	transportReportRoutingTable (void)
	Reports content of routing table.

uint8_t	transportGetNodeId (void)
	Get node ID. More...

uint8_t	transportGetParentNodeId (void)
	Get parent node ID. More...

uint8_t	transportGetDistanceGW (void)
	Get distance to GW. More...

void	transportTogglePassiveMode (const bool OnOff)
	Toggle passive mode, i.e. transport does not wait for ACK. More...

void	transportDisable (void)
	Disable transport, if xxx_POWER_PIN is defined, transport is powered down, else send to sleep.

void	transportReInitialise (void)
	Reinitialise transport. Put transport to standby - If xxx_POWER_PIN set, power up and go to standby.

int16_t	transportSignalReport (const char command) __attribute__((unused))
	Get transport signal report. More...

int16_t	transportGetSignalReport (const signalReport_t signalReport) __attribute__((unused))
	Get transport signal report. More...

Macro Definition Documentation

◆ MY_TRANSPORT_MAX_TX_FAILURES

#define MY_TRANSPORT_MAX_TX_FAILURES (5u)

search for a new parent node after this many transmission failures, lower threshold for non-repeating nodes

Define to override max. consecutive TX failures until SNP is initiated.

Typedef Documentation

◆ transportRSSI_t

typedef int16_t transportRSSI_t

Datatype for internal RSSI storage.

Datatype for internal RSSI storage

Definition at line 281 of file MyTransport.h.

Function Documentation

◆ isMessageReceived()

bool isMessageReceived ( void )

Flag valid message received.

Returns: true if valid message received, needs to be reset if used

◆ isTransportExtendedFailure()

bool isTransportExtendedFailure ( void )

Flag TSM extended failure.

Returns: true if TSM had too many consecutive failure state entries

◆ isTransportReady()

bool isTransportReady ( void )

Flag transport ready.

Returns: true if transport is initialized and ready

◆ isTransportSearchingParent()

bool isTransportSearchingParent ( void )

Flag searching parent ongoing.

Returns: true if transport is searching for parent

◆ transportAssignNodeID()

bool transportAssignNodeID ( const uint8_t newNodeId )

Assign node ID.

Parameters

newNodeId New node ID

Returns: true if node ID is valid and successfully assigned

◆ transportCheckUplink()

bool transportCheckUplink ( const bool force = false )

Check uplink to GW, includes flooding control.

Parameters

force to override flood control timer

Returns: true if uplink ok

◆ transportGetDistanceGW()

uint8_t transportGetDistanceGW ( void )

Get distance to GW.

Returns: distance (=hops) to GW

◆ transportGetHeartbeat()

uint32_t transportGetHeartbeat ( void )

Return heart beat.

Returns: MS in current state

◆ transportGetNodeId()

uint8_t transportGetNodeId ( void )

Get node ID.

Returns: node ID

◆ transportGetParentNodeId()

uint8_t transportGetParentNodeId ( void )

Get parent node ID.

Returns: parent node ID

◆ transportGetRoute()

uint8_t transportGetRoute ( const uint8_t node )

Load route to node.

Parameters

node

Returns: route to node

◆ transportGetSignalReport()

int16_t transportGetSignalReport ( const signalReport_t signalReport )

Get transport signal report.

Parameters

signalReport

Returns: report

◆ transportPingNode()

uint8_t transportPingNode ( const uint8_t targetId )

Ping node.

Parameters

targetId Node to be pinged

Returns: hops from pinged node or 255 if no answer received within 2000ms

◆ transportRouteMessage()

bool transportRouteMessage ( MyMessage & message )

Send and route message according to destination.

This function is used in MyTransport and omits the transport state check, i.e. message can be sent even if transport is not ready

Parameters

message

Returns: true if message sent successfully

◆ transportSendRoute()

bool transportSendRoute ( MyMessage & message )

Send and route message according to destination with transport state check.

Parameters

message

Returns: true if message sent successfully and false if sending error or transport !OK

◆ transportSendWrite()

bool transportSendWrite	(	const uint8_t	to,
		MyMessage &	message
	)

Send message to recipient.

Parameters

to	Recipient of message
message

Returns: true if message sent successfully

◆ transportSetRoute()

void transportSetRoute	(	const uint8_t	node,
		const uint8_t	route
	)

Update routing table.

Parameters

node
route

◆ transportSignalReport()

int16_t transportSignalReport ( const char command )

Get transport signal report.

Parameters

command R = RSSI (if available) of incoming I_SIGNAL_REPORT_REQUEST message (from last hop) R! = RSSI (if available) of ACK to I_SIGNAL_REPORT_REVERSE message received from last hop S = SNR (if available) of incoming I_SIGNAL_REPORT_REQUEST message (from last hop) S! = SNR (if available) of ACK to I_SIGNAL_REPORT_REVERSE message received from last hop P = TX powerlevel in % T = TX powerlevel in dBm U = Uplink quality (via ACK from parent node), avg. RSSI

Returns: Signal report (if report is not available, INVALID_RSSI, INVALID_SNR, INVALID_PERCENT, or INVALID_LEVEL is sent instead)

◆ transportSwitchSM()

void transportSwitchSM ( transportState_t & newState )

Switch SM state.

Parameters

newState New state to switch SM to

◆ transportTimeInState()

uint32_t transportTimeInState ( void )

Request time in current SM state.

Returns: ms in current state

◆ transportTogglePassiveMode()

void transportTogglePassiveMode ( const bool OnOff )

Toggle passive mode, i.e. transport does not wait for ACK.

Parameters

OnOff

◆ transportWait()

bool transportWait	(	const uint32_t	waitingMS,
		const uint8_t	cmd,
		const uint8_t	msgType
	)

Wait and process messages for a defined amount of time until specified message received.

Parameters

waitingMS	Time to wait and process incoming messages in ms
cmd	Specific command
msgType	Specific message type

Returns: true if specified command received within waiting time

◆ transportWaitUntilReady()

bool transportWaitUntilReady ( const uint32_t waitingMS = 0 )

Wait until transport is ready.

Parameters

waitingMS timeout in MS, set 0 (default) for no timeout, i.e. wait indefinitely. For a node in standalone mode (optional network connection) set >0 to allow a node entering the main loop() function.

Returns: true if transport is ready

Detailed Description

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ MY_TRANSPORT_MAX_TX_FAILURES

Typedef Documentation

◆ transportRSSI_t

Function Documentation

◆ isMessageReceived()

◆ isTransportExtendedFailure()

◆ isTransportReady()

◆ isTransportSearchingParent()

◆ transportAssignNodeID()

◆ transportCheckUplink()

◆ transportGetDistanceGW()

◆ transportGetHeartbeat()

◆ transportGetNodeId()

◆ transportGetParentNodeId()

◆ transportGetRoute()

◆ transportGetSignalReport()

◆ transportPingNode()

◆ transportRouteMessage()

◆ transportSendRoute()

◆ transportSendWrite()

◆ transportSetRoute()

◆ transportSignalReport()

◆ transportSwitchSM()

◆ transportTimeInState()

◆ transportTogglePassiveMode()

◆ transportWait()

◆ transportWaitUntilReady()