Doxygenize MyGatewayTransport (#1023)

mysensors · Jan 1, 2018 · d557cb3 · d557cb3
1 parent 292dc84
commit d557cb3
Show file tree

Hide file tree

Showing 3 changed files with 94 additions and 43 deletions.
diff --git a/core/MyGatewayTransport.h b/core/MyGatewayTransport.h
@@ -17,46 +17,95 @@
  * version 2 as published by the Free Software Foundation.
  */
 
+/**
+* @file MyGatewayTransport.h
+*
+* @defgroup MyGatewayTransportgrp MyGatewayTransport
+* @ingroup internals
+* @{
+*
+*
+* Gateway transport-related log messages, format: [!]SYSTEM:[SUB SYSTEM:]MESSAGE
+* -[!] Exclamation mark is prepended in case of error
+* -SYSTEM:
+*  -<b>GWT</b>: messages emitted by MyGatewayTransport
+* -SUB SYSTEMS:
+*   -GWT:<b>TIN</b>		from @ref gatewayTransportInit()
+*   -GWT:<b>TPS</b>		from @ref gatewayTransportSend()
+*   -GWT:<b>RFC</b>		from _readFromClient()
+*   -GWT:<b>TSA</b>		from @ref gatewayTransportAvailable()
+*   -GWT:<b>TRC</b>		from @ref gatewayTransportReceive()
+*
+* Gateway transport debug log messages :
+*
+* |E| SYS | SUB   | Message                   | Comment
+* |-|-----|-------|---------------------------|---------------------------------------------------------------------
+* | | GWT | TIN   | CONNECTING...             | Connecting to router
+* | | GWT | TIN   | IP=%s                     | IP address obtained
+* |!| GWT | TIN   | DHCP FAIL                 | DHCP request failed
+* | | GWT | TIN   | ETH OK                    | Connected to network
+* |!| GWT | TIN   | ETH FAIL                  | Connection failed
+* | | GWT | TPS   | ETH OK                    | Connected to network
+* |!| GWT | TPS   | ETH FAIL                  | Connection failed
+* | | GWT | RFC   | C%d,MSG=%s                | Received message [%s] from client [%d]
+* |!| GWT | RFC   | C%d,MSG TOO LONG          | Received message from client [%d] too long
+* | | GWT | TSA   | UDP MSG=%s                | Received UDP message [%s]
+* | | GWT | TSA   | ETH OK                    | Connected to network
+* |!| GWT | TSA   | ETH FAIL                  | Connection failed
+* | | GWT | TSA   | C%d,DISCONNECTED          | Client [%d] disconnected
+* | | GWT | TSA   | C%d,CONNECTED             | Client [%d] connected
+* |!| GWT | TSA   | NO FREE SLOT              | No free slot for client
+* |!| GWT | TRC   | IP RENEW FAIL             | IP renewal failed
+*
+* @brief API declaration for MyGatewayTransport
+*
+*/
+
 #ifndef MyGatewayTransport_h
 #define MyGatewayTransport_h
 
 #include "MyProtocol.h"
 #include "MySensorsCore.h"
 
-#define MSG_GW_STARTUP_COMPLETE "Gateway startup complete."
+#define MSG_GW_STARTUP_COMPLETE "Gateway startup complete."		//!< Gateway startup message
 
-// debug output
 #if defined(MY_DEBUG_VERBOSE_GATEWAY)
-#define GATEWAY_DEBUG(x,...)	DEBUG_OUTPUT(x, ##__VA_ARGS__)	//!< debug
+#define GATEWAY_DEBUG(x,...)	DEBUG_OUTPUT(x, ##__VA_ARGS__)	//!< debug output
 #else
 #define GATEWAY_DEBUG(x,...)									//!< debug NULL
 #endif
 
-// Common gateway functions
-
+/**
+ * @brief Process gateway-related messages
+ */
 void gatewayTransportProcess(void);
 
-
-// Gateway "interface" functions
-
 /**
- * initialize the driver
+ * @brief Initialize gateway transport driver
+ * @return true if transport initialized
  */
 bool gatewayTransportInit(void);
 
 /**
- * Send message to controller
+ * @brief Send message to controller
+ * @param message to send
+ * @return true if message delivered
  */
 bool gatewayTransportSend(MyMessage &message);
 
-/*
- * Check if a new message is available from controller
+/**
+ * @brief Check if a new message is available from controller
+ * @return true if message available
  */
 bool gatewayTransportAvailable(void);
 
-/*
- * Pick up last message received from controller
+/**
+ * @brief Pick up last message received from controller
+ * @return message
  */
 MyMessage& gatewayTransportReceive(void);
 
 #endif /* MyGatewayTransportEthernet_h */
+
+/** @}*/
+
diff --git a/core/MyGatewayTransportEthernet.cpp b/core/MyGatewayTransportEthernet.cpp
@@ -132,9 +132,9 @@ bool gatewayTransportInit(void)
 	(void)WiFi.begin(MY_ESP8266_SSID, MY_ESP8266_PASSWORD, 0, MY_ESP8266_BSSID);
 	while (WiFi.status() != WL_CONNECTED) {
 		wait(500);
-		GATEWAY_DEBUG(PSTR("."));
+		GATEWAY_DEBUG(PSTR("GWT:TIN:CONNECTING...\n"));
 	}
-	GATEWAY_DEBUG(PSTR("IP: %s\n"), WiFi.localIP().toString().c_str());
+	GATEWAY_DEBUG(PSTR("GWT:TIN:IP=%s\n"), WiFi.localIP().toString().c_str());
 #endif /* End of MY_ESP8266_SSID */
 #elif defined(MY_GATEWAY_LINUX) /* Elif part of MY_GATEWAY_ESP8266 */
 	// Nothing to do here
@@ -147,12 +147,13 @@ bool gatewayTransportInit(void)
 #else /* Else part of MY_IP_GATEWAY_ADDRESS && MY_IP_SUBNET_ADDRESS */
 	// Get IP address from DHCP
 	if (!Ethernet.begin(_ethernetGatewayMAC)) {
-		GATEWAY_DEBUG(PSTR("DHCP FAILURE..."));
+		GATEWAY_DEBUG(PSTR("!GWT:TIN:DHCP FAIL\n"));
 		_w5100_spi_en(false);
 		return false;
 	}
 #endif /* End of MY_IP_GATEWAY_ADDRESS && MY_IP_SUBNET_ADDRESS */
-	GATEWAY_DEBUG(PSTR("IP: %" PRIu8 ".%" PRIu8 ".%" PRIu8 ".%" PRIu8 "\n"), Ethernet.localIP()[0],
+	GATEWAY_DEBUG(PSTR("GWT:TIN:IP=%" PRIu8 ".%" PRIu8 ".%" PRIu8 ".%" PRIu8 "\n"),
+	              Ethernet.localIP()[0],
 	              Ethernet.localIP()[1], Ethernet.localIP()[2], Ethernet.localIP()[3]);
 	// give the Ethernet interface a second to initialize
 	delay(1000);
@@ -170,14 +171,14 @@ bool gatewayTransportInit(void)
 #else
 	if (client.connect(_ethernetControllerIP, MY_PORT)) {
 #endif /* End of MY_CONTROLLER_URL_ADDRESS */
-		GATEWAY_DEBUG(PSTR("Eth: connect\n"));
+		GATEWAY_DEBUG(PSTR("GWT:TIN:ETH OK\n"));
 		_w5100_spi_en(false);
 		gatewayTransportSend(buildGw(_msgTmp, I_GATEWAY_READY).set(MSG_GW_STARTUP_COMPLETE));
 		_w5100_spi_en(true);
 		presentNode();
 	} else {
 		client.stop();
-		GATEWAY_DEBUG(PSTR("Eth: Failed to connect\n"));
+		GATEWAY_DEBUG(PSTR("!GWT:TIN:ETH FAIL\n"));
 	}
 #endif /* End of MY_USE_UDP */
 #else /* Else part of MY_GATEWAY_CLIENT_MODE */
@@ -219,14 +220,14 @@ bool gatewayTransportSend(MyMessage &message)
 #else
 		if (client.connect(_ethernetControllerIP, MY_PORT)) {
 #endif /* End of MY_CONTROLLER_URL_ADDRESS */
-			GATEWAY_DEBUG(PSTR("Eth: connect\n"));
+			GATEWAY_DEBUG(PSTR("GWT:TPS:ETH OK\n"));
 			_w5100_spi_en(false);
 			gatewayTransportSend(buildGw(_msgTmp, I_GATEWAY_READY).set(MSG_GW_STARTUP_COMPLETE));
 			_w5100_spi_en(true);
 			presentNode();
 		} else {
 			// connecting to the server failed!
-			GATEWAY_DEBUG(PSTR("Eth: Failed to connect\n"));
+			GATEWAY_DEBUG(PSTR("!GWT:TPS:ETH FAIL\n"));
 			_w5100_spi_en(false);
 			return false;
 		}
@@ -262,7 +263,7 @@ bool _readFromClient(uint8_t i)
 			if (inChar == '\n' || inChar == '\r') {
 				// Add string terminator and prepare for the next message
 				inputString[i].string[inputString[i].idx] = 0;
-				GATEWAY_DEBUG(PSTR("Client %" PRIu8 ": %s\n"), i, inputString[i].string);
+				GATEWAY_DEBUG(PSTR("GWT:RFC:C%" PRIu8 ",MSG=%s\n"), i, inputString[i].string);
 				inputString[i].idx = 0;
 				if (protocolParse(_ethernetMsg, inputString[i].string)) {
 					return true;
@@ -274,7 +275,7 @@ bool _readFromClient(uint8_t i)
 			}
 		} else {
 			// Incoming message too long. Throw away
-			GATEWAY_DEBUG(PSTR("Client %" PRIu8 ": Message too long\n"), i);
+			GATEWAY_DEBUG(PSTR("!GWT:RFC:C%" PRIu8 ",MSG TOO LONG\n"), i);
 			inputString[i].idx = 0;
 			// Finished with this client's message. Next loop() we'll see if there's more to read.
 			break;
@@ -292,7 +293,7 @@ bool _readFromClient(void)
 			if (inChar == '\n' || inChar == '\r') {
 				// Add string terminator and prepare for the next message
 				inputString.string[inputString.idx] = 0;
-				GATEWAY_DEBUG(PSTR("Eth: %s\n"), inputString.string);
+				GATEWAY_DEBUG(PSTR("GWT:RFC:MSG=%s\n"), inputString.string);
 				inputString.idx = 0;
 				if (protocolParse(_ethernetMsg, inputString.string)) {
 					return true;
@@ -304,7 +305,7 @@ bool _readFromClient(void)
 			}
 		} else {
 			// Incoming message too long. Throw away
-			GATEWAY_DEBUG(PSTR("Eth: Message too long\n"));
+			GATEWAY_DEBUG(PSTR("!GWT:RFC:MSG TOO LONG\n"));
 			inputString.idx = 0;
 			// Finished with this client's message. Next loop() we'll see if there's more to read.
 			break;
@@ -331,7 +332,7 @@ bool gatewayTransportAvailable(void)
 		//GATEWAY_DEBUG(PSTR("UDP packet available. Size:%" PRIu8 "\n"), packet_size);
 		_ethernetServer.read(inputString.string, MY_GATEWAY_MAX_RECEIVE_LENGTH);
 		inputString.string[packet_size] = 0;
-		GATEWAY_DEBUG(PSTR("UDP packet received: %s\n"), inputString.string);
+		GATEWAY_DEBUG(PSTR("GWT:TSA:UDP MSG=%s\n"), inputString.string);
 		_w5100_spi_en(false);
 		const bool ok = protocolParse(_ethernetMsg, inputString.string);
 		if (ok) {
@@ -347,13 +348,13 @@ bool gatewayTransportAvailable(void)
 #else
 		if (client.connect(_ethernetControllerIP, MY_PORT)) {
 #endif /* End of MY_CONTROLLER_URL_ADDRESS */
-			GATEWAY_DEBUG(PSTR("Eth: connect\n"));
+			GATEWAY_DEBUG(PSTR("GWT:TSA:ETH OK\n"));
 			_w5100_spi_en(false);
 			gatewayTransportSend(buildGw(_msgTmp, I_GATEWAY_READY).set(MSG_GW_STARTUP_COMPLETE));
 			_w5100_spi_en(true);
 			presentNode();
 		} else {
-			GATEWAY_DEBUG(PSTR("Eth: Failed to connect\n"));
+			GATEWAY_DEBUG(PSTR("!GWT:TSA:ETH FAIL\n"));
 			_w5100_spi_en(false);
 			return false;
 		}
@@ -372,14 +373,14 @@ bool gatewayTransportAvailable(void)
 	for (uint8_t i = 0; i < ARRAY_SIZE(clients); i++) {
 		if (!clients[i].connected()) {
 			if (clientsConnected[i]) {
-				GATEWAY_DEBUG(PSTR("Client %" PRIu8 " disconnected\n"), i);
+				GATEWAY_DEBUG(PSTR("GWT:TSA:C%" PRIu8 ",DISCONNECTED\n"), i);
 				clients[i].stop();
 			}
 			//check if there are any new clients
 			if (_ethernetServer.hasClient()) {
 				clients[i] = _ethernetServer.available();
 				inputString[i].idx = 0;
-				GATEWAY_DEBUG(PSTR("Client %" PRIu8 " connected\n"), i);
+				GATEWAY_DEBUG(PSTR("GWT:TSA:C%" PRIu8 ",CONNECTED\n"), i);
 				gatewayTransportSend(buildGw(_msgTmp, I_GATEWAY_READY).set(MSG_GW_STARTUP_COMPLETE));
 				// Send presentation of locally attached sensors (and node if applicable)
 				presentNode();
@@ -391,7 +392,7 @@ bool gatewayTransportAvailable(void)
 	}
 	if (allSlotsOccupied && _ethernetServer.hasClient()) {
 		//no free/disconnected spot so reject
-		GATEWAY_DEBUG(PSTR("No free slot available\n"));
+		GATEWAY_DEBUG(PSTR("!GWT:TSA:NO FREE SLOT\n"));
 		EthernetClient c = _ethernetServer.available();
 		c.stop();
 	}
@@ -411,7 +412,7 @@ bool gatewayTransportAvailable(void)
 		if (client != newclient) {
 			client.stop();
 			client = newclient;
-			GATEWAY_DEBUG(PSTR("Eth: connect\n"));
+			GATEWAY_DEBUG(PSTR("GWT:TSA:ETH OK\n"));
 			_w5100_spi_en(false);
 			gatewayTransportSend(buildGw(_msgTmp, I_GATEWAY_READY).set(MSG_GW_STARTUP_COMPLETE));
 			_w5100_spi_en(true);
@@ -420,7 +421,7 @@ bool gatewayTransportAvailable(void)
 	}
 	if (client) {
 		if (!client.connected()) {
-			GATEWAY_DEBUG(PSTR("Eth: disconnect\n"));
+			GATEWAY_DEBUG(PSTR("!GWT:TSA:ETH FAIL\n"));
 			client.stop();
 		} else {
 			if (_readFromClient()) {
@@ -460,7 +461,7 @@ void gatewayTransportRenewIP(void)
 		return;
 	}
 	if (Ethernet.maintain() & ~(0x06)) {
-		GATEWAY_DEBUG(PSTR("IP was not renewed correctly\n"));
+		GATEWAY_DEBUG(PSTR("!GWT:TRC:IP RENEW FAIL\n"));
 		/* Error occured -> IP was not renewed */
 		return;
 	}

diff --git a/core/MyGatewayTransportMQTTClient.cpp b/core/MyGatewayTransportMQTTClient.cpp
@@ -63,7 +63,7 @@ bool gatewayTransportSend(MyMessage &message)
 	}
 	setIndication(INDICATION_GW_TX);
 	char *topic = protocolFormatMQTTTopic(MY_MQTT_PUBLISH_TOPIC_PREFIX, message);
-	GATEWAY_DEBUG(PSTR("Sending message on topic: %s\n"), topic);
+	GATEWAY_DEBUG(PSTR("GWT:TPS:Sending message on topic: %s\n"), topic);
 #if defined(MY_MQTT_CLIENT_PUBLISH_RETAIN)
 	bool retain = mGetCommand(message) == C_SET ||
 	              (mGetCommand(message) == C_INTERNAL && message.type == I_BATTERY_LEVEL);
@@ -75,20 +75,20 @@ bool gatewayTransportSend(MyMessage &message)
 
 void incomingMQTT(char* topic, uint8_t* payload, unsigned int length)
 {
-	GATEWAY_DEBUG(PSTR("Message arrived on topic: %s\n"), topic);
+	GATEWAY_DEBUG(PSTR("GWT:TPS:Message arrived on topic: %s\n"), topic);
 	_MQTT_available = protocolMQTTParse(_MQTT_msg, topic, payload, length);
 }
 
 bool reconnectMQTT(void)
 {
-	GATEWAY_DEBUG(PSTR("Attempting MQTT connection...\n"));
+	GATEWAY_DEBUG(PSTR("GWT:TPS:Attempting MQTT connection...\n"));
 	// Attempt to connect
 	if (_MQTT_client.connect(MY_MQTT_CLIENT_ID
 #if defined(MY_MQTT_USER) && defined(MY_MQTT_PASSWORD)
 	                         , MY_MQTT_USER, MY_MQTT_PASSWORD
 #endif
 	                        )) {
-		GATEWAY_DEBUG(PSTR("MQTT connected\n"));
+		GATEWAY_DEBUG(PSTR("GWT:TPS:MQTT connected\n"));
 
 		// Send presentation of locally attached sensors (and node if applicable)
 		presentNode();
@@ -107,9 +107,9 @@ bool gatewayTransportConnect(void)
 #if defined(MY_GATEWAY_ESP8266)
 	while (WiFi.status() != WL_CONNECTED) {
 		wait(500);
-		GATEWAY_DEBUG(PSTR("."));
+		GATEWAY_DEBUG(PSTR("GWT:TPC:CONNECTING...\n"));
 	}
-	GATEWAY_DEBUG(PSTR("IP: %s\n"),WiFi.localIP().toString().c_str());
+	GATEWAY_DEBUG(PSTR("GWT:TPC:IP=%s\n"),WiFi.localIP().toString().c_str());
 #elif defined(MY_GATEWAY_LINUX) /* Elif part of MY_GATEWAY_ESP8266 */
 #if defined(MY_IP_ADDRESS)
 	_MQTT_ethClient.bind(_MQTT_clientIp);
@@ -120,12 +120,13 @@ bool gatewayTransportConnect(void)
 #else /* Else part of MY_IP_ADDRESS */
 	// Get IP address from DHCP
 	if (!Ethernet.begin(_MQTT_clientMAC)) {
-		GATEWAY_DEBUG(PSTR("DHCP FAILURE..."));
+		GATEWAY_DEBUG(PSTR("!GWT:TPC:DHCP FAIL\n"));
 		_MQTT_connecting = false;
 		return false;
 	}
 #endif /* End of MY_IP_ADDRESS */
-	GATEWAY_DEBUG(PSTR("IP: %" PRIu8 ".%" PRIu8 ".%" PRIu8 ".%" PRIu8 "\n"), Ethernet.localIP()[0],
+	GATEWAY_DEBUG(PSTR("GWT:TPC:IP=%" PRIu8 ".%" PRIu8 ".%" PRIu8 ".%" PRIu8 "\n"),
+	              Ethernet.localIP()[0],
 	              Ethernet.localIP()[1], Ethernet.localIP()[2], Ethernet.localIP()[3]);
 	// give the Ethernet interface a second to initialize
 	delay(1000);