Batsy4-Pro - Firmware, Code, and Analyses

Analysis software, figure-generation workflows, processed Batsy4-Pro validation data, and firmware for Batsy4-Pro, an open-source four-channel ultrasonic recorder for field bioacoustics. This repository accompanies the manuscript: Batsy4-Pro: An Open-Source Multichannel Ultrasound Recorder for Field Bioacoustics Ravi Umadi Preprint: https://doi.org/10.1101/2025.08.11.669530 The repository supports reproducibility of the reported signal quality, spectral clustering, three-dimensional localisation, and grid simulation analyses. It also provides the recorder firmware source and the corresponding compiled Teensy release artefacts. Repository contents analysis/ Analysis and figure-generation scriptsdata/processed/ Prepared audio clips used in the analysesdata/derived/ Analysis tables and grid-simulation resultsdiagrams/ Standalone TikZ sources for Figures 2 and 3docs/FIGURE_PROVENANCE.md Figure-to-code and data provenance tablefirmware/Batsy4-Pro/ Teensy firmware, build information, and BOMoutputs/reference_figures/ Figures used in the manuscriptoutputs/generated/ Output directory for reproduced figuressrc/ MATLAB functions and localisation classestests/ MATLAB regression tests Reproducing the analyses Open MATLAB with the repository root as the current folder, then initialise the project paths: setup Run the validation suite: run_checks This verifies the processed-data inventory, the published cluster membership, the firmware artifacts, the propagation-buffer regression tests, and the principal numerical results reported in the manuscript. Generate the MATLAB-produced manuscript figures: run_all_figures New figures and analysis tables are written to outputs/generated/. Source inputs and reference figures are never overwritten. Figure 5B is excluded from run_all_figures because its professional-audio- interface recordings belong to a separate study and are not distributed here. The analysis script remains available and can be run against that external dataset by setting the BATSY_SOUNDCARD_DATA environment variable. Grid simulation Figure 8 is generated from the corrected trial-level results in data/derived/grid/. This allows the figure and associated statistics to be reproduced without repeating the full Monte Carlo simulation. To regenerate all 272,322 trials from first principles, run: run('analysis/figure8_run_grid_simulation.m') The full simulation is computationally intensive. Its signal renderer allocates a common output buffer that retains the complete waveform at every microphone, including the largest relative propagation delay. The associated regression tests are provided in tests/test_no_delay_clipping.m. WAH-i geometry-to-hub conversion Supplementary Figure S2 converts a WAH-i Cartesian microphone geometry into physical hub settings. The workflow reports the target arm length, azimuth, and elevation for each microphone, together with the signed changes from a tetrahedral starting geometry: run('analysis/figureS2_wahi_hub_conversion.m') For another WAH-i output, call wahiGeometryToHubSettings with a headerless three-column x,y,z CSV in metres. Microphone identity follows row order. A custom starting geometry and the hub's angular and radial graduation increments can be supplied as optional arguments. System diagrams Figures 2 and 3 can be compiled independently with a LaTeX distribution that includes TikZ and the standalone document class: cd diagramspdflatex system_architecture.texpdflatex ring_buffer.tex Software requirements The MATLAB workflows require: MATLAB R2025b; Signal Processing Toolbox; Statistics and Machine Learning Toolbox; Optimization Toolbox; Communications Toolbox; Curve Fitting Toolbox; Parallel Computing Toolbox for the optional process-based grid rerun. Data included in the repository The repository contains the processed inputs required by the manuscript analyses: 368 validated, synchronised, four-channel Batsy4-Pro call clips; a prepared laboratory playback segment used for the waveform example; derived duration, localisation, SNR, and clustering tables; complete corrected grid-simulation results. Continuous field recordings and the call-detection and extraction pipeline are outside the scope of this repository. The included audio files are processed analysis inputs rather than the original continuous recordings. Additional details are available in data/README.md. Recordings and derived tables from the professional-audio-interface comparison are not included because they form part of a separate study. The published Figure 5B panel is retained solely as a reference output used by the Batsy4-Pro manuscript. Figure provenance A complete mapping between manuscript figures, source scripts, input data, and reference outputs is provided in docs/FIGURE_PROVENANCE.md. The original raw-data plotting script for the sequence spectrogram in Figure 6A was not retained. The exact PDF and editable MATLAB .fig used in the manuscript are included to preserve that panel. All other code-generated panels have repository-contained analysis or plotting scripts. Firmware The firmware/Batsy4-Pro/ directory contains: the Arduino/Teensy source (batsy4pro.ino); compiled HEX, ELF, EEP, symbol, and listing files; firmware build metadata; the bill of materials and operating documentation. The included build targets the Teensy 4.1 and records four synchronised 16-bit channels at 192 kHz. Build-specific information is documented in firmware/Batsy4-Pro/firmware/BUILD_INFO.md. Citation If you use Batsy4-Pro or the accompanying analysis workflows, please cite the manuscript and the corresponding software release. Machine-readable citation metadata are provided in CITATION.cff. Preprint DOI: 10.1101/2025.08.11.669530 Licences Different project components are distributed under the following licences: software and firmware: GPL-3.0-only; hardware documentation: CERN-OHL-S-2.0; documentation and figures: CC-BY-SA-4.0. See LICENSE.md for the complete licensing statement. Processed acoustic data are supplied for reproducibility of the manuscript analyses; contact the author before redistributing the recordings as a standalone dataset.