Modification:

1. Change the testbed circuit.
The TX and RX Arduinos now use "Serial1" to synchronize between
experimental traces, which is a more robust way than the previous one
(the voltage of two digital pins are not stable enough during
transmission, and will lead to unexpected save file break).

2. Change the Arduino codes according to the above modification.

3. Fix some bugs in the "plain0" TX Arduino codes.

4. Fix some bugs in the data processing and figure plotting code.
Some data processing were missing, and figure plotting used wrong
results.

5. Add a main file "main_sim_txrx.m" which calls the simulation
functions used in the early stage of the project, which is not fully
compatible with the latest decoder.

6. About documentation.
- Add detailed description on the two MATLAB toolboxes used in the code,
which are highly recommended. The modification of corresponding codes to
avoid these toolboxes are also provided.
- Fix the description about the symbol interval of the data.

Arduino/Rx/Rx.ino

@@ -10,34 +10,32 @@ const int Ts = 5; //Gap between sampling in ms
 //********************************************
 
 //*****************Setup Connections**********
-const int sync = 9;
-const int ack  = 8; //acknowledge to tx that rx is ready
-const int chipSelect = 10;
+int record = LOW;
+const int chipSelect = 53;
 const byte ECsensorPin = A1;  // EC Meter analog output,pin on analog 1
 //********************************************
 
 //*******************Variables****************
 File myFile;
 
-int fileIndex = 15;
+int fileIndex = 6;
 char fileName[50];
 int activated = 0;
 
 unsigned int AnalogReading;
 unsigned long AnalogSampleTime;
+
 //*********************************************
 void rx_receive (void);
 Ticker timerRx (rx_receive, Ts, 0, MILLIS);
 
-void setup()
-{
-  pinMode (sync, INPUT);
-  pinMode (ack, OUTPUT);
-  digitalWrite (ack,LOW);
-
+void setup ()
+{  
   while (activated == 0)
   {
     Serial.begin (115200);
+    Serial1.begin (19200);
+
     Serial.print ("\n\n\n\n\n");
     Serial.print ("Initializing SD card...");
     if (!SD.begin (chipSelect)) 
@@ -54,19 +52,36 @@ void setup()
   AnalogReading = 0;
   AnalogSampleTime = millis ();
   AnalogReading = analogRead (ECsensorPin);
-  digitalWrite (ack, HIGH);
+  Serial1.write ('a');
 }
 
 void loop ()
 {
-  switch (digitalRead (sync))
+  Serial1.write ('a');
+  if (Serial1.available ())
+  {
+    switch (Serial1.read ())
+    {
+      case 'a':
+        record = HIGH;
+        break;
+      case 'z':
+        record = LOW;
+        break;
+      default:
+        Serial.println ("Tx sent a wrong message");
+        exit (0);
+    }
+  }
+
+  switch (record)
   {
     case HIGH:
       if (!myFile)
       {
         Serial.print ("Opening File Number: ");
         Serial.println (fileIndex);
-        sprintf(fileName, "%02d.txt", fileIndex);
+        sprintf (fileName, "%02d.txt", fileIndex);
         if (SD.exists (fileName)) {SD.remove (fileName);}
         myFile = SD.open (fileName, FILE_WRITE);
         if (myFile) {Serial.println ("File Created");}
@@ -103,4 +118,5 @@ void rx_receive (void)
   myFile.print (AnalogSampleTime);
   myFile.print ('\t');
   myFile.println (AnalogReading);
+  // Serial.println (AnalogReading);
 }

README.md

@@ -14,9 +14,46 @@ Use `git clone` to download this repository.
 
 This project is composed of the experiment part and the data processing part.
 
-For experiment part, please prepare two Arduinos (one for TXs and one for RX) and install the Arduino IDE. The required `Ticker.h` and `OneWire.h` can be downloaded from the Arduino IDE library.
-
-For data processing part, please install MATLAB R2019b or any later version. Please install any toolbox that is reported missing when you run the scripts.
+### Experiment
+
+For experiment part, please prepare two Arduinos (one for TXs and one for RX) and install the Arduino IDE. The following two header files required to run the code, which can be found in the Arduino IDE library (In the Arduino IDE, click the `Tools > Manage Libraries...`).
+
+* `Ticker.h`
+* `OneWire.h`
+
+And of course, you need to prepare pumps, tubes, salt (and/or baking soda) and the [EC reader](https://www.dfrobot.com/product-1123.html).
+
+### Data processing
+
+For data processing part, please install MATLAB R2019b or any later version. The following toolboxes are **_highly recommended_**.
+
+* `Communication Toolbox`
+    + This toolbox is used in `code_algo/get_gold_code.m` to generate Gold code of certain parameters, and `code_algo/get_gold_code2.m` to generate MoMA code (which is Gold code modulated with Manchester code). 
+    + However, these two functions are only used in simulation for the early stage of the research. Once we go to experiment, we only need to generate the codes of required length and store in a TXT file before hand. Thus, during transmission the TX Arduino will pick the code for each TX from this file. Since MoMA assumes that the RX knows the pre-assigned code to each TX, the decoding will proceed depending on this assignment. 
+
+* `Parallel Computing Toolbox`
+    + This toolbox is used in `loop_emulates_txrx_all.m` and `loop_emulates_txrx_noncoherent.m` to parallel the decoding of multiple traces, thus accelerate the whole result generating procedure. Note that this toolbox is NOT used to speed up the decoding of ONE trace. Instead, each CPU core is used to process different traces concurrently. 
+    + You can get rid of this toolbox by making the following modifications to the code, **_which will definitely and extremely increase the time to generate the results_**.
+        - In `main_emulates_txrx_allloop.m`, comment the following code from line 5 to 7.
+        ```
+        if isempty(gcp("nocreate"))
+            parpool(feature("numcores"));
+        end
+        ```
+        This code creates the maximum number of workers, which is the same as the number of the CPU cores. But you can also specify a suitable number you want, e.g. 8 workers with the following code
+        ```
+        if isempty(gcp("nocreate"))
+            parpool(8);
+        end
+        ```
+        - In `loop_emulates_txrx_all.m` and `loop_emulates_txrx_noncoherent.m`, change the code in line 108 from
+        ```
+        parfor kk = 1:totalruns
+        ```
+        to
+        ```
+        for kk = 1:totalruns
+        ```
 
 ## How to run this artifact?
 
@@ -28,10 +65,14 @@ The data processing codes are MATLAB scripts and functions.
 
 We provide two MATLAB scripts that can directly generate the figures in the paper.
 
-[`main_emulates_txrx_allloop.m`](/main_emulates_txrx_allloop.m) processes the experiment data and save the results as `.mat` files in corresponding folders. The script contains multiple loops, each defining a variable that specifies either the experiment data or the algorithm. Since not all combinations are reported in the paper, we add multiple `if` conditions and mark in comment their corresponding figure indices. Please feel free to modify the `if` conditions if you would like to see other results.
+[`main_emulates_txrx_allloop.m`](/main_emulates_txrx_allloop.m) processes the experiment data and save the results as `.mat` files in corresponding folders. The script contains multiple loops, each defining a variable that specifies either the experiment data or the algorithm. Since not all combinations are reported in the paper, we add multiple `if` conditions and mark in comment their corresponding figure indices. Please feel free to modify the `if` conditions if you would like to see other results. The script then calls [`loop_emulates_txrx_all.m`](/loop_emulates_txrx_all.m) and [`loop_emulates_txrx_noncoherent.m`](/loop_emulates_txrx_noncoherent.m) to process the specified data in the specified way.
 
 [`code_figure/generate_all_fig.m`](/code_figure/generate_all_fig.m) reads the results in `.mat` files and generate the figures. It calls multiple scripts, each generating one figure, and corresponding indices in the paper are marked in comment. And you can run each of them separately as well.
 
-Simply running these two scripts in sequence will generate all the reported figures, but `main_emulates_txrx_allloop.m` may take a long time. 
+Simply running these two scripts in sequence will generate all the reported figures, but `main_emulates_txrx_allloop.m` may take a long time.
+
+## How to reuse this artifact?
+
+[`main_emulate_txrx.m`](/main_emulate_txrx.m) is a cleaner version of `main_emulates_txrx_allloop.m`, which is used to debug the algorithms with a single experiment trace.
 
-For more details about  the scripts, please refer to [Processing the data](/documentation/data_process.md).
+For more details about the scripts, please refer to [Processing the data](/documentation/data_process.md).

code_algo/DecodeSequence_ViterbiBackward.m

@@ -8,7 +8,7 @@
     dBit = params.dBit;
     lags = params.lags;
 catch
-    error('decoding missing variables');
+    error("decoding missing variables");
 end
 
 %%

code_algo/DecodeSequence_ViterbiForward4.m

@@ -10,7 +10,7 @@
     hPres = params.hPres;
     chan = params.chan;
 catch
-    error('decoding missing variables');
+    error("decoding missing variables");
 end
 
 %%
@@ -22,9 +22,9 @@
 try lags_new = params.lags_new; catch, lags_new = inf(1,nTx); end
 try cpIdx = params.cpIdx; catch, cpIdx = 0; end
 try endIdx = params.endIdx; catch, endIdx = length(yd{1}); end
-try mode = params.mode; catch, mode = 'de'; end
+try mode = params.mode; catch, mode = "dc"; end
 
-try code = params.code; catch, code = 'goldman'; end
+try code = params.code; catch, code = "goldman"; end
 for j = 1:nMo
     for i = 1:nTx
         xChip{j,i} = GenerateCodeChips(xChip{j,i},code);
@@ -174,14 +174,14 @@
                 end
             end
         end
-        clear('VStatesTemp2');
+        clear("VStatesTemp2");
 
         % delete inf
         ind = isinf(cell2mat(VStatesTemp(:,end)));
         VStatesTemp(ind,:) = [];
         VTraces{j,jy+1}(ind,:) = [];
         if size(VStatesTemp,1) == 0
-            error('viterbi reaches all states with zero probability');
+            error("viterbi reaches all states with zero probability");
         end
 
         % probability of current state
@@ -215,12 +215,12 @@
             end
 
             switch mode
-                case 'pd'
+                case "pd"
                     ViterbiLogProbCurrent(k) = -abs(yd{j}(jy) - yh);
-                case 'ce'
+                case "ce"
                     ViterbiLogProbCurrent(k) =  ComputeViterbiLogProb(yd{j}(jy), yh, ...
                           10*chan.nn{j}, 10*chan.np{j});
-                case 'de'
+                case "dc"
                     ViterbiLogProbCurrent(k) = ComputeViterbiLogProb(yd{j}(jy), yh, ...
                           chan.nn{j}, chan.np{j});
             end
@@ -240,7 +240,7 @@
         end
 
         % sort and truncate lower probability
-        [~, ind] = sort(cell2mat(VStatesTemp(:,end)), 'descend');
+        [~, ind] = sort(cell2mat(VStatesTemp(:,end)), "descend");
         if length(ind) > nTracks
             ind(nTracks+1:end) = [];
         end
@@ -253,19 +253,19 @@
     %% values for next window (only once)
     if jy == cpIdx
         checkpoint = struct( ...
-            'tracedBits', {tracedBits}, ...
-            'VTraceLast', {VTraces(:,jy+1)}, ...
-            'VStateLast', {VStates});
+            "tracedBits", {tracedBits}, ...
+            "VTraceLast", {VTraces(:,jy+1)}, ...
+            "VStateLast", {VStates});
     end
 end
 
 %%
-if exist('checkpoint', 'var')
+if exist("checkpoint", "var")
     rval.checkpoint = checkpoint;
 end
 rval.viterbi = struct( ...
-    'tracedBits', {tracedBits}, ...
-    'VStates', {VStates}, ...
-    'VTraces', {VTraces});
+    "tracedBits", {tracedBits}, ...
+    "VStates", {VStates}, ...
+    "VTraces", {VTraces});
 
 end