This guide covers everything you need to know to develop firmware for the BioAcoustic Index Tool (BAIT), work with the analysis scripts, and contribute to the project.
- Development Environment Setup
- Project Structure
- Firmware Development
- Running Tests
- Data Analysis
- Hardware Development
- Contributing
Before you begin, make sure you have the following installed:
- Git — for version control
- PlatformIO Core — the build system for embedded firmware
- Python 3 — required by PlatformIO and for analysis notebooks
- An IDE — either CLion (recommended) or VS Code with PlatformIO extension
PlatformIO can be installed as a standalone command-line tool:
brew install platformiopip install platformiopip install platformioFor detailed installation instructions, see the PlatformIO Installation Guide.
CLion provides excellent C++ support with advanced code completion, refactoring, and debugging.
- Download and install CLion from JetBrains
- Install the PlatformIO plugin:
- Open CLion
- Go to Settings/Preferences → Plugins
- Search for "PlatformIO" and install it
- Restart CLion
- Open a firmware directory (e.g.,
firmware/bait2/) as a project
For complete setup instructions, see the PlatformIO + CLion Integration Guide.
Visual Studio Code is a free, lightweight alternative.
- Download and install VS Code
- Install the PlatformIO IDE extension from the Extensions marketplace
- Restart VS Code
- Open a firmware directory using PlatformIO: Open Project
The following versions have been tested and confirmed to work:
| Tool | Version |
|---|---|
| PlatformIO | 6.1.7 |
| CLion | 2023.1.3 |
| Python | 3.8+ |
Newer versions should also work, but if you encounter issues, consider using these verified versions.
The BioAcousticIndexTool repository is organized as follows:
BioAcousticIndexTool/
├── firmware/
│ ├── bait/ # BAIT v1 firmware (Teensy 3.5/3.6/MicroMod)
│ └── bait2/ # BAIT v2 firmware (Teensy MicroMod — active development)
├── electronics/
│ ├── BAIT.fzz # v1 Fritzing schematic
│ ├── BAIT_bb.png # v1 breadboard wiring diagram
│ └── BAIT2_MicroMod/ # v2 Eagle PCB & schematic
├── enclosure/
│ ├── BAIT.dwg # AutoCAD enclosure drawing
│ └── BAIT.f3z # Fusion 360 enclosure design
├── analysis/ # Jupyter notebooks and R scripts for data analysis
├── data/ # Sample raw and processed data
│ ├── raw/ # Raw acoustic and sensor data
│ └── processed/ # Processed data files
└── docs/ # Developer documentation
├── developing.md # This file
└── v2_ideas.md # Hardware design notes for v2
The original firmware for Teensy 3.5, 3.6, and MicroMod processors.
firmware/bait/
├── src/ # Source files
│ ├── main.cpp # Main program entry point
│ ├── AcousticComplexityIndex.* # ACI implementation
│ ├── AcousticDiversityIndex.* # ADI implementation
│ ├── AcousticDifferenceIndex.* # ADE implementation
│ ├── FFTReader.* # FFT capture from Teensy Audio Library
│ ├── AtmosphericSensors.* # Si7021 temperature/humidity driver
│ ├── BatteryMeasurement.* # Battery voltage monitoring
│ ├── sdcard.h # SD card helpers
│ ├── definitions.h # Pin definitions and constants
│ └── parameters.h # Measurement parameters
├── platformio.ini # PlatformIO build configuration
└── README.md
Build Environments:
teensy35— Teensy 3.5 boardteensy36— Teensy 3.6 board (120 MHz)teensymm— Teensy MicroMod
The actively developed v2 firmware with modular library structure.
firmware/bait2/
├── src/ # Main application code
│ └── main.cpp # Entry point
├── lib/ # Internal libraries
│ ├── Ecoacoustics/ # Acoustic index computation (ACI, ADI, ADE)
│ ├── Environment/ # Environmental sensors (BME680, TSL2591, BQ27441)
│ ├── Communication/ # LoRaWAN via Seeed WIO-E5
│ ├── Logging/ # SD card logging
│ ├── Display/ # Display driver
│ └── Sensor/ # Base sensor abstraction
├── test/ # Unit tests
├── platformio.ini # PlatformIO build configuration
└── README.md
Build Environments:
teensymm— Development build with USB serial, waits for serial monitor on startupteensymm-release— Release build with USB audio only, no serial waitdesktop— Native (x86/ARM) build for unit testing without hardware
The BAIT v2 firmware is organized into modular libraries:
| Library | Purpose | Key Components |
|---|---|---|
| Ecoacoustics | Acoustic index computation | ACI, ADI, ADE algorithms; FFT processing |
| Environment | Environmental monitoring | BME680 (temp, humidity, pressure, gas), TSL2591 (light), BQ27441 (battery) |
| Communication | Wireless data transmission | LoRaWAN via Seeed WIO-E5 module, CayenneLPP encoding |
| Logging | Data persistence | SD card file management, CSV logging |
| Display | User interface | Optional display output |
| Sensor | Abstraction layer | Base classes for sensor drivers |
Make sure to clone with submodules, as some libraries are linked as Git submodules:
git clone --recurse-submodules https://github.com/dkadish/BioAcousticIndexTool.git
cd BioAcousticIndexToolIf you already cloned without submodules, initialize them:
git submodule update --init --recursiveNavigate to the BAIT v2 firmware directory:
cd firmware/bait2Development Build (with serial debugging):
pio run -e teensymmUpload to connected Teensy MicroMod:
pio run -e teensymm -t uploadRelease Build (for deployment):
pio run -e teensymm-release -t uploadNative Desktop Build (for testing without hardware):
pio run -e desktopNavigate to the BAIT v1 firmware directory:
cd firmware/baitBuild for Teensy 3.5:
pio run -e teensy35Upload to Teensy 3.5:
pio run -e teensy35 -t uploadBuild for Teensy 3.6:
pio run -e teensy36 -t uploadBuild for Teensy MicroMod:
pio run -e teensymm -t uploadTo view serial debug output from a connected device:
pio device monitorOr specify a baud rate:
pio device monitor -b 115200If you encounter build issues, clean the build cache:
pio run -t cleanBAIT v2 includes unit tests that can run both on the desktop (without hardware) and on embedded devices.
Desktop tests run natively on your development machine using the desktop environment:
cd firmware/bait2
pio test -e desktopThis is the fastest way to verify core functionality without needing a physical Teensy board.
To run tests on a connected Teensy MicroMod:
cd firmware/bait2
pio test -e teensymmEmbedded tests validate hardware-specific functionality like sensor communication and audio processing.
Tests are located in firmware/bait2/test/. To add a new test, create a file in the test/ directory following the PlatformIO testing conventions.
Example test structure:
#include <unity.h>
void test_example_function(void) {
TEST_ASSERT_EQUAL(42, example_function());
}
void setup() {
UNITY_BEGIN();
RUN_TEST(test_example_function);
UNITY_END();
}
void loop() {}The analysis/ directory contains Jupyter notebooks (Python) and R Markdown files for verifying acoustic index calculations and visualizing field data.
-
Install Python dependencies:
pip install jupyter numpy scipy matplotlib pandas
-
Launch Jupyter:
cd analysis jupyter notebook -
Open a notebook (e.g.,
prototype_data_analysis.ipynb)
-
Install R from r-project.org
-
Install required R packages:
install.packages(c("soundecology", "tuneR", "seewave", "ggplot2", "rmarkdown"))
-
Open an R Markdown file (e.g.,
aci_verification/compare_bait_soundecology_aci.Rmd) in RStudio and click KnitOr render from the command line:
Rscript -e "rmarkdown::render('aci_verification/compare_bait_soundecology_aci.Rmd')"
| File / Directory | Description |
|---|---|
prototype_data_analysis.ipynb |
Jupyter notebook — exploratory analysis of field data |
aci_verification/FFT_Comparison.ipynb |
Python — compares BAIT FFT output to reference implementations |
aci_verification/compare_bait_soundecology_aci.Rmd |
R Markdown — compares BAIT ACI against soundecology package |
aci_verification/compare_bait_soundecology_chunks.Rmd |
R Markdown — chunk-level ACI comparison |
Sample data files for testing are located in the data/ directory.
Hardware design files are in the electronics/ directory:
- BAIT v1: Fritzing schematic (
BAIT.fzz) and breadboard diagram (BAIT_bb.png) - BAIT v2: Eagle schematic and PCB layout in
BAIT2_MicroMod/
Required Tools:
- Fritzing — for v1 designs
- Autodesk Eagle — for v2 designs
See ../electronics/README.md for details.
Mechanical design files are in the enclosure/ directory:
- AutoCAD:
BAIT.dwg - Fusion 360:
BAIT.f3z
See ../enclosure/README.md for details.
For ideas and notes on v2 hardware improvements, see v2_ideas.md.
Contributions to BAIT are welcome! Whether you're fixing bugs, adding features, improving documentation, or sharing field deployment experiences, your input is valuable.
- Code Style: Follow the existing code style in the firmware (consistent indentation, meaningful variable names)
- Testing: Add tests for new features when possible
- Documentation: Update README files and comments when changing functionality
- Commit Messages: Write clear, descriptive commit messages
- Fork the repository on GitHub
- Create a feature branch (
git checkout -b feature/my-new-feature) - Make your changes and commit them (
git commit -am 'Add new feature') - Push to your branch (
git push origin feature/my-new-feature) - Open a Pull Request on GitHub
If you encounter bugs or have feature requests, please open an issue on GitHub with:
- A clear description of the problem or request
- Steps to reproduce (for bugs)
- Expected vs. actual behavior
- Hardware and software versions
For questions about the project, feel free to open a GitHub Discussion or reach out to the maintainers.
- Firmware READMEs:
- Hardware:
- Data Analysis:
- PlatformIO Documentation:
Happy developing! 🎤🔧