Cross/GNURadioReferenceImplementation

A reference implementation is available that component developers understand how the different components within the CROSS system communication. The current reference implementation is EXTREMELY simple, and is only meant to provide a demonstrate of the protocol exchange, it is not a fully functional communications system. In fact, the reference implementation demo does not use any radio hardware.

Running the GNUradio Reference Implementation

The reference implementation consists of three primary CROSS components and GNUradio 3.2.2:

Following the Build Guide will result in an executable that is built for each of the reference implementation components. These executables are located in the individual component source file directories.

Cognitive Radio Shell Component

Once the components are built, the next step is to start the shell component using the compiled executable named shell_demo. The command line parameter format for the shell is as follows: 

 shell_demo <Radio XML Configuration File> <Cognitive Engine Port> <Policy Engine Port> <Application Port>

The radio XML configuration file for the GNU radio demon is "dsa_gnuradio.xml". The Cognitive Engine port number can be any number 1 through 65535, but is typically set higher than 1024 to avoid interfering with common process and services. The Policy Engine port should be assigned in the same way as the Cognitive Engine port. However, in the simple demonstration application, the policy engine component is currently not used, so this number really has no significance.

The application port is the server port that the applications connect to in order to issue commands to the system. Currently, applications simply link to a library and the library takes care of all the socket communication functionality. This requires the socket port to be hardwired into the library. So for the demonstration application, the Application port MUST BE set to 40000. 

 ./shell_demo configs/dsa_gnuradio.xml 30000 35000 40000

Once the shell is executed with the example configuration file you should see the following output. 

Creating Cognitive Radio Shell.
Cognitive Radio Shell:: Loading radio configuration.
Cognitive Radio Shell:: Parsed 1 utilities.
Cognitive Radio Shell:: Parsed 2 observables.
Cognitive Radio Shell:: Parsed 1 parameters.

At this point the shell component has parsed the Radio XML Configuration and is waiting for other components to connect.

Cognitive Engine Component

With the shell component activated and awaiting connections, the Case-Based Reasoning Cognitive Engine demo component can now be executed. The executable for the Cognitive Engine is located in the cognitive_engines/DSA_CE source directory and follows a similar command line parameter format as the shell. 

 DSA_Demo <IP Address of Shell> <Shell Port>

The IP Address of Shell parameter is simply the IP address of the host that the shell component process is being ran. If you're running this demo on a single machine, then localhost will suffice. The Shell Port parameter is the port number that is used to connect to the shell. It should be the same port number as the Cognitive Engine Port specified in the shell component command line. In the reference implementation example we execute the following in the cognitive_engines directory. 

 ./DSA_Demo localhost 30000

Once the DSA CBR Cognitive Engine is activated, it will connect to the shell component and the following output should be displayed by the Cognitive Engine component. 

Creating Cognitive Engine.
Cognitive Engine:: Registration message sent to shell.
Cognitive Engine connected to shell at localhost.
Cognitive Engine:: Receiving Radio Configuration.
Cognitive Engine:: Receiving Experience Report.
Cognitive Engine:: Waiting for 0 number of entries.
Waiting for signal...

In addition, the shell component terminal should indicate that a Cognitive Engine has connected by printing out the following. 

Cognitive Radio Shell:: Received registration message from Cognitive Engine.
Cognitive Radio Shell:: Sending radio configuration to Cognitive Engine.
Cognitive Radio Shell:: Sending radio experience to Cognitive Engine.

At this point the demo Cognitive Engine has registered itself with the shell, and the shell has forwarded the information from the Radio XML Configuration file over to the Cognitive Engine.

In our reference implementation, the information from the Radio Configuration XML is used by the CBR Cognitive Engine to create an sqlite database to hold the history of the operating parameters and the environments that are seen by the system. Assuming this is a new system that has just been brought up, the database is initially empty. However, if the Cognitive Engine were to connect to a shell component that has been operating with other existing Cognitive Engines, then a local cache of previous experience and actions would also be sent to the newly connected Cognitive Engine in order to create a small initial population of experience to improve the performance of newly connected Cognitive Engines.

At the moment the passing of the experience is disabled in the Shell component.

Running the GNUradio Demo Application

Both the Shell component and the DSA CBR Cognitive Engine should be connected. These two components constitute a simple, yet functional CROSS system. The last thing to do is to have an application that is aware of the parameters in the Radio XML Configuration file, use the CROSS library to communicate with the system.

A GNUradio reference implementation application for demonstrating how to access the functionality of the CROSS library in the {cross_src_dir}/src/cross-examples/python/gnuradio-examples/ directory.

In this directory is benchmark_dsa.py. benchmark_dsa.py is a modification of the gnuradio benchmark_rx/tx example script and integrates spectrum sensing with dynamic spectrum access. If the CROSS source was compiled correctly, there will be a CROSS python package installed. benchmark_dsa.py imports this package so it can communicate with an online CROSS system. benchmark_dsa.py can also be ran WITHOUT cross. In this case the channel selection algorithm is random, rather than having the CROSS Cognitive Engine decide.

To run the benchmark_dsa.py demo with the CROSS DSA Cognitive Engine: 

 sudo python ./benchmark_dsa.py --cross

To run the benchmark_dsa.py demo with a random channel selection DSA algorithm: 

 sudo python ./benchmark_dsa.py

To set the DSA primary user energy detection threshold use the --threshold command line argument with a given threshold: 

 sudo python ./benchmark_dsa.py --threshold 1.5e8

At this point a single node will begin scanning over the specified channels looking for other nodes. In order to complete the demo, perform the same setup procedure on another node and the two nodes will rendezvous and begin exchanging data.

The console screen shows the rendezvous channel. To test the DSA capabilities simply simulate a primary user by transmitting energy on that specific channel. In our case, by default the nodes use the FRS band, channels 1,7,8, and 14. An FRS 2-way radio can be used to cause the DSA process to start. Once the nodes sense energy above the specified energy threshold, they will begin to scan over multiple channels in order to rendezvous once again.