Skip to content

Commit 7ec072c

Browse files
int2001int2001
committed
Update Readme
1 parent 63f02f6 commit 7ec072c

File tree

2 files changed

+296
-105
lines changed

2 files changed

+296
-105
lines changed

‎README.md‎

Lines changed: 226 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,245 @@
1-
# CAT and WSJT-X Bridge for Wavelog
1+
# WaveLogGate - CAT and WSJT-X Bridge for WaveLog
22

3-
## Prerequisites
4-
5-
* [FLRig](http://www.w1hkj.com/) properly SetUp to your TRX (if you want to use the CAT-Feature. It's optional!)
6-
* WSJT-X (if you want to use the automatic logging from WSJT-X/Z/Y / FLDigi / Tool which produces UDP-Log-Packets)
7-
* WaveLog-Account on any WaveLog instance
8-
* HTTPS (SSL) has to be enabled for Wavelog to use WLGate
9-
10-
## WARNING // IMPORTANT! (When using AppleSilicon Mac)
3+
A modern Electron-based gateway application that connects WSJT-X, FLRig, Hamlib, and other amateur radio software to WaveLog for seamless logging and radio control.
114

12-
If you use a newer mac (with M1,M2,M3, etc.) apple changed their policy for unsigned Apps.
13-
There's a workaround available, but you need the Terminal aka Shell for that.
14-
Instructions:
5+
## Features
156

16-
1. Download Binary/DMG
17-
2. Copy Binary/DMG to Application-Folder
18-
3. Launch Terminal.app
19-
4. Type in the following:
20-
* `xattr -d com.apple.quarantine /Applications/WaveLogGate.app`
21-
* Launch the Application (should launch now)
7+
### Core Functionality
8+
- **Automatic QSO Logging**: Real-time logging from WSJT-X, FLDigi, and any software sending ADIF via UDP
9+
- **CAT Radio Control**: Full radio control via FLRig or Hamlib integration
10+
- **Dual Profile Support**: Switch between two complete configuration profiles
11+
- **Real-time Radio Status**: Live frequency, mode, and power status updates to WaveLog
12+
- **Cross-platform**: Windows, macOS, and Linux support
13+
14+
### Advanced Features
15+
- **WebSocket Server**: Real-time broadcasting of radio status changes to external clients
16+
- **HTTP API**: Simple frequency/mode control endpoint for external integrations
17+
- **Power Monitoring**: Automatic power level reporting (can be disabled if needed)
18+
- **Split Operation**: Support for split frequency operations
19+
- **ADIF Processing**: Robust ADIF and XML parsing with automatic band detection
20+
- **Modern UI**: Bootstrap 4-based interface with responsive design
2221

23-
## Setup
22+
## Prerequisites
2423

25-
1. Download Binary
26-
2. Start Binary (for Windows: Start Binary and after that you have a NEW Binary. One can delete the old one)
27-
3. Fill in informations:
28-
* WAVELog-URL including index.php (if you setted it up with that)
29-
* API-Key (from Wavelog / Right Menu / API-Keys)
30-
* Station-ID (from Wavelog / Right Menu / See Stationlocations / small badge with station-ID)
31-
4. If you're running FLRig on the same machine put 127.0.0.1 to FLRig-Host and 12345 to FLRig Port and enable it.
32-
5. Click "Test" - Button becomes green if working, Red with detailled issue below, when faulty.
33-
6. Click "Save" if everything is okay
24+
- **WaveLog Instance**: Any WaveLog installation with HTTPS (SSL) enabled
25+
- **WaveLog API Key**: Generated from WaveLog right menu → API-Keys
26+
- **WaveLog Station ID**: Found in WaveLog right menu → Station locations
27+
- **Radio Control Software** (optional):
28+
- FLRig for CAT control
29+
- Hamlib for CAT control
30+
- OR any software capable of sending ADIF via UDP
31+
- **WSJT-X** (optional): For automatic digital mode logging
32+
33+
## Installation
34+
35+
### Download Pre-built Binaries
36+
1. Download the latest release from the [WaveLogGate GitHub repository](https://github.com/wavelog/WaveLogGate/releases)
37+
2. Run the installer for your platform:
38+
- **Windows**: Run the `.exe` installer
39+
- **macOS**: Copy the `.app` file to Applications folder
40+
- **Linux**: Install the `.deb` package or extract the AppImage
41+
42+
### Apple Silicon Mac Users
43+
Due to macOS security restrictions for unsigned apps:
44+
45+
```bash
46+
# After copying to Applications folder
47+
xattr -d com.apple.quarantine /Applications/WaveLogGate.app
48+
```
49+
50+
## Configuration
51+
52+
### Basic Setup
53+
1. **Launch WaveLogGate**
54+
2. **Enter WaveLog Details**:
55+
- **WaveLog URL**: Full URL including `/index.php` (e.g., `https://your-wavelog.com/index.php`)
56+
- **API Key**: From WaveLog right menu → API-Keys
57+
- **Station ID**: From WaveLog right menu → Station locations (click the small badge)
58+
3. **Configure Radio Control** (optional):
59+
- Select radio type: FLRig, Hamlib, or None
60+
- Enter host and port (default: 127.0.0.1 and appropriate port)
61+
- Enable/disable mode control and power monitoring
62+
4. **Test Configuration**: Click the "Test" button - it turns green if successful
63+
5. **Save Settings**: Click "Save" to persist your configuration
64+
65+
### Radio Configuration Options
66+
67+
#### FLRig Setup
68+
- **Host**: Usually `127.0.0.1` if running locally
69+
- **Port**: Default `12345`
70+
- **Mode Control**: Enable to let WaveLogGate set radio modes automatically
71+
72+
#### Hamlib Setup
73+
- **Host**: Usually `127.0.0.1` if running locally
74+
- **Port**: Default `4532`
75+
- **Mode Control**: Enable to let WaveLogGate set radio modes automatically
76+
- **Ignore Power**: Check if your radio doesn't report power correctly
77+
78+
### Profile Management
79+
WaveLogGate supports two complete configuration profiles:
80+
- Click the profile toggle button (1/2) to switch between profiles
81+
- Each profile maintains independent WaveLog and radio settings
82+
- Useful for multiple stations or operating locations
83+
84+
## Software Integration
85+
86+
### WSJT-X Setup
87+
1. Open WSJT-X Settings → Reporting
88+
2. **Enable "Secondary UDP Server"**
89+
3. Set UDP port to **2333**
90+
4. **Important**: Do NOT set the main "UDP Server" to port 2333
91+
92+
### FLDigi Setup
93+
Configure FLDigi to send ADIF logs via UDP to port 2333.
94+
95+
### WaveLog Integration
96+
1. **For Live QSOs**: Open WaveLog Live Logging → Radio tab → Select "WLGate"
97+
2. **For Manual QSOs**: In Stations tab, select "WLGate" as radio
98+
3. **Bandmap Control**: Click spots in WaveLog bandmap to automatically QSY your radio
99+
100+
## API and Integration
101+
102+
### HTTP API
103+
**Endpoint**: `http://localhost:54321/{frequency}/{mode}`
104+
105+
Example:
106+
```bash
107+
# Set radio to 7.155 MHz LSB
108+
curl http://localhost:54321/7155000/LSB
109+
```
110+
111+
### WebSocket Server
112+
**Port**: `54322`
113+
**Protocol**: WebSocket
114+
115+
Real-time radio status updates:
116+
```javascript
117+
const ws = new WebSocket('ws://localhost:54322');
118+
ws.onmessage = (event) => {
119+
const data = JSON.parse(event.data);
120+
if (data.type === 'radio_status') {
121+
console.log(`Frequency: ${data.frequency}, Mode: ${data.mode}`);
122+
}
123+
};
124+
```
125+
126+
See [WEBSOCKET_README.md](WEBSOCKET_README.md) for detailed integration examples.
127+
128+
## Advanced Settings
129+
130+
Access advanced settings by pressing **Ctrl+Shift+D** in the configuration window:
131+
132+
- **Force Hamlib**: Override FLRig and use Hamlib instead
133+
- **Disable Power Transfer**: Stop sending power readings to WaveLog
134+
- **Debug Options**: Additional logging and troubleshooting options
135+
136+
**Note**: Advanced settings are in beta - restart the application after changes to ensure they're applied correctly.
137+
138+
## Development
139+
140+
### Prerequisites
141+
- Node.js (v14+) or Bun
142+
- Git
143+
144+
### Setup Development Environment
145+
```bash
146+
# Clone repository
147+
git clone https://github.com/wavelog/WaveLogGate.git
148+
cd WaveLogGate
149+
150+
# Install dependencies
151+
npm install
152+
# or with bun
153+
bun install
154+
155+
# Start development mode
156+
npm start
157+
# or with bun
158+
bun start
159+
160+
# Build application
161+
npm run make
162+
```
34163

35-
## WSJT-X (and derivates) SetUp
164+
### Development Notes
165+
- Configuration stored in application data directory
166+
- Debug console available in development mode
167+
- Single instance enforcement (only one can run at a time)
168+
169+
## Network Ports
36170

37-
Go To WSJT-X-Settings // Reporting
38-
Enable "Secondary UDP Server" like shown in the picture. Do NOT set "UDP Server" (above) to the same Port!
171+
- **2333/UDP**: WSJT-X and ADIF log reception
172+
- **54321/HTTP**: Frequency/mode control API
173+
- **54322/WebSocket**: Real-time radio status broadcasting
174+
- **12345**: Default FLRig port (if used)
175+
- **4532**: Default Hamlib port (if used)
39176

40-
![image](https://github.com/wavelog/waveloggate/assets/1410708/7238b193-c589-4ae3-97f8-eae506965dff)
177+
## Troubleshooting
41178

42-
## SetUp/Working with CAT in Wavelog
179+
### Common Issues
180+
181+
#### Port Conflicts
182+
- Ensure ports 2333, 54321, and 54322 are not blocked
183+
- Stop other applications using these ports
184+
- Application shows clear error messages for port conflicts
185+
186+
#### Radio Connection Issues
187+
- Verify FLRig/Hamlib is running and accessible
188+
- Check host/port configuration matches your radio control software
189+
- Test connectivity using the "Test" button in WaveLogGate
190+
191+
#### WaveLog Connection Issues
192+
- Verify WaveLog URL is correct and accessible
193+
- Check API key is valid and not expired
194+
- Ensure Station ID exists in your WaveLog instance
195+
- HTTPS must be enabled on WaveLog
196+
197+
#### Linux Specific Issues
198+
- Some distributions may need additional libraries:
199+
```bash
200+
# For Raspberry Pi or some Linux distributions
201+
sudo apt-get install libasound2-dev
202+
```
203+
See [DB4SCW's guide](https://www.db4scw.de/getting-waveloggate-to-run-on-the-raspberry-pi/) for detailed Raspberry Pi setup.
204+
205+
#### macOS Apple Silicon Issues
206+
If the app won't start on Apple Silicon Mac:
207+
```bash
208+
xattr -d com.apple.quarantine /Applications/WaveLogGate.app
209+
```
210+
211+
### Debug Information
212+
- Check the application log for detailed error messages
213+
- Use Ctrl+Shift+D to access advanced settings
214+
- In development mode, use the browser console for debugging
43215

44-
1. Open Live-Logging
45-
2. Set Radio at Radio-Tab
46-
3. Do QSO
47-
4. Log
216+
## Contributing
48217

49-
Radio will be saved for next QSO
218+
Contributions are welcome! Please:
50219

51-
## Features
220+
1. Fork the repository
221+
2. Create a feature branch
222+
3. **Submit pull requests to the `dev` branch only**
223+
4. Follow the existing code style
224+
5. Test changes across platforms if possible
52225

53-
* When clicking on a spot in WaveLog-Bandmap your TRX with QSY to the Spot.
54-
* If you log a (non WSJT-X) QSO first go to "Stations Tab" and chose "WLGate" as Radio. After that Band/Mode/QRG will be automatically taken from your Rig into the QSO-Fields
55-
* When clicking the loupe at Live-QSO/Post-QSO Wavelog will automaticly lookup the Spot behind the QRG (if there's a spot)
226+
### Notable Contributors
227+
- [gotoradio](https://github.com/gotoradio)
228+
- [Northrup](https://github.com/northrup)
229+
- [Frédéric (ON4PFD)](https://github.com/fred-corp)
56230

57-
Enjoy
231+
## Version History
58232

59-
## Advanced Settings (Beta!)
60-
* Press CTRL+SHIFT+D in config-Window. A second window appears.
61-
* You can enable Hamlib instead of FLRig here.
62-
* You can disable taking over the Power to Wavelog here.
63-
* WARNING: This is in Beta-State. The main-config-window may(!) not show all changes. To make sure whats saved, pse restart the Application after changing the advanced-config
233+
- **v1.1.x**: Current stable version with full WebSocket support and dual profiles
234+
- **v1.0.x**: Basic FLRig and WSJT-X integration
235+
- Earlier versions: Limited feature set
64236

65-
## Contributing
237+
## License
66238

67-
Contribution is welcome. PRs will only be accepted against the Dev-Branch.
239+
This project is licensed under the terms specified in the [LICENSE](LICENSE) file.
68240

69-
## Contributions
70-
Tnx for contributing:
71-
[gotoradio](https://github.com/gotoradio) [Northrup](https://github.com/northrup) [Frédéric (ON4PFD)](https://github.com/fred-corp)
241+
## Support
72242

73-
## Troubleshooting
74-
Since we are not able to test every Linux-Version out there, we're collecting some "workarounds" and tips if there are problems with the Linux-Version.
75-
* Problem: libasound.so.2 cannot be found AND possible Problems for Raspberry: [Blogpost from DB4SCW (Thank u!)](https://www.db4scw.de/getting-waveloggate-to-run-on-the-raspberry-pi/)
76-
##
243+
- **Issues**: Report via [GitHub Issues](https://github.com/wavelog/WaveLogGate/issues)
244+
- **Documentation**: See additional README files in the repository for specific features
245+
- **WaveLog**: [WaveLog Website](https://wavelog.org/) for logging system support

0 commit comments

Comments
 (0)