Changes between Initial Version and Version 1 of Cross/ReferenceImplementation

Timestamp:

07/15/09 16:48:39 (15 years ago)

Author:

trnewman

Comment:

--

Cross/ReferenceImplementation

@@ +1 @@
+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 Reference Implementation ==
+The reference implementation consists of three primary CROSS components:
+
+ * Shell Component
+ * Cognitive Engine
+ * Demo application
+
+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.
+
+=== 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 demonstration Radio XML Configuration File is located in the examples directory, and is named demonstration.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 <cross_src_dir>/examples/demo.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 2 utilities.
+Cognitive Radio Shell:: Parsed 2 observables.
+Cognitive Radio Shell:: Parsed 2 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 source directory and follows a similar command line parameter format as the shell.
+
+{{{
+ cbr_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.
+
+{{{
+ ./cbr_demo localhost 30000
+}}}
+
+Once the 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 Demo Application ===
+At this point both the Shell component and the demonstration 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 reference implementation application for demonstrating how to access the functionality of the CROSS library in the {cross_src_dir}/src/libvtcross/ directory. 
+
+The demonstration application calls the ''GetOptimalParameters'' function to activate the system.  At this point the shell forwards the request onto the Cognitive Engine, which in turn records the environment and current operation parameters and suggests a new set of transmission parameters using a very simple set of adjustment algorithms.  This new set is sent back to the application through the Shell component.  At this point the ''GetOptimalParameters'' function returns the suggested set of parameters and the output of the application should be similar to the following.
+
+{{{
+Application:: Received the following parameters.
+bandwidth:: 305.000000
+tx_power:: 20.000000
+Application:: Received the following parameters.
+bandwidth:: 310.000000
+tx_power:: 30.000000
+Application:: Received the following parameters.
+bandwidth:: 315.000000
+tx_power:: 40.000000
+Application:: Received the following parameters.
+bandwidth:: 320.000000
+tx_power:: 50.000000
+Application:: Received the following parameters.
+bandwidth:: 325.000000
+tx_power:: 60.000000
+Application:: Received the following parameters.
+bandwidth:: 330.000000
+tx_power:: 70.000000
+Application:: Received the following parameters.
+bandwidth:: 335.000000
+tx_power:: 80.000000
+Application:: Received the following parameters.
+bandwidth:: 340.000000
+tx_power:: 90.000000
+Application:: Received the following parameters.
+bandwidth:: 345.000000
+tx_power:: 100.000000
+Application:: Received the following parameters.
+bandwidth:: 350.000000
+tx_power:: 110.000000
+}}}
+
+At this point our reference application uses another function supplied by the CROSS library in order to update the Cognitive Engine on the result of the new parameters.  This process is critical to any cognitive radio system because without some sort of feedback, there is no cognition and the system can not learn from the decisions that were previously made.  The application calls the ''UpdateParameterPerformance'' function and provides as parameters the previous set of transmission parameters that were used, and the resulting observable values.  These are sent through the Shell component to the Cognitive Engine where the sqlite database is updated and the set of transmission parameters that were previously sent to the application is now associated with the resulting environment.  This will help the Cognitive Engine make future decisions.