Skip to content

Commit f36c4ae

Browse files
mfalkviddmfalkvidd
authored
Rename "soft ack" to echo (#1292)
* Rename "soft ack" to echo The ack parameter is often confused with what might be called "hardware ack" (see https://forum.mysensors.org/post/34263 for one of many lengthy discussions) This change should make it harder to confuse echo with the hardware ack, and reflects more accurately what will actually happen. This fixes #1103 I hope I have found all places where the naming needs to be changed, and that I haven't inadvertently renamed any of the *real* ack stuff. Thanks to @tekka007 for reviewing the changes and catching my mistakes.
1 parent cdfd8d7 commit f36c4ae

16 files changed

+177
-132
lines changed

‎MyConfig.h

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -85,14 +85,19 @@
8585
//#define MY_DEBUG_OTA (0)
8686

8787
/**
88-
* @def MY_DEBUG_OTA_DISABLE_ACK
89-
* @brief Define MY_DEBUG_OTA_DISABLE_ACK to send messages with no ACK flag.
88+
* @def MY_DEBUG_OTA_DISABLE_ECHO
89+
* @brief Define MY_DEBUG_OTA_DISABLE_ECHO to send messages without requesting the
90+
* destination to echo the message.
9091
*
9192
* This option reduces the latency added by OTA debug messages by sending packages
9293
* only once. You can loose debug messages.
9394
*
9495
*/
95-
//#define MY_DEBUG_OTA_DISABLE_ACK
96+
//#define MY_DEBUG_OTA_DISABLE_ECHO
97+
#if defined(MY_DEBUG_OTA_DISABLE_ACK) && !defined(DOXYGEN)
98+
#warning MY_DEBUG_OTA_DISABLE_ACK is deprecated, please use MY_DEBUG_OTA_DISABLE_ECHO instead
99+
#define MY_DEBUG_OTA_DISABLE_ECHO
100+
#endif
96101

97102
/**
98103
* @def MY_OTA_LOG_RECEIVER_FEATURE
@@ -2083,7 +2088,7 @@
20832088
#ifndef MY_OTA_LOG_SENDER_FEATURE
20842089
#define MY_OTA_LOG_SENDER_FEATURE
20852090
#endif
2086-
#ifndef MY_DEBUG_OTA_DISABLE_ACK
2091+
#ifndef MY_DEBUG_OTA_DISABLE_ECHO
20872092
#define DEBUG_OUTPUT(x,...) OTALog((MY_DEBUG_OTA), true, x, ##__VA_ARGS__) //!< debug
20882093
#else
20892094
#define DEBUG_OUTPUT(x,...) OTALog((MY_DEBUG_OTA), false, x, ##__VA_ARGS__) //!< debug
@@ -2174,7 +2179,7 @@
21742179
#define MY_DEBUG
21752180
#define MY_DEBUGDEVICE
21762181
#define MY_DEBUG_OTA
2177-
#define MY_DEBUG_OTA_DISABLE_ACK
2182+
#define MY_DEBUG_OTA_DISABLE_ECHO
21782183
#define MY_SPECIAL_DEBUG
21792184
#define MY_DISABLED_SERIAL
21802185
#define MY_SPLASH_SCREEN_DISABLED

‎core/MyGatewayTransport.cpp

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -31,13 +31,14 @@ inline void gatewayTransportProcess(void)
3131
_msg = gatewayTransportReceive();
3232
if (_msg.destination == GATEWAY_ADDRESS) {
3333

34-
// Check if sender requests an ack back.
35-
if (mGetRequestAck(_msg)) {
34+
// Check if sender requests an echo
35+
if (mGetRequestEcho(_msg)) {
3636
// Copy message
3737
_msgTmp = _msg;
38-
mSetRequestAck(_msgTmp,
39-
false); // Reply without ack flag (otherwise we would end up in an eternal loop)
40-
mSetAck(_msgTmp, true);
38+
// Reply without echo flag, otherwise we would end up in an eternal loop
39+
mSetRequestEcho(_msgTmp,
40+
false);
41+
mSetEcho(_msgTmp, true);
4142
_msgTmp.sender = getNodeId();
4243
_msgTmp.destination = _msg.sender;
4344
gatewayTransportSend(_msgTmp);

‎core/MyMessage.cpp

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ void MyMessage::clear(void)
4242
sender = 0u;
4343
destination = 0u; // Gateway is default destination
4444
version_length = 0u;
45-
command_ack_payload = 0u;
45+
command_echo_payload = 0u;
4646
type = 0u;
4747
sensor = 0u;
4848
(void)memset((void *)data, 0u, sizeof(data));
@@ -51,9 +51,15 @@ void MyMessage::clear(void)
5151
miSetVersion(PROTOCOL_VERSION);
5252
}
5353

54+
// TODO: Remove before v3 is released, use isEcho instead
5455
bool MyMessage::isAck(void) const
5556
{
56-
return miGetAck();
57+
return isEcho();
58+
}
59+
60+
bool MyMessage::isEcho(void) const
61+
{
62+
return miGetEcho();
5763
}
5864

5965
uint8_t MyMessage::getCommand(void) const

‎core/MyMessage.h

Lines changed: 28 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ typedef enum {
9696
S_WATER_QUALITY = 39 //!< V_TEMP, V_PH, V_ORP, V_EC, V_STATUS
9797
} mysensors_sensor_t;
9898

99-
/// @brief Type of sensor data (for set/req/ack messages)
99+
/// @brief Type of sensor data (for set/req/echo messages)
100100
typedef enum {
101101
V_TEMP = 0, //!< S_TEMP. Temperature S_TEMP, S_HEATER, S_HVAC
102102
V_HUM = 1, //!< S_HUM. Humidity
@@ -247,36 +247,36 @@ typedef enum {
247247
#define mSetLength(_message,_length) BF_SET(_message.version_length, _length, 3, 5) //!< Set length field
248248
#define mGetLength(_message) ((uint8_t)BF_GET(_message.version_length, 3, 5)) //!< Get length field
249249

250-
#define mSetCommand(_message,_command) BF_SET(_message.command_ack_payload, _command, 0, 3) //!< Set command field
251-
#define mGetCommand(_message) ((uint8_t)BF_GET(_message.command_ack_payload, 0, 3)) //!< Get command field
250+
#define mSetCommand(_message,_command) BF_SET(_message.command_echo_payload, _command, 0, 3) //!< Set command field
251+
#define mGetCommand(_message) ((uint8_t)BF_GET(_message.command_echo_payload, 0, 3)) //!< Get command field
252252

253-
#define mSetRequestAck(_message,_rack) BF_SET(_message.command_ack_payload, _rack, 3, 1) //!< Set ack-request field
254-
#define mGetRequestAck(_message) ((bool)BF_GET(_message.command_ack_payload, 3, 1)) //!< Get ack-request field
253+
#define mSetRequestEcho(_message,_rEcho) BF_SET(_message.command_echo_payload, _rEcho, 3, 1) //!< Set echo request field
254+
#define mGetRequestEcho(_message) ((bool)BF_GET(_message.command_echo_payload, 3, 1)) //!< Get echo request field
255255

256-
#define mSetAck(_message,_ackMsg) BF_SET(_message.command_ack_payload, _ackMsg, 4, 1) //!< Set ack field
257-
#define mGetAck(_message) ((bool)BF_GET(_message.command_ack_payload, 4, 1)) //!< Get ack field
256+
#define mSetEcho(_message,_echoMsg) BF_SET(_message.command_echo_payload, _echoMsg, 4, 1) //!< Set echo field
257+
#define mGetEcho(_message) ((bool)BF_GET(_message.command_echo_payload, 4, 1)) //!< Get echo field
258258

259-
#define mSetPayloadType(_message, _pt) BF_SET(_message.command_ack_payload, _pt, 5, 3) //!< Set payload type field
260-
#define mGetPayloadType(_message) ((uint8_t)BF_GET(_message.command_ack_payload, 5, 3)) //!< Get payload type field
259+
#define mSetPayloadType(_message, _pt) BF_SET(_message.command_echo_payload, _pt, 5, 3) //!< Set payload type field
260+
#define mGetPayloadType(_message) ((uint8_t)BF_GET(_message.command_echo_payload, 5, 3)) //!< Get payload type field
261261

262262

263263
// internal access for special fields
264-
#define miGetCommand() ((uint8_t)BF_GET(command_ack_payload, 0, 3)) //!< Internal getter for command field
264+
#define miGetCommand() ((uint8_t)BF_GET(command_echo_payload, 0, 3)) //!< Internal getter for command field
265265

266266
#define miSetLength(_length) BF_SET(version_length, _length, 3, 5) //!< Internal setter for length field
267267
#define miGetLength() ((uint8_t)BF_GET(version_length, 3, 5)) //!< Internal getter for length field
268268

269269
#define miSetVersion(_version) BF_SET(version_length, _version, 0, 2) //!< Internal setter for version field
270270
#define miGetVersion() ((uint8_t)BF_GET(version_length, 0, 2)) //!< Internal getter for version field
271271

272-
#define miSetRequestAck(_rack) BF_SET(command_ack_payload, _rack, 3, 1) //!< Internal setter for ack-request field
273-
#define miGetRequestAck() ((bool)BF_GET(command_ack_payload, 3, 1)) //!< Internal getter for ack-request field
272+
#define miSetRequestEcho(_rEcho) BF_SET(command_echo_payload, _rEcho, 3, 1) //!< Internal setter for echo request field
273+
#define miGetRequestEcho() ((bool)BF_GET(command_echo_payload, 3, 1)) //!< Internal getter for echo request field
274274

275-
#define miSetAck(_ack) BF_SET(command_ack_payload, _ack, 4, 1) //!< Internal setter for ack field
276-
#define miGetAck() ((bool)BF_GET(command_ack_payload, 4, 1)) //!< Internal getter for ack field
275+
#define miSetEcho(_echo) BF_SET(command_echo_payload, _echo, 4, 1) //!< Internal setter for echo field
276+
#define miGetEcho() ((bool)BF_GET(command_echo_payload, 4, 1)) //!< Internal getter for echo field
277277

278-
#define miSetPayloadType(_pt) BF_SET(command_ack_payload, _pt, 5, 3) //!< Internal setter for payload type field
279-
#define miGetPayloadType() (uint8_t)BF_GET(command_ack_payload, 5, 3) //!< Internal getter for payload type field
278+
#define miSetPayloadType(_pt) BF_SET(command_echo_payload, _pt, 5, 3) //!< Internal setter for payload type field
279+
#define miGetPayloadType() (uint8_t)BF_GET(command_echo_payload, 5, 3) //!< Internal getter for payload type field
280280

281281

282282
#if defined(__cplusplus) || defined(DOXYGEN)
@@ -380,11 +380,18 @@ class MyMessage
380380
uint8_t getCommand(void) const;
381381

382382
/**
383-
* @brief Getter for ack-flag.
384-
* @return true if this is an ack message
383+
* \deprecated use isEcho()
384+
* @brief Getter for echo-flag.
385+
* @return true if this is an echoed message
385386
*/
386387
bool isAck(void) const;
387388

389+
/**
390+
* @brief Getter for echo-flag.
391+
* @return true if this is an echoed message
392+
*/
393+
bool isEcho(void) const;
394+
388395
/**
389396
* @brief Set message type
390397
* @param type see http://korturl.nu/stupidurl
@@ -485,11 +492,11 @@ typedef union {
485492

486493
/**
487494
* 3 bit - Command type<br>
488-
* 1 bit - Request an ack - Indicator that receiver should send an ack back<br>
489-
* 1 bit - Is ack message - Indicator that this is the actual ack message<br>
495+
* 1 bit - Request an echo - Indicator that receiver should echo the message back to the sender<br>
496+
* 1 bit - Is echo message - Indicator that this is the echoed message<br>
490497
* 3 bit - Payload data type
491498
*/
492-
uint8_t command_ack_payload;
499+
uint8_t command_echo_payload;
493500

494501
uint8_t type; //!< 8 bit - Type varies depending on command
495502
uint8_t sensor; //!< 8 bit - Id of sensor that this message concerns.

‎core/MyOTALogging.cpp

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
// global variables
2323
static bool inOTALog = false;
2424

25-
void OTALog(uint8_t logNode, bool enableAck, const char *fmt, ... )
25+
void OTALog(uint8_t logNode, bool echo, const char *fmt, ... )
2626
{
2727
// Avoid recursion
2828
if (inOTALog==true) {
@@ -62,7 +62,7 @@ void OTALog(uint8_t logNode, bool enableAck, const char *fmt, ... )
6262
msg.sender = getNodeId();
6363
msg.setDestination(logNode);
6464
mSetCommand(msg, C_INTERNAL);
65-
mSetRequestAck(msg, enableAck);
65+
mSetRequestEcho(msg, echo);
6666

6767
// Send package
6868
for (int pos = 0; pos<n; pos+=MAX_PAYLOAD) {

‎core/MyOTALogging.h

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,11 +47,11 @@
4747
* new debug message line starts. Incomplete messages are ending with '...'
4848
*
4949
* @param logNode Destination node ID
50-
* @param enableAck Enable or disable ACK flag
50+
* @param echo Enable or disable echo flag
5151
* @param fmt printf format string
5252
* @param ... arguments
5353
*/
54-
void OTALog(uint8_t logNode, bool enableAck, const char *fmt, ... );
54+
void OTALog(uint8_t logNode, bool echo, const char *fmt, ... );
5555

5656
/**
5757
* @brief Handles output of OTA log or debug messages

‎core/MyProtocol.cpp

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ bool protocolSerial2MyMessage(MyMessage &message, char *inputString)
3333
uint8_t command = 0;
3434
message.sender = GATEWAY_ADDRESS;
3535
message.last = GATEWAY_ADDRESS;
36-
mSetAck(message, false);
36+
mSetEcho(message, false);
3737

3838
// Extract command data coming on serial line
3939
for (str = strtok_r(inputString, ";", &p); // split using semicolon
@@ -51,8 +51,8 @@ bool protocolSerial2MyMessage(MyMessage &message, char *inputString)
5151
command = atoi(str);
5252
mSetCommand(message, command);
5353
break;
54-
case 3: // Should we request ack from destination?
55-
mSetRequestAck(message, atoi(str) ? 1 : 0);
54+
case 3: // Should we request echo from destination?
55+
mSetRequestEcho(message, atoi(str) ? 1 : 0);
5656
break;
5757
case 4: // Data type
5858
message.type = atoi(str);
@@ -91,7 +91,7 @@ char *protocolMyMessage2Serial(MyMessage &message)
9191
{
9292
(void)snprintf_P(_fmtBuffer, MY_GATEWAY_MAX_SEND_LENGTH,
9393
PSTR("%" PRIu8 ";%" PRIu8 ";%" PRIu8 ";%" PRIu8 ";%" PRIu8 ";%s\n"), message.sender,
94-
message.sensor, mGetCommand(message), mGetAck(message), message.type,
94+
message.sensor, mGetCommand(message), mGetEcho(message), message.type,
9595
message.getString(_convBuffer));
9696
return _fmtBuffer;
9797
}
@@ -100,7 +100,7 @@ char *protocolMyMessage2MQTT(const char *prefix, MyMessage &message)
100100
{
101101
(void)snprintf_P(_fmtBuffer, MY_GATEWAY_MAX_SEND_LENGTH,
102102
PSTR("%s/%" PRIu8 "/%" PRIu8 "/%" PRIu8 "/%" PRIu8 "/%" PRIu8 ""), prefix,
103-
message.sender, message.sensor, mGetCommand(message), mGetAck(message), message.type);
103+
message.sender, message.sensor, mGetCommand(message), mGetEcho(message), message.type);
104104
return _fmtBuffer;
105105
}
106106

@@ -111,7 +111,7 @@ bool protocolMQTT2MyMessage(MyMessage &message, char *topic, uint8_t *payload,
111111
uint8_t index = 0;
112112
message.sender = GATEWAY_ADDRESS;
113113
message.last = GATEWAY_ADDRESS;
114-
mSetAck(message, false);
114+
mSetEcho(message, false);
115115
for (str = strtok_r(topic + strlen(MY_MQTT_SUBSCRIBE_TOPIC_PREFIX) + 1, "/", &p);
116116
str && index < 5;
117117
str = strtok_r(NULL, "/", &p)
@@ -150,8 +150,8 @@ bool protocolMQTT2MyMessage(MyMessage &message, char *topic, uint8_t *payload,
150150
break;
151151
}
152152
case 3:
153-
// Ack flag
154-
mSetRequestAck(message, atoi(str) ? 1 : 0);
153+
// Echo flag
154+
mSetRequestEcho(message, atoi(str) ? 1 : 0);
155155
break;
156156
case 4:
157157
// Sub type

‎core/MySensorsCore.cpp

Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -320,11 +320,11 @@ bool _sendRoute(MyMessage &message)
320320
#endif
321321
}
322322

323-
bool send(MyMessage &message, const bool enableAck)
323+
bool send(MyMessage &message, const bool echo)
324324
{
325325
message.sender = getNodeId();
326326
mSetCommand(message, C_SET);
327-
mSetRequestAck(message, enableAck);
327+
mSetRequestEcho(message, echo);
328328

329329
#if defined(MY_REGISTRATION_FEATURE) && !defined(MY_GATEWAY_FEATURE)
330330
if (_coreConfig.nodeRegistered) {
@@ -338,74 +338,74 @@ bool send(MyMessage &message, const bool enableAck)
338338
#endif
339339
}
340340

341-
bool sendBatteryLevel(const uint8_t value, const bool ack)
341+
bool sendBatteryLevel(const uint8_t value, const bool echo)
342342
{
343343
return _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, NODE_SENSOR_ID, C_INTERNAL, I_BATTERY_LEVEL,
344-
ack).set(value));
344+
echo).set(value));
345345
}
346346

347-
bool sendHeartbeat(const bool ack)
347+
bool sendHeartbeat(const bool echo)
348348
{
349349
#if defined(MY_SENSOR_NETWORK)
350350
const uint32_t heartbeat = transportGetHeartbeat();
351351
return _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, NODE_SENSOR_ID, C_INTERNAL, I_HEARTBEAT_RESPONSE,
352-
ack).set(heartbeat));
352+
echo).set(heartbeat));
353353
#elif defined(MY_GATEWAY_FEATURE)
354354
const uint32_t heartbeat = hwMillis();
355355
return _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, NODE_SENSOR_ID, C_INTERNAL, I_HEARTBEAT_RESPONSE,
356-
ack).set(heartbeat));
356+
echo).set(heartbeat));
357357
#else
358-
(void)ack;
358+
(void)echo;
359359
return false;
360360
#endif
361361
}
362362

363363

364364

365365
bool present(const uint8_t childSensorId, const uint8_t sensorType, const char *description,
366-
const bool ack)
366+
const bool echo)
367367
{
368368
return _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, childSensorId, C_PRESENTATION, sensorType,
369-
ack).set(childSensorId == NODE_SENSOR_ID ? MYSENSORS_LIBRARY_VERSION : description));
369+
echo).set(childSensorId == NODE_SENSOR_ID ? MYSENSORS_LIBRARY_VERSION : description));
370370
}
371371

372372
#if !defined(__linux__)
373373
bool present(const uint8_t childSensorId, const uint8_t sensorType,
374374
const __FlashStringHelper *description,
375-
const bool ack)
375+
const bool echo)
376376
{
377377
return _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, childSensorId, C_PRESENTATION, sensorType,
378-
ack).set(childSensorId == NODE_SENSOR_ID ? F(" MYSENSORS_LIBRARY_VERSION "): description));
378+
echo).set(childSensorId == NODE_SENSOR_ID ? F(" MYSENSORS_LIBRARY_VERSION "): description));
379379
}
380380
#endif
381381

382382

383-
bool sendSketchInfo(const char *name, const char *version, const bool ack)
383+
bool sendSketchInfo(const char *name, const char *version, const bool echo)
384384
{
385385
bool result = true;
386386
if (name) {
387387
result &= _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, NODE_SENSOR_ID, C_INTERNAL, I_SKETCH_NAME,
388-
ack).set(name));
388+
echo).set(name));
389389
}
390390
if (version) {
391391
result &= _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, NODE_SENSOR_ID, C_INTERNAL, I_SKETCH_VERSION,
392-
ack).set(version));
392+
echo).set(version));
393393
}
394394
return result;
395395
}
396396

397397
#if !defined(__linux__)
398398
bool sendSketchInfo(const __FlashStringHelper *name, const __FlashStringHelper *version,
399-
const bool ack)
399+
const bool echo)
400400
{
401401
bool result = true;
402402
if (name) {
403403
result &= _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, NODE_SENSOR_ID, C_INTERNAL, I_SKETCH_NAME,
404-
ack).set(name));
404+
echo).set(name));
405405
}
406406
if (version) {
407407
result &= _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, NODE_SENSOR_ID, C_INTERNAL, I_SKETCH_VERSION,
408-
ack).set(version));
408+
echo).set(version));
409409
}
410410
return result;
411411
}
@@ -416,9 +416,10 @@ bool request(const uint8_t childSensorId, const uint8_t variableType, const uint
416416
return _sendRoute(build(_msgTmp, destination, childSensorId, C_REQ, variableType).set(""));
417417
}
418418

419-
bool requestTime(const bool ack)
419+
bool requestTime(const bool echo)
420420
{
421-
return _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, NODE_SENSOR_ID, C_INTERNAL, I_TIME, ack).set(""));
421+
return _sendRoute(build(_msgTmp, GATEWAY_ADDRESS, NODE_SENSOR_ID, C_INTERNAL, I_TIME,
422+
echo).set(""));
422423
}
423424

424425
// Message delivered through _msg

0 commit comments

Comments
 (0)