#README
##COMPATIBLE PLATFORMS
Windows
Linux
##INSTALL
On Windows or Linux, the following command will install the python package:
pip3 install swampsat2
On Linux systems, the sudo priviledge can be circumvented with the follow command which downloads the package to the local user path by default $HOME/.local/bin/*
:
pip3 install --user swampsat2
If pip
is not installed on your system it can be installed with one of the following approaches:
Windows:
pip
is often packaged with python on Windows and a standard installation of python will include pip
Linux:
Run the following command on linux to install pip
:
sudo apt-get install python3-pip
##NOTES
The SwampSat II beacon parser utility is implemented in Python and can be called from command-line. The input/data, whether a string or file containing strings, must be in HEX
HEX String Formatting
-
All whitespace is ignored
-
Parsing is case insensitive
-
Strings must contain only HEX characters [0-9, A-F]
-
The header containing the callsigns should not be included in the string
-
Strings are identified by number of bytes included; valid lengths are {163, 185, and 46} bytes
Example strings
12 00 94 03 02 00 7B 03 02 00 93 03 26 00 5B 03 19 00 05 03 09 03 0F 03 12 00 17 00 28 00 02 00 03 00 02 00 03 00 02 00 5B 03 02 00 02 00 03 00 05 03 06 00 05 03 0E 00 04 03 1D 00 27 02 4D 02 29 01 05 00 39 02 81 02 3F 01 1C 00 74 00 27 02 6A 02 18 02 02 00 0F 00 51 01 01 00 05 00 18 01 09 00 57 00 00 40 82 00 77 00 84 00 00 00 3C 00 3C 00 D3 00 FF 03 1B 80 06 03 FF 03 E3 02 E8 02 EA 02 01 00 01 00 11 00 03 9F 06 0E 0C 02 D6 01 FE 00 0F DE 46 06 00 3A 03 E8 04 74 01 61 01 3E 02 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
OR
1400940302007C03 030093031D005B03 190005030B031103 1200170028000300 0300020003000300 5B03020002000300 0403060004030E00 04031C0027024B02 36011A003D027802 41012D004C002202 7E02110202000400 1C0115001E001701 1900140000408200 7700840000003C00 3C00D300FF031480 0603FF03E502EA02 EA02010001001100 033D050F0D02D601 FE000FAF4600003A 03E804740160012F 0200000000000000 0000000000000000 0000000000000000 00
##USAGE: COMMAND-LINE
Usage:
swampsat2 [-i] [-l LOGFILE] [-t FILETYPE] [-d DELIMITER] [-f FILE]
swampsat2 [-i] [-l LOGFILE] [-t FILETYPE] [-d DELIMITER] [-s HEXSTRING]
Parse SwampSat II beacons from either a file or command-line string
Options:
-f FILE, --file=FILE input file containing hex strings from a SwampSat II beacon
-s HEXSTRING, --hexstring=HEXSTRING hex string from a SwampSat II beacon
-l LOGFILE, --logfile=LOGFILE file where parsed data will be saved [default: [$HOME]/ss2logs/ss2beacon_parsed_[$TIMESTAMP].json]
-t FILETYPE, --filetype=FILETYPE file type of input file (default behavior is to read the file extension, valid extensions are: '.txt', '.log', '.hex', '.kss')
-i, --image flag to read data as jpg image (log name remains the same as default but a .jpg file extension is added)
-d DELIMITER, --delimiter=DELIMITER delimiter for input HEX string (whitespace is automatically removed)
-h --help prints this help message
--version prints current version
Options Flag FILETYPE
:
The FILETYPE
option let's you provide the file type the parser should expect
The parser can accept either .log
, .txt
, .hex
, or .kss
files (.log
, .txt
, and `.hex are treated the same)
The default behavior is to read the file type from the file path; thus this flag should usually not be necessary
Examples of acceptable files can be found on GitHub: github.com/ralent/swampsat2
Note This parser only accepts the TEXT representation of the .kiss
log, not the raw .kss output (file examples on GitHub)
Options Flag image
:
You should use this flag if you expect your file to have image data (JPG); this flag will try to parse an image from the data in the file
The default log path remains the same except that the file is saved with a .jpg
extension
Options Flag DELIMITER
:
Whitespace is ignored in any HEX strings so there is no need to specify a whitespace delimiter
If there are additional delimiters, such as a comma, then they can be specified using the delimiter flag (example for comma delimiting: -d ','
)
Options Flag LOGFILE
:
Specifying a LOGFILE
path will ignore the following default behaviors except for placeholder substitutions
-
Default
LOGFILE
path when used withFILE
flag[FILE_PATH]/ss2logs/[FILE_NAME]_parsed.json
-
Default
LOGFILE
path when used withHEXSTRING
flag[$HOME]/ss2logs/ss2beacon_parsed_[$TIMESTAMP].json
-
Default filename when
LOGFILE
is a directory[LOGFILE]/ss2beacon_parsed_[$TIMESTAMP].json
Regardless of the above default behavior, the following placeholders will always be substituted for the following values:
- The placeholder
[$HOME]
is substuted with the home directory adjusted for the current OS and User - The placeholder
[$TIMESTAMP]
is substuted with the current datetime in the following format:%Y-%m-%d_%H-%M-%S
Example parsing data with HEX string (Windows and Linux respectively):
swampsat2 -s " 1400940302007C03 030093031D005B03 190005030B031103 1200170028000300 0300020003000300 5B03020002000300 0403060004030E00 04031C0027024B02 36011A003D027802 41012D004C002202 7E02110202000400 1C0115001E001701 1900140000408200 7700840000003C00 3C00D300FF031480 0603FF03E502EA02 EA02010001001100 033D050F0D02D601 FE000FAF4600003A 03E804740160012F 0200000000000000 0000000000000000 0000000000000000 00"
swampsat2 -s ' 1400940302007C03 030093031D005B03 190005030B031103 1200170028000300 0300020003000300 5B03020002000300 0403060004030E00 04031C0027024B02 36011A003D027802 41012D004C002202 7E02110202000400 1C0115001E001701 1900140000408200 7700840000003C00 3C00D300FF031480 0603FF03E502EA02 EA02010001001100 033D050F0D02D601 FE000FAF4600003A 03E804740160012F 0200000000000000 0000000000000000 0000000000000000 00'
Example parsing data from file (Windows and Linux respectively):
swampsat2 -f "<filepath>/beacondata.txt"
swampsat2 -f '<filepath>/beacondata.txt'
Example parsing data from file and specifying a log file path (Windows and Linux respectively):
swampsat2 -l "ss2logs/ss2beacon_parsed_.json" -f "<filepath>/beacondata.txt"
swampsat2 -l 'ss2logs/ss2beacon_parsed_.json' -f '<filepath>/beacondata.txt'