Skip to content

Commit d557cb3

Browse files
tekka007henrikekblad
tekka007
authored and
henrikekblad
committed
Doxygenize MyGatewayTransport (#1023)
1 parent 292dc84 commit d557cb3

File tree

3 files changed

+94
-43
lines changed

3 files changed

+94
-43
lines changed

‎core/MyGatewayTransport.h

Lines changed: 63 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -17,46 +17,95 @@
1717
* version 2 as published by the Free Software Foundation.
1818
*/
1919

20+
/**
21+
* @file MyGatewayTransport.h
22+
*
23+
* @defgroup MyGatewayTransportgrp MyGatewayTransport
24+
* @ingroup internals
25+
* @{
26+
*
27+
*
28+
* Gateway transport-related log messages, format: [!]SYSTEM:[SUB SYSTEM:]MESSAGE
29+
* -[!] Exclamation mark is prepended in case of error
30+
* -SYSTEM:
31+
* -<b>GWT</b>: messages emitted by MyGatewayTransport
32+
* -SUB SYSTEMS:
33+
* -GWT:<b>TIN</b> from @ref gatewayTransportInit()
34+
* -GWT:<b>TPS</b> from @ref gatewayTransportSend()
35+
* -GWT:<b>RFC</b> from _readFromClient()
36+
* -GWT:<b>TSA</b> from @ref gatewayTransportAvailable()
37+
* -GWT:<b>TRC</b> from @ref gatewayTransportReceive()
38+
*
39+
* Gateway transport debug log messages :
40+
*
41+
* |E| SYS | SUB | Message | Comment
42+
* |-|-----|-------|---------------------------|---------------------------------------------------------------------
43+
* | | GWT | TIN | CONNECTING... | Connecting to router
44+
* | | GWT | TIN | IP=%s | IP address obtained
45+
* |!| GWT | TIN | DHCP FAIL | DHCP request failed
46+
* | | GWT | TIN | ETH OK | Connected to network
47+
* |!| GWT | TIN | ETH FAIL | Connection failed
48+
* | | GWT | TPS | ETH OK | Connected to network
49+
* |!| GWT | TPS | ETH FAIL | Connection failed
50+
* | | GWT | RFC | C%d,MSG=%s | Received message [%s] from client [%d]
51+
* |!| GWT | RFC | C%d,MSG TOO LONG | Received message from client [%d] too long
52+
* | | GWT | TSA | UDP MSG=%s | Received UDP message [%s]
53+
* | | GWT | TSA | ETH OK | Connected to network
54+
* |!| GWT | TSA | ETH FAIL | Connection failed
55+
* | | GWT | TSA | C%d,DISCONNECTED | Client [%d] disconnected
56+
* | | GWT | TSA | C%d,CONNECTED | Client [%d] connected
57+
* |!| GWT | TSA | NO FREE SLOT | No free slot for client
58+
* |!| GWT | TRC | IP RENEW FAIL | IP renewal failed
59+
*
60+
* @brief API declaration for MyGatewayTransport
61+
*
62+
*/
63+
2064
#ifndef MyGatewayTransport_h
2165
#define MyGatewayTransport_h
2266

2367
#include "MyProtocol.h"
2468
#include "MySensorsCore.h"
2569

26-
#define MSG_GW_STARTUP_COMPLETE "Gateway startup complete."
70+
#define MSG_GW_STARTUP_COMPLETE "Gateway startup complete." //!< Gateway startup message
2771

28-
// debug output
2972
#if defined(MY_DEBUG_VERBOSE_GATEWAY)
30-
#define GATEWAY_DEBUG(x,...) DEBUG_OUTPUT(x, ##__VA_ARGS__) //!< debug
73+
#define GATEWAY_DEBUG(x,...) DEBUG_OUTPUT(x, ##__VA_ARGS__) //!< debug output
3174
#else
3275
#define GATEWAY_DEBUG(x,...) //!< debug NULL
3376
#endif
3477

35-
// Common gateway functions
36-
78+
/**
79+
* @brief Process gateway-related messages
80+
*/
3781
void gatewayTransportProcess(void);
3882

39-
40-
// Gateway "interface" functions
41-
4283
/**
43-
* initialize the driver
84+
* @brief Initialize gateway transport driver
85+
* @return true if transport initialized
4486
*/
4587
bool gatewayTransportInit(void);
4688

4789
/**
48-
* Send message to controller
90+
* @brief Send message to controller
91+
* @param message to send
92+
* @return true if message delivered
4993
*/
5094
bool gatewayTransportSend(MyMessage &message);
5195

52-
/*
53-
* Check if a new message is available from controller
96+
/**
97+
* @brief Check if a new message is available from controller
98+
* @return true if message available
5499
*/
55100
bool gatewayTransportAvailable(void);
56101

57-
/*
58-
* Pick up last message received from controller
102+
/**
103+
* @brief Pick up last message received from controller
104+
* @return message
59105
*/
60106
MyMessage& gatewayTransportReceive(void);
61107

62108
#endif /* MyGatewayTransportEthernet_h */
109+
110+
/** @}*/
111+

‎core/MyGatewayTransportEthernet.cpp

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -132,9 +132,9 @@ bool gatewayTransportInit(void)
132132
(void)WiFi.begin(MY_ESP8266_SSID, MY_ESP8266_PASSWORD, 0, MY_ESP8266_BSSID);
133133
while (WiFi.status() != WL_CONNECTED) {
134134
wait(500);
135-
GATEWAY_DEBUG(PSTR("."));
135+
GATEWAY_DEBUG(PSTR("GWT:TIN:CONNECTING...\n"));
136136
}
137-
GATEWAY_DEBUG(PSTR("IP: %s\n"), WiFi.localIP().toString().c_str());
137+
GATEWAY_DEBUG(PSTR("GWT:TIN:IP=%s\n"), WiFi.localIP().toString().c_str());
138138
#endif /* End of MY_ESP8266_SSID */
139139
#elif defined(MY_GATEWAY_LINUX) /* Elif part of MY_GATEWAY_ESP8266 */
140140
// Nothing to do here
@@ -147,12 +147,13 @@ bool gatewayTransportInit(void)
147147
#else /* Else part of MY_IP_GATEWAY_ADDRESS && MY_IP_SUBNET_ADDRESS */
148148
// Get IP address from DHCP
149149
if (!Ethernet.begin(_ethernetGatewayMAC)) {
150-
GATEWAY_DEBUG(PSTR("DHCP FAILURE..."));
150+
GATEWAY_DEBUG(PSTR("!GWT:TIN:DHCP FAIL\n"));
151151
_w5100_spi_en(false);
152152
return false;
153153
}
154154
#endif /* End of MY_IP_GATEWAY_ADDRESS && MY_IP_SUBNET_ADDRESS */
155-
GATEWAY_DEBUG(PSTR("IP: %" PRIu8 ".%" PRIu8 ".%" PRIu8 ".%" PRIu8 "\n"), Ethernet.localIP()[0],
155+
GATEWAY_DEBUG(PSTR("GWT:TIN:IP=%" PRIu8 ".%" PRIu8 ".%" PRIu8 ".%" PRIu8 "\n"),
156+
Ethernet.localIP()[0],
156157
Ethernet.localIP()[1], Ethernet.localIP()[2], Ethernet.localIP()[3]);
157158
// give the Ethernet interface a second to initialize
158159
delay(1000);
@@ -170,14 +171,14 @@ bool gatewayTransportInit(void)
170171
#else
171172
if (client.connect(_ethernetControllerIP, MY_PORT)) {
172173
#endif /* End of MY_CONTROLLER_URL_ADDRESS */
173-
GATEWAY_DEBUG(PSTR("Eth: connect\n"));
174+
GATEWAY_DEBUG(PSTR("GWT:TIN:ETH OK\n"));
174175
_w5100_spi_en(false);
175176
gatewayTransportSend(buildGw(_msgTmp, I_GATEWAY_READY).set(MSG_GW_STARTUP_COMPLETE));
176177
_w5100_spi_en(true);
177178
presentNode();
178179
} else {
179180
client.stop();
180-
GATEWAY_DEBUG(PSTR("Eth: Failed to connect\n"));
181+
GATEWAY_DEBUG(PSTR("!GWT:TIN:ETH FAIL\n"));
181182
}
182183
#endif /* End of MY_USE_UDP */
183184
#else /* Else part of MY_GATEWAY_CLIENT_MODE */
@@ -219,14 +220,14 @@ bool gatewayTransportSend(MyMessage &message)
219220
#else
220221
if (client.connect(_ethernetControllerIP, MY_PORT)) {
221222
#endif /* End of MY_CONTROLLER_URL_ADDRESS */
222-
GATEWAY_DEBUG(PSTR("Eth: connect\n"));
223+
GATEWAY_DEBUG(PSTR("GWT:TPS:ETH OK\n"));
223224
_w5100_spi_en(false);
224225
gatewayTransportSend(buildGw(_msgTmp, I_GATEWAY_READY).set(MSG_GW_STARTUP_COMPLETE));
225226
_w5100_spi_en(true);
226227
presentNode();
227228
} else {
228229
// connecting to the server failed!
229-
GATEWAY_DEBUG(PSTR("Eth: Failed to connect\n"));
230+
GATEWAY_DEBUG(PSTR("!GWT:TPS:ETH FAIL\n"));
230231
_w5100_spi_en(false);
231232
return false;
232233
}
@@ -262,7 +263,7 @@ bool _readFromClient(uint8_t i)
262263
if (inChar == '\n' || inChar == '\r') {
263264
// Add string terminator and prepare for the next message
264265
inputString[i].string[inputString[i].idx] = 0;
265-
GATEWAY_DEBUG(PSTR("Client %" PRIu8 ": %s\n"), i, inputString[i].string);
266+
GATEWAY_DEBUG(PSTR("GWT:RFC:C%" PRIu8 ",MSG=%s\n"), i, inputString[i].string);
266267
inputString[i].idx = 0;
267268
if (protocolParse(_ethernetMsg, inputString[i].string)) {
268269
return true;
@@ -274,7 +275,7 @@ bool _readFromClient(uint8_t i)
274275
}
275276
} else {
276277
// Incoming message too long. Throw away
277-
GATEWAY_DEBUG(PSTR("Client %" PRIu8 ": Message too long\n"), i);
278+
GATEWAY_DEBUG(PSTR("!GWT:RFC:C%" PRIu8 ",MSG TOO LONG\n"), i);
278279
inputString[i].idx = 0;
279280
// Finished with this client's message. Next loop() we'll see if there's more to read.
280281
break;
@@ -292,7 +293,7 @@ bool _readFromClient(void)
292293
if (inChar == '\n' || inChar == '\r') {
293294
// Add string terminator and prepare for the next message
294295
inputString.string[inputString.idx] = 0;
295-
GATEWAY_DEBUG(PSTR("Eth: %s\n"), inputString.string);
296+
GATEWAY_DEBUG(PSTR("GWT:RFC:MSG=%s\n"), inputString.string);
296297
inputString.idx = 0;
297298
if (protocolParse(_ethernetMsg, inputString.string)) {
298299
return true;
@@ -304,7 +305,7 @@ bool _readFromClient(void)
304305
}
305306
} else {
306307
// Incoming message too long. Throw away
307-
GATEWAY_DEBUG(PSTR("Eth: Message too long\n"));
308+
GATEWAY_DEBUG(PSTR("!GWT:RFC:MSG TOO LONG\n"));
308309
inputString.idx = 0;
309310
// Finished with this client's message. Next loop() we'll see if there's more to read.
310311
break;
@@ -331,7 +332,7 @@ bool gatewayTransportAvailable(void)
331332
//GATEWAY_DEBUG(PSTR("UDP packet available. Size:%" PRIu8 "\n"), packet_size);
332333
_ethernetServer.read(inputString.string, MY_GATEWAY_MAX_RECEIVE_LENGTH);
333334
inputString.string[packet_size] = 0;
334-
GATEWAY_DEBUG(PSTR("UDP packet received: %s\n"), inputString.string);
335+
GATEWAY_DEBUG(PSTR("GWT:TSA:UDP MSG=%s\n"), inputString.string);
335336
_w5100_spi_en(false);
336337
const bool ok = protocolParse(_ethernetMsg, inputString.string);
337338
if (ok) {
@@ -347,13 +348,13 @@ bool gatewayTransportAvailable(void)
347348
#else
348349
if (client.connect(_ethernetControllerIP, MY_PORT)) {
349350
#endif /* End of MY_CONTROLLER_URL_ADDRESS */
350-
GATEWAY_DEBUG(PSTR("Eth: connect\n"));
351+
GATEWAY_DEBUG(PSTR("GWT:TSA:ETH OK\n"));
351352
_w5100_spi_en(false);
352353
gatewayTransportSend(buildGw(_msgTmp, I_GATEWAY_READY).set(MSG_GW_STARTUP_COMPLETE));
353354
_w5100_spi_en(true);
354355
presentNode();
355356
} else {
356-
GATEWAY_DEBUG(PSTR("Eth: Failed to connect\n"));
357+
GATEWAY_DEBUG(PSTR("!GWT:TSA:ETH FAIL\n"));
357358
_w5100_spi_en(false);
358359
return false;
359360
}
@@ -372,14 +373,14 @@ bool gatewayTransportAvailable(void)
372373
for (uint8_t i = 0; i < ARRAY_SIZE(clients); i++) {
373374
if (!clients[i].connected()) {
374375
if (clientsConnected[i]) {
375-
GATEWAY_DEBUG(PSTR("Client %" PRIu8 " disconnected\n"), i);
376+
GATEWAY_DEBUG(PSTR("GWT:TSA:C%" PRIu8 ",DISCONNECTED\n"), i);
376377
clients[i].stop();
377378
}
378379
//check if there are any new clients
379380
if (_ethernetServer.hasClient()) {
380381
clients[i] = _ethernetServer.available();
381382
inputString[i].idx = 0;
382-
GATEWAY_DEBUG(PSTR("Client %" PRIu8 " connected\n"), i);
383+
GATEWAY_DEBUG(PSTR("GWT:TSA:C%" PRIu8 ",CONNECTED\n"), i);
383384
gatewayTransportSend(buildGw(_msgTmp, I_GATEWAY_READY).set(MSG_GW_STARTUP_COMPLETE));
384385
// Send presentation of locally attached sensors (and node if applicable)
385386
presentNode();
@@ -391,7 +392,7 @@ bool gatewayTransportAvailable(void)
391392
}
392393
if (allSlotsOccupied && _ethernetServer.hasClient()) {
393394
//no free/disconnected spot so reject
394-
GATEWAY_DEBUG(PSTR("No free slot available\n"));
395+
GATEWAY_DEBUG(PSTR("!GWT:TSA:NO FREE SLOT\n"));
395396
EthernetClient c = _ethernetServer.available();
396397
c.stop();
397398
}
@@ -411,7 +412,7 @@ bool gatewayTransportAvailable(void)
411412
if (client != newclient) {
412413
client.stop();
413414
client = newclient;
414-
GATEWAY_DEBUG(PSTR("Eth: connect\n"));
415+
GATEWAY_DEBUG(PSTR("GWT:TSA:ETH OK\n"));
415416
_w5100_spi_en(false);
416417
gatewayTransportSend(buildGw(_msgTmp, I_GATEWAY_READY).set(MSG_GW_STARTUP_COMPLETE));
417418
_w5100_spi_en(true);
@@ -420,7 +421,7 @@ bool gatewayTransportAvailable(void)
420421
}
421422
if (client) {
422423
if (!client.connected()) {
423-
GATEWAY_DEBUG(PSTR("Eth: disconnect\n"));
424+
GATEWAY_DEBUG(PSTR("!GWT:TSA:ETH FAIL\n"));
424425
client.stop();
425426
} else {
426427
if (_readFromClient()) {
@@ -460,7 +461,7 @@ void gatewayTransportRenewIP(void)
460461
return;
461462
}
462463
if (Ethernet.maintain() & ~(0x06)) {
463-
GATEWAY_DEBUG(PSTR("IP was not renewed correctly\n"));
464+
GATEWAY_DEBUG(PSTR("!GWT:TRC:IP RENEW FAIL\n"));
464465
/* Error occured -> IP was not renewed */
465466
return;
466467
}

‎core/MyGatewayTransportMQTTClient.cpp

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ bool gatewayTransportSend(MyMessage &message)
6363
}
6464
setIndication(INDICATION_GW_TX);
6565
char *topic = protocolFormatMQTTTopic(MY_MQTT_PUBLISH_TOPIC_PREFIX, message);
66-
GATEWAY_DEBUG(PSTR("Sending message on topic: %s\n"), topic);
66+
GATEWAY_DEBUG(PSTR("GWT:TPS:Sending message on topic: %s\n"), topic);
6767
#if defined(MY_MQTT_CLIENT_PUBLISH_RETAIN)
6868
bool retain = mGetCommand(message) == C_SET ||
6969
(mGetCommand(message) == C_INTERNAL && message.type == I_BATTERY_LEVEL);
@@ -75,20 +75,20 @@ bool gatewayTransportSend(MyMessage &message)
7575

7676
void incomingMQTT(char* topic, uint8_t* payload, unsigned int length)
7777
{
78-
GATEWAY_DEBUG(PSTR("Message arrived on topic: %s\n"), topic);
78+
GATEWAY_DEBUG(PSTR("GWT:TPS:Message arrived on topic: %s\n"), topic);
7979
_MQTT_available = protocolMQTTParse(_MQTT_msg, topic, payload, length);
8080
}
8181

8282
bool reconnectMQTT(void)
8383
{
84-
GATEWAY_DEBUG(PSTR("Attempting MQTT connection...\n"));
84+
GATEWAY_DEBUG(PSTR("GWT:TPS:Attempting MQTT connection...\n"));
8585
// Attempt to connect
8686
if (_MQTT_client.connect(MY_MQTT_CLIENT_ID
8787
#if defined(MY_MQTT_USER) && defined(MY_MQTT_PASSWORD)
8888
, MY_MQTT_USER, MY_MQTT_PASSWORD
8989
#endif
9090
)) {
91-
GATEWAY_DEBUG(PSTR("MQTT connected\n"));
91+
GATEWAY_DEBUG(PSTR("GWT:TPS:MQTT connected\n"));
9292

9393
// Send presentation of locally attached sensors (and node if applicable)
9494
presentNode();
@@ -107,9 +107,9 @@ bool gatewayTransportConnect(void)
107107
#if defined(MY_GATEWAY_ESP8266)
108108
while (WiFi.status() != WL_CONNECTED) {
109109
wait(500);
110-
GATEWAY_DEBUG(PSTR("."));
110+
GATEWAY_DEBUG(PSTR("GWT:TPC:CONNECTING...\n"));
111111
}
112-
GATEWAY_DEBUG(PSTR("IP: %s\n"),WiFi.localIP().toString().c_str());
112+
GATEWAY_DEBUG(PSTR("GWT:TPC:IP=%s\n"),WiFi.localIP().toString().c_str());
113113
#elif defined(MY_GATEWAY_LINUX) /* Elif part of MY_GATEWAY_ESP8266 */
114114
#if defined(MY_IP_ADDRESS)
115115
_MQTT_ethClient.bind(_MQTT_clientIp);
@@ -120,12 +120,13 @@ bool gatewayTransportConnect(void)
120120
#else /* Else part of MY_IP_ADDRESS */
121121
// Get IP address from DHCP
122122
if (!Ethernet.begin(_MQTT_clientMAC)) {
123-
GATEWAY_DEBUG(PSTR("DHCP FAILURE..."));
123+
GATEWAY_DEBUG(PSTR("!GWT:TPC:DHCP FAIL\n"));
124124
_MQTT_connecting = false;
125125
return false;
126126
}
127127
#endif /* End of MY_IP_ADDRESS */
128-
GATEWAY_DEBUG(PSTR("IP: %" PRIu8 ".%" PRIu8 ".%" PRIu8 ".%" PRIu8 "\n"), Ethernet.localIP()[0],
128+
GATEWAY_DEBUG(PSTR("GWT:TPC:IP=%" PRIu8 ".%" PRIu8 ".%" PRIu8 ".%" PRIu8 "\n"),
129+
Ethernet.localIP()[0],
129130
Ethernet.localIP()[1], Ethernet.localIP()[2], Ethernet.localIP()[3]);
130131
// give the Ethernet interface a second to initialize
131132
delay(1000);

0 commit comments

Comments
 (0)