Two branches are for main development: master and bot

• master branch stores all developing scripts
  • is_poster.pdf on master is the poster done for an independent study on this system. It is posted for reference and to give people a quick overview of the whole system
• bot branch stores working scripts to be used on the robot

cross_corr_fft.py is the latest processing script, run with Python3 and taking path to a csv file as input argument.

• It uses Short-time Fourier Transform (STFT) to find the phase difference, usually generated by cross correlation
• Filtering with STFT, finding ping window with moving average, extracting phase difference with the smallest variance, and then converting phase difference to directional information.
• To adjust for different noise environment, try changing fft_w_size, large_window_portion, and invalidation requirement in get_pdiff function inside cross_corr_fft.py
• cross_corr_fft.py defaults the hydrophone array configuration to square (see hydrophone_data.md for detail explanation). If a new array configuration is used (i.e. tetrahedron), hp2, hp3 and hp4 need to be changed
• The script runs cross_corr_func in its main function, and this function can be modified for flexible usage
  • cross_corr_func(filename, if_double, version, if_plot, samp_f=fs, tar_f=freq, guess_x=gx, guess_y=gy, guess_z=gz)
  • It returns no value but prints out multiple intermediate outputs in the process.
  • It is best ran with a series of csv files recorded under the same condition (position, noise environment etc.). When run with multiple versions or two datasets inside a file, the function would print out a final horizontal angle, the mean of all output horizontal angles within the majority quadrant.
  • filename, when only 1 csv file needs to be processed (version=0), will be the path to this csv file; if a series of csv files needs to be processed (version>0), filename would be the path to this csv file format without the parentheses at the end (i.e. 625k_40k_0_0_0.csv instead of 625k_40k_0_0_0(1).csv)
  • if_double is True when two pings are recorded in the dataset (recording time ~4.5s to guarantee 2 pings) and False when only 1 ping is recorded
  • version is an integer indicating the number of csv files need to processed. All file should have names under the same format with version number at the end, starting from 1. version=0 when only 1 file needs to be processed
  • if_plot is True is user wants a 3-D plot to be displayed at the end
  • samp_f is sampling frequency, default to hard-coded value in cross_corr_fft.py
  • tar_f is target frequency, default to hard-coded value in cross_corr_fft.py
  • guess_x is the x-coordinate guess for optimization solver, default to hard-coded value in cross_corr_fft.py
  • guess_y is the y-coordinate guess for optimization solver, default to hard-coded value in cross_corr_fft.py
  • guess_z is the z-coordinate guess for optimization solver, default to hard-coded value in cross_corr_fft.py

• Sampling is done by saleae hardware device in the latest development, but we are looking to replace saleae with other devices with more flexible interfacing software.
• Logic is the GUI that interfaces with saleae and runs on x86 linux.
• pool_test.py is the script that automates the sampling procedure in Logic with saleae python package. It runs with Python3
  • pool_test.py in master and bot are only different in their paths to Logic and some commented developing code
  • When running this script, make sure Logic software is located in the same location specified in the script
• Before running pool_test.py, make sure saleae device is plugged in and Logic software is running
• pool_test.py, once starts running, will request input from user for pinger location and csv file version, which will be recorded as the names of output csv files
  • Once a recording is done and the output process is finished, another input request will be sent for the next recording
  • Recording is default to last for 4.5s to guarantee 2 pings are captured, and a wait time of at least 10s (12s in pool_test.py) to make sure the outputting process is finished. This wait time needs to be changed according to the length of recording time, some references can be found under Saleae Python Automation Script (Outdated) section.
• pool_test.py outputs 1 csv file for each recording
  • Output path is hardcoded in pool_test.py
  • Output file name is default to 625k_40k_ format, so please adjust the script when different sampling frequency and target frequency are used
• For reference in further development, a demo script from saleae Python package, saleae_cli.py, is uploaded in master branch.

Simulation is developed in MATLAB to model the Transdec competition pool and generate some ideal datasets with simple noise to test the processing script.

• model_new.m should be run in MATLAB, and it will output a csv file based on the hardcoded path in the script
• A working processing script should be able to output correct direction after processing simulated dataset from this model, given the correct guess (or guess with small modification). A script fails to do so should not be tested in real environment as more complicated noises would be added in the sampling process and from the real underwater environment.
• model_new.m defaults the hydrophone array configuration to square (see hydrophone_data.md for detail explanation). If a new array configuration needs to be simulated (i.e. tetrahedron), hydrophone locations need to be changed
• model_new.m simulates a uniform white gaussian noise as the environment noise. For more accurate noise simulation, try plotting the power density spectrum of Transdec dataset and model new noises according to the plot

• sampling.c for 3 channels
  • sampling.c sampling_time(s) sampling_freq(Hz)
  • sampling speed similar to sampling_4.c
  • python2
• sampling_4.c for 4 channels
  • sampling_4.c sampling_time(s) sampling_freq(Hz)
  • needs 3.5 second to sample 3 second samples at 125 kS/s
  • needs 1.2 second to sample 1 second samples at 125 kS/s
  • python2
• modified usb-1608G.c
  • need to replace the original one in mcc-libusb
• both need to be inside /Linux_Drivers/USB/mcc-libusb/ directory and compiled with Makefile inside
  • make
  • sudo make install
• max sampling frequency = 500/#channel kS/s
• differential input mode available
• sampling time can only be integer due to libusb library constraint
• if encounter Resource temporarily unavailable error, disconnect usb and reconnect

• saleae_sampling.py for 4 channels
  • have saleae software running before running the script
  • python3
  • if getting saleae software down, open saleae software before next script run, open another terminal to run saleae software
  • need 14 second to sample 3 second samples at 1250 kS/s
  • need 6 second to sample 1 second samples at 1250 kS/s
  • need 10 second to sample 3 second samples at 625 kS/s
  • need 4 second to sample 1 second samples at 625 kS/s
  • need 6 second to sample 3 second samples at 125 kS/s
  • need 3 second to sample 1 second samples at 125 kS/s
  • export path need to be absolute path
  • the export csv data would be slightly longer then the set sampling time, but the sampling rate is accurate
  • sampling_rate: 2 = 1250 kS/s, 3 = 625 kS/s, 4 = 125 kS/s