Files and Images

Some satellites transmit files, such as JPEG images or spectrum measurements, split into many small telemetry packets. gr-satellites can reassemble these files while you receive them and, for images, display them in real time as the data arrives. This page explains which satellites support this, the options involved, how files are named and stored, and the behaviors to watch out for.

Supported Satellites

Satellite Kind Receiver definition
1KUNS-PF JPEG images sat_1kuns_pf
BY70-1 JPEG images by70_1
LilacSat-1 JPEG images by70_1
CAS-5A Images cas5a_new
D-SAT JPEG images dsat
Lucky-7 Images lucky7
Swiatowid Images swiatowid
SMOG-P RF spectrum data smogp
ATL-1 RF spectrum data smogp
SMOG-1 RF spectrum data smog1
MIR-SAT1 Files mirsat1

These come from the files: and image: entries in the SatYAML files (see SatYAML Format). Reception is enabled by default: there is nothing to switch on.

Options

Option Default Effect
--file_output_path DIR . (the current directory) Directory where received files are written.
--verbose_file_receiver off Print the receiver's progress: new files, sequence numbers, completion, errors.

These options only exist for satellites that have a file or image receiver.

mkdir -p ~/lilacsat1_images
gr_satellites LilacSat-1 --wavfile lilacsat1.wav \
    --file_output_path ~/lilacsat1_images --verbose_file_receiver

Note: The upstream documentation states that files are stored in /tmp/ by default. In the current code the default is the current working directory ('.').

How Reassembly Works

Each receiver definition is a small class that knows the satellite's chunk format. For every packet it extracts:

  • a file ID (if the protocol has one),
  • a sequence number or a byte offset,
  • the data in the chunk,
  • optionally the total size or number of chunks.

The generic logic then:

  1. Picks the file. If the chunk has no file ID, it uses the file currently being received; a sequence number lower than expected starts a new file. If there is no current file, a counter (0, 1, 2, ...) is used.
  2. Writes the data at the computed offset, so chunks with offsets can arrive out of order.
  3. When only sequence numbers are available, requires them to be consecutive. A gap marks the file as broken: later chunks of that file are ignored and the verbose log says File reception is broken.
  4. Marks the file complete when it reaches its declared size or chunk count, or when the protocol signals the last chunk.

Verbose messages look like this (prefixed with FileReceiver: or ImageReceiver:):

ImageReceiver: new file 0
ImageReceiver: received sequence 0 for file 0
ImageReceiver: received sequence 1 for file 0
...
ImageReceiver: file 0 complete

File Names

The name of each file comes from the receiver definition:

  • Image receivers default to <file id>.jpg, for example 0.jpg or 1.jpg.
  • The SMOG-P/ATL-1/SMOG-1 spectrum receivers use names built from the measurement metadata, such as spectrum_start_824000000_step_24000_rbw_6_measid_312. The smog_p_spectrum utility plots these files.

If a definition ever produces a name with directory components, gr-satellites replaces it with a random UUID and logs filename ... contains path components; replacing by ..., so files cannot be written outside the output directory.

Warning: Existing files are opened for update (r+b), not truncated. If you run the decoder twice with the same output directory, a new image 0.jpg is written over the old 0.jpg, and if the new image is shorter, the tail of the old one remains. Use a fresh --file_output_path per session, or delete old files first.

Real-Time Image Display

For image: receivers, gr-satellites launches the feh image viewer as soon as 640 bytes of an image have been written. feh is started:

  • in fullscreen mode (-F),
  • with automatic reload every second (-R 1), so the picture fills in as chunks arrive.

One feh window is opened per image. If feh is not installed, the tool prints Unable to open feh image viewer and the error, and continues receiving; the image is still saved. Install feh with your distribution's package manager. To avoid fullscreen windows, use the Image Receiver block in GNU Radio Companion, which has Display and Fullscreen parameters (see Data Sink Blocks).

Interaction with Other Options

  • --hexdump keeps file receivers that are fed directly by a transmitter, but disables those fed through a transport. LilacSat-1 and BY70-1 images arrive through a KISS transport, so --hexdump stops their reassembly.
  • With --kiss_in, frames go straight to the data sinks without transports. For satellites whose images come through a transport, a KISS file written by --kiss_out (which stores deframer output) cannot be used to reassemble images.

See Also