📡 xrit-rx - LRIT/HRIT Downlink Processor

xrit-rx is a packet demultiplexer and file processor for receiving images from geostationary weather satellite GEO-KOMPSAT-2A (GK-2A). It is designed for use with goesrecv (originally by Pieter Noordhuis), or xritdecoder by Lucas Teske.

xrit-rx receives Virtual Channel Data Units (VCDUs) over the network from either goesrecv or xritdecoder and demultiplexes them into separate virtual channels, each containing a different type of image data. The demultiplexed packets are assembled into complete files which are output as images such as the ones below.

Getting Started

A guide for setting up the hardware and software components of a GK-2A LRIT receiver is available on my site. It also covers the types of images that can be received, image post-processing techniques and data decryption.

The RTL-SDR Blog has also written a guide for setting up the hardware and software required to receive imagery from GOES-16/17 and GK-2A. Once you are able to receive the GK-2A LRIT downlink with goesrecv, you can begin installing and configuring xrit-rx.

Installing xrit-rx

Download the latest version of xrit-rx (xrit-rx.zip) from the Releases page, then unzip the contents to a new folder.

numpy, pillow, colorama and pycryptodome are required to run xrit-rx. Use the following command to download and install these packages:

pip3 install -r requirements.txt

Images downlinked from GK-2A are encrypted by the Korean Meteorological Administration (KMA). Decryption keys can be downloaded from KMA's website and used with xrit-rx. More information is available in the setup guide.

Configuring xrit-rx

All user-configurable options are found in the xrit-rx.ini file. The default configuration will work for most situations.

If xrit-rx is not running on the same device as goesrecv / xritdecoder, the ip option will need to be updated with the IP address of the device running goesrecv / xritdecoder.

List of options

`rx` section

Setting	Description	Options	Default
`spacecraft`	Name of spacecraft being received	`GK-2A`	`GK-2A`
`mode`	Type of downlink being received	`lrit` or `hrit`	`lrit`
`input`	Input source	`goesrecv` or `osp`	`goesrecv`
`keys`	Path to decryption key file	Absolute or relative file path	`EncryptionKeyMessage.bin`

`output` section

Setting	Description	Options	Default
`path`	Root output path for received files	Absolute or relative file path	`"received"`
`images`	Enable/Disable saving Image files to disk	`true` or `false`	`true`
`xrit`	Enable/Disable saving xRIT files to disk	`true` or `false`	`false`
`channel_blacklist`	List of virtual channels to ignore Can be multiple channels (e.g. `4,5`)	`0: Full Disk` `4: Alpha-numeric Text` `5: Additional Data`	none

`goesrecv` section

Setting	Description	Options	Default
`ip`	IP Address of a device running goesrecv	Any IPv4 address	`127.0.0.1`
`vchan`	Output port of goesrecv	Any TCP port number	`5004`

`osp` section

Setting	Description	Options	Default
`ip`	IP Address of a device running Open Satellite Project xritdecoder	Any IPv4 address	`127.0.0.1`
`vchan`	Output port of Open Satellite Project xritdecoder	Any TCP port number	`5001`

`udp` section

Setting	Description	Options	Default
`ip`	IP Address to bind UDP socket to	Any IPv4 address	`127.0.0.1`
`vchan`	Port number to bind UDP socket to	Any UDP port number	`5002`

`dashboard` section

Setting	Description	Options	Default
`enabled`	Enable/Disable dashboard server	`true` or `false`	`true`
`port`	Port number for server to listen on	Any TCP port number	`1692`
`interval`	Update interval in seconds	`integer`	`1`

Dashboard

xrit-rx includes a web-based dashboard for easy monitoring and viewing of received data. The current GK-2A LRIT schedule is also displayed on the dashboard (retrieved from KMA NMSC).

By default the dashboard is enabled and accessible on port 1692 via HTTP (no HTTPS). These settings can be changed in the [dashboard] section of xrit-rx.ini.

HTTP API

xrit-rx has a basic API accessible via HTTP primarily to support its web-based monitoring dashboard. This may be useful for integrating xrit-rx with other applications.

The API only supports GET requests and will return either a 200 OK or 404 Not Found status. The root endpoint is located at /api which returns information about the current xrit-rx configuration (example below).

{
  "version": 1.1,
  "spacecraft": "GK-2A",
  "downlink": "LRIT",
  "vcid_blacklist": [
    4,
    5
  ],
  "output_path": "received/LRIT/",
  "images": true,
  "xrit": false,
  "interval": 1
}

The API also supports a special dynamic endpoint for retrieving image files over a network. This endpoint uses the start of the relative decoder output path found in the configuration object at the API root endpoint (/api).

For example, if output_path is "received/LRIT" the endpoint will be /api/received/LRIT. From there the URL follows the folder structure created by xrit-rx for saving received images (e.g. /api/received/LRIT/20190722/FD/IMG_FD_047_IR105_20190722_075006.jpg). The API does not currently support directory listing.

List of Endpoints

URL	Description	Example	MIME
`/api`	General configuration information	see above	`application/json`
`/api/current/vcid`	Currently active virtual channel number	`{ "vcid": 63 }`	`application/json`
`/api/latest/image`	Path to most recently received product	`{ "image": "received/LRIT/[...].jpg" }`	`application/json`
`/api/latest/xrit`	Path to most recently received xRIT file	`{ "xrit": "received/LRIT/[...].lrit" }`	`application/json`

Acknowledgments

Lucas Teske - Developer of Open Satellite Project and writer of "GOES Satellite Hunt"
Pieter Noordhuis - Developer of goestools
John Bell - Software testing and IQ recordings
"kisaa" - GK-2A HRIT debugging and packet recordings
@Rasiel_J - IQ recordings

libjpeg

xrit-rx uses libjpeg for converting JPEG2000 (J2K/JP2) images to Portable Pixmap Format (PPM) images. A compiled 32-bit binary for Windows is included in xrit-rx releases along with the libjpeg LICENSE (GPLv3) and README.

The source code for libjpeg can be found at https://github.com/thorfdbg/libjpeg.

Lawrence-Link/xrit-rx