wxapt User Manual

  1. Introduction
  2. Features
  3. Compilation
  4. Command line options
  5. Operation
  6. Bugs and annoyances
  7. Version history
  8. Copying

1. Introduction
wxapt is a non-interactive console application for the decoding of APT weather satellite images. Currently wxapt can decode images transmitted in the American NOAA and Russian Meteor satellite APT formats. Images are decoded either in real time, direct from an analogue receiver or a librtsdr-compatible dongle, or from a file of sound samples recorded by wxapt. Starting from version 1.6-beta, wxapt supports reception through the now very popular RTL-SDR receiver dongles, available cheaply from many sources.

2. Features
The original wxapt application was designed from the beginning to be simple and efficient, decoding images using only integer arithmetic and simple processing methods. After version 0.8 the 2.4 kHz APT sub-carrier is sampled at 48 kHz instead of 9.6 kHz, since software re-sampling in ALSA caused severe artifacts in the decoded images. This also made it necessary to change the formula used to calculate instantaneous carrier amplitude, since the phase angle between consecutive samples is no longer 90 deg. To restore this phase relationship, a ring buffer is used to store DSP samples over 1/4 period of the 2.4 kHz Sub-Carrier. For a 48kHz sampling rate, this would require a ring buffer of 5 stages. The sub-carrier amplitude is calculated by the hypotenuse of the current DSP sample and one store at the end of the ring buffer.

Sound-card set-up
If reception with a linear receiver is specified in wxaptrc config file, wxapt automatically sets up the required sound card parameters (sample format, sampling speed, mixer levels etc) for correct operation. The Capture level set up is no longer automatic in this version, because limitations in the resolution of mixer level settings and incompatibility between the period size of the PCM and wxapt's 'samples' buffer make the settings inaccurate. Audio level setting is now done manually as a one-off procedure after installation of 'wxapt', using the audio level set-up function.

RTL-SDR Dongle set-up
If reception with an RTL-SDR Dongle is specified in wxaptrc config file, wxapt automatically sets up the required RTL-SDR parameters (Center Frequency, Sampling Rate, Butterworth LPF cut-off etc) for correct operation. The Signal Level setup is not required when using the RTL-SDR dongle because this is set up permanently in the source code and should be right with most compatible dongles.

Synchronous decoding
wxapt decodes images or records the APT signal in a synchronized manner. Whether decoding images in real time or recording the APT signal, wxapt detects the sync train included in the APT format and arranges for the samples buffer, used in reading from the dsp device, to contain the sync train near its beginning. The result is that image lines are aligned quite accurately and the recorded samples are stored in a file in a line-by-line fashion. This makes decoding from files easier and faster.

Detection of the sync pulse train is done by simulating a synchronous detector, matching the waveform of the sync pulse train. In NOAA type APT signals, the sync train of Channel A is detected and used for alignment of both images. In Meteor type APT signals there is only one image and sync train. The NOAA sync train is 7 cycles at 1040 Hz with a 1/1 mark/space ratio superimposed on the 2.4 kHz sub-carrier. The Meteor sync train is 5 cycles at 1200 Hz with a 2/1 mark/space ratio. Identification of satellite type and APT format is now not done automatically, since this process is unreliable in noisy signal conditions and caused wxapt to abort if the sync train signature was not identified.

Normalization of images
wxapt performs simple (linear) histogram normalization of the APT images to enhance low contrast, especially in the channel B images of NOAA satellites. If normalization is not desired, it can be suppressed by using the -n command-line option.

Pseudo-colorization of images
wxapt can colorize the decoded gray scale images by using a simple gray-level-to-color scheme, based on a color map in the ~/wxapt/wxaptrc file. This color map is specified by a table of gray-scale range values with corresponding Red, Green and Blue ranges. The table can have a maximum of six rows of gray-to-RGB ranges which is enough for the simple scheme used by wxapt. More details on the format of this color table scheme are in the ~/wxapt/wxaptrc file itself. Only the day-time A channel image of the NOAA satellites is colorized, since the gray scale values of other images don't represent ground features nearly enough. Actually the NOAA colorized image is a hybrid of the day-time A and B channel images, with ground features rendered from the A channel and clouds from the B channel.

Rotation of images
wxapt can perform 180 degree rotation of the APT images if the -o command line option is used. This is useful for righting the inverted images produced by the South-to-North passes of the satellites.

Modes of operation
wxapt has two modes of operation: Real-time decoding of APT images directly from the audio output of a receiver via the sound card, or from streaming ADC data from an RTL-SDR Dongle, or decoding images from a file of pre-recorded samples of APT signals. In either case, wxapt produces images in raw binary (P5 type) pgm files, one for each of the two (ch A and ch B) images in NOAA APT signals and one for the single Meteor APT image. In both cases the various additions to the images (e.g. the sync train, gray scale wedges, margins etc) are removed form the images. Pseudo-colorized versions of the gray scale images are produced in raw binary (P6 type) ppm files. APT signal recording is done in straight binary format.

3. Compilation
Please note that I use Void Linux AMD64 which is a "bleeding edge" type distribution, so there may be compilation and/or run time difficulties if you are using a relatively old distro. This is mostly true of the basic dependencies and there can also be sound card incompatibility problems at run time.

To compile the package, it may be preferable to first run the included "autogen.sh" script in the package's top directory, to produce a fresh build environment. Then the "configure" script can be run with optional parameters to override the default settings and compiler flags, e.g: ./configure --prefix=/usr CFLAGS="-g -O2" will override the default /usr/local installation prefix and the "-Wall -O2" compiler flags.

Running "make" in the package's top directory should produce the executable binary in src/. Running "sudo make install" will install the binary into /usr/local/bin by default or under the specified prefix. It will also install the wxapt working directory and default configuration file into the user's home directory. This will have to be edited by the user as required. There is also this hypertext documentation file which you can copy to a location of your choice.

4. Command line options

      -a<satellite-type>: 0=NOAA-15 1=NOAA-18 2=NOAA-19 3=METEOR

      -b:<LPF-cutoff>: Specify Low Pass Filter Cutoff in Hz

      -c: Produce a pseudo-colorized image from NOAA A and B images

      -f:<tuner-frequency>: Specify Tuner Center Frequency in Hz

      -s<start-time[-<stop-time>]>: Time (UTC) in format hh:mm at which
       to start and optionally to stop APT recording or processing
      
      -t<duration>: Duration of APT recording or processing. If duration
       is >= 60, it is taken as seconds, else as minutes

      -i<file>: Specify image file name. If this option is not used,
        use date and time as file name: ddMonyy-hhmm<extension>

      -p<file>: Process images from samples recorded in <file>

      -r[<file>]: Only record APT signal in <file>. If no file name is
       specified, use date and time as file name: ddMonyy-hhmm.bin

      -R[<file>]: Record APT signal in <file> and process images
       If no file is specified, files will be named as above

      -l: Start in audio input-level setup mode

      -n: Suppress histogram normalization of images

      -o: Rotate images by 180 degrees

      -v: Print version number and exit
    
      -h: Print this usage information and exit

5. Operation
Setting up working directories:
Before wxapt is used to receive images, it is important to understand how the resulting image files are named and saved. In normal usage, wxapt will be allowed to generate default file names and store image and recorded APT files in its default directories. The image and recorded audio file names are created from a base string of the format ddMonyyyy-hhmm where dd is the day number, Mon is the month name, yyyy is the year and hhmm the current time (UTC) in hours and minutes. To this, the satellite type, image channel (for NOAA) and the extension .pgm for images and .bin for recorded audio are appended, to form the file name. This is then pre-pended with images/ for image or record/ for recorded audio files so that they are saved in <working-directory>/images/ or <working-directory>/record/ respectively. <working-directory> is "wxapt/" in the user's home directory.

Before running wxapt, it may be necessary to customize some entries in the wxapt/wxaptrc configuration text file in your home directory. These are the items that will need editing:

The color-mapping tables may also need editing to get realistic colors (this is especially true for the green color) but this is not easy. Its best done by waiting for clear and dry weather, and then using an application like the Gimp to measure the gray scale values in various regions of the image. By comparing the image with a color map (like satellite images in Google Maps (tm)) the gray level ranges corresponding to water bodies, forested areas, land, desert etc can be identified and entered in the color tables in ~/wxapt/wxaptrc.

Stereo mode (e.g. specifying a "channel" name other than MONO) allows the computer's sound card to be connected to two audio sources, without the need to move plugs or switch audio. In my case this allows me to feed audio from my ham radio receiver and a weather satellite receiver to the sound card separately.

Audio level set-up: Weather satellites transmitting images in the APT format transmit in the 137 MHz band with medium-bandwidth (~40 kHz) FM modulation. The VHF carrier is modulated with a 2.4 kHz sub-carrier which in turn carries the image and related signals (sync train, Gray-scale wedge etc) as AM modulation. Considering the Doppler shift (~3 kHz) and possible errors in the receiver local oscillator(s) the recommended IF bandwidth for VHF APT reception is 50 kHz. Unfortunately few of the available popular receivers (scanners) have such a facility, so reception requires either a modification to the receiver or the use of wide-band FM modes. This results in a lot of interference (in my region at least) and more noise, resulting in poor image quality. However there are reasonably priced dedicated satellite receivers which can be used with excellent results (I use a Hamtronics R139).

Before wxapt is used to decode images or record samples with an analogue receiver, the sound card's recording source input, (usually "Line"), must be connected with the VHF receiver's o/p. The connection must be done with a suitable (normally 3.5 mm) stereo jack plug with either the left or right channel connected to the receiver's o/p if in stereo mode, or if in mono mode usually the left channel input should be used. Then the receiver's audio o/p level must be adjusted manually to the correct level as follows:

Run wxapt with the -l option and while a clear and strong signal is being received from a NOAA-type satellite, adjust the volume control of the receiver so that the print-out of the maximum signal level is not more than suggested, e.g.
Signal Level: 31234 (Maximum 32000).

To receive images with an RTL-SDR Dongle, it is only necessary to plug the dongle into a USB2 port and connect the antenna to it. Software wise, it is necessary to install librtlsdr which is nowadays available in most Linux distros. This depends on libusb but this is also usually installed by default in most distros.

Direct real-time decoding:
1. Specify the required satellite type using the -a option, e.g. wxapt -a>n< where n: 0 = NOAA-15, 1 = NOAA-18, 2 = NOAA-19 and 3 = Meteor. If using an rtlsdr dongle, specify the satellite's frequency using the -f option:
wxapt -a2 -f137100000 for NOAA-19.

2. Use the -c option to specify pseudo-colorization based on NOAA Ch.A and Ch.B images and the -o option to flip (rotate images 180) for South to North passages. Histogram normalization of image luminosity is on by default but it can be canceled using the -n option.

3. If required, set either the duration (in minutes) of the decoding operation with the -t option, or the start and stop times of decoding using the -s option so:
wxapt -a2 -f137100000 -c -o -t6 or wxapt -a2 -f137100000 -c -o -s12:40-12:46. Otherwise the default time-out of 10 min will apply to the operation.

4. When the decoding process is started, wxapt will first synchronize the dsp buffer with the APT sync train and then start decoding the APT image(s) line by line. The decoding operation will either stop when it times out (as set up in step 3), or if needed it can be stopped by User Interrupt (Ctl+C). This will also cause wxapt to save image files to disk.

Recording APT signals to disk:
The process of recording APT signals to a file on disk is very similar to direct decoding of images as above. The main difference is that options affecting image processing have no effect. The recording is done in a raw binary format (8 bits/sample at a sampling rate of 48000 s/sec) and without any compression of data so a recorded file can be quite large. This facility is really only useful for debugging and testing:
wxapt -a2 -f137100000 -r -t6 will record samples from NOAA-19 for 6 min into a file in ~/wxapt/record/ using a default file name by date and time.
wxapt -a2 -f137100000 -R test-file -t6 will do as above but after recording samples in "~/wxapt/record/test-file", wxapt will also decode the images contained in the saved file.

Decoding from a recorded APT signal:
This is done by using the -p option with the pre-recorded file name specified. Decoded image file names will have the same base string of the recorded file but with the appropriate satellite type and file extension appended. PLEASE NOTE that only files recorded by wxapt can be processed!

6. Bugs and annoyances
I have fixed whatever bugs I came across testing wxapt but there may be some hiding, waiting for the right conditions to appear. There is a little geometric distortion since an integer number of carrier samples must be summed in each pixel, but for a simple and efficient application, image quality is quite good at least as far as meteorological uses go.

The hardest job wxapt has to do is detecting the sync train included in APT transmissions. Although under good receiving conditions this seems to work very well, when there is some noise in the signal sync detection fails. However, under such conditions wxapt continues by 'dead reckoning' the sync train position so short-lived noise will not throw wxapt out of sync permanently.

7. Version history
Version 0.1 was a simple un-synchronized test bed for learning about APT decoding and was not released.

Version 0.2 was a much better synchronized decoder and recorder but only for the NOAA type APT format and was not released.

Version 0.3-beta is the first beta release of wxapt incorporating code for the Meteor type APT format and many refinements in sync detection and file naming.

Version 0.4-beta incorporates linear histogram normalization of the APT images produced, on by default but suppressible with the -n option, and 180 degree rotation of the APT images with the -o option.
A fix for an 'off-by-one' bug in a strcpy() statement, which could affect the auto sound-card mixer level setup, is also incorporated.

Version 0.5-beta incorporates an additional command line option, -s<start-time>[-<stop-time>] which allows automatic starting and/or stopping of wxapt at the time(s) specified.
Processing of the -t<duration> option has been modified so that if duration is >= 60, it is taken as seconds, else as minutes.
Auto-detection of the recording level device has also been incorporated to avoid incompatibilities between different distributions regarding ioctl() request codes for setting recording levels.
A bug in an ioctl() call for setting the recording level has been fixed.

Version 0.6 beta has improved sync train detection reliability and stability and a fix for a bug that caused wxapt to abort with an error message after saving Meteor file images although there was no error.

Version 0.7 beta has an improved automatic recording/capture level setup process which takes into account the block size of the DSP which varies for different sound cards and drivers. This allows a useful increase of the pixel value range for an improved contrast.

Version 0.8 Added the ability to work in either stereo or mono mode so that more than one audio sources can be connected to the sound card without switching or removing plugs.

Version 0.9 Minor bug fixes and adjustment of image parameters to accommodate NOAA-17's apparently brighter images.

Version 1.0 After testing locally and receiving reports of successful operation by other users, this is the first release candidate version of wxapt. In this version automatic recording level setup and auto satellite-type recognition have been discarded mainly because of some unreliability in noisy signal conditions. Audio input level is set up once manually using the -l option and satellite type is specified with the -a command line option.

Version 1.1 In this version the margins of detection of the Meteor type sync train have been widened to allow easier synchronization of the dsp buffer with the APT signal.
The file format of the recorded APT signal has been changed so that the 'satellite type number' is written as a 32 bit 'int' rather than an 8 bit 'char' so that its much less likely for a non wxapt- recorded file to be accepted for decoding.
The audio level set-up function has been modified slightly and as a result the level indication when running 'wxapt -l' tends to wonder up-down more than previously. This is not a problem if the audio level adjustment is done so that successive indications are centered around the '0' mark.

Version 1.2 Modified the sync train detection method so that the error in the dsp's sampling frequency is also measured. This error must be compensated to allow the sync detector to maintain lock during image decoding.

Version 1.3 After a bug report from Juha Vierinen regarding seg faulting of xnec2c, my graphical adaptation of NEC2, I changed all "sprintf" commands to "snprintf" to avoid buffer overruns. Following on the above changes, I revised all similar situations in wxapt source code and changed all "sprintf" commands to "snprintf" just in case. While going through the wxapt source code, I also fixed some minor bugs like typos and tidied error messages.

Version 1.4: Changed the source file tree to make it more like the correct arrangement commonly used nowadays. Change the sound card functions from the OSS API to the ALSA API as OSS is no longer fully supported.

Version 1.5: Made changes to the source code to silence many warnings that were issued by the LLVM clang compiler, when used with the -Weverything option. Changed the method of compilation to the established GNU Autotools way, by providing the various files needed (Makefile.am, configure.ac etc) to setup the build environment and to compile wxapt.

Version 1.6: Major changes introduced here, basically wxapt has been re-created from xwxapt by stripping out the Graphical User Interface and making the application non-interactive. A lot of things had to change, with the introduction of compatibility with librtlsdr dongles being the most important. Now wxapt is on par with xwxapt!

Version 1.7: I have fixed a bug in the calculation of phase changes in the FM Detector that demodulates the subcarrier.

Version 1.7.1: Correction! - the above fix apparently was not quite right so I changed the code again to compensate.

8. Copying This software package is released under the GNU Public License. Please see the COPYING file for more details.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details

Last modified: Wed Sep 7 13:35 EET 2016