MySensors Library & Examples  2.3.0-32-g121648f
Classes | Macros | Typedefs | Functions
+ Collaboration diagram for MyTransport:

Detailed Description

API declaration for MyTransport.

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

Transport debug log messages:

ESYS 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 ACK REQ ACK message requested
TSF MSG ACK ACK 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 LEN=%d,EXP=%d Invalid message length (LEN), exptected length (EXP)
!TSF MSG PVER,%d!=%d Message protocol version mismatch (actual!=expected)
!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

Sending a message

Prepended char:

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)
 Get transport signal report. More...
 
int16_t transportGetSignalReport (const signalReport_t signalReport)
 Get transport signal report. More...
 

Macro Definition Documentation

#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

typedef int16_t transportRSSI_t

Datatype for internal RSSI storage.

Datatype for internal RSSI storage

Function Documentation

bool isMessageReceived ( void  )

Flag valid message received.

Returns
true if valid message received, needs to be reset if used
bool isTransportExtendedFailure ( void  )

Flag TSM extended failure.

Returns
true if TSM had too many consecutive failure state entries
bool isTransportReady ( void  )

Flag transport ready.

Returns
true if transport is initialized and ready
bool isTransportSearchingParent ( void  )

Flag searching parent ongoing.

Returns
true if transport is searching for parent
bool transportAssignNodeID ( const uint8_t  newNodeId)

Assign node ID.

Parameters
newNodeIdNew node ID
Returns
true if node ID is valid and successfully assigned
bool transportCheckUplink ( const bool  force = false)

Check uplink to GW, includes flooding control.

Parameters
forceto override flood control timer
Returns
true if uplink ok
uint8_t transportGetDistanceGW ( void  )

Get distance to GW.

Returns
distance (=hops) to GW
uint32_t transportGetHeartbeat ( void  )

Return heart beat.

Returns
MS in current state
uint8_t transportGetNodeId ( void  )

Get node ID.

Returns
node ID
uint8_t transportGetParentNodeId ( void  )

Get parent node ID.

Returns
parent node ID
uint8_t transportGetRoute ( const uint8_t  node)

Load route to node.

Parameters
node
Returns
route to node
int16_t transportGetSignalReport ( const signalReport_t  signalReport)

Get transport signal report.

Parameters
signalReport
Returns
report
uint8_t transportPingNode ( const uint8_t  targetId)

Ping node.

Parameters
targetIdNode to be pinged
Returns
hops from pinged node or 255 if no answer received within 2000ms
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
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
bool transportSendWrite ( const uint8_t  to,
MyMessage message 
)

Send message to recipient.

Parameters
toRecipient of message
message
Returns
true if message sent successfully
void transportSetRoute ( const uint8_t  node,
const uint8_t  route 
)

Update routing table.

Parameters
node
route
int16_t transportSignalReport ( const char  command)

Get transport signal report.

Parameters
commandR = 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)
void transportSwitchSM ( transportState_t newState)

Switch SM state.

Parameters
newStateNew state to switch SM to
uint32_t transportTimeInState ( void  )

Request time in current SM state.

Returns
ms in current state
void transportTogglePassiveMode ( const bool  OnOff)

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

Parameters
OnOff
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
waitingMSTime to wait and process incoming messages in ms
cmdSpecific command
msgTypeSpecific message type
Returns
true if specified command received within waiting time
bool transportWaitUntilReady ( const uint32_t  waitingMS = 0)

Wait until transport is ready.

Parameters
waitingMStimeout 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