Fixed deadlock issue for TX_COMPLETE CE event.

README.md

@@ -59,6 +59,7 @@ CRTS also relies on each node having network synchronized clocks. On CORNET this
 with Network Time Protocol (NTP). Precision Time Protocol (PTP) would work as well.
 
 Note to CORNET users: These dependencies are already installed for you on all CORNET nodes.
+You will still need to download the CRTS source repository and compile it however.
 
 ###Downloading and Configuring CRTS 
 Official releases of CRTS can be downloaded from the
@@ -70,10 +71,14 @@ Note that because using CRTS involves actively writing and compiling
 cognitive engine code, it is not installed like traditional software.
 
 #### Official Releases
-1. Download the Version 1.0 tar.gz from the [Official Releases Page](https://github.com/ericps1/crts/releases):
 
-        $ wget -O crts-v1.0.tar.gz https://github.com/ericps1/crts/archive/v1.0.tar.gz
+In the following commands 'v1.0' should be replaced with the release version you
+wish to download.
+
+1. Download the latest released version of CRTS from the [Official Releases Page](https://github.com/ericps1/crts/releases):
 
+        $ wget -O crts-v1.0.tar.gz https://github.com/ericps1/crts/archive/v1.0.tar.gz
+
 2. Unzip the archive and move into the main source tree:
 
         $ tar xzf crts-v1.0.tar.gz
@@ -84,14 +89,14 @@ cognitive engine code, it is not installed like traditional software.
         $ make
 
 4. Then configure the system to allow certain networking commands without a password 
-    (CORNET users should skip this step):
+    (CORNET users can skip this step):
 
         $ sudo make install
 
 The last step should only ever need to be run once. 
 It configures the system to allow all users to run
-certain very specific networking commands which are necessary for CRTS.
-They are required because CRTS creates and 
+certain specific networking commands which are necessary for CRTS.
+They are required because CRTS creates, manipulates, and 
 tears down a virtual network interface upon each run. 
 The commands may be found in the .crts\_sudoers file.
 
@@ -142,6 +147,9 @@ or
     generating particular noise or interference patterns against which the 
     CR nodes must operate.
 
+In the next sections we provide an overview of the high level components
+used by CRTS to enable flexible, scalable testing of CR's.
+
 ### Scenarios
 
 The `master_scenario_file.cfg` specifies which scenario(s) should be run for a
@@ -175,6 +183,27 @@ configuration file and the default setting will be used.
 Examples of scenario files are provided in the `scenarios/` directory of the
 source tree.
 
+### Scenario Controllers
+
+Scenario controllers provide a centralized and customizable way to receive 
+feedback and exert control over a scenario's operation in real time. A
+simple API can be used to enable or disable specific types of feedback from
+each node involved in the scenario, receive said feedback, and even directly
+control the scenario test parameters e.g. the network throughput as well as
+the operating parameters of the radio e.g. its transmit power.
+
+The behavior of the scenario controller is defined by two functions. The
+initialize node feedback function is called at the beginning of the scenario
+so that feedback can be setup once since this will often be a static setting.
+The execute function implements the behavior of the scenario controller. It 
+is triggered whenever feedback is received or after a certain period of time 
+has passed.
+
+To make a new scenario controller a user needs to define a new scenario controller
+subclass. The SC\_Template.cpp and SC\_Template.hpp can be used as a guide in terms
+of the structure and API. Once the SC has been defined it can be integrated into CRTS
+by running $ ./config\_SCs and $ make in the top directory.
+
 ### The Extensible Cognitive Radio
 
 As mentioned above the ECR uses an OFDM based waveform defined by liquid-dsp. The
@@ -208,7 +237,7 @@ To make a new cognitive engine a user needs to define a new cognitive engine
 subclass. The CE\_Template.cpp and CE\_Template.hpp can be used as a guide in terms
 of the structure, and some of the other examples show how the CE can interact
 with the ECR. Once the CE has been defined it can be integrated into CRTS
-by running $ ./config\_CEs in the top directory.
+by running $ ./config\_CEs and $ make in the top directory.
 
 Other source files in the cognitive\_engine directory will be automatically
 linked into the build process. This way you can define other classes that your

cognitive_engines/README.md

@@ -47,3 +47,10 @@ This CE makes no adaptations but serves as a template for creating new CE's.
 
 This CE illustrates how a CE can change the subcarrier allocation of its transmitter.
 The method for setting the receiver subcarrier allocation is identical.
+
+## 8. CE\_Network\_Loading
+
+When a pair of these CEs are communicating they will negotiate to adapt their occupied 
+bandwidths based on the network loads they detect. Note that this example simply
+shows bandwidth adaptation based on network load, the bands actually being used by the
+radios do not overlap so they aren't really sharing spectrum.

include/ECR.hpp

@@ -967,6 +967,7 @@ class ExtensibleCognitiveRadio {
   pthread_mutex_t tx_state_mutex;
   pthread_mutex_t tx_params_mutex;
   pthread_cond_t tx_cond;
+  bool tx_complete;
   bool tx_thread_running;
   int tx_worker_state;
   int tx_state;

scenarios/README.md

@@ -60,3 +60,10 @@ allocation can be changed on the fly by the CE. If you run uhd\_fft on a
 nearby node before running this scenario you can observe the initial
 subcarrier allocation defined in the scenario configuration file followed
 by switching between a custom allocation and the default liquid-dsp allocation.
+
+## 9. Network\_Loading
+
+This example scenario sets up two CR nodes which have asymmetric network loads.
+The network loads are then periodically swapped by the scenario controller. The
+cognitive engines used in this scenario will adapt their bandwidths based on the
+network loads that they detect.

src/ECR.cpp

@@ -166,6 +166,7 @@ ExtensibleCognitiveRadio::ExtensibleCognitiveRadio() {
   // create and start tx thread
   frame_num = 0;
   tx_state = TX_STOPPED;    // transmitter is not running initially
+  tx_complete = false;
   tx_thread_running = true; // transmitter thread IS running initially
   tx_worker_state = WORKER_HALTED;  // transmitter worker is not yet ready for signal
   pthread_mutex_init(&tx_mutex, NULL); // transmitter mutex
@@ -1697,9 +1698,13 @@ void *ECR_tx_worker(void *_arg) {
     } // while tx_running
 
     // signal CE that transmission has finished
-    pthread_mutex_lock(&ECR->CE_mutex);
-    ECR->CE_metrics.CE_event = ExtensibleCognitiveRadio::TX_COMPLETE;
-    pthread_cond_signal(&ECR->CE_execute_sig);
+    int lock_failed = pthread_mutex_trylock(&ECR->CE_mutex);
+    if(!lock_failed){
+      ECR->CE_metrics.CE_event = ExtensibleCognitiveRadio::TX_COMPLETE;
+      pthread_cond_signal(&ECR->CE_execute_sig);
+    } else {
+      ECR->tx_complete = true;
+    }
     pthread_mutex_unlock(&ECR->CE_mutex);
     dprintf("tx_worker finished running\n");
   } // while tx_thread_running
@@ -1740,9 +1745,13 @@ void *ECR_ce_worker(void *_arg) {
 
       // Wait for signal from receiver
       pthread_mutex_lock(&ECR->CE_mutex);
-      if (ETIMEDOUT == pthread_cond_timedwait(&ECR->CE_execute_sig,
-                                              &ECR->CE_mutex, &timeout))
+      if (ECR->tx_complete){
+        ECR->tx_complete = false;
+        ECR->CE_metrics.CE_event = ExtensibleCognitiveRadio::TX_COMPLETE;
+      } else if (ETIMEDOUT == pthread_cond_timedwait(&ECR->CE_execute_sig,
+                                              &ECR->CE_mutex, &timeout)) {
         ECR->CE_metrics.CE_event = ExtensibleCognitiveRadio::TIMEOUT;
+      }
 
       // execute CE
       ECR->CE->execute(ECR);