📡 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.txtImages 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 Disk4: Alpha-numeric Text5: 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.
