Add ability to specify repeats for raw Pilight strings (#803)

* Add ability to specify repeats for raw Pilight strings

* Updated RF Pilight doc to add raw transmission tut

Added information about transmitting raw messages using the MQTTtoPilight topic, including using the new repeats functionality. Fixed some scattered English mistakes.

Author: melyux

.gitignore

@@ -1,3 +1,4 @@
 .pio
 .vscode
 *_env.ini
+**/.DS_Store

docs/use/rf.md

@@ -73,16 +73,31 @@ Generate your RF signals by pressing a remote button or other and you will see :
 
 ![](../img/OpenMQTTGateway_Pilight_Digoo-DG-R8S.png)
 
-### Send data by MQTT to convert it on RF signal 
-**ON**
+### Send data by MQTT to transmit a RF signal
 
+#### Using a known protocol
+**ON**
 `mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTtoPilight" -m '{"message":"{\"systemcode\":12,\"unitcode\":22,\"on\":1}","protocol":"elro_400_switch"}'`
 
 **OFF**
-
 `mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTtoPilight" -m '{"message":"{\"systemcode\":12,\"unitcode\":22,\"off\":1}","protocol":"elro_400_switch"}'`
 
-Theses commands will send by RF the signals to actuate an elro_400 switch
+These commands will transmit by RF the signals to actuate an elro_400 switch.
+
+#### Using a raw signal
+You can transmit raw signal data by using the "raw" protocol. This uses the Pilight pulse train string format. One such example string, representing a transmission for Nexus protocol weather stations, looks like this: `c:03020202010102020102010101010101010202020201020102020202020101010201010202;p:500,1000,2000,4000;r:12@`. This string represents pulses and gaps directly.
+
+Each number in the list after `p:` that ends with `;` stands for **p**ulse and gap lengths in microseconds (µs). In this example, we have a list containing lengths of 500µs, 1000µs, 2000µs, and 4000µs.
+
+Each number after `c:` and ended by `;` represents a **c**ode that references the `p:` list by index. In this example, the first 4 numbers after `c:` are 0, 3, 0, and 2, which reference `p:`[0] = 500, `p:`[3] = 4000, `p:`[0] = 500, and `p:`[2] = 2000, respectively. In the language of digital radio transceiving, the most basic unit is usually a pulse and gap pair; in other words, 0s and 1s are represented by a pulse followed by a gap (lack of pulse) and the time lengths of these pulses and gaps. Different protocols have different pulse lengths and gap lengths representing 0, and a different one representing 1. Because of this pulse-gap nature, the codes in `c:` must be taken as pairs; the first number in a pair represents the length of the pulse, and the second number the subsequent gap. In this example, the first pair, 03, represents a pulse of 500µs followed by a gap of 4000µs. The next pair, 02, represents a pulse of 500µs followed by a gap of 2000µs.
+
+The number after `r:` represents how many times the message in the string is to be **r**epeated. The `r:` block is optional. The default number of repeats if `r:` is not specified is 10. Greater than about 100 repeats will cause a crash due to memory usage. If this example were written without specifying repeats, it would look like this: `{"raw":"c:03020202010102020102010101010101010202020201020102020202020101010201010202;p:500,1000,2000,4000@"}`
+
+The entire string must end in a `@`. Each block must end in a `;`, but if it is the last block in the string, the `@` replaces the `;`. Since the `r:` block is optional, this last block could be either `p:` or `r:`.
+
+The JSON for the MQTT message to `home/OpenMQTTGateway/commands/MQTTtoPilight` should specify the pulse train string as the value for the "raw" key: `{"raw":"c:03020202010102020102010101010101010202020201020102020202020101010201010202;p:500,1000,2000,4000;r:12@"}`.
+
+e.g. `mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTtoPilight" -m '{"raw":"c:03020202010102020102010101010101010202020201020102020202020101010201010202;p:500,1000,2000,4000;r:12@"}'`
 
 ## RF with SONOFF RF BRIDGE
 ### Receiving data from RF signal

main/ZgatewayPilight.ino

@@ -108,10 +108,21 @@ void MQTTtoPilight(char* topicOri, JsonObject& Pilightdata) {
     const char* raw = Pilightdata["raw"];
     if (raw) {
       uint16_t codes[MAXPULSESTREAMLENGTH];
-      int msgLength = rf.stringToPulseTrain(
-          raw, codes, MAXPULSESTREAMLENGTH);
+      int repeats = rf.stringToRepeats(raw);
+      if (repeats < 0) {
+        switch (repeats) {
+          case ESPiLight::ERROR_INVALID_PULSETRAIN_MSG_R:
+            Log.trace(F("'r' not found in string, or has no data" CR));
+            break;
+          case ESPiLight::ERROR_INVALID_PULSETRAIN_MSG_END:
+            Log.trace(F("';' or '@' not found in data string" CR));
+            break;
+        }
+        repeats = 10;
+      }
+      int msgLength = rf.stringToPulseTrain(raw, codes, MAXPULSESTREAMLENGTH);
       if (msgLength > 0) {
-        rf.sendPulseTrain(codes, msgLength);
+        rf.sendPulseTrain(codes, msgLength, repeats);
         Log.notice(F("MQTTtoPilight raw ok" CR));
       } else {
         Log.trace(F("MQTTtoPilight raw KO" CR));

main/config_RF.h

@@ -78,7 +78,6 @@ extern void MQTTtoPilight(char* topicOri, JsonObject& RFdata);
 #define subjectMQTTtoPilight    "/commands/MQTTtoPilight"
 #define subjectPilighttoMQTT    "/PilighttoMQTT"
 #define subjectGTWPilighttoMQTT "/PilighttoMQTT"
-#define PilightRAW              "RAW"
 #define repeatPilightwMQTT      false // do we repeat a received signal by using mqtt with Pilight gateway
 
 /*-------------------CC1101 frequency----------------------*/