grape-utils.sh

#!/bin/bash

###  grape_utils.sh:  wakes up at every UTC 00:05, creates and uploads Digial RF files of the last 24 hours of WWV IQ recordings

###    Copyright (C) 2024  Robert S. Robinett
###
###    This program is free software: you can redistribute it and/or modify
###    it under the terms of the GNU General Public License as published by
###    the Free Software Foundation, either version 3 of the License, or
###    (at your option) any later version.
###
###    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.
###
###    You should have received a copy of the GNU General Public License
###    along with this program.  If not, see <https://www.gnu.org/licenses/>.

function wd_merge_file_trees()
{
    local SRC_ROOT="${1}"
    local DST_ROOT="${2}"
    local src_dev=$(df --output=source "$SRC_ROOT" | tail -1)
    local dst_dev=$(df --output=source "$DST_ROOT" | tail -1)

    # set -x
    if [[ "$src_dev" == "$dst_dev" ]]; then
        wd_logger 2 "'mv'ing files from  '$SRC_ROOT' to  '$DST_ROOT'..."
        find "$SRC_ROOT" -type f | while read -r src_file; do
            rel_path="${src_file#$SRC_ROOT/}"
            dst_file="$DST_ROOT/$rel_path"
            mkdir -p "$(dirname "$dst_file")"
            mv "$src_file" "$dst_file"
        done
    else
        # return
        wd_logger 1 "'rsync'ing  files from  '$SRC_ROOT' to  '$DST_ROOT'..."
        rsync -a --info=progress2 --remove-source-files "$SRC_ROOT"/ "$DST_ROOT"/
    fi
    wd_logger 2 "Merging files into '$DST_ROOT' is complete, so 'rm -r $SRC_ROOT'"
    rm -r "$SRC_ROOT"
}


declare    GRAPE_ARCHIVE_PRESERVE_DATES_LIST=( ${GRAPE_ARCHIVE_PRESERVE_DATES_LIST[@]-20240407 20240408 20240409} )    ### Preserve the .wv files for the April 8th 2024 total eclipse +- 1 day
declare -r GRAPE_TMP_DIR="/run/wsprdaemon/grape_drf_cache"                                                          ### While creating a 24 hour 10 Hz IQ wav file, decompress the 1440 one minute wav files into this tmpfs file system
declare -r GRAPE_WAV_ARCHIVE_ROOT_PATH="${WSPRDAEMON_ROOT_DIR}/wav-archive"                                          ### Cache all 1440 one minute long, wavpack-compressed, 16000 IQ wav files in this dir tree
mkdir -p ${GRAPE_WAV_ARCHIVE_ROOT_PATH}
declare -r LEGACY_GRAPE_WAV_ARCHIVE_ROOT_PATH="${WSPRDAEMON_ROOT_DIR}/wav-archive.d"                                          ### Cache all 1440 one minute long, wavpack-compressed, 16000 IQ wav files in this dir tree
if [[ -d ${LEGACY_GRAPE_WAV_ARCHIVE_ROOT_PATH} ]]; then
    wd_logger 2 "Transferring the legacy files from ${LEGACY_GRAPE_WAV_ARCHIVE_ROOT_PATH} into ${GRAPE_WAV_ARCHIVE_ROOT_PATH}"
    wd_merge_file_trees ${LEGACY_GRAPE_WAV_ARCHIVE_ROOT_PATH} ${GRAPE_WAV_ARCHIVE_ROOT_PATH}
else
    wd_logger 2 "There is no legacy file tree '${LEGACY_GRAPE_WAV_ARCHIVE_ROOT_PATH}', so nothing to clean up"
fi

declare -r WD_SILENT_WV_FILE_PATH="${WSPRDAEMON_ROOT_DIR}/one-minute-silent-float.wv"                                  ### A wavpack-compressed wav file of one minute of silence.  When a minute file is missing  soft link to this file
declare -r MINUTES_PER_DAY=$(( 60 * 24 ))
declare -r HOURS_LIST=( $(seq -f "%02g" 0 23) )
declare -r MINUTES_LIST=( $(seq -f "%02g" 0 59) )
declare -r GRAPE_24_HOUR_10_HZ_WAV_FILE_NAME="24_hour_10sps_iq.wav"

### GRAPE carrier strip charts (WD 3.4.6+).  Each time a 24_hour_10sps_iq.wav is created, a PNG strip chart (a Doppler spectrogram of
### the channel with the carrier of each path the station arrives over tracked on it, plus carrier power and SNR, vs UTC and local
### time) and a JSON copy of the series are written under ~/wsprdaemon/grape-charts/www/...
### A tiny web server (python3 -m http.server) publishes that directory so the station owner can browse and overlay the charts.
declare    GRAPE_CHARTS_ENABLED=${GRAPE_CHARTS_ENABLED-yes}                ### Set to "no" in WD.conf to disable chart creation and the web server
declare    GRAPE_CHARTS_PORT=${GRAPE_CHARTS_PORT-8088}                     ### TCP port of the chart web server
declare    GRAPE_CHARTS_BIND=${GRAPE_CHARTS_BIND-0.0.0.0}                  ### Set to 127.0.0.1 to make the charts reachable only through an ssh tunnel
declare    GRAPE_CHARTS_TZ=${GRAPE_CHARTS_TZ-}                             ### IANA zone (e.g. "America/Los_Angeles") for the charts' local-time axis on a server whose clock runs on UTC.
                                                                            ### Search order: the server's zone if it isn't UTC, then this variable, then the zone at the reporter's grid
declare -r GRAPE_CHARTS_ROOT_DIR="${WSPRDAEMON_ROOT_DIR}/grape-charts"      ### Home dir of the web daemon (logs and pid) ...
declare -r GRAPE_CHARTS_WWW_DIR="${GRAPE_CHARTS_ROOT_DIR}/www"              ### ... and the directory it serves: index.html, manifest.json, <DATE>/<REPORTER>/<RECEIVER>/<BAND>.{png,json}
declare -r GRAPE_CHART_PYTHON_CMD="${WSPRDAEMON_ROOT_DIR}/grape-strip-chart.py"
declare -r GRAPE_CHARTS_MANIFEST_PYTHON_CMD="${WSPRDAEMON_ROOT_DIR}/grape-charts-manifest.py"
declare -r GRAPE_CHARTS_INDEX_HTML_SRC="${WSPRDAEMON_ROOT_DIR}/grape-charts-index.html"
declare -r GRAPE_24_HOUR_10_HZ_WAV_STATS_FILE_NAME="24_hour_10sps_iq.stats"

### Return codes can only be in the range 0-255.  So we reserve a few of those codes for the following routines to commmunicate errors back to grape calling functions
declare -r          GRAPE_ERROR_RETURN_BASE=240
declare -r        GRAPE_ERROR_RETURN_NO_WVS=$(( ${GRAPE_ERROR_RETURN_BASE} + 0 ))
declare -r          GRAPE_ERROR_RETURN_BAND=$(( ${GRAPE_ERROR_RETURN_BASE} + 1 ))
declare -r        GRAPE_ERROR_REPAIR_FAILED=$(( ${GRAPE_ERROR_RETURN_BASE} + 2 ))
declare -r            GRAPE_ERROR_WV_FAILED=$(( ${GRAPE_ERROR_RETURN_BASE} + 3 ))
declare -r           GRAPE_ERROR_SOX_FAILED=$(( ${GRAPE_ERROR_RETURN_BASE} + 4 ))
declare -r GRAPE_ERROR_RETURN_REPAIR_FAILED=$(( ${GRAPE_ERROR_RETURN_BASE} + 5 ))
declare -r           GRAPE_ERROR_RETURN_MAX=$(( ${GRAPE_ERROR_RETURN_BASE} + 10 ))

function grape_return_code_is_error() {
    if [[ $1 -ge  ${GRAPE_ERROR_RETURN_BASE} && $1 -le  ${GRAPE_ERROR_RETURN_MAX} ]]; then
        return 0
    fi
    return 1
}

######### The functions which implement this service daemon follow this line ###############

# upload_24hour_wavs_to_grape_drf_server() is derived from Franco's grape.sh
# go from wav files to Grape:
# - convert from wav to Digital RF dataset
# - upload Digital RF dataset directory to PSWS network
#
# Franco Venturi - K4VZ - Mon 22 Jan 2024 01:20:14 PM UTC
# Rob Robinett - AI6VN - Mon Jan 30 2024 modified to be part of a Wsprdaemon client

#set -euo pipefail

declare -r PSWS_SERVER_URL='pswsnetwork.eng.ua.edu'
declare -r UPLOAD_TO_PSWS_SERVER_COMPLETED_FILE_NAME='pswsnetwork_upload_completed'
### Written beside the 'completed' marker when a day can NEVER be uploaded, so that it is not retried for
### ever.  Only for a failure which cannot improve by itself: a band whose 24 hour wav is short AND whose
### .wv source files have already been purged, so nothing is left to rebuild it from.  A transient failure
### -- PSWS down, network out, sftp refused -- writes no marker and is retried on the next pass as before.
declare -r UPLOAD_TO_PSWS_SERVER_IMPOSSIBLE_FILE_NAME='pswsnetwork_upload_impossible'
### A full day of the 10 sps IQ wav is a fixed size: MINUTES_PER_DAY * 60 s * 10 sps * 2 channels * 4 bytes
declare -r GRAPE_24_HOUR_WAV_SAMPLE_BYTES=$(( MINUTES_PER_DAY * 60 * 10 * 2 * 4 ))
declare -r WAV2GRAPE_PYTHON_CMD="${WSPRDAEMON_ROOT_DIR}/wav2grape.py"

### '-u ' sub menu
function grape_upload_all_local_wavs() {
   wd_logger 2 "Upload wav files not yet uploaded to the GRAPE server"

    local date_dir_list=( $( find -L ${GRAPE_WAV_ARCHIVE_ROOT_PATH} -mindepth 1 -maxdepth 1 -type d -name '20??????' | sort ) )   ## Follow symbolic link to /mnt/wd-archive/...
    local date_dir
    for date_dir in ${date_dir_list[@]} ; do
        wd_logger 2 "Checking date_dir ${date_dir}"
        local site_dir_list=( $( find -L ${date_dir} -mindepth 1 -maxdepth 1 -type d  | sort) )
        local site_dir
        for site_dir in ${site_dir_list[@]} ; do
            wd_logger 2 "Checking site_dir ${site_dir}"
            upload_24hour_wavs_to_grape_drf_server ${site_dir}
: <<'TBD'
            wd_logger 2 "Checking site_dir ${site_dir} for NOT DEFINED"
            if [[ "$site_dir" == "*$search_txt*" ]]; then
                wd_logger 2 "Skipping ${site_dir} with NOT_DEFINED"
                new_dir=${site_dir/NOT_DEFINED/${GRAPE_PSWS_ID}}
                ### what we need to do:
                # test for new_dir existing.  If not, rename site_dir to new_dir
                # OTHERWISE, for each folder in site_dir, copy its contents to the same dir in new_dir
                wd_logger 1 "would create ${new_dir}"
            else
                wd_logger 2 "Checking site_dir ${site_dir}"
                upload_24hour_wavs_to_grape_drf_server ${site_dir}
            fi
TBD
        done
    done
    wd_logger 2 "Completed"
}

### Given: the path to the .../wav-archive/<DATE>/<RPORTER>_<GRID> directory under which there  may be  one or  more receivers with 24 hour wav files which have not 
###  been converted to DRF and uploaded to the GRAPE server
### Returns:  0 on nothing to do or success on uploading

function upload_24hour_wavs_to_grape_drf_server() {
    local reporter_wav_root_dir=$( realpath $1 )
    wd_logger 2 "Upload bands for reporter ${reporter_wav_root_dir##*/}"

    if [[ ! -d ${reporter_wav_root_dir} ]]; then
        wd_logger 1 "ERROR:  reporter_wav_root_dir='${reporter_wav_root_dir}' does not exist"
        return 1
    fi
    local reporter_wav_root_dir_list=( ${reporter_wav_root_dir//\// } )
    local reporter_wav_root_dir_date="${reporter_wav_root_dir_list[-2]}"
    local current_date=$(TZ=UTC printf "%(%Y%m%d)T" -1)
    if [[ "${reporter_wav_root_dir_date}" == "${current_date}" ]]; then
        wd_logger 2 "Skipping work on .wv files for today's date ${current_date}"
        return 0
    fi
    wd_logger 2 "On date '${current_date}' checking for date '${reporter_wav_root_dir_date}' bands which need a wav file to be created and then convert them to DRF and upload to the GRAPE server"

    local reporter_upload_complete_file_name="${reporter_wav_root_dir}/${UPLOAD_TO_PSWS_SERVER_COMPLETED_FILE_NAME}"

    if [[ -f ${reporter_upload_complete_file_name} ]]; then
        wd_logger 2 "File ${reporter_upload_complete_file_name} exists, so upload of wav files has already been successful"
        return 0
    fi
    local reporter_upload_impossible_file_name="${reporter_wav_root_dir}/${UPLOAD_TO_PSWS_SERVER_IMPOSSIBLE_FILE_NAME}"
    if [[ -f ${reporter_upload_impossible_file_name} ]]; then
        ### Reported once, when the marker was written.  Saying it again every 30 minutes for ever helps nobody.
        wd_logger 2 "This day cannot be uploaded and was given up on: $(< ${reporter_upload_impossible_file_name})"
        return 0
    fi
    wd_logger 1 "File ${reporter_upload_complete_file_name} does not exist, so create the wav files and upload the DRF files"

    ### On the WD client the .wv  and 24hour.wav files are cached in the non-volitile  file system which has the format:
    ### ...../wsprdaemon/wav-archive/<DATE>/<WSPR_REPORTER_ID>_<WSPR_REPORTER_GRID>/<WD_RECEIVER_NAME>@<PSWS_SITE_ID>_<PSWS_INSTRUMENT_NUMBER>/<BAND>
    ### WSPR_REPORTER_ID, WSPR_REPORTER_GRID and WD_RECEIVER and WD_RECEIVER_NAME are assigned by the WD client and entered into the wsprdaemon.conf file
    ### Each WD client can support multiple WSPR_REPORTER_IDs, each of which can have the same or a unique WSPR_REPORTER_GRID
    ### Each WSPR_REPORTER_ID+WSPR_REPORTER_GRID is associated with one or more WSPR_RECIEVER_NAMEs, and each of those will support one or more BANDS
    ###
    local dir_path_list=( ${reporter_wav_root_dir//\// } )
    local wav_date=${dir_path_list[-2]}
    local reporter_info=${dir_path_list[-1]}
    local reporter_id=${reporter_info%_*}         ### Chop off the _GRID to get the WSPR reporter id
    local reporter_grid=${reporter_info#*_}       ### Chop off the REPROTER_ID to get the grid

    ### Search each receiver for wav files
    local receiver_dir
    local receiver_dir_list=( $( find -L "${reporter_wav_root_dir}" -mindepth 1 -maxdepth 1 -type d -not -name '*mutex.lock'| sort ) )
    if [[ ${#receiver_dir_list[@]} -eq 0 ]]; then
        wd_logger 1  "There are no receiver dirs under ${reporter_wav_root_dir}"
        return 1
    fi
    ### Count what actually reaches the server, so that the completion marker at the bottom is only
    ### written when something really was uploaded.
    local uploaded_band_count=0
    local uploaded_receiver_count=0
    local expected_band_count=0
    for receiver_dir in ${receiver_dir_list[@]} ; do
        local receiver_info="${receiver_dir##*/}"
        local receiver_name="${receiver_info%@*}"
        local pswsnetwork_info="${receiver_info#*@}"
        local search_txt="NOT_DEFINED"
        if [[ "$pswsnetwork_info" == "*$search_txt*" ]]; then
            pswsnetwork_info=${GRAPE_PSWS_ID}
        fi
        local psws_station_id="${pswsnetwork_info%_*}"
        local psws_instrument_id="${pswsnetwork_info#*_}"

        if [[ ! "${receiver_info}" =~ @ ]] || [[ -z "${psws_station_id}" ]] || [[ -z "${psws_instrument_id}" ]]; then
            wd_logger 1 "ERROR: directory ${receiver_dir} doesn't contain the '@' which is part of a PSWS ID OR the psws_station_id or the psws_instrument_id couldn't be extracted from it, so skip uploading of it"
            continue
        fi

        wd_logger 1  "Checking and cleaning up the band directories for receiver ${receiver_dir}"
        wd_logger 2  "date: ${wav_date}- site: ${reporter_id} - receiver_name: $receiver_name - psws_station_id: $psws_station_id - psws_instrument_id: ${psws_instrument_id}"

        ### Cleanup the .wv files  and create 24hour.wavs in all the bands
        local wav_file_count=0
        local band_dir_list=( $( find -L ${receiver_dir} -maxdepth 1 -type d  -regex '.*/\(WWV\|CHU\|K_BEACON\).*' | awk -F_ '{print $(NF-1), $NF, $0}' | sort -k1,1r -k2,2n  | cut -d' ' -f3) )
        (( expected_band_count += ${#band_dir_list[@]} ))
        local band_dir
        for band_dir in ${band_dir_list[@]} ; do
            wd_logger 2 "Checking WWV/CHU/K_BEACON band dir ${band_dir}"
            local band_24hour_wav_file="${band_dir}/24_hour_10sps_iq.wav"
            if [[ -f ${band_24hour_wav_file} ]]; then
                 ### This check used to ask soxi for the sample count, and soxi cannot answer it: sox writes
                 ### the wav header with the INTENDED length before it writes the samples, so a file which was
                 ### truncated when its build was killed still reports a confident
                 ###     Duration : 24:00:00.00 = 864000 samples
                 ### Measured at KI4AFE 2026-09-16, soxi gives exactly that line for a 3366912 byte file and
                 ### for the 6912058 byte good one beside it, so the guard passed every truncated file it was
                 ### written to catch.  Only the size on disk tells the truth.
                 local band_wav_bytes
                 band_wav_bytes=$( stat -c %s "${band_24hour_wav_file}" 2>/dev/null || echo 0 )
                 if (( band_wav_bytes >= GRAPE_24_HOUR_WAV_SAMPLE_BYTES )) ; then
                     wd_logger 2 "Found a good existing ${band_24hour_wav_file}"
                  else
                     wd_logger 1 "ERROR: wav file ${band_24hour_wav_file} is ${band_wav_bytes} bytes, short of the ${GRAPE_24_HOUR_WAV_SAMPLE_BYTES} bytes of samples a 10 Hz 24 hour wav holds, so deleting it"
                     wd_rm ${band_24hour_wav_file}
                 fi
            fi
            if !  [[ -f ${band_24hour_wav_file} ]]; then
                wd_logger 1 "Creating ${band_24hour_wav_file}"
                grape_repair_band_bad_compressed_files ${band_dir}
                rc=$? ; if (( rc )); then
                    wd_logger 1 "WARNING: 'grape_repair_band_bad_compressed_files ${band_dir}' => ${rc}"
                fi
                grape_create_wav_file  ${band_dir}
                rc=$? ; if (( rc )); then
                    wd_logger 1 "WARNING: 'grape_create_wav_file ${band_dir}' => ${rc}"
                fi
            fi 
            if [[  -f ${band_24hour_wav_file} ]]; then
                wd_logger 1 "Found wav file ${band_24hour_wav_file}"
                (( ++wav_file_count ))
            else
                 wd_logger 1 "Neither found nor could create  ${band_24hour_wav_file}"
            fi
        done
        ### A band which has no good 24 hour wav is only worth waiting for if something could still build one.
        ### Once a day has been through here its .wv files may already have been purged, and then no number of
        ### retries will ever produce that band -- but the day had no completed marker, so it was retried on
        ### every pass for ever: KI4AFE had 20260731 and 20260903 failing this way for six weeks and twelve
        ### days, 150 logged DRF conversions, each one re-reading seven bands before failing.  Neither day
        ### ever reached PSWS.  Decide here whether waiting can possibly help.
        local missing_band_count=$(( ${#band_dir_list[@]} - wav_file_count ))
        if (( missing_band_count > 0 )); then
            local rebuildable_band_list=() unrebuildable_band_list=() check_band_dir
            for check_band_dir in ${band_dir_list[@]} ; do
                [[ -f "${check_band_dir}/${GRAPE_24_HOUR_10_HZ_WAV_FILE_NAME}" ]] && continue
                if compgen -G "${check_band_dir}/*.wv" > /dev/null 2>&1 ; then
                    rebuildable_band_list+=( "${check_band_dir##*/}" )
                else
                    unrebuildable_band_list+=( "${check_band_dir##*/}" )
                fi
            done
            if (( ${#rebuildable_band_list[@]} )); then
                wd_logger 1 "WARNING: ${missing_band_count} of ${#band_dir_list[@]} bands have no 24 hour wav yet, but '${rebuildable_band_list[*]}' still have .wv files to build from, so try again on the next pass"
                continue
            fi
            ### Nothing left to build the missing bands from, so this day can never be completed.  Do not
            ### upload a partial day -- PSWS would take it as the whole day -- and do not come back to it.
            local impossible_reason="$(date -u +%Y-%m-%dT%H:%M:%SZ) ${#unrebuildable_band_list[@]} of ${#band_dir_list[@]} bands ('${unrebuildable_band_list[*]}') have no 24 hour wav and no .wv files left to build one from, so this day can never be completed and was never uploaded"
            echo "${impossible_reason}" > ${reporter_upload_impossible_file_name}
            wd_logger 1 "ERROR: ${impossible_reason}.  Giving up on it: ${reporter_upload_impossible_file_name} now marks it so it is not retried on every pass.  Delete that file to try again"
            continue
        fi
        if (( ! wav_file_count )); then
            wd_logger 1 "WARNING: no wav files found or created for any bands, so skip DRF creation for this receiver/band"
            continue
        fi

        wd_logger 1  "Creating the DRF file from ${wav_file_count} bands of wav files"

        ### Create the DRF files for all the bands on this receiver
        rm -rf  ${GRAPE_TMP_DIR}/*          ## the -f suppresses an error when there are no files in that dir
        umask 022    ### Ensures that our 'sftp put .' doesn't enable the group access to the PSWS home directory and thus disable ssh autologin
        local wav2grape_stdout_file="${GRAPE_TMP_DIR}/${WAV2GRAPE_PYTHON_CMD##*/}.stdout"
        local wav2grape_stderr_file="${GRAPE_TMP_DIR}/${WAV2GRAPE_PYTHON_CMD##*/}.stderr"
        ${WAV2GRAPE_PYTHON_CMD} -i "${receiver_dir}" -o "${GRAPE_TMP_DIR}" > ${wav2grape_stdout_file}  2> ${wav2grape_stderr_file}
        rc=$? ; if (( rc )); then
            wd_logger 1 "ERROR: '${WAV2GRAPE_PYTHON_CMD} -i $receiver_dir -o $GRAPE_TMP_DIR' =${rc}:\n$(<${wav2grape_stderr_file})"
            return ${rc}
        fi
        local receiver_tmp_dir="$(<${wav2grape_stdout_file} )"
        if [[ -z "${receiver_tmp_dir}" ]]; then
            wd_logger 1 "ERROR: wvunpack  decompressed files, but return a zero length name for its  receiver_tmp_dir"
            return 1
        fi

        wd_logger 1  "The DRF files have been created under ${receiver_tmp_dir}.  Now upload them.."

        local psws_trigger_dir_name="c${receiver_tmp_dir##*/}_\#${psws_instrument_id}_\#$(date -u +%Y-%m%dT%H-%M)"       ### The root directory of where our DRF file tree will go on th ePSWS server
        wd_logger 1 "Uploading our DRF directory tree from local dir '${receiver_tmp_dir%/*}' and then creating the trigger dir '${psws_trigger_dir_name}' on our site's home dir on  the PSWS server"

        local sftp_cmds_file="${WSPRDAEMON_TMP_DIR}/sftp.cmds" 
        echo "put -r . 
              mkdir ${psws_trigger_dir_name}" > ${sftp_cmds_file}
        cd "${receiver_tmp_dir%/*}"
        rc=$? ; if (( rc )); then
            cd - > /dev/null
            wd_logger 1 "ERROR: 'cd ${receiver_tmp_dir%/*}' => ${rc}"
            return ${rc}
        fi

        local sftp_stderr_file="${GRAPE_TMP_DIR}/sftp.out"
        local sftp_bw_limit_kbps="${SFTP_BW_LIMIT_KBPS-0}"
        if (( sftp_bw_limit_kbps == 0 )) && (( ${SIGNAL_LEVEL_FTP_RATE_LIMIT_BPS-0} )) ; then
            sftp_bw_limit_kbps=$(( SIGNAL_LEVEL_FTP_RATE_LIMIT_BPS / 1000 ))
        fi
        if (( sftp_bw_limit_kbps == 0 )); then
            sftp_bw_limit_kbps=100
        fi
        sftp -v  -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o ConnectTimeout=20 \
            -l ${sftp_bw_limit_kbps} -b ${sftp_cmds_file} "${psws_station_id}@${PSWS_SERVER_URL}" >& ${sftp_stderr_file}
        rc=$?
        cd - > /dev/null
        if (( rc )); then
            wd_logger 1 "ERROR: 'sftp -l ${SFTP_BW_LIMIT_KBPS-1000} -b ${sftp_cmds_file} ${psws_station_id}@${PSWS_SERVER_URL}' -> ${rc}:\n$(<${sftp_stderr_file})"
            return ${rc}
        fi
        (( ++uploaded_receiver_count ))
        (( uploaded_band_count += wav_file_count ))
    done

    ### Only record the day as uploaded if a receiver actually reached the server.  Each 'continue' above --
    ### a band still rebuildable, a day given up on as impossible, no 24 hour wav at all -- skips the DRF
    ### creation and the sftp, but still fell through to this touch, so the day was recorded as uploaded when
    ### nothing had been sent and this function then returned early for ever.  At G4ZFQ 20260915 and 20260916
    ### were both marked uploaded while holding no 24 hour wav at all, so no later pass would look at them
    ### again even after the wavs were repaired.  A day whose bands can never be built is already kept from
    ### being retried by ${UPLOAD_TO_PSWS_SERVER_IMPOSSIBLE_FILE_NAME}, so returning without the completed
    ### marker here does not bring back the endless retries that marker was added to stop.
    if (( ! uploaded_receiver_count )); then
        wd_logger 1 "ERROR: none of the ${#receiver_dir_list[@]} receivers under ${reporter_wav_root_dir} uploaded any of its ${expected_band_count} bands, so '${reporter_upload_complete_file_name}' is NOT created and this day is left to be retried"
        return 1
    fi
    touch "${reporter_upload_complete_file_name}"
    wd_logger 1  "Uploaded ${uploaded_band_count} bands from ${uploaded_receiver_count} of the ${#receiver_dir_list[@]} receivers under ${reporter_wav_root_dir}, so create '${reporter_upload_complete_file_name}'"
}

function grape_test_auto_login() {
    local station_id=$1
    local rc
    local start_epoch
    local end_epoch
    local runtime_seconds

    local nc_timeout=${PSWS_NC_TIMEOUT-2}    ### Default is to wait up to 2 seconds to make a tcp connection to the ssh port of the PSWS server
    wd_logger 2 "Checking the Internet connection to the ssh port 22 of the PSWS server ${PSWS_SERVER_URL}"
    start_epoch=${EPOCHSECONDS}
    nc -vz -w ${nc_timeout} ${PSWS_SERVER_URL} 22 >& /dev/null
    rc=$?
    end_epoch=${EPOCHSECONDS}
    runtime_seconds=$(( end_epoch - start_epoch ))
    if (( rc )); then
        wd_logger 1 "WARNING: There is no Internet connectio to the PSWS server, since it timeout after ${runtime_seconds} seconds running 'nc -vz -w ${nc_timeout} ${PSWS_SERVER_URL} 22' => ${rc}"
        return 1
    fi
    wd_logger 2 "It took ${runtime_seconds} to verify the Internet connection to the sftp/ssh port 22 at the PSWS server at ${PSWS_SERVER_URL}"

    local psws_timeout=$(( nc_timeout * 10 ))    ### Default is to wait up to 20 seconds to execute a simple sftp connection to the PSWS server
    wd_logger 2 "Waiting ${psws_timeout} up to seconds to see if we can open a sftp connection to the PSWS GRAPE server at ${PSWS_SERVER_URL}"
    start_epoch=${EPOCHSECONDS}
    sftp -o ConnectTimeout=${psws_timeout}  -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -b /dev/null ${station_id}@${PSWS_SERVER_URL} &>/dev/null
    rc=$?
    end_epoch=${EPOCHSECONDS}
    runtime_seconds=$(( end_epoch - start_epoch ))
    if (( rc )); then
        wd_logger 1 "After ${runtime_seconds} seconds: ERROR: 'sftp -o ConnectTimeout=${psws_timeout}  -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -b /dev/null ${station_id}@${PSWS_SERVER_URL}' => ${rc}"
    else
        wd_logger 2 "After ${runtime_seconds} seconds: Successfully ran 'sftp -o ConnectTimeout=${psws_timeout}  -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -b /dev/null ${station_id}@${PSWS_SERVER_URL}'"
    fi
    return ${rc}
}

function get-or-create-ssh-public-key() {
    local -n _return_var_name=$1

    if [[ ! -d ~/.ssh ]]; then
        mkdir -p ~/.ssh
        chmod 700 ~/.ssh
        wd_logger 1 "Created missing ~/.ssh directory"
    fi
    if [[ -f ~/.ssh/id_ed25519.pub ]]; then
        _return_var_name="$( realpath ~/.ssh/id_ed25519.pub )"
        wd_logger 2 "Found existing public key file '${_return_var_name}'"
    elif [[ -f ~/.ssh/id_rsa.pub ]]; then
        _return_var_name="$( realpath ~/.ssh/id_rsa.pub )"
        wd_logger 2 "Found existing public key file '${_return_var_name}'"
    else
        public_key_file_path="$( realpath ~/.ssh/id_ed25519.pub )"
        ssh-keygen -t ed25519 -C "$(whoami)@$(hostname)" -f ${public_key_file_path%.pub} -N ""
        _return_var_name="${public_key_file_path}"
        wd_logger 1 "Created a missing public key file '${_return_var_name}'"
    fi
    return 0
}

######  '-p'   upload public key to PSWS server
function grape_check_auto_upload() {
    local rc

    wd_logger 2 "Starting"

    if [[ -z "${GRAPE_PSWS_ID-}" ]]; then
        wd_logger 1 "ERROR: GRAPE_PSWS_ID has not been defined in wsprdameon.conf"
        return 1
    fi

    local public_key_file_path
    get-or-create-ssh-public-key "public_key_file_path"
    wd_logger 2 "ssh public key file path is ${public_key_file_path}"

    local station_id=${GRAPE_PSWS_ID%_*}   ### Chop off the _ID.. to get the PSWS site name
    grape_test_auto_login $station_id
    rc=$? ; if (( rc == 0 )); then
        wd_logger 2 "Autologin for site ${station_id} is already setup"
        return 0
    fi
    wd_logger 1 "Autologin to the GRAPE PSWS server has failed for this GRAPE SITE_ID='${station_id}'. So enter this server's public key, or email it to the PSWS administrator that:\nPSWS station '${station_id}' needs this ssh public key added to its account:\n$( < ${public_key_file_path} )"
    return 1
}

###### '-S'
function grape_get_date_status() {
    local date=$1

    if [[ "${date}" == "h" ]]; then
        wd_logger 1 "usage: -S YYYYMMDD"
        return 0
    fi
    local date_root_dir="${GRAPE_WAV_ARCHIVE_ROOT_PATH}/${date}"

    if [[  ! -d ${date_root_dir} ]]; then
        wd_logger 1 "Can't find ${date_root_dir}"
        return 1
    fi
    local rc=0
    local band_dir_list=( $( find -L ${date_root_dir} -mindepth 3 -type d  -regex '.*/\(WWV\|CHU\|K_BEACON\).*' | awk -F_ '{print $(NF-1), $NF, $0}' | sort -k1,1r -k2,2n  | cut -d' ' -f3) )
    wd_logger 1 "Found ${#band_dir_list[@]} bands for UTC date ${date}"
    for band_dir in ${band_dir_list[@]} ; do
        local compressed_wav_file_list=( $( find -L ${band_dir} -name '*.wv' ) )
        local silent_compressed_wav_file_list=( $( find -L ${band_dir} -type l -name '*.wv' ) )
        printf "In %-90s found ${#compressed_wav_file_list[@]} .wv files"  ${band_dir}
        if [[ ${#silent_compressed_wav_file_list[@]} -gt 0 ]]; then
            printf ", of which ${#silent_compressed_wav_file_list[@]} are silence files"
        fi
        printf "\n"
    done
    return ${rc}
}

### '-t' 
function grape_show_all_dates_status(){
    local wav_archive_dates_dir_list=( $( find -L ${GRAPE_WAV_ARCHIVE_ROOT_PATH} -mindepth 1 -maxdepth 1 -type d -printf '%p\n' | sort)  )
    local wav_archive_date
    for wav_archive_date in ${wav_archive_dates_dir_list[@]##*/} ; do
        grape_get_date_status ${wav_archive_date}
    done
}

### '-p' 
function grape_purge_all_empty_date_trees(){
    local wav_archive_dates_dir_list=( $( find -L ${GRAPE_WAV_ARCHIVE_ROOT_PATH} -mindepth 1 -maxdepth 1 -type d -printf '%p\n' | sort)  )
    local wav_archive_date
    for wav_archive_date in ${wav_archive_dates_dir_list[@]##*/} ; do
        local date_files_list=( $( find -L ${GRAPE_WAV_ARCHIVE_ROOT_PATH}/${wav_archive_date} -type f ) )
        if [[ ${#date_files_list[@]} -eq 0 ]]; then
            wd_logger 1 "Purging empty date  tree ${GRAPE_WAV_ARCHIVE_ROOT_PATH}/${wav_archive_date}"
            rm -r ${GRAPE_WAV_ARCHIVE_ROOT_PATH}/${wav_archive_date}
        else
            wd_logger 2 "$(printf  "Found %5d files in %s\n" ${#date_files_list[@]} "${GRAPE_WAV_ARCHIVE_ROOT_PATH}/${wav_archive_date}" )"
        fi
    done
}

declare GRAPE_AUTO_DELETE_BAD_FLACS="${GRAPE_AUTO_DELETE_BAD_FLACS-yes}"

function grape_repair_band_bad_compressed_files() {
    local band_dir=$1

    if [[ ! "${band_dir}" =~ WWV|CHU ]]; then
        wd_logger 1 "Band '${band_dir}' is not a WWV or CHU band, so skip repairing"
        return 0
    fi
    local compressed_wav_file_list=( $( find -L ${band_dir} -name '*.wv' | sort) )
    if [[ ${#compressed_wav_file_list[@]} -eq 0 ]]; then
        wd_logger 1 "There are no .wv files in ${band_dir}, so returning an this as an error"
        return 1
    fi

    wd_logger 1 "Checking all the ${#compressed_wav_file_list[@]} .wv files in band dir ${band_dir} are present and valid and that the wav files they contain are valid"
    local rc
    local bad_wav_file_count=0
    local good_wav_file_count=0
    local compressed_wav_file
    for compressed_wav_file in  ${compressed_wav_file_list[@]} ; do
        wvunpack -v ${compressed_wav_file} 2> /tmp/wvunpack.log
        rc=$? ; if (( ! rc )); then
            (( ++good_wav_file_count ))
            wd_logger 3 " wavunpack reports file ${compressed_wav_file} is good"
        else
            wd_logger 1 "ERROR: wavunpack reports file ${compressed_wav_file} is corrupt, so deleting it"
            (( ++bad_wav_file_count ))
            wd_rm  ${compressed_wav_file}
        fi
    done
    if (( bad_wav_file_count )); then
        wd_logger 1 "Removed ${bad_wav_file_count} bad .wv files"
    fi
    if (( ! good_wav_file_count )); then
        wd_logger 1 "There are no good .wv files in this ${band_dir}"
        return 1
    fi

    local band_date=${compressed_wav_file_list[0]##*/}
    band_date=${band_date%%T*}

    ### A minute file is named <YYYYMMDD>T<HHMMSS>Z_<freq>_<tail>, where <tail> is whatever ka9q-radio's
    ### wd-record calls the channel.  Until ka9q-radio db97fdca ("make preset write-only", 2026-09-08) that
    ### was the preset name, so a WWV IQ minute arrived as '..._10000000_iq.wv'; from that commit on it is
    ### the demodulator name and the same minute arrives as '..._10000000_linear.wv'.  WD inherited the
    ### change when its ka9q-radio pin moved to 6a4fe1bf in 674115b.  Hardcoding either spelling makes all
    ### 1440 expected names wrong for the other: at G4ZFQ that filled six band dirs with bogus
    ### '..._linear.wv_iq.wv' silence links so no day could ever be assembled, and on 20260915, which
    ### straddled the rename, it flushed 1672 real recordings as 'not expected in this directory'.
    ### So learn the tail from the files actually on disk instead of assuming it, and match a minute on its
    ### timestamp alone.  Silence fillers are symlinks, so only real recordings vote on the tail, and the
    ### most common tail wins so that a day straddling a rename keeps its majority spelling rather than
    ### deleting one half of itself.
    local -A tail_counts=()
    local found_file
    local file_tail
    local tail_count
    for found_file in "${compressed_wav_file_list[@]}" ; do
        [[ -L ${found_file} ]] && continue
        file_tail=${found_file##*/}
        file_tail=${file_tail#*_}
        tail_count=${tail_counts[${file_tail}]-0}
        tail_counts[${file_tail}]=$(( tail_count + 1 ))
    done
    local band_freq=""
    local best_tail_count=0
    for file_tail in "${!tail_counts[@]}" ; do
        tail_count=${tail_counts[${file_tail}]}
        if (( tail_count > best_tail_count )); then
            best_tail_count=${tail_count}
            band_freq=${file_tail}
        fi
    done
    if [[ -z ${band_freq} ]]; then
        wd_logger 1 "ERROR: ${band_dir} holds ${#compressed_wav_file_list[@]} .wv files but not one of them is a real recording, so the minute file name cannot be learned and silence files cannot be named"
        return 1
    fi
    if (( ${#tail_counts[@]} > 1 )); then
        wd_logger 1 "${band_dir} holds ${#tail_counts[@]} different minute file names, as happens when ka9q-radio renames them part way through a day.  Using the most common one, '${band_freq}', to name any silence files"
    fi
    wd_logger 1 "Found ${#compressed_wav_file_list[@]} .wv files in ${band_dir}. Check there is a .wv for each minute for this band_date=${band_date},  band_freq=${band_freq}"

    ### Index what is on disk by the minute it covers, so that a minute counts as present whatever its tail
    ### is, and a real recording always beats a silence link for the same minute.
    local -A minute_files=()
    local file_minute
    local link_tail
    for found_file in "${compressed_wav_file_list[@]}" ; do
        if [[ -L ${found_file} ]]; then
            link_tail=${found_file##*/}
            link_tail=${link_tail#*_}
            ### A silence link left under some other spelling -- which is what the old hardcoded '_iq.wv'
            ### name produced here -- does not count as covering its minute.  Ignoring it now means a
            ### correctly named link is made for that minute below and this one is flushed as an extra, so
            ### the archive is left holding canonical names only.
            if [[ ${link_tail} != ${band_freq} ]]; then
                continue
            fi
        fi
        file_minute=${found_file##*/}
        file_minute=${file_minute%%Z_*}
        if [[ -z ${minute_files[${file_minute}]-} ]]; then
            minute_files[${file_minute}]=${found_file}
        elif [[ -L ${minute_files[${file_minute}]} && ! -L ${found_file} ]]; then
            minute_files[${file_minute}]=${found_file}
        fi
    done

    local silence_file_list=()
    local -A keep_files_map=()
    local hour
    for hour in ${HOURS_LIST[@]} ; do
        local minute 
        for minute in ${MINUTES_LIST[@]} ; do
            local expected_minute="${band_date}T${hour}${minute}00"
            local minute_file=${minute_files[${expected_minute}]-}
            if [[ -n ${minute_file} ]]; then
                wd_logger 2 "Found ${minute_file} for minute ${expected_minute}"
                keep_files_map[${minute_file}]="yes"
            else
                local expected_file_path="${band_dir}/${expected_minute}Z_${band_freq}"
                wd_logger 2 "Can't find a .wv for minute ${expected_minute}, so link the 1 minute of silence file in its place"
                ln -s ${WD_SILENT_WV_FILE_PATH}  ${expected_file_path}
                keep_files_map[${expected_file_path}]="yes"
                silence_file_list+=( ${expected_file_path##*/} )
            fi
        done
    done

    local silence_files_added=${#silence_file_list[@]}
    if (( ! silence_files_added )); then
        wd_logger 1 "No silence files were added"
    else
        echo "${silence_file_list[@]}" > silence_file_list.txt
        wd_logger 1 "Created ${silence_files_added} silence files"
        if (( silence_files_added >=  GRAPE_ERROR_RETURN_BASE)); then
            silence_files_added=$(( ${GRAPE_ERROR_RETURN_BASE} - 1 ))
            wd_logger 1 "Added ${#silence_file_list[@]} silence files, more than can be returned from a bash function.  So returning instead ${silence_files_added}"
        fi
    fi

    wd_logger 1 "Check for extra .wv files and flush them"
    local extra_files_list=()
    for found_file in "${compressed_wav_file_list[@]}"; do
        ### An exact keyed lookup.  This test used to be a =~ substring match against the whole expected
        ### list, which silently spared '..._linear.wv' because it is a substring of '..._linear.wv_iq.wv';
        ### with any other pair of spellings the same match would have deleted every real recording here.
        if [[ -z ${keep_files_map[${found_file}]-} ]]; then
            wd_logger 1 "Flushing file ${found_file} which is not expected to be in this directory"
            extra_files_list+=( ${found_file} )
            wd_rm ${found_file}
        fi
    done
    if (( ${#extra_files_list[@]} )); then
        wd_logger 1 "Founbd and flushed ${#extra_files_list[@]} extra .wv files"
    else
        wd_logger 1 "Found no extra .wv files"
    fi

    if (( silence_files_added )); then
        wd_logger 1 "Returning count of the ${silence_files_added}"
        return ${silence_files_added}
    else
         wd_logger 1 "Returning zero, since no silence files were added"
         return 0
    fi
}

### 'To execute this ffrom the cmd line execute: 'WD -g "R <YYYYMMDD>"'
function grape_repair_date_wvs() {
    local date=$1

    if [[ "${date}" == "h" ]]; then
        wd_logger 1 "usage: -R YYYYMMDD"
        return 0
    fi
    local date_root_dir="${GRAPE_WAV_ARCHIVE_ROOT_PATH}/${date}"
    
    if [[  ! -d ${date_root_dir} ]]; then
        wd_logger 1 "Can't find ${date_root_dir}"
        return 1
    fi

    ### Get a list of bands sorted so the WWV bands are first and in frequency order followed by the CHU bands in frequency order. Thanks to chatgbt:
    local band_dir_list=( $( find -L ${date_root_dir} -mindepth 3 -type d  -regex '.*/\(WWV\|CHU\|K_BEACON\).*' | awk -F_ '{print $(NF-1), $NF, $0}' | sort -k1,1r -k2,2n  | cut -d' ' -f3) )
    wd_logger 1 "Repairing any defective and/or missing .wv files in these ${#band_dir_list[@]} bands: ${band_dir_list[*]##*/}"
    for band_dir in ${band_dir_list[@]} ; do
        wd_logger 1 "Repairing ${band_dir##*/}"
        grape_repair_band_bad_compressed_files ${band_dir}
    done
}

### '-r' 
function grape_repair_all_dates_wvs()
{
    local current_date
    TZ=UTC printf -v current_date "%(%Y%m%d)T"
    local wav_archive_dates_dir_list=( $( find -L ${GRAPE_WAV_ARCHIVE_ROOT_PATH} -mindepth 1 -maxdepth 1 -type d -printf '%p\n' | sort)  )
    local wav_archive_date
    for wav_archive_date in ${wav_archive_dates_dir_list[@]##*/} ; do
        if [[ ${wav_archive_date} ==  ${current_date} ]] ; then
            wd_logger 1 "Skipping grape_repair_date_wvs for current UTC day ${current_date}"
        else
            grape_repair_date_wvs ${wav_archive_date}
        fi
    done
}

### Give a DATE...BAND directory which should have the requried 1440 minute .wv files. create a single w4 hour long 10 Hz BW wav file
### Returns: 0 => if GRAPE_24_HOUR_10_HZ_WAV_FILE_NAME existed, 1 => created new GRAPE_24_HOUR_10_HZ_WAV_FILE_NAME, >  ${GRAPE_ERROR_RETURN_BASE} if there was a error
function grape_create_wav_file()
{
    local compressed_wav_file_dir=$1
    local rc

    local output_10sps_wav_file="${compressed_wav_file_dir}/${GRAPE_24_HOUR_10_HZ_WAV_FILE_NAME}"
    ### A full day of this file is a fixed size: MINUTES_PER_DAY minutes * 60 s * 10 sps * 2 channels (IQ)
    ### * 4 bytes per float sample, plus a 58 byte wav header.  284 of the 287 files at KI4AFE were exactly
    ### that.  The test below is against the SAMPLE bytes alone so a differing header size can never make a
    ### good file look short.
    local -r full_day_sample_bytes=$(( MINUTES_PER_DAY * 60 * 10 * 2 * 4 ))
    local -r partial_output_file="${output_10sps_wav_file}.partial"

    wd_logger 2 "Check for the 10 sps wav file ${output_10sps_wav_file} and create it if it doesn't exist"
    if [[ -f ${output_10sps_wav_file} ]]; then
        ### 'it exists' is not the same as 'it is finished'.  sox writes this file progressively, in place,
        ### over the 5-30 minutes it takes, and it runs inside WD's cgroup -- so a 'systemctl restart
        ### wsprdaemon' part way through leaves a half written file here.  That file then satisfied the -f
        ### test below for ever, so the band was never rebuilt and the truncated file was uploaded to PSWS
        ### as a full day.  It cannot be caught by reading the file either: sox writes the header with the
        ### INTENDED length before the samples, so 'soxi -D' reports a confident 86400.000000 seconds for a
        ### file which is half missing.  Only the size on disk tells the truth.
        ### Found at KI4AFE 2026-09-15: 20260731/WWV_2_5 at 19% and 20260903/WWV_2_5 at 49%, written six
        ### weeks and twelve days earlier, both long since uploaded, and neither rebuildable because their
        ### source .wv files had been purged after that upload.
        local existing_file_bytes
        existing_file_bytes=$( stat -c %s "${output_10sps_wav_file}" 2>/dev/null || echo 0 )
        if (( existing_file_bytes >= full_day_sample_bytes )); then
            wd_logger 2 "The 10 sps wav file ${output_10sps_wav_file} exists and is a full day, so there is nothing to do in this directory"
            return 0
        fi
        ### Only throw the short file away if it can actually be replaced.  Once a day has been uploaded its
        ### .wv files are purged, so for an old truncation there is nothing left to rebuild from -- deleting
        ### it then would just leave the band with no file at all and log the same error on every pass for
        ### ever.  Both of KI4AFE's were in that state.  Say so once per pass and leave the evidence in place.
        if ! compgen -G "${compressed_wav_file_dir}/*.wv" > /dev/null 2>&1 ; then
            wd_logger 1 "ERROR: ${output_10sps_wav_file} is only ${existing_file_bytes} of the ${full_day_sample_bytes} bytes a full day holds, so an earlier run was interrupted while writing it -- and its source .wv files have since been purged, so it CANNOT be rebuilt.  That day is incomplete at PSWS and this file is being left in place as the record of it"
            return 0
        fi
        wd_logger 1 "ERROR: ${output_10sps_wav_file} is only ${existing_file_bytes} bytes, short of the ${full_day_sample_bytes} bytes a full day holds, so an earlier run was interrupted part way through writing it.  Deleting it and building it again"
        wd_rm "${output_10sps_wav_file}"
    fi
    ### Anything left from a previous interrupted run is worthless; it is rebuilt from the .wv files below
    [[ -f ${partial_output_file} ]] && wd_rm "${partial_output_file}"

    local compressed_wav_file_list=()
    compressed_wav_file_list=( $( find -L ${compressed_wav_file_dir} -name '*.wv' -printf '%p\n' | sort ) )   ### sort the output of find to ensure the array elements are in time order
    rc=$?
    if (( rc )); then
        wd_logger 1 "ERROR: 'find -L ${compressed_wav_file_dir}  -name '*.wv' -printf '%p\n' | sort' => ${rc}"
        return ${rc}
    fi
    if (( ${#compressed_wav_file_list[@]} == 0 )); then
        wd_logger 1 "ERROR: found no .wv files in ${compressed_wav_file_dir}, so delete that directory"
        echo rm -r ${compressed_wav_file_dir}
        return ${GRAPE_ERROR_RETURN_NO_WVS} 
    fi
    if (( ${#compressed_wav_file_list[@]} !=  MINUTES_PER_DAY )); then
        local files_date=${compressed_wav_file_list[0]##*/}       ### The file date of all the .wv files should match the date of the root directory, but it is easier to parse the .wv file name to get the date
        files_date=${files_date%%T*}
        local current_date
        TZ=UTC printf -v current_date "%(%Y%m%d)T"
        if false && [[ ${files_date} == ${current_date} ]] ; then
            wd_logger 1 "Skipping create for current UTC day ${current_date}"
            return 0
        fi

        local missing_compressed_wav_file_count=$((  MINUTES_PER_DAY - ${#compressed_wav_file_list[@]} ))
        if (( missing_compressed_wav_file_count > 0 )); then
            wd_logger 1 "${missing_compressed_wav_file_count} .wv files are missing in ${compressed_wav_file_dir}, so add silence files to fill the directory"
        else
            wd_logger 1 "${compressed_wav_file_dir} holds ${#compressed_wav_file_list[@]} .wv files, $(( - missing_compressed_wav_file_count )) more than the ${MINUTES_PER_DAY} minutes in a day, so call the repair to work out which of them belong here"
        fi
        grape_repair_band_bad_compressed_files ${compressed_wav_file_dir}
        rc=$?
        if (( ! rc )); then
            wd_logger 1 "ERROR: because there were ${#compressed_wav_file_list[@]} .wv files instead of the expected ${MINUTES_PER_DAY} .wv files in ${compressed_wav_file_dir} we called grape_repair_band_bad_compressed_files(), but no repairs were done or silent files added"
        else
            wd_logger 1 "grape_repair_band_bad_compressed_files() reported it repaired  ${compressed_wav_file_dir} by adding ${rc} (or more) silence files"
        fi
        ### Since the repair reported success we need to recreate the compressed_wav_file_list() 
        compressed_wav_file_list=( $( find -L ${compressed_wav_file_dir} -name '*.wv' -printf '%p\n' | sort ) )
        if [[ ${#compressed_wav_file_list[@]} -ne ${MINUTES_PER_DAY}  ]]; then
            wd_logger 1 "ERROR: grape_repair_band_bad_compressed_files() failed to leave ${compressed_wav_file_dir} with the expected ${MINUTES_PER_DAY} .wv files"
            return  ${GRAPE_ERROR_RETURN_REPAIR_FAILED}
        fi
    fi

    wd_logger 1 "Creating one 24 hour, 10 hz wav file ${output_10sps_wav_file} from ${#compressed_wav_file_list[@]} .wv files..."
    local sox_log_file_name="${compressed_wav_file_dir}/sox.log"
    ulimit -n 2048    ### sox will open 1440+ files, so up the open file limit
    ### Write to a temporary name and rename only once sox has succeeded AND produced a full day.  This run
    ### takes 5-30 minutes inside WD's cgroup, so it WILL be killed part way through by an ordinary
    ### 'systemctl restart wsprdaemon'; writing straight to the final name is what turned each of those
    ### kills into a permanently truncated file that nothing ever rebuilt.  The rename is atomic and within
    ### the same directory, so the final name only ever appears complete.
    ### '-t wav' is required because the output is written to a '.partial' name: sox picks the output
    ### format from the file extension, and without it every run dies instantly with
    ### "sox FAIL formats: no handler for file extension `partial'", so no 24 hour wav is ever built.
    nice -n 19 sox ${compressed_wav_file_list[@]} --encoding float --bits 32 -t wav ${partial_output_file} rate 10 >& ${sox_log_file_name}
    rc=$? ; if (( rc )); then
        wd_logger 1 "ERROR: 'sox ...' => ${rc}:\n$(<${sox_log_file_name})"
        wd_rm "${partial_output_file}"
        return ${GRAPE_ERROR_SOX_FAILED}
    fi
    local created_file_bytes
    created_file_bytes=$( stat -c %s "${partial_output_file}" 2>/dev/null || echo 0 )
    if (( created_file_bytes < full_day_sample_bytes )); then
        ### sox returned 0 but did not produce a whole day, so something upstream is short.  Do not publish it.
        wd_logger 1 "ERROR: 'sox ...' reported success but wrote only ${created_file_bytes} bytes, short of the ${full_day_sample_bytes} bytes a full day holds, so ${output_10sps_wav_file} was NOT created"
        wd_rm "${partial_output_file}"
        return ${GRAPE_ERROR_SOX_FAILED}
    fi
    mv "${partial_output_file}" "${output_10sps_wav_file}"
    rc=$? ; if (( rc )); then
        wd_logger 1 "ERROR: 'mv ${partial_output_file} ${output_10sps_wav_file}' => ${rc}"
        wd_rm "${partial_output_file}"
        return ${GRAPE_ERROR_SOX_FAILED}
    fi
    if [[ -z  ${sox_log_file_name} ]]; then
        wd_logger 1 "Created ${output_10sps_wav_file}, but sox reported:\n$(< ${sox_log_file_name})"
    else
        wd_logger 1 "Created ${output_10sps_wav_file}"
    fi
    grape_create_chart ${output_10sps_wav_file}
    return 1
}

##########################################################################################################################################################
########## GRAPE carrier strip charts ####################################################################################################################
##########################################################################################################################################################

### Given the path of a 24_hour_10sps_iq.wav, create (or refresh) its strip chart PNG + JSON under GRAPE_CHARTS_WWW_DIR.
### The wav path has the form  .../wav-archive/<DATE>/<REPORTER>_<GRID>/<RECEIVER>@<PSWS_ID>/<BAND>/24_hour_10sps_iq.wav
### Returns: 0 => chart is up to date (created now or already current), 1 => charts disabled, > 1 => error
function grape_create_chart() {
    local wav_file_path=$1

    if [[ ${GRAPE_CHARTS_ENABLED} != "yes" ]]; then
        wd_logger 2 "GRAPE_CHARTS_ENABLED=${GRAPE_CHARTS_ENABLED}, so not charting ${wav_file_path}"
        return 1
    fi
    if [[ ! -f ${wav_file_path} ]]; then
        wd_logger 1 "ERROR: can't find ${wav_file_path}"
        return 2
    fi
    local band_dir=${wav_file_path%/*}
    local dir_path_list=( ${band_dir//\// } )
    if (( ${#dir_path_list[@]} < 4 )); then
        wd_logger 1 "ERROR: path ${wav_file_path} is too short to contain DATE/REPORTER/RECEIVER/BAND"
        return 3
    fi
    local chart_base_path="${GRAPE_CHARTS_WWW_DIR}/${dir_path_list[-4]}/${dir_path_list[-3]}/${dir_path_list[-2]}/${dir_path_list[-1]}"
    if [[ -s ${chart_base_path}.json && ${chart_base_path}.json -nt ${wav_file_path} ]]; then
        wd_logger 2 "Chart ${chart_base_path}.png is already current"
        return 0
    fi
    mkdir -p ${chart_base_path%/*}
    local chart_log_file="${GRAPE_CHARTS_ROOT_DIR}/grape-strip-chart.log"
    wd_logger 1 "Creating chart ${chart_base_path}.png from ${wav_file_path}"
    GRAPE_CHARTS_TZ="${GRAPE_CHARTS_TZ}" nice -n 19 python3 ${GRAPE_CHART_PYTHON_CMD} ${wav_file_path} ${chart_base_path} >> ${chart_log_file} 2>&1
    local rc=$?
    if (( rc )); then
        wd_logger 1 "ERROR: 'python3 ${GRAPE_CHART_PYTHON_CMD} ${wav_file_path} ${chart_base_path}' => ${rc}:\n$(tail -n 5 ${chart_log_file})"
        return 4
    fi
    return 0
}

### Copies the viewer page into the www dir if it has changed and rebuilds manifest.json, which the page reads to learn what charts exist
function grape_charts_update_manifest() {
    if [[ ${GRAPE_CHARTS_ENABLED} != "yes" ]]; then
        return 1
    fi
    mkdir -p ${GRAPE_CHARTS_WWW_DIR}
    if [[ ! -f ${GRAPE_CHARTS_WWW_DIR}/index.html || ${GRAPE_CHARTS_INDEX_HTML_SRC} -nt ${GRAPE_CHARTS_WWW_DIR}/index.html ]]; then
        cp -p ${GRAPE_CHARTS_INDEX_HTML_SRC} ${GRAPE_CHARTS_WWW_DIR}/index.html
        wd_logger 1 "Installed ${GRAPE_CHARTS_INDEX_HTML_SRC} as ${GRAPE_CHARTS_WWW_DIR}/index.html"
    fi
    local manifest_log_file="${GRAPE_CHARTS_ROOT_DIR}/grape-charts-manifest.log"
    python3 ${GRAPE_CHARTS_MANIFEST_PYTHON_CMD} ${GRAPE_CHARTS_WWW_DIR} >> ${manifest_log_file} 2>&1
    local rc=$?
    if (( rc )); then
        wd_logger 1 "ERROR: 'python3 ${GRAPE_CHARTS_MANIFEST_PYTHON_CMD} ${GRAPE_CHARTS_WWW_DIR}' => ${rc}:\n$(tail -n 5 ${manifest_log_file})"
        return 2
    fi
    wd_logger 2 "Updated ${GRAPE_CHARTS_WWW_DIR}/manifest.json"
    return 0
}

### '-K'  Charts every 24_hour_10sps_iq.wav under the wav-archive which has no current chart, then refreshes the manifest.
### Called by grape_uploader() after it has created the day's 24 hour wav files.  Returns the number of new charts created.
function grape_create_all_charts() {
    if [[ ${GRAPE_CHARTS_ENABLED} != "yes" ]]; then
        wd_logger 2 "GRAPE_CHARTS_ENABLED=${GRAPE_CHARTS_ENABLED}, so no charts are created"
        return 0
    fi
    local wav_file_list=( $( find -L ${GRAPE_WAV_ARCHIVE_ROOT_PATH} -mindepth 5 -maxdepth 5 -type f -name ${GRAPE_24_HOUR_10_HZ_WAV_FILE_NAME} 2>/dev/null | sort ) )
    wd_logger 2 "Found ${#wav_file_list[@]} 24 hour wav files to check for charts"
    local new_chart_count=0
    local wav_file_path
    for wav_file_path in ${wav_file_list[@]} ; do
        local dir_path_list=( ${wav_file_path//\// } )
        local chart_json="${GRAPE_CHARTS_WWW_DIR}/${dir_path_list[-5]}/${dir_path_list[-4]}/${dir_path_list[-3]}/${dir_path_list[-2]}.json"
        if [[ -s ${chart_json} && ${chart_json} -nt ${wav_file_path} ]]; then
            continue
        fi
        if grape_create_chart ${wav_file_path} ; then
            (( ++new_chart_count ))
        fi
    done
    ### Charts are also created one at a time by grape_create_chart() as each 24 hour wav is finished, and that path doesn't touch the
    ### manifest.  So refresh the manifest whenever a chart is newer than it, not just when this sweep is the one which created it.
    ### The last test installs a viewer page which a WD upgrade has just replaced, on a site where no chart has changed since.
    local manifest_file="${GRAPE_CHARTS_WWW_DIR}/manifest.json"
    if (( new_chart_count )) || [[ ! -s ${manifest_file} ]] \
       || [[ -n $( find ${GRAPE_CHARTS_WWW_DIR} -mindepth 4 -maxdepth 4 -name '*.json' -newer ${manifest_file} -print -quit 2>/dev/null ) ]] \
       || [[ ${GRAPE_CHARTS_INDEX_HTML_SRC} -nt ${GRAPE_CHARTS_WWW_DIR}/index.html ]]; then
        grape_charts_update_manifest
    fi
    wd_logger 1 "Created ${new_chart_count} new charts"
    return ${new_chart_count}
}

### Spawned by the watchdog daemon when GRAPE_PSWS_ID is defined and GRAPE_CHARTS_ENABLED == "yes".
### Serves GRAPE_CHARTS_WWW_DIR with python's built-in static file server and restarts it if it ever exits.
function grape_charts_web_daemon() {
    local root_dir=$1

    mkdir -p ${root_dir} ${GRAPE_CHARTS_WWW_DIR}
    cd ${GRAPE_CHARTS_WWW_DIR}
    setup_verbosity_traps
    grape_charts_update_manifest
    wd_logger 1 "Starting: serving ${GRAPE_CHARTS_WWW_DIR} at http://${GRAPE_CHARTS_BIND}:${GRAPE_CHARTS_PORT}/"
    while true; do
        python3 -m http.server ${GRAPE_CHARTS_PORT} --bind ${GRAPE_CHARTS_BIND} >> ${root_dir}/http.server.log 2>&1
        wd_logger 1 "ERROR: 'python3 -m http.server ${GRAPE_CHARTS_PORT} --bind ${GRAPE_CHARTS_BIND}' => $?.  Restarting it in 30 seconds"
        wd_sleep 30
    done
}

### To execute this from the command line run:  'WD -g "C <YYYYMMDD>"
### Searches all receivers and bands under 'date' for 24h wav files and creates them if needed
### Returns:  0 if date is today UTC or no 24 wav files were created, < 0 if there is an error, > 0 is the count of newly created wav files
function grape_create_24_hour_wavs() {
    local archive_date=$1

    if [[ "${archive_date}" == "h" ]]; then
        wd_logger 1 "usage: -s yyyymmdd"
        return 0
    fi
    local current_date
    TZ=UTC printf -v current_date "%(%Y%m%d)T"
    if [[ ${archive_date} ==  ${current_date} ]] ; then
        wd_logger 2 "Skipping create for current UTC day ${current_date}"
        return -1
    fi

    local date_root_dir="${GRAPE_WAV_ARCHIVE_ROOT_PATH}/${archive_date}"

    if [[  ! -d ${date_root_dir} ]]; then
        wd_logger 1 "ERROR: can't find ${date_root_dir}"
        return -2
    fi
    local new_wav_count=0
    local return_code=0
    local band_dir_list=( $( find -L ${date_root_dir} -mindepth 3 -type d  -regex '.*/\(WWV\|CHU\|K_BEACON\).*' | awk -F_ '{print $(NF-1), $NF, $0}' | sort -k1,1r -k2,2n  | cut -d' ' -f3) )
    wd_logger 2 "found ${#band_dir_list[@]} bands"
    for band_dir in ${band_dir_list[@]} ; do
        wd_logger 2 "create 24 hour wav file in ${band_dir}"
        local rc
        grape_create_wav_file ${band_dir}
        rc=$?
        if grape_return_code_is_error ${rc} ; then
             wd_logger 1 "ERROR: 'grape_create_wav_file ${band_dir}' => ${rc}"
        elif (( ! rc )); then
            wd_logger 2 "Found existing 24h.wav file for band ${band_dir}"
        else
            wd_logger 1 "Created a new 24h.wav file for band ${band_dir}"
            (( ++ new_wav_count ))
        fi
    done
    
    if (( return_code <  0 )); then
         wd_logger 1 "Returning error ${return_code} after one or more errors.  Also created ${new_wav_count} new wav files"
         return ${return_code}
    fi
    if (( new_wav_count )); then
        wd_logger 1 "Returning ${new_wav_count} new wav files"
    fi
     return ${new_wav_count}  
}

### '-c' Searches all the date/... directories (except for today), repairs if necessary by adding silence files, then creates a 24 hour 10 hz wav file.
###  Returns:  number of newly created wav files, or -1 if there was a failure
function grape_create_all_24_hour_wavs(){
    local current_date
    TZ=UTC printf -v current_date "%(%Y%m%d)T"    ### This assigns the output of printf to the bash variable we declared on the line above

    local return_code=0
    local new_wav_count=0

    local wav_archive_dates_dir_list=( $( find -L ${GRAPE_WAV_ARCHIVE_ROOT_PATH} -mindepth 1 -maxdepth 1 -type d -printf '%p\n' | sort)  )
    local wav_archive_date
    for wav_archive_date in ${wav_archive_dates_dir_list[@]##*/} ; do
        local rc
        if [[ ${wav_archive_date} ==  ${current_date} ]] ; then
            wd_logger 2 "Skipping grape_create_24_hour_wavs for current UTC day ${current_date}"
            rc=0
        else
            grape_create_24_hour_wavs ${wav_archive_date}
            rc=$?
            if [[ ${rc} -lt 0 ]]; then
                wd_logger 1 "ERROR: 'grape_create_24_hour_wavs ${wav_archive_date}' => ${rc}"
                return_code=${rc}
            elif [[  ${rc} -gt 0 ]]; then
                wd_logger 1 "'grape_create_24_hour_wavs ${wav_archive_date}' encountered no errors and created ${rc} new wav files"
                (( new_wav_count +=  ${rc} ))
            else
                wd_logger 2 "'grape_create_24_hour_wavs ${wav_archive_date}' encountered no errors, nor did it need to create one or more wav files"
            fi
        fi
    done

    if [[ ${return_code} -lt 0 ]]; then
         wd_logger 1 "Returning error ${return_code} after one or more errors.  Also created ${new_wav_count} new wav files"
         return ${return_code}
    fi
     wd_logger 2 "Returning ${new_wav_count} new wav files"
     return ${new_wav_count}
}

declare LAST_HHMM="0"                       ### Check and upload each time WD is started
declare GRAPE_UPLOAD_START_HHMM="0005"      ### Then check and upload each dat at 5 minutes after UTC 00:00

function grape_upload_service() {
    local grape_uploads_enabled="no"
    get_config_file_variable grape_uploads_enabled "GRAPE_UPLOADS_ENABLED"
    if [[ ${grape_uploads_enabled} == "yes" ]]; then
        grape_uploader
    fi
}

### '-a' This function is called every odd 2 minutes by the watchdog daemon.
function grape_uploader() {
    local force_upload="${1-no}"

    if [[ -z "${GRAPE_PSWS_ID-}"  ]]; then
         wd_logger 2 "GRAPE uploads are not enabled, so do nothing"
         return 0
    fi
    local current_hhmm=$(TZ=UTC printf "%(%H%M)T")
    if [[ ${force_upload} == "no" && ${LAST_HHMM} == "0" || ${current_hhmm} != ${LAST_HHMM} && ${current_hhmm} == ${GRAPE_UPLOAD_START_HHMM} ]]; then
        wd_logger 1 "Skipping upload at current HHMM = ${current_hhmm}, LAST_HHMM = ${LAST_HHMM}"
        LAST_HHMM=${current_hhmm}
        return 0
    fi
    LAST_HHMM=${current_hhmm}
    wd_logger 1 "Checking for new 24h.wav files to upload"
    local rc

    grape_create_all_24_hour_wavs
    rc=$? ; if (( rc )); then
        wd_logger 1 "There were ${rc} new 24h.wav files created"
    else
        wd_logger 1 "There were no new 24h.wav files created"
    fi
    grape_create_all_charts            ### Charts any 24h.wav which has no current strip chart and refreshes the web page's manifest
    grape_upload_all_local_wavs
    rc=$? ; if (( rc )); then
        wd_logger 1 "ERROR: grape_upload_all_local_wavs => ${rc}"
    else
        wd_logger 2 "Successful upload of  ${rc} new 24h.wav files"
    fi
    return ${rc}
}

### This is the number of minutes between checks for new files to upload. Default to 30 minutes
### This should always be an even number of minutes
declare GRAPE_UPLOAD_CHECK_RATE=${GRAPE_UPLOAD_CHECK_RATE-30}

### Spawned by watchdog daemon at startup and every odd minute it looks for wav files to compress and archive 

function grape_upload_daemon() {
    local root_dir=$1

    mkdir -p ${root_dir}
    cd ${root_dir}

    wd_logger 1 "Starting in $PWD"

    setup_verbosity_traps          ### So we can increment and decrement verbosity without restarting WD
    while true; do
        wd_logger 1 "Checking for new .wav files to upload"
        grape_uploader

        local sleep_seconds=$(seconds_until_next_odd_minute)
        (( sleep_seconds += GRAPE_UPLOAD_CHECK_RATE * 60 ))
        wd_logger 1 "Sleeping ${sleep_seconds} seconds in order to wake up at $(date -d "${sleep_seconds} seconds" +%T), the odd minute ${GRAPE_UPLOAD_CHECK_RATE} minutes from now"
        wd_sleep  ${sleep_seconds}
    done
}

### Calculate the semitones needed by sox to change freqeuncies in a file:  "soc in.wav out.wav pitch PITCH_CHANGE_IN_CENTS"
### Where PITCH_CHANGE_IN_CENTS can be computed by:  'bc -l <<< "l(NEW_FREQ/OLD_FREQ) / l(2) * 12 *100 "'
### But I don't know if soc can change the pitch of 800 to 10 hz.

function grape_print_usage() {
    wd_logger 1 "GRAPE sub-menu commands:
    -C YYYYMMDD      Create 24 hour 10 Hz wav files for all bands 
    -S YYYYMMDD      Show the status of the files in that tree
    -R YYYYMMDD      Repair the directory tree by filling in missing minutes with soft links to ~/wsprdaemon/one-minute-silent-float.wv
    -a               Search for 24h.wav files.  If a new 24h.wav is created, then upload it to wsprdaemon.org.  Called by the watchdog_daemon()
    -c               Create 10 Hz wav files for each band for all dates from the 1440 compressed .wv files in each band
    -K               Create carrier strip charts for all 24_hour_10sps_iq.wav files which don't yet have one, then refresh the chart web page
    -p               Purge all empty date trees
    -r               Repair all date trees
    -t               Show status of all the date trees
    -u               Upload all of the local 24_hour_10sps_iq.wav files to the grape@wsprdaemon.org account
    -d [a|i|z|s]     systemctl commands for daemon (a=start, i=install and enable, z=disable and stop, s=show status"
}

function grape_menu() {
    case ${1--h} in
        -a)
            grape_uploader "yes"        ### Force the upload to run
            ;;
        -c)
            grape_create_all_24_hour_wavs
            ;;
        -C)
            grape_create_24_hour_wavs ${2-h}
            ;;
        -K)
            grape_create_all_charts
            ;;
        -S)
            grape_get_date_status ${2-h}
            ;;
        -R)
            grape_repair_date_wvs ${2-h}
            ;;
        -p)
            grape_check_auto_upload
            ;;
        -P)
            grape_purge_all_empty_date_trees
            ;;
        -t)
            grape_show_all_dates_status
            ;; 
        -r) 
            grape_repair_all_dates_wvs
            ;;
        -u)
            grape_upload_all_local_wavs
            ;;
       -a)
            spawn_daemon ${2-0}
            ;;
        -A)
            ### If this is installed as a Pi daemon by '-d a', the systemctl system will execute '-A'.  
            spawn_daemon ${KIWI_STARTUP_DELAY_SECONDS}
            ;;
        -z)
            kill_daemon
            ;;
        -s)
            get_daemon_status
            ;;
        -d)
            startup_daemon_control ${2-h}
            ;;
        -h)
            grape_print_usage
            ;;
        *)
            wd_logger 1 "ERROR: flag '$1' is not valid"
            ;;
    esac
    return 0
}

### The strip charts' local-time axis falls back to the zone at the reporter's grid, which needs the python package 'timezonefinder'.
### Recent releases of it require numpy 2, which must never be forced onto a server whose numpy came from Debian/Ubuntu (digital_rf
### and soundfile depend on it), so: pin numpy to the version already installed and let pip pick a compatible timezonefinder, or
### fail harmlessly.  Without it the charts show solar time for the grid.  Tried once per server; delete the marker file to retry.
declare -r GRAPE_TIMEZONEFINDER_MARKER_FILE="${WSPRDAEMON_ROOT_DIR}/.timezonefinder-install-attempted"
function grape_install_timezonefinder() {
    if python3 -c "import timezonefinder" >& /dev/null; then
        wd_logger 2 "Python package timezonefinder is installed"
        return 0
    fi
    if [[ -f ${GRAPE_TIMEZONEFINDER_MARKER_FILE} ]]; then
        wd_logger 2 "timezonefinder is not installed and an install was already attempted on $(< ${GRAPE_TIMEZONEFINDER_MARKER_FILE}), so the charts use solar time at the grid"
        return 1
    fi
    TZ=UTC printf "%(%Y-%m-%d %H:%M:%S)T UTC\n" > ${GRAPE_TIMEZONEFINDER_MARKER_FILE}
    local numpy_version=$( python3 -c "import numpy; print(numpy.__version__)" 2>/dev/null )
    if [[ -z "${numpy_version}" ]]; then
        wd_logger 1 "NOTE: python numpy is not installed, so not installing the optional timezonefinder package; charts will show solar time at the grid"
        return 1
    fi
    local pip3_extra_args=""
    if ls /usr/lib/python3*/EXTERNALLY-MANAGED >& /dev/null; then
        pip3_extra_args="--break-system-packages"
    fi
    local constraints_file="${WSPRDAEMON_TMP_DIR}/timezonefinder-constraints.txt"
    echo "numpy==${numpy_version}" > ${constraints_file}
    local pip_log_file="${WSPRDAEMON_TMP_DIR}/timezonefinder-pip.log"
    wd_logger 1 "Installing the optional python package timezonefinder (numpy pinned to the installed ${numpy_version}) for the strip charts' grid-to-timezone lookup"
    if sudo pip3 install ${pip3_extra_args} --constraint ${constraints_file} timezonefinder >& ${pip_log_file} \
        && python3 -c "from timezonefinder import TimezoneFinder; assert TimezoneFinder().timezone_at(lng=-122.4, lat=37.8) == 'America/Los_Angeles'" >& /dev/null; then
        wd_logger 1 "Installed python package timezonefinder"
        return 0
    fi
    wd_logger 1 "NOTE: could not install a timezonefinder release compatible with the installed numpy ${numpy_version}, so the strip charts will show solar time at the reporter's grid (or set GRAPE_CHARTS_TZ in WD.conf).  pip said: $( tail -n 3 ${pip_log_file} 2>/dev/null | tr '\n' '|' )"
    return 1
}

### grape_init() is run during wd_setup, so I/O goes to the user terminal so they can be asked for their PSWS token/password
function grape_init() {
    wd_logger 2 "Starting"
    if [[ -z "${GRAPE_PSWS_ID-}" ]]; then
        if [[ -z "${PSWS_STATION_ID-}" || -z "${PSWS_DEVICE_ID-}" ]]; then
            wd_logger 2 "This WD server is not configured to upload to the HamSCI GRAPE server"
            return 0
        fi
        GRAPE_PSWS_ID="${PSWS_STATION_ID}_${PSWS_DEVICE_ID}"
        wd_logger 1 "The GRAPE_PSWS_ID=${GRAPE_PSWS_ID} is being derived from PSWS_STATION_ID=${PSWS_STATION_ID} and PSWS_DEVICE_ID=${PSWS_DEVICE_ID}"
    fi

    local rc
    sudo mkdir -p ${GRAPE_TMP_DIR}
    rc=$? ; if (( rc )); then
        wd_logger 1 "ERROR: can't create ${GRAPE_TMP_DIR} "
        return ${rc}
    fi
    sudo chown "${USER}:$(id -gn)" ${GRAPE_TMP_DIR}

    if ! install_debian_package "libhdf5-dev" ; then
        wd_logger 1 "ERROR: 'install_debian_package libhdf5-dev' => $?"
        exit 1
    fi

    local grape_python_package_list=( "digital_rf" "soundfile" "matplotlib" )     ### matplotlib draws the GRAPE carrier strip charts
    local python_package
    for python_package in ${grape_python_package_list[@]}; do
        install_python_package "${python_package}"
        rc=$? ; if (( rc )); then
            wd_logger 1 "ERROR: can't install python package '${python_package}'"
            return ${rc}
        fi
    done

    grape_install_timezonefinder       ### Optional: never fails WD, tried once per server

    if ! [[ -d ~/.ssh ]] || ! find -L ~/.ssh -type f -name '*.pub' | grep -q .; then
        wd_logger 1 "This server has no ssh private/public keypair which is needed for the GRAPE upload service to run.  So running 'ssh-keygen' to create them"
        ssh-keygen -t ed25519 -C "$(whoami)@$(hostname)" -f ~/.ssh/id_ed25519 -N ""    ### Non-interactive: a bare 'ssh-keygen' prompts for the file and passphrase, which hangs WD startup
        rc=$? ;  if (( rc )); then
            wd_logger 1 "ERROR:  GRAPE_PSWS_ID is configured, but this server has no ssh public key needed for this feature to run"
            return ${rc}
        fi
    fi

    ### Verifies auto login is enabled OR prompts for the user to enter the token/passsword for this <SITE_ID>
    grape_check_auto_upload
    rc=$? ; if (( rc )); then
        wd_logger 2 "ERROR: ftp auto-login which is needed for our sftp uploads doesn't work"
    fi
    return $rc
}

grape_init || true   ### Suppress error message if any
return 0