Modem <-> App Interface

the Amsat High Speed Modem is a combination of two programs:

1. the modem functions are handled by hsmodem.exe (Linux: hsmodem). This is a pure console program without GUI. It has two interfaces: an UDP interface to the application and an audio driver to the sound card.
2. the Application (GUI) interacts with the user and exchanges data with the modem over an UDP link. The default Amsat applications is oscardata.exe

This makes it easy to run hsmodem on one computer and the application (oscardata.exe) on another, communication via network.

This document is addressed to programmers who want to use hsmodem.exe but make their own application to transfer any possible data.

The picture shows these functional blocks. hsmodem.exe covers the modulator/demodulator, the frame packing and data security. On the top an UDP interface handles the complete communication with the User application. This enables programmers to build their own application and use the modem as it is. The Amsat default application oscardata.exe is written in C# and therefore runs on Windows as well as on Linux (using mono).

App to modem, broadcast messages only: 40131
App to modem, data and configuration: 40132
Modem to app, all data: 40133

before the app can send data to the modem it has to know the modem's IP address. This address can be discovered automatically with the following procedure:

App: send a broadcast UDP message (addressed to 255.255.255.255) with a specific contents (see below)
Modem: response to this UDP message
App: read the modem-IP from the response and address all further messages directly to the modem

this message contains some configuration data and should be sent every couple of seconds to the modem.
Format of the broadcast message:

• Byte 0 … 0x3c
• Byte 1 … initial Audio volume Modem→Transceiver (0..100 %). Attention! this is only the inital value after program start. To set the volume during program run use the message No.21,22,24 and 25 as described in GUI data transfer chapter)
• Byte 2 … initial Audio volume Transceiver→Modem (0..100 %)
• Byte 3 … Timespan for voice announcements (make announcement every n transmissions, default 4)
• Byte 4 … initial Audio volume Modem→Loudspeaker (0..100 %), used for Codec-2 or Opus Codec
• Byte 5 … initial Audio volume Microphone→Modem (0..100 %), used for Codec-2 or Opus Codec
• Byte 6 … Number of retransmission of each frame (default: 1). Every single frame can be retransmitted by the modem for n times. This makes transmission time longer but increases the chance to have a good transmission. On QO-100 usually not used and should have value:1
• Byte 7 … 0 or 1: send a prerecorded PCM audio file before each announcement. This PCM file must be located in …/oscardata/intro/ and has the name intro.pcm
• Byte 8 … 0 or 1: RTTY autosync. If 1 then (in RTTY mode only) the receiver will find the RTTY signal within the passband automatically.
• Byte 9 … Transmission Speed Selection

  0: 1200 BPSK BW: 1300 Hz
  1: 2400 BPSK BW: 2500 Hz
  2: 3000 QPSK BW: 1700 Hz 
  3: 4000 QPSK BW: 2400 Hz  
  4: 4410 QPSK BW: 2500 Hz (QO-100 Standard)
  5: 4800 QPSK BW: 2700 Hz
  6: 5500 8APSK BW: 2300 Hz
  7: 6000 8APSK BW: 2500 Hz (QO-100 Transceiver)
  8: 6600 8APSK BW: 2600 Hz
  9: 7200 8APSK BW: 2700 Hz (QO-100 SDR)
 10: 45.45 Baud RTTY

• Byte 10-19 … unused
• Byte 20 - 119 … name of the selected audio playback device (modem→transceiver). May be left empty if no device is selected (i.e. after the program was started for the very first time)
• Byte 120 - 219 … name of the selected audio capture device (transceiver→modem). May be left empty if no device is selected (i.e. after the program was started for the very first time)
• Byte 220 - 239 … my callsign
• Byte 240 - 249 … my QTH locator
• Byte 250 - 269 … my name (callsign QTHloc and name are automatically transmitted by the modem at the beginning of a new file transmission)

the modem sends an UDP message to the IP of the application. If the modem receives broadcast messages from multiple applications then it prefers the local one (the app running on the same computer). This is the message format of the response to the App's broadcast message:

• Byte 0 … 0x03
• Byte 1 … 0 or 1. Status of the capture device connected to the transceiver. Can be used to show a red or green marker in the GUI
• Byte 2 … 0 or 1. Status of the playback device connected to the transceiver.
• Byte 3 … 0 or 1. Status of the capture device connected to the microphone.
• Byte 4 … 0 or 1. Status of the capture device connected to the loudspeaker.
• Byte 5 - end of frame … List of all sound cards available in the modem computer. This is an ASCII text string in the following format:

Name of a playback device - 1 followed by delimiter '~'
Name of a playback device - 2 followed by delimiter '~'
Name of a playback device - n followed by delimiter '~'
delimiter '^'
Name of a capture device - 1 followed by delimiter '~'
Name of a capture device - 2 followed by delimiter '~'
Name of a capture device - n followed by delimiter '~'

in some cases it may be required to set fixed IP adresses (i.e. if multiple hsmodems operate in the same network).

hsmodem.exe accepts a command line parameter to specify a fixed IP address of the application. If specified the modem will send messages ONLY to this IP.

usage: hsmodem -m 192.168.0.5 (or any other IP address)