Embedded Files
Please follow the following sequence to obtain access to the development environment. All instructions refer to the user manual available here: https://sites.google.com/ncsu.edu/aerpaw-user-manual/. You are also recommended to go through the Hello AERPAW! experiment in section 2.
1) For all participants, please make an account following the instructions in section 4.2 of the user manual, then upload your public keys to the system (see section 4.3).
2) For the PIs, please request PI privileges (see section 4.3).
3) For the PIs, once you have PI privileges, create a project for your team, please include the team name in the name of the project, as well as the word AADM. See section 4.4.
4) For the PIs, add each of the experimenters in your team to the project (see Section 4.4).
5) Either one of the experimenters or the PI creates one experiment and adds all the other experimenters to the experiment. The experiment should consist of 5 nodes. Choose fixed nodes LW1, LW2, LW3, and LW4 as Node 1 through Node 4, respectively. Then add a portable node (e.g., LPN1) acting as UAV, which will be designated as Node 5 (see Section 4.5).
6) Once the experiment is created, initiate the development and access the development environment (see Section 4.6).
7) If you are not familiar with the AERPAW setup, please read the background information in sections 5.1, 5.2, and 5.4.
8) You will likely want to have a QGroundControl installation, so please read the instructions on installing QGroundControl (and connect it) in 5.1.1.
9) Get connected to the five E-VMs (for the LPN on the drone and the four fixed nodes), and to the OEO-Console. Start QGroundControl and verify that you see the drone.
10) Before creating an experiment for this challenge, ensure the following requirements:
i) The experiment requires one UAV and four LWs (LW1, LW2, LW3, and LW4).
ii) Do not consider LW5. The code is not configured for it.
11) To set up the AADM sample experiment:
a) In the OEO Console, go to the directory (/root/workarea/AERPAW-Dev/OEO/AADMChallenge) with the command:
cd /root/workarea/AERPAW-Dev/OEO/AADMChallenge
Ensure that two TCP ports are available, one for QgroundControl and One for controller. Check with the command:
screen -ls
If you see two screen (mavproxy and mavlink-additional-port), it means two TCP ports are open. If you see only one screen such as “69615.mavproxy”, it means only one TCP port (for QgroundControl) is active. Execute the following commands to have two TCP ports open:
./stopMavproxy.sh
./startMavproxy.sh
Now, check with the command:
screen -ls
You should see the following:
10400.mavlink-additional-port (12/23/24 21:42:49) (Detached)
10397.mavproxy (12/23/24 21:42:48) (Detached)
Then, start OEOConsole as follows:
./startOEOConsole.sh
b) UAV broadcasts a probing signal using channel sounder transmitter script (GE2 transmitter part in Section 4.1.3), and also sends BS-related information through the XM interface to download data from a BS. Both preplanned (Section 4.2.1) and autonomous trajectory (Section 4.2.4) can be implemented through the script uav_data_mule.py.
(i) Log in to the UAV E-VM, and type nano /root/startexperiment.sh and uncomment the following lines:
./Radio/startRadio.sh, and ./Vehicle/startVehicle.sh
Also, include ./Other/startRequester.sh and uncomment it.
Save the script.
(ii) Copy the channel sounder transmitter script as startRadio.sh with the command:
cp /root/Profiles/ProfileScripts/Radio/Samples/startGNURadio-ChannelSounder-TX.sh /root/Profiles/ProfileScripts/Radio/startRadio.sh
(iii) A requester requests the Controller to send data volume (amount of data to be downloaded from each BS), signal strength, total download data, and the overall report with a time stamp. A requester program is responsible for it. Copy the requester script as startRequester.sh with the command:
cp /root/Profiles/ProfileScripts/Other/Samples/startAADMPortableNode.sh /root/Profiles/ProfileScripts/Other/startRequester.sh
(iv) Copy the vehicle script as startVehicle.sh with the command:
cp /root/Profiles/ProfileScripts/Vehicle/Samples/startUAVdataMule.sh /root/Profiles/ProfileScripts/Vehicle/startVehicle.sh
c) All the BSs running on the channel sounder receiver script (GE2 receiver part in Section 4.1.3) will receive the probing signal from the UAV and send SNR through the XM interface.
(i) For all four fixed nodes (also called BSs or LWs), namely LW1, LW2, LW3, LW4, log in to the E-VM, type nano /root/startexperiment.sh and uncomment ./Radio/startRadio.sh
In LW1 include
./Other/startResponder.sh
./Other/startController.sh
In LW2, LW3 and LW4 include
./Other/startResponder.sh
Save the script.
(ii) Set up LW1 as a controller. A controller manages, monitors, and coordinates other entities in the system (e.g., base stations, UAVs and OEO). Copy the controller script as startController.sh with the command:
cp /root/Profiles/ProfileScripts/Other/Samples/startAADMCoordinator.sh /root/Profiles/ProfileScripts/Other/startController.sh
(iii) There are four fixed nodes also called base stations (BSs) or lake wheelers (LWs): LW1, LW2, LW3, and LW4. Copy the channel sounder receiver script as startRadio.sh with the command:
cp /root/Profiles/ProfileScripts/Radio/Samples/startGNURadio-ChannelSounder-RX.sh /root/Profiles/ProfileScripts/Radio/startRadio.sh
(iv) All the base stations (BSs) or lake wheelers (LWs) will respond to the controller to send the SNR measured in step (iii). A responder program on the BS side is responsible for it. Copy the responder script as startResponder.sh with the command:
cp /root/Profiles/ProfileScripts/Other/Samples/startAADMFixedNode.sh /root/Profiles/ProfileScripts/Other/startResponder.sh
d) Please start the experiment on the E-VM of UAV and all fixed nodes separately with the command:
/root/startexperiment.sh
or, you can start all the experiments in the OEO-Console as follows:
all start_experiment
e) You can continuously check the reports in the UAV and Controller (LW1) E-VM directory:
[UAV] /root/Results (report_log.txt, vehicle_log.txt, vehicleOut.txt)
[Controller/LW1] /root/Results (controller_log.txt)
f) Once the experiment is finished, stop it by the command in the OEO-Console:
all stop_experiment
g) Finally, reset one of the E-VMs with the command:
/root/reset.sh
12) Log details:
a) report_log.txt:
By default, BS1 is selected by the experimenter if no base station is chosen. Here, the UAV sends a request to the Controller to retrieve data from BS1. However, the Controller will not share the data until the desired altitude is reached. The UAV requests signal strengths and other information, such as data volume and total downloaded data, from each BS. Once the desired altitude is reached, the Controller shares the data volume and SNR with the UAV.
[2024-12-15 12:45:32.617405] [UAV-->Controller] Send data from BS1
[2024-12-15 12:45:32.617493] [Controller-->UAV] Please wait for the UAV to reach the desired altitude.
[2024-12-15 12:45:32.617647] [UAV-->Controller] Send SNR and Downloaded Data.
[2024-12-15 12:45:32.618171] [Controller-->UAV] Vol:1:1000.0, 2:1000.0, 3:1000.0, 4:1000.0
[2024-12-15 12:45:32.618434] [Controller-->UAV] SNR:1:43.68,2:43.68,3:43.67,4:43.69
In the sample experiment, BS with higher SNR is selected by the experimenter code regardless of data volume and downloaded data (Experimenters need to set their logic.) Here, UAV finds base station 4 has higher signal strength and UAV sends a request to the controller to download data from BS4. Controller then sends the data to the UAV.
[2024-12-15 12:45:33.619820] [UAV-->Controller] Send data from BS4
[2024-12-15 12:45:33.619993] [Controller-->UAV] Report: ts>2024-12-15 12:45:33.619874, bs>4, snr>43.69 db, rate>7.77 mbps, RECV>7.77 mbits
[2024-12-15 12:45:33.620131] [UAV-->Controller] Send SNR and Downloaded Data.
[2024-12-15 12:45:33.620733] [Controller-->UAV] Download:1:0.00, 2:0.00, 3:0.00, 4:7.77
[2024-12-15 12:45:33.621032] [Controller-->UAV] SNR:1:43.66,2:43.67,3:43.66,4:43.68
b) vehicle_log.txt:
i) You can check the signal strength, the base station (BS) used for data collection, and the total data received from each BS.
ii) You can also check this log file for compilation when you modify the code in uav_data_mule.py.
13) The script uav_data_mule.py is located in the /root/Profiles/AADMChallenge/PortableNode directory of the UAV E-VM, where you will write code for the AADM challenge. Several auto-generated text files will be present in the same directory when you start the experiment. Please do not open or modify these files. They will be updated and used in the experiment for various purposes, and there is nothing you need to check or change in them.
14) To create a preplanned trajectory, make a plan file named aadm.plan using QGroundControl and upload it to the directory /root/Profiles/AADMChallenge/PortableNode. Inside uav_data_mule.py, you will find instructions on using the plan file or creating waypoints directly and how to proceed. Please ensure that your waypoints comply with the AERPAW Phase 1 geofence regulations (Section 3.1.2).
15) You can check QGroundControl how the drone flies.
Challenge Overview
The goal is to download mission-specific data from four AERPAW base stations (BSs) as quickly as possible using a UAV.
Key Details about the script uav_data_mule.py where you will write your code:
How to compute the initial waypoints and dynamic waypoints
There are two options for initially computing the waypoints in the function compute_initial_waypoints(). First, if you make a plan file from the QGroundControl, you have to upload the file in /root/Profiles/AADMChallenge/PortableNode. Then, you will need to extract the waypoint using the function extractWaypointsFromPlanFile.
Second, if you do not consider the plan file, you can generate waypoints similar to default waypoints in the code. However, initially, default waypoints have been set up in the code.
If you want to develop an autonomous trajectory for optimizing the problem, you have to do coding in the function update_uav_waypoints where you first need to calculate a waypoint and then append/ update it in the self.waypoints with the desired format that has been shown in the code. UAV then automatically will go there. You have to update two parameters self.nextWaypointIndex and self.lastWaypointIndex depending on how you code. self.nextWaypointIndex indicates the index that contains the target waypoint and UAV will go there from its current position. self.lastWaypointIndex is the index having a waypoint you think the UAV launch position. There are three conditions by which the UAV returns to launch position and lands: i) flight time is more than 10 minutes, ii) UAV completes download data from all the BSs, and iii) UAV reaches the last waypoint.
How to update the target base station (update_target_bs)
The UAV receives updated link quality metrics from each BS every second using the function checkSNR(). How much data the UAV has downloaded from each base station can be checked by the function checkDownload(). Depending on your choice, you can update the base station by setting self.update_token. A simple example with maximum signal strength among four BSs has been set as the target base station in the code. UAV will then download data from that target base station.
You might also consider the orientation of the UAV and wait time for hovering near a BS because when you are close to a BS, you might get better signal strength, which will allow you to download data at a higher rate. To change the orientation, you need to update self.angles and for hovering at a waypoint, update self.waitTime. An example of how to change these parameters has been shown in the function update_uav_wayponts().
State Diagram
You might not need to change the codes in the different states. All the changes you did in update_target_bs, update_uav_wayponts, and compute_initial_waypoints, will be automatically updated. There are five states in the state diagram. UAV starts at state "start", after reaching at an altitude of 25 m, UAV goes to another state "go_forward". If your waypoint is invalid or the UAV reaches the last waypoint, the UAV will go to the "return_to_launch_and_land" state. Otherwise, the UAV goes to the target waypoint and when it reaches there it will go to another state "wait_for_dowload" where you can also change the UAV orientation and the waiting time depending on your choice. You might change the code in the "wait_for_dowload" state for autonomous trajectory if you need to. After this state, the UAV goes to the "go_foward" state again and continues. There is another state "run_update_target_bs" which periodically calls the function "update_target_bs".
Frequently Asked Questions:
1) Are the base stations going to be busy with other things while the UAV is making its downloads?
A: Some overhead will always exist, but the basestation (which are actually Fixed AERPAW Nodes) will be primarily waiting to provide data to the mules during the challenge run.
2) Will there be multiple mules on the field at the same time?
A: The plan is to run only one mule at a time.
3) Is there any way to see what data is contained on the base station and how it is formatted in the file that we will download? I mean, the sample data.
A: There is no actual data downloaded. The data is calculated based on SNR and look up table.
4) Apart from the link quality, will other sensor i.e., IMU and timer data, be available from the UAV?
A: Vehicle location, vehicle attitude, battery left, voltage, GPS readings, etc. The complete list is at the bottom of this page: https://sites.google.com/ncsu.edu/aerpaw-user-manual/6-sample-experiments-repository/6-2-vehicle-control-software/vcs2-gps-logger?authuser=0
5) Will we be informed what kind of data we are downloading? Based on the data type, there are different algorithms that can increase the download speed (i.e. sound and video data can have different download algorithm).
A: There is no actual data downloaded. The data is calculated based on SNR and look-up table. For this challenge, the data download only depends on SNR. It is best to think of it as undifferentiated data. The scoring will be based on the total amount of bulk data that would have been downloaded at that SNR.
6) Is the total data amount known, or does the UAV have to figure it out on the fly?
A: Yes, the amount of data from each base station will be revealed when the UAV reaches 25 m altitude.
7) Is the data amount at each station going to be randomized for each UAV? How will you generate that data amount? Will those amounts be the same for all experimenters?
A: The challenge is to develop an algorithm that should not to make any assumptions regarding the same. The specific data will not be shared with the experimenters ahead of time, but you can test your algorithm for uniform, random, and exponential scenarios. We will test all the experiments with the same exact set of data challenges, and they will not vary from one team to another.
8) Does the UAV have a guaranteed link to each BS as soon as it reaches 25m? Or, will it have to wander to get the link with each BS?
A: The UAV will monitor the SNR from all four BSs at each second. There can be locations where the SNR can be very low for a BS, and hence, the data rate at those locations can be zero. This paper shows the coverage areas of different BSs at different altitudes using ray tracing simulations: https://arxiv.org/pdf/2502.10324.
Some other real-world datasets can be found here: https://aerpaw.org/experiments/datasets/
See e.g.:
Additional field data will be released to the competition teams in the coming weeks.
9) How can the PI generate a project?
A: Links for creating and managing the project are as follows:
10 The seminar earlier this morning mentioned a MATLAB simulation - where can I find it?
A: It can be accessed from the following github repository:
https://github.com/mhossenece/UAVFlexSimFramework.git
A paper that describes how to use the Matlab simulator can be found here: https://drive.google.com/file/d/1Ua2ArWH8ONBQuV5JmTjItgQ-4-THn9zC/view. Note that performance evaluation will be done in the development and testbed environments -- Matlab simulator is provided in case it can be used for early development and it is provided as is.
AADM Challenge Slides_v5.pdfPage updated
Report abuse