Contributing to Minimodem

Minimodem is an open-source project that welcomes contributions from the community. Whether you’re fixing bugs, adding features, improving documentation, or testing, your help is appreciated!

Ways to Contribute

Report Bugs

Found an issue? Report it on GitHub with detailed information about the problem.

Submit Code

Fix bugs, add features, or improve performance by submitting pull requests.

Improve Documentation

Help others by improving documentation, adding examples, or writing tutorials.

Test & Verify

Test minimodem on different platforms and with various protocols.

Getting Started

Setting Up Development Environment

Clone the repository

git clone https://github.com/kamalmostafa/minimodem.git
cd minimodem

Install dependencies

Debian/Ubuntu:

sudo apt-get install build-essential pkg-config automake autoconf \
     libasound2-dev libfftw3-dev libpulse-dev libsndfile1-dev

Fedora/RHEL:

sudo dnf install gcc pkg-config automake autoconf \
     alsa-lib-devel fftw3-devel pulseaudio-libs-devel libsndfile-devel

macOS:

brew install fftw libsndfile pkg-config automake autoconf

Or use the provided scripts:

# Linux
./install-dependencies-linux.sh

# macOS  
./install-dependencies-macos.sh

Build from source

autoreconf -i
./configure
make

Use ./configure --help to see available build options.

Run tests

make check

All tests should pass before submitting changes.

Project Structure

minimodem/
├── src/                    # Source code
│   ├── minimodem.c        # Main program
│   ├── fsk.c              # FSK modem implementation
│   ├── simpleaudio*.c     # Audio backend implementations
│   ├── baudot.c           # Baudot encoding/decoding
│   ├── databits*.c        # Data framing implementations
│   └── *.h                # Header files
├── tests/                 # Test suite
│   ├── self-test          # Test runner script
│   ├── *.test             # Individual test scripts
│   └── testdata-*.txt     # Test data files
├── configure.ac           # Autoconf configuration
├── Makefile.am            # Automake makefile
├── README                 # Basic project info
├── THANKS                 # Acknowledgments
└── AUTHORS                # Contributors list

Code Architecture

Main Components

minimodem.c

Command-line parsing
Main transmit/receive loops
Protocol selection and configuration

fsk.c

FSK modulation/demodulation algorithms
FFT-based frequency detection
Signal analysis and confidence calculation

simpleaudio.c

Audio backend abstraction layer
Supports ALSA, PulseAudio, sndio, and file I/O

Audio Backends

Each audio system has its own implementation:

simpleaudio-alsa.c - ALSA support (Linux)
simpleaudio-pulse.c - PulseAudio support
simpleaudio-sndio.c - sndio support (BSD)
simpleaudio-sndfile.c - File-based audio (all platforms)
simpleaudio-benchmark.c - Performance testing

The simpleaudio layer provides a unified interface.

Data Framing

Protocol-specific framing implementations:

databits_ascii.c - ASCII 8-N-1 framing
databits_baudot.c - Baudot 5-N-1.5 framing
databits_binary.c - Raw binary output
databits_callerid.c - Caller-ID (MDMF/SDMF)
databits_uic.c - UIC train protocol

Coding Guidelines

Code Style

C Code
Comments
Error Handling

Use 4-space indentation (spaces, not tabs)
Opening braces on same line for functions
K&R style for control structures
Comment complex algorithms
Keep lines under 80 characters where practical

// Good
void my_function( int param )
{
    if ( param > 0 ) {
        // do something
    }
}

// Not preferred
void my_function(int param) {
  if(param>0){
    // do something
  }
}

Use // for single-line comments
Use /* */ for multi-line block comments
Document public APIs and complex logic
Mark temporary code with FIXME: or TODO:
Reference relevant issues or RFCs

/*
 * fsk_find_frame()
 *
 * Analyzes audio samples to detect and decode FSK frames.
 * Returns confidence value based on signal quality.
 */

Check return values
Use perror() for system errors
Print to stderr for error messages
Clean up resources on error paths

if ( !fskp ) {
    perror("fsk_plan_new");
    return NULL;
}

Build Configuration

Minimodem uses autotools for build configuration: Adding new features:

Add detection to configure.ac

Use conditional compilation:

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#if USE_MY_FEATURE
// feature code
#endif

Update Makefile.am if adding new files

Configuration options:

--with-alsa / --without-alsa
--with-pulseaudio / --without-pulseaudio
--with-sndio / --without-sndio
--with-sndfile / --without-sndfile
--disable-benchmarks

Testing

Running Tests

# Run complete test suite
make check

Test Types

Self Tests (01-09)

Basic round-trip tests at various baud rates:

1200 bps (Bell202)
300 bps (Bell103)
RTTY (Baudot)
Very low (0.5 bps) and very high (12000 bps) rates
Float vs. integer samples
LUT (lookup table) variations

Verification Tests (10-17)

Tests for perfect decoding with exact parameters:

Confidence = infinity expected
Rate perfect decoding
Consistent TX output
Various sample formats

Robustness Tests (21-41)

Tests with challenging conditions:

Rate slop (TX/RX baud rate mismatch)
Amplitude variations
Noise injection
Pure frequencies vs. real-world signals

Protocol Tests (60-81)

Specific protocol implementations:

Multibyte characters
Caller-ID (MDMF and SDMF)
SAME protocol
ASCII-7 mode
TDD/TTY

Adding New Tests

Create a new test file in tests/:

#!/bin/bash
# tests/99-my-new-test.test
exec ./self-test testdata-ascii.txt 2400

Make it executable:

chmod +x tests/99-my-new-test.test

Tests are automatically discovered by the build system.

Contributing Code

Submitting Pull Requests

Fork and create a branch

git checkout -b feature/my-new-feature

Make your changes

Write clean, documented code
Follow coding style guidelines
Add tests if applicable
Update documentation if needed

Test thoroughly

make clean
./configure
make
make check

Ensure all tests pass on your platform.

Commit with clear messages

git add .
git commit -m "Add support for new protocol XYZ

- Implement XYZ framing in databits_xyz.c
- Add command-line option --xyz
- Include test case for XYZ protocol
- Update man page with XYZ documentation"

Push and create pull request

git push origin feature/my-new-feature

Create a pull request on GitHub with:

Clear description of changes
Motivation/use case
Test results
Any breaking changes noted

Pull Request Checklist

Bug Reports

Filing Issues

When reporting a bug, include:

System Information

Operating system and version
Minimodem version: minimodem --version
Audio backend being used (ALSA/PulseAudio/sndio)
Hardware details (if relevant)

Reproduction Steps

Exact command(s) used
Input data or file (if applicable)
Expected behavior
Actual behavior

Diagnostic Information

Complete error messages
Output from make check
Sample audio file (if problem is protocol-specific)
Configuration options used: ./configure --help

Example Bug Report

**Environment:**
- Ubuntu 22.04 LTS
- minimodem 0.24
- ALSA backend
- Intel HDA audio

**Problem:**
Carrier detection fails when using --auto-carrier with Bell103 300 baud.

**Steps to reproduce:**
1. Generate test file: `echo "test" | minimodem --tx --file test.wav 300`
2. Try to receive: `minimodem --rx --auto-carrier --file test.wav 300`

**Expected:** Should decode "test"
**Actual:** Reports "NOCARRIER" immediately

**Workaround:** Works without --auto-carrier flag

**Additional info:**
- Sample file attached: test.wav
- Regular RX works: `minimodem --rx --file test.wav 300`

Development Tips

Debug Builds

./configure CFLAGS="-g -O0"
make
gdb ./src/minimodem

Verbose Output

Enable debug output in code:

#define FSK_DEBUG

Or use --verbose flag (if implemented).

Audio Analysis

Use Audacity or similar tools to visualize generated audio files:

minimodem --tx --file debug.wav 1200
audacity debug.wav

Valgrind

Check for memory leaks:

valgrind --leak-check=full \
  ./src/minimodem --rx --file test.wav 1200

Documentation

Man Page

The man page source is src/minimodem.1.in. It uses:

Autoconf substitutions (e.g., @PACKAGE_VERSION@)
Standard man page formatting (groff)

Preview man page:

man ./src/minimodem.1

After changes:

Update minimodem.1.in
Run ./configure to regenerate
Test: man -l src/minimodem.1

Code Comments

Important areas to document:

Public API functions
Complex algorithms (especially FSK detection)
Non-obvious design decisions
Performance considerations
Protocol specifications

Community

GitHub

Source code, issues, and pull requests

Mailing List

Contact: [email protected]

IRC/Forums

Check GitHub for community links

Credits

Minimodem is maintained by Kamal Mostafa ([email protected]). Major contributors:

Marcos Vives Del Sol - UIC-751-3 mode
Nick Moriarty - --tx-carrier feature
Colin Ian King - Bug fixes and testing
José Miguel Sánchez García - sndio backend

See the THANKS file for a complete list of contributors.

License

Minimodem is licensed under the GNU General Public License v3.0 or later (GPLv3+). By contributing, you agree that your contributions will be licensed under the same license.

All contributions must be compatible with GPLv3+. Ensure you have the right to contribute any code or documentation you submit.

Questions?

If you have questions about contributing:

Check existing GitHub issues and pull requests
Review this guide and the project documentation
Ask on GitHub Discussions (if available)
Contact the maintainer

Thank you for contributing to minimodem!

Additional Resources

Contributing to Minimodem

Ways to Contribute

Report Bugs

Submit Code

Improve Documentation

Test & Verify

Getting Started

Setting Up Development Environment

Project Structure

Code Architecture

Coding Guidelines

Code Style

Build Configuration

Testing

Running Tests

Test Types

Adding New Tests

Contributing Code

Submitting Pull Requests

Pull Request Checklist

Bug Reports

Filing Issues

Example Bug Report

Development Tips

Debug Builds

Verbose Output

Audio Analysis

Valgrind

Documentation

Man Page

Code Comments

Community

GitHub

Mailing List

IRC/Forums

Credits

License

Questions?

Build docs developers (and LLMs) love

Additional Resources

​Ways to Contribute

Report Bugs

Submit Code

Improve Documentation

Test & Verify

​Getting Started

​Setting Up Development Environment

​Project Structure

​Code Architecture

​Coding Guidelines

​Code Style

​Build Configuration

​Testing

​Running Tests

​Test Types

​Adding New Tests

​Contributing Code

​Submitting Pull Requests

​Pull Request Checklist

​Bug Reports

​Filing Issues

​Example Bug Report

​Development Tips

Debug Builds

Verbose Output

Audio Analysis

Valgrind

​Documentation

​Man Page

​Code Comments

​Community

GitHub

Mailing List

IRC/Forums

​Credits

​License

​Questions?

Build docs developers (and LLMs) love

Ways to Contribute

Getting Started

Setting Up Development Environment

Project Structure

Code Architecture

Coding Guidelines

Code Style

Build Configuration

Testing

Running Tests

Test Types

Adding New Tests

Contributing Code

Submitting Pull Requests

Pull Request Checklist

Bug Reports

Filing Issues

Example Bug Report

Development Tips

Documentation

Man Page

Code Comments

Community

Credits

License

Questions?