MySensors Library & Examples  2.3.2-36-g2e00bf6
MyTransport.h
Go to the documentation of this file.
1 /*
2  * The MySensors Arduino library handles the wireless radio link and protocol
3  * between your home built sensors/actuators and HA controller of choice.
4  * The sensors forms a self healing radio network with optional repeaters. Each
5  * repeater and gateway builds a routing tables in EEPROM which keeps track of the
6  * network topology allowing messages to be routed to nodes.
7  *
8  * Created by Henrik Ekblad <[email protected]>
9  * Copyright (C) 2013-2020 Sensnology AB
10  * Full contributor list: https://github.com/mysensors/MySensors/graphs/contributors
11  *
12  * Documentation: http://www.mysensors.org
13  * Support Forum: http://forum.mysensors.org
14  *
15  * This program is free software; you can redistribute it and/or
16  * modify it under the terms of the GNU General Public License
17  * version 2 as published by the Free Software Foundation.
18  */
19 
200 #ifndef MyTransport_h
201 #define MyTransport_h
202 
203 #include "hal/transport/MyTransportHAL.h"
204 
205 #ifndef MY_TRANSPORT_MAX_TX_FAILURES
206 #if defined(MY_REPEATER_FEATURE)
207 #define MY_TRANSPORT_MAX_TX_FAILURES (10u)
208 #else
209 #define MY_TRANSPORT_MAX_TX_FAILURES (5u)
210 #endif
211 #endif
212 
213 #ifndef MY_TRANSPORT_MAX_TSM_FAILURES
214 #define MY_TRANSPORT_MAX_TSM_FAILURES (7u)
215 #endif
216 
217 #ifndef MY_TRANSPORT_TIMEOUT_FAILURE_STATE_MS
218 #define MY_TRANSPORT_TIMEOUT_FAILURE_STATE_MS (10*1000ul)
219 #endif
220 #ifndef MY_TRANSPORT_TIMEOUT_EXT_FAILURE_STATE_MS
221 #define MY_TRANSPORT_TIMEOUT_EXT_FAILURE_STATE_MS (60*1000ul)
222 #endif
223 #ifndef MY_TRANSPORT_STATE_TIMEOUT_MS
224 #define MY_TRANSPORT_STATE_TIMEOUT_MS (2*1000ul)
225 #endif
226 #ifndef MY_TRANSPORT_CHKUPL_INTERVAL_MS
227 #define MY_TRANSPORT_CHKUPL_INTERVAL_MS (10*1000ul)
228 #endif
229 #ifndef MY_TRANSPORT_STATE_RETRIES
230 #define MY_TRANSPORT_STATE_RETRIES (3u)
231 #endif
232 
233 #define AUTO (255u)
234 #define BROADCAST_ADDRESS (255u)
235 #define DISTANCE_INVALID (255u)
236 #define MAX_HOPS (254u)
237 #define INVALID_HOPS (255u)
238 #define MAX_SUBSEQ_MSGS (5u)
239 #define UPLINK_QUALITY_WEIGHT (0.05f)
240 
241 
242 // parent node check
243 #if defined(MY_PARENT_NODE_IS_STATIC) && !defined(MY_PARENT_NODE_ID)
244 #error MY_PARENT_NODE_IS_STATIC but no MY_PARENT_NODE_ID defined!
245 #endif
246 
247 #define _autoFindParent (bool)(MY_PARENT_NODE_ID == AUTO)
248 #define isValidDistance(_distance) (bool)(_distance!=DISTANCE_INVALID)
249 #define isValidParent(_parent) (bool)(_parent != AUTO)
250 
251 
254 typedef void(*transportCallback_t)(void);
255 
261 typedef struct {
262  uint8_t nodeId;
263  uint8_t parentNodeId;
264  uint8_t distanceGW;
265  uint8_t passiveMode : 1;
266  uint8_t reserved : 7;
268 
274 typedef struct {
275  void(*Transition)(void);
276  void(*Update)(void);
281 typedef int16_t transportRSSI_t;
282 
283 // helper macro for conversion
284 #define transportInternalToRSSI(__value) ((int16_t)__value >> 4)
285 #define transportRSSItoInternal(__value) ((transportRSSI_t)__value << 4)
286 
287 
292 typedef struct {
293  // SM variables
295  uint32_t stateEnter;
296  // general transport variables
297  uint32_t lastUplinkCheck;
298  // 8 bits
299  bool findingParentNode : 1;
301  bool uplinkOk : 1;
302  bool pingActive : 1;
303  bool transportActive : 1;
304  uint8_t stateRetries : 3;
305  // 8 bits
307  uint8_t failureCounter : 3;
308  bool msgReceived : 1;
309  uint8_t pingResponse;
310 #if defined(MY_SIGNAL_REPORT_ENABLED)
311  transportRSSI_t uplinkQualityRSSI;
312 #endif
313 } transportSM_t;
314 
318 typedef struct {
319  uint8_t route[SIZE_ROUTES];
321 
322 // PRIVATE functions
323 
327 void stInitTransition(void);
331 void stInitUpdate(void);
335 void stParentTransition(void);
339 void stParentUpdate(void);
343 void stIDTransition(void);
347 void stIDUpdate(void);
351 void stUplinkTransition(void);
355 void stUplinkUpdate(void);
359 void stReadyTransition(void);
363 void stReadyUpdate(void);
367 void stFailureTransition(void);
371 void stFailureUpdate(void);
376 void transportSwitchSM(transportState_t &newState);
380 void transportUpdateSM(void);
385 uint32_t transportTimeInState(void);
389 void transportInvokeSanityCheck(void);
393 void transportProcessFIFO(void);
397 void transportProcessMessage(void);
403 bool transportAssignNodeID(const uint8_t newNodeId);
411 bool transportWait(const uint32_t waitingMS, const uint8_t cmd, const uint8_t msgType);
417 uint8_t transportPingNode(const uint8_t targetId);
426 bool transportRouteMessage(MyMessage &message);
432 bool transportSendRoute(MyMessage &message);
439 bool transportSendWrite(const uint8_t to, MyMessage &message);
445 bool transportCheckUplink(const bool force = false);
446 
447 // PUBLIC functions
448 
454 bool transportWaitUntilReady(const uint32_t waitingMS = 0);
458 void transportInitialise(void);
462 void transportProcess(void);
467 bool isTransportReady(void);
472 bool isTransportSearchingParent(void);
477 bool isTransportExtendedFailure(void);
482 bool isMessageReceived(void);
486 void resetMessageReceived(void);
490 void transportClearRoutingTable(void);
495 uint32_t transportGetHeartbeat(void);
501 void transportLoadRoutingTable(void);
505 void transportSaveRoutingTable(void);
511 void transportSetRoute(const uint8_t node, const uint8_t route);
517 uint8_t transportGetRoute(const uint8_t node);
521 void transportReportRoutingTable(void);
526 uint8_t transportGetNodeId(void);
531 uint8_t transportGetParentNodeId(void);
536 uint8_t transportGetDistanceGW(void);
541 void transportTogglePassiveMode(const bool OnOff);
545 void transportDisable(void);
549 void transportReInitialise(void);
550 
563 int16_t transportSignalReport(const char command) __attribute__((unused));
564 
570 int16_t transportGetSignalReport(const signalReport_t signalReport) __attribute__((unused));
571 
572 #endif // MyTransport_h
573 
stInitUpdate
void stInitUpdate(void)
Initialize transport.
transportSendWrite
bool transportSendWrite(const uint8_t to, MyMessage &message)
Send message to recipient.
transportConfig_t::nodeId
uint8_t nodeId
Current node id.
Definition: MyTransport.h:262
routingTable_t
RAM routing table.
Definition: MyTransport.h:318
transportProcessFIFO
void transportProcessFIFO(void)
Process all pending messages in RX FIFO.
transportUpdateSM
void transportUpdateSM(void)
Update SM state.
stReadyUpdate
void stReadyUpdate(void)
Monitor transport link.
transportProcess
void transportProcess(void)
Process FIFO msg and update SM.
transportSM_t::pingActive
bool pingActive
flag ping active
Definition: MyTransport.h:302
transportCheckUplink
bool transportCheckUplink(const bool force=false)
Check uplink to GW, includes flooding control.
transportSM_t::failedUplinkTransmissions
uint8_t failedUplinkTransmissions
counter failed uplink transmissions (max 15)
Definition: MyTransport.h:306
transportGetParentNodeId
uint8_t transportGetParentNodeId(void)
Get parent node ID.
transportSaveRoutingTable
void transportSaveRoutingTable(void)
Save routing table to EEPROM.
transportConfig_t::passiveMode
uint8_t passiveMode
Passive mode.
Definition: MyTransport.h:265
transportSignalReport
int16_t transportSignalReport(const char command) __attribute__((unused))
Get transport signal report.
transportGetDistanceGW
uint8_t transportGetDistanceGW(void)
Get distance to GW.
stFailureTransition
void stFailureTransition(void)
Transport failure and power down radio.
stReadyTransition
void stReadyTransition(void)
Set transport OK.
transportSM_t::transportActive
bool transportActive
flag transport active
Definition: MyTransport.h:303
transportSM_t::currentState
transportState_t * currentState
pointer to current FSM state
Definition: MyTransport.h:294
transportWaitUntilReady
bool transportWaitUntilReady(const uint32_t waitingMS=0)
Wait until transport is ready.
transportSM_t::uplinkOk
bool uplinkOk
flag uplink ok
Definition: MyTransport.h:301
transportGetRoute
uint8_t transportGetRoute(const uint8_t node)
Load route to node.
transportGetSignalReport
int16_t transportGetSignalReport(const signalReport_t signalReport) __attribute__((unused))
Get transport signal report.
transportSM_t::lastUplinkCheck
uint32_t lastUplinkCheck
last uplink check, required to prevent GW flooding
Definition: MyTransport.h:297
transportSM_t::stateEnter
uint32_t stateEnter
state enter timepoint
Definition: MyTransport.h:295
transportTimeInState
uint32_t transportTimeInState(void)
Request time in current SM state.
transportGetNodeId
uint8_t transportGetNodeId(void)
Get node ID.
transportTogglePassiveMode
void transportTogglePassiveMode(const bool OnOff)
Toggle passive mode, i.e. transport does not wait for ACK.
isMessageReceived
bool isMessageReceived(void)
Flag valid message received.
transportRSSI_t
int16_t transportRSSI_t
Datatype for internal RSSI storage.
Definition: MyTransport.h:281
transportConfig_t::reserved
uint8_t reserved
Reserved.
Definition: MyTransport.h:266
stFailureUpdate
void stFailureUpdate(void)
Re-initialize transport after timeout.
transportConfig_t
Node configuration.
Definition: MyTransport.h:261
stInitTransition
void stInitTransition(void)
Initialize SM variables and transport HW.
stParentTransition
void stParentTransition(void)
Find parent.
__attribute__
struct @4::@5 __attribute__
Doxygen will complain without this comment.
Definition: DigitalPin.h:65
transportSM_t::pingResponse
uint8_t pingResponse
stores I_PONG hops
Definition: MyTransport.h:309
stParentUpdate
void stParentUpdate(void)
Verify find parent responses.
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.
stUplinkUpdate
void stUplinkUpdate(void)
Verify uplink response.
transportSwitchSM
void transportSwitchSM(transportState_t &newState)
Switch SM state.
SIZE_ROUTES
#define SIZE_ROUTES
Size routing table.
Definition: MyEepromAddresses.h:38
transportSetRoute
void transportSetRoute(const uint8_t node, const uint8_t route)
Update routing table.
stUplinkTransition
void stUplinkTransition(void)
Send uplink ping request.
transportPingNode
uint8_t transportPingNode(const uint8_t targetId)
Ping node.
transportLoadRoutingTable
void transportLoadRoutingTable(void)
Load routing table from EEPROM to RAM. Only for GW devices with enough RAM, i.e. ESP8266,...
transportSM_t::findingParentNode
bool findingParentNode
flag finding parent node is active
Definition: MyTransport.h:299
isTransportReady
bool isTransportReady(void)
Flag transport ready.
transportProcessMessage
void transportProcessMessage(void)
Receive message from RX FIFO and process.
transportGetHeartbeat
uint32_t transportGetHeartbeat(void)
Return heart beat.
isTransportExtendedFailure
bool isTransportExtendedFailure(void)
Flag TSM extended failure.
transportRouteMessage
bool transportRouteMessage(MyMessage &message)
Send and route message according to destination.
transportSM_t::failureCounter
uint8_t failureCounter
counter for TSM failures (max 7)
Definition: MyTransport.h:307
transportSM_t::stateRetries
uint8_t stateRetries
retries / state re-enter (max 7)
Definition: MyTransport.h:304
transportReInitialise
void transportReInitialise(void)
Reinitialise transport. Put transport to standby - If xxx_POWER_PIN set, power up and go to standby.
transportAssignNodeID
bool transportAssignNodeID(const uint8_t newNodeId)
Assign node ID.
transportClearRoutingTable
void transportClearRoutingTable(void)
Clear routing table.
resetMessageReceived
void resetMessageReceived(void)
Reset message received flag.
transportSM_t
Status variables and SM state.
Definition: MyTransport.h:292
transportConfig_t::parentNodeId
uint8_t parentNodeId
Where this node sends its messages.
Definition: MyTransport.h:263
transportDisable
void transportDisable(void)
Disable transport, if xxx_POWER_PIN is defined, transport is powered down, else send to sleep.
transportCallback_t
void(* transportCallback_t)(void)
Callback type.
Definition: MyTransport.h:254
transportSM_t::msgReceived
bool msgReceived
flag message received
Definition: MyTransport.h:308
stIDUpdate
void stIDUpdate(void)
Verify ID response and GW link.
transportInvokeSanityCheck
void transportInvokeSanityCheck(void)
Call transport driver sanity check.
transportInitialise
void transportInitialise(void)
Initialize transport and SM.
transportSM_t::preferredParentFound
bool preferredParentFound
flag preferred parent found
Definition: MyTransport.h:300
MyMessage
MyMessage is used to create, manipulate, send and read MySensors messages.
Definition: MyMessage.h:289
transportConfig_t::distanceGW
uint8_t distanceGW
This nodes distance to sensor net gateway (number of hops)
Definition: MyTransport.h:264
transportSendRoute
bool transportSendRoute(MyMessage &message)
Send and route message according to destination with transport state check.
isTransportSearchingParent
bool isTransportSearchingParent(void)
Flag searching parent ongoing.
transportReportRoutingTable
void transportReportRoutingTable(void)
Reports content of routing table.
transportState_t
SM state.
Definition: MyTransport.h:274
stIDTransition
void stIDTransition(void)
Send ID request.