Skip to content

Commit b89765b

Browse files
consuelitaconsuelita
committed
Update README.md
1 parent ff1dbd7 commit b89765b

File tree

1 file changed

+217
-2
lines changed

1 file changed

+217
-2
lines changed

‎README.md‎

Lines changed: 217 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,217 @@
1-
# AudioCoderAndroid
2-
Audio library based on TheMetallists/LoudBang
1+
# AudioCoder Android Library
2+
3+
A standalone Android library for WSPR (Weak Signal Propagation Reporter) encoding and decoding, extracted from the [LoudBang](https://github.com/TheMetallists/LoudBang) application to provide WSPR functionality for other Android applications.
4+
5+
## Overview
6+
7+
AudioCoder provides a complete WSPR implementation for Android, including:
8+
- **WSPR Signal Encoding**: Generate WSPR audio signals from callsign, grid locator, and power data
9+
- **WSPR Signal Decoding**: Decode WSPR messages from audio recordings
10+
- **Utility Functions**: Distance calculations, grid square conversions, and callsign hashing
11+
- **Database Integration**: Store and manage decoded WSPR contacts
12+
13+
The library uses native C/C++ code with FFTW for high-performance signal processing, wrapped with a clean Java/Kotlin API.
14+
15+
## Installation
16+
17+
### Using JitPack
18+
19+
Add JitPack to your project's `settings.gradle`:
20+
21+
```gradle
22+
dependencyResolutionManagement {
23+
repositories {
24+
maven { url 'https://jitpack.io' }
25+
}
26+
}
27+
```
28+
29+
Add the dependency to your app's `build.gradle`:
30+
31+
```gradle
32+
dependencies {
33+
implementation 'com.github.OperatorFoundation:AudioCoderAndroid:main-SNAPSHOT'
34+
}
35+
```
36+
37+
For specific versions, replace `main-SNAPSHOT` with a commit hash or release tag.
38+
39+
## Quick Start
40+
41+
### Basic WSPR Encoding
42+
43+
```java
44+
import org.operatorfoundation.audiocoder.CJarInterface;
45+
46+
// Generate WSPR signal
47+
byte[] audioData = CJarInterface.WSPREncodeToPCM(
48+
"K1JT", // Callsign
49+
"FN20", // Grid locator
50+
30, // Power (dBm)
51+
0, // Frequency offset (Hz)
52+
false // LSB mode
53+
);
54+
55+
// audioData contains 16-bit PCM samples at 12kHz sample rate
56+
// Ready for audio playback or file output
57+
```
58+
59+
### Basic WSPR Decoding
60+
61+
```java
62+
import org.operatorfoundation.audiocoder.WSPRMessage;
63+
64+
// Decode WSPR from audio data
65+
WSPRMessage[] messages = CJarInterface.WSPRDecodeFromPcm(
66+
audioData, // PCM audio data
67+
14.097, // Dial frequency (MHz)
68+
false // LSB mode
69+
);
70+
71+
// Process decoded messages
72+
for (WSPRMessage msg : messages) {
73+
System.out.println("Callsign: " + msg.call);
74+
System.out.println("Grid: " + msg.loc);
75+
System.out.println("Power: " + msg.power + " dBm");
76+
System.out.println("SNR: " + msg.getSNR() + " dB");
77+
System.out.println("Frequency: " + msg.getFREQ() + " Hz");
78+
}
79+
```
80+
81+
## API Reference
82+
83+
### Core Interface: `CJarInterface`
84+
85+
#### Encoding
86+
```java
87+
public static native byte[] WSPREncodeToPCM(String callsign, String locator, int power, int offset, boolean lsb)
88+
```
89+
Generates WSPR audio signal as PCM data.
90+
91+
**Parameters:**
92+
- `callsign`: Ham radio call sign (e.g., "W1AW")
93+
- `locator`: Maidenhead grid square (e.g., "FN31")
94+
- `power`: Transmit power in dBm (0-60)
95+
- `offset`: Frequency offset in Hz
96+
- `lsb`: Use LSB mode (inverts symbol order)
97+
98+
**Returns:** 16-bit PCM audio data as byte array
99+
100+
#### Decoding
101+
```java
102+
public static native WSPRMessage[] WSPRDecodeFromPcm(byte[] sound, double dialfreq, boolean lsb)
103+
```
104+
Decodes WSPR messages from audio data.
105+
106+
**Parameters:**
107+
- `sound`: PCM audio data as byte array
108+
- `dialfreq`: Radio dial frequency in MHz
109+
- `lsb`: Signal uses LSB mode
110+
111+
**Returns:** Array of decoded `WSPRMessage` objects
112+
113+
#### Utility Functions
114+
```java
115+
public static native int WSPRNhash(String call)
116+
public static native double WSPRGetDistanceBetweenLocators(String a, String b)
117+
public static native String WSPRLatLonToGSQ(double lat, double lon)
118+
public static native int radioCheck(int testvar)
119+
```
120+
121+
### Data Classes
122+
123+
#### `WSPRMessage`
124+
```java
125+
public class WSPRMessage {
126+
public float getSNR() // Signal-to-noise ratio (dB)
127+
public double getFREQ() // Frequency offset (Hz)
128+
public String getMSG() // Complete decoded message
129+
public float getDT() // Time offset (seconds)
130+
public float getDRIFT() // Frequency drift (Hz)
131+
132+
// Additional fields
133+
public String call; // Callsign
134+
public String loc; // Grid locator
135+
public int power; // Power level (dBm)
136+
}
137+
```
138+
139+
#### Database Classes
140+
- `DBHelper`: SQLite database management for WSPR contacts
141+
- `WSPRNetSender`: Upload decoded spots to WSPRNet
142+
- `Bandplan`: Ham radio band plan definitions
143+
144+
## Technical Specifications
145+
146+
- **Audio Format**: 16-bit PCM, 12 kHz sample rate
147+
- **WSPR Mode**: WSPR-2 (2-minute transmission periods)
148+
- **Frequency**: 1500 Hz center frequency with ±200 Hz range
149+
- **Signal Processing**: Native C/C++ with FFTW for performance
150+
- **Android Support**: API 26+ (Android 8.0+)
151+
- **Architectures**: armeabi-v7a, arm64-v8a, x86, x86_64
152+
153+
## Examples
154+
155+
### Distance Calculation
156+
```java
157+
// Calculate great circle distance between grid squares
158+
double distance = CJarInterface.WSPRGetDistanceBetweenLocators("FN20", "JO65");
159+
System.out.println("Distance: " + Math.round(distance) + " km");
160+
```
161+
162+
### Grid Square Conversion
163+
```java
164+
// Convert latitude/longitude to Maidenhead grid square
165+
String gridSquare = CJarInterface.WSPRLatLonToGSQ(40.7128, -74.0060); // NYC
166+
System.out.println("Grid Square: " + gridSquare); // "FN30as"
167+
```
168+
169+
### Database Integration
170+
```java
171+
// Store decoded messages in local database
172+
DBHelper dbHelper = new DBHelper(context);
173+
// Database operations for managing WSPR contacts
174+
```
175+
176+
## Requirements
177+
178+
- Android API 26+ (Android 8.0+)
179+
- NDK support for native libraries
180+
- Approximately 10MB additional APK size
181+
182+
## License
183+
184+
This library is licensed under the MIT License. See [LICENSE](LICENSE) for details.
185+
186+
## Attribution
187+
188+
This library is a fork of the [LoudBang](https://github.com/TheMetallists/LoudBang) Android application, extracted and modified to serve as a standalone WSPR library. We gratefully acknowledge the original authors' work.
189+
190+
The WSPR protocol implementation is based on code by Joe Taylor (K1JT) and Steven Franke (K9AN) from the WSJT-X project.
191+
192+
## Contributing
193+
194+
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
195+
196+
1. Fork the repository
197+
2. Create a feature branch
198+
3. Make your changes with tests
199+
4. Submit a pull request
200+
201+
## Support
202+
203+
- **Issues**: [GitHub Issues](https://github.com/OperatorFoundation/AudioCoderAndroid/issues)
204+
- **Documentation**: This README and inline code documentation
205+
- **Community**: WSPR and amateur radio communities
206+
207+
## Changelog
208+
209+
### Pre-release Development
210+
- Initial library extraction from LoudBang
211+
- JitPack publishing configuration
212+
- Native library optimization
213+
- API documentation
214+
215+
---
216+
217+
**Note**: This library is currently in pre-release development. APIs may change before the first stable release.

0 commit comments

Comments
 (0)