diff --git a/README.md b/README.md index 800c957..d1e3b7f 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ **SkywarnPlus** is an advanced software solution tailored for Asterisk/app_rpt nodes. It is designed to provide important information about local government-issued alerts in the United States, thereby broadening the scope and functionality of your node. By intelligently integrating local alert data, SkywarnPlus brings a new layer of relevance and utility to your existing system. **SkywarnPlus** works with all major distributions, including AllstarLink, HAMVOIP, myGMRS, GMRS Live, and more. - [Installation](#installation) - - [**Instructional Video**](#instructional-video) - - [Written Instructions](#written-instructions) + - [Automated Installation](#automated-installation) + - [Configuration](#configuration) - [TimeType Configuration](#timetype-configuration) - [Tail Messages](#tail-messages) - [Courtesy Tones](#courtesy-tones) @@ -20,7 +20,7 @@ - [Dynamic Tone Switching](#dynamic-tone-switching) - [Consistent Filenames](#consistent-filenames) - [CW / Voice IDs](#cw--voice-ids) - - [Configuration](#configuration) + - [Configuration](#configuration-1) - [Pushover Integration](#pushover-integration) - [SkyControl](#skycontrol) - [Usage](#usage) @@ -48,13 +48,14 @@ - [County Identifiers](#county-identifiers) - [Automated Setup using `CountyIDGen.py`](#automated-setup-using-countyidgenpy) - [Manual Setup](#manual-setup) +- [Manual Installation](#manual-installation) - [Testing](#testing) - [Debugging](#debugging) - [Maintenance and Bug Reporting](#maintenance-and-bug-reporting) - [Contributing](#contributing) - [Frequently Asked Questions](#frequently-asked-questions) - - [I just installed SkywarnPlus on my HAMVOIP node, why is it giving me errors?](#i-just-installed-skywarnplus-on-my-hamvoip-node-why-is-it-giving-me-errors) - - [Why do I see depreciation warnings when installing SWP on my HAMVOIP node?](#why-do-i-see-depreciation-warnings-when-installing-swp-on-my-hamvoip-node) + - [I just installed SkywarnPlus on my HamVoIP node, why is it giving me errors?](#i-just-installed-skywarnplus-on-my-hamvoip-node-why-is-it-giving-me-errors) + - [Why do I see depreciation warnings when installing SkywarnPlus on my HamVoIP node?](#why-do-i-see-depreciation-warnings-when-installing-skywarnplus-on-my-hamvoip-node) - [Can I change the crontab interval to something other than 60 seconds?](#can-i-change-the-crontab-interval-to-something-other-than-60-seconds) - [What does "with multiples" mean?](#what-does-with-multiples-mean) - [Why is SkywarnPlus saying the same thing every 60 seconds?](#why-is-skywarnplus-saying-the-same-thing-every-60-seconds) @@ -148,138 +149,56 @@ SkywarnPlus supports all 128 alert types included in the [NWS v1.2 API](https:// # Installation -## **[Instructional Video](https://youtu.be/QyccjEZj20E)** - -[![Instructional Video](https://img.youtube.com/vi/QyccjEZj20E/maxresdefault.jpg)](https://youtu.be/QyccjEZj20E) - -## Written Instructions -SkywarnPlus is recommended to be installed at the `/usr/local/bin/SkywarnPlus` location on both Debian and Arch systems. - -Follow the steps below to install: - -1. **Dependencies** - - Install the required dependencies using the following commands: - - 1. **Debian 11 and Older (ASL 1 & ASL 2)** - - ```bash - # EXECUTE ONE LINE AT A TIME - apt install unzip python3 python3-pip ffmpeg - pip3 install ruamel.yaml requests python-dateutil pydub - ``` - - 2. **Debian 12 and Newer (ASL 3+)** - - Beginning around Debian 12 "Bookworm", installing Python packages via `pip` will have Debian throw a fit about package managers and externally managed virtual environments. Use these commands instead on newer distros. - - ```bash - # EXECUTE ONE LINE AT A TIME - apt install unzip python3 python3-pip ffmpeg - apt install python3-ruamel.yaml python3-requests python3-dateutil python3-pydub - ``` - - 3. **Arch (HAMVOIP)** - - It is a good idea to first update your HAMVOIP system using **Option 1** in the HAMVOIP menu before installing the dependencies. - - ```bash - # EXECUTE ONE LINE AT A TIME - pacman -S ffmpeg - wget https://bootstrap.pypa.io/pip/3.5/get-pip.py - python get-pip.py - pip install requests python-dateutil pydub - pip install ruamel.yaml==0.15.100 - ``` - -2. **Download SkywarnPlus** - - Download the latest release of SkywarnPlus from GitHub - - ```bash - cd /usr/local/bin - wget https://github.com/Mason10198/SkywarnPlus/releases/latest/download/SkywarnPlus.zip - unzip SkywarnPlus.zip - rm SkywarnPlus.zip - ``` - -3. **Configure Permissions** - - The scripts must be made executable. Use the chmod command to change the file permissions: - - ```bash - cd SkywarnPlus - chmod +x *.py - ``` - - **NOTE: ONLY if you are using ASL3 or newer**, then you must additionally execute the following commands to allow the `asterisk` user access to SkywarnPlus files. - - ```bash - chown -R asterisk:asterisk /usr/local/bin/SkywarnPlus/ - chmod -R u+rwx /usr/local/bin/SkywarnPlus/ - ``` - -4. **Edit Configuration** - - SkywarnPlus was designed with customization in mind, making it possible to fit nearly any usage scenario you can throw at it. However, this can make the configuration seem a bit daunting. Be patient, and when in doubt, read the documentation. - - Edit the [config.yaml](config.yaml) file according to your needs. This is where you will enter your NWS codes, enable/disable specific functions, etc. - +## Automated Installation +1. Access the terminal of your node and execute the following command as `root`: ```bash - nano config.yaml + bash -c "$(curl -fsSL https://raw.githubusercontent.com/Mason10198/SkywarnPlus/main/swp-install)" ``` +2. Continue with [Configuration](#configuration). - You can find your county codes in the [CountyCodes.md](CountyCodes.md) file included in this repository. Navigate to the file and look for your state and then your specific county to find the associated County Code you'll use in SkywarnPlus to poll for alerts. - - **IMPORTANT**: YOU WILL MISS ALERTS IF YOU USE A **ZONE** CODE. DO NOT USE **ZONE** CODES UNLESS YOU KNOW WHAT YOU ARE DOING. +To install manually, see [Manual Installation](#manual-installation). - According to the official [NWS API documentation](https://www.weather.gov/documentation/services-web-api): +## Configuration - > "For large scale or longer lasting events, such as snow storms, fire threat, or heat events, alerts are issued - > by NWS public forecast zones or fire weather zones. These zones differ in size and can cross county - > boundaries." +SkywarnPlus was designed with customization in mind, making it possible to fit nearly any usage scenario you can throw at it. However, this can make the configuration seem a bit daunting. Be patient, and when in doubt, read the documentation. - > "...county based alerts are not mapped to zones but zone based alerts are mapped to counties. The effect this has is for requests such as: - > - > https://api.weather.gov/alerts/active?zone=MDZ013 - > - > or - > - > https://api.weather.gov/alerts?zone=MDZ013 - > - > Will not contain county based products. However requests such as: - > - > https://api.weather.gov/alerts?zone=MDC033 - > - > or - > - > https://api.weather.gov/alerts/active?zone=MDC033 - > - > Will contain all county based alerts and all zone based alerts that are associated to the county or counties requested. If there are multiple zones associated with that county, the response from API will include all alerts for those zones." +Edit the [config.yaml](config.yaml) file according to your needs. This is where you will enter your NWS codes, enable/disable specific functions, etc. - [This information was obtained from this document.](https://www.weather.gov/media/documentation/docs/NWS_Geolocation.pdf) +```bash +nano config.yaml +``` - This means that if you use a County code, you will receive all alerts for both your County **AND** your Zone - but if you use a Zone code, you will **ONLY** receive alerts that cover the entire Zone, and none of the alerts specific to your County. + You can find your county codes in the [CountyCodes.md](CountyCodes.md) file included in this repository. Navigate to the file and look for your state and then your specific county to find the associated County Code you'll use in SkywarnPlus to poll for alerts. -5. **Crontab Entry** +**IMPORTANT**: YOU WILL MISS ALERTS IF YOU USE A **ZONE** CODE. DO NOT USE **ZONE** CODES UNLESS YOU KNOW WHAT YOU ARE DOING. - 1. **ASL1, ASL2, and HamVoIP** +According to the official [NWS API documentation](https://www.weather.gov/documentation/services-web-api): - Add a crontab entry to call SkywarnPlus on an interval **as the `root` user**. +> "For large scale or longer lasting events, such as snow storms, fire threat, or heat events, alerts are issued +> by NWS public forecast zones or fire weather zones. These zones differ in size and can cross county +> boundaries." - ```bash - echo '* * * * * root /usr/local/bin/SkywarnPlus/SkywarnPlus.py' > /etc/cron.d/SkywarnPlus - ``` - - 1. **ASL3** +> "...county based alerts are not mapped to zones but zone based alerts are mapped to counties. The effect this has is for requests such as: +> +> https://api.weather.gov/alerts/active?zone=MDZ013 +> +> or +> +> https://api.weather.gov/alerts?zone=MDZ013 +> +> Will not contain county based products. However requests such as: +> +> https://api.weather.gov/alerts?zone=MDC033 +> +> or +> +> https://api.weather.gov/alerts/active?zone=MDC033 +> +> Will contain all county based alerts and all zone based alerts that are associated to the county or counties requested. If there are multiple zones associated with that county, the response from API will include all alerts for those zones." - Add a crontab entry to call SkywarnPlus on an interval **as the `asterisk` user** +[This information was obtained from this document.](https://www.weather.gov/media/documentation/docs/NWS_Geolocation.pdf) - ```bash - echo '* * * * * asterisk /usr/local/bin/SkywarnPlus/SkywarnPlus.py' > /etc/cron.d/SkywarnPlus - ``` - - This command will execute SkywarnPlus (poll NWS API for data) every 60 seconds. For slower systems, or systems with several counties and/or advanced configurations, the interval may need to be increased. +This means that if you use a County code, you will receive all alerts for both your County **AND** your Zone - but if you use a Zone code, you will **ONLY** receive alerts that cover the entire Zone, and none of the alerts specific to your County. **NOTE:** @@ -832,6 +751,93 @@ Alerting: - VAC683: "County10.wav" ``` +# Manual Installation +SkywarnPlus is recommended to be installed at the `/usr/local/bin/SkywarnPlus` location on both Debian and Arch systems. + +Follow the steps below to install: + +1. **Dependencies** + + Install the required dependencies using the following commands: + + 1. **Debian 11 and Older (ASL 1 & ASL 2)** + + ```bash + # EXECUTE ONE LINE AT A TIME + apt install unzip python3 python3-pip ffmpeg + pip3 install ruamel.yaml requests python-dateutil pydub + ``` + + 2. **Debian 12 and Newer (ASL 3+)** + + Beginning around Debian 12 "Bookworm", installing Python packages via `pip` will have Debian throw a fit about package managers and externally managed virtual environments. Use these commands instead on newer distros. + + ```bash + # EXECUTE ONE LINE AT A TIME + apt install unzip python3 python3-pip ffmpeg + apt install python3-ruamel.yaml python3-requests python3-dateutil python3-pydub + ``` + + 3. **Arch (HAMVOIP)** + + It is a good idea to first update your HAMVOIP system using **Option 1** in the HAMVOIP menu before installing the dependencies. + + ```bash + # EXECUTE ONE LINE AT A TIME + pacman -S ffmpeg + wget https://bootstrap.pypa.io/pip/3.5/get-pip.py + python get-pip.py + pip install requests python-dateutil pydub + pip install ruamel.yaml==0.15.100 + ``` + +2. **Download SkywarnPlus** + + Download the latest release of SkywarnPlus from GitHub + + ```bash + cd /usr/local/bin + wget https://github.com/Mason10198/SkywarnPlus/releases/latest/download/SkywarnPlus.zip + unzip SkywarnPlus.zip + rm SkywarnPlus.zip + ``` + +3. **Configure Permissions** + + The scripts must be made executable. Use the chmod command to change the file permissions: + + ```bash + cd SkywarnPlus + chmod +x *.py + ``` + + **NOTE: ONLY if you are using ASL3 or newer**, then you must additionally execute the following commands to allow the `asterisk` user access to SkywarnPlus files. + + ```bash + chown -R asterisk:asterisk /usr/local/bin/SkywarnPlus/ + chmod -R u+rwx /usr/local/bin/SkywarnPlus/ + ``` + +4. **Crontab Entry** + + 1. **ASL1, ASL2, and HamVoIP** + + Add a crontab entry to call SkywarnPlus on an interval **as the `root` user**. + + ```bash + echo '* * * * * root /usr/local/bin/SkywarnPlus/SkywarnPlus.py' > /etc/cron.d/SkywarnPlus + ``` + + 1. **ASL3** + + Add a crontab entry to call SkywarnPlus on an interval **as the `asterisk` user** + + ```bash + echo '* * * * * asterisk /usr/local/bin/SkywarnPlus/SkywarnPlus.py' > /etc/cron.d/SkywarnPlus + ``` + + This command will execute SkywarnPlus (poll NWS API for data) every 60 seconds. For slower systems, or systems with several counties and/or advanced configurations, the interval may need to be increased. + # Testing SkywarnPlus provides the ability to inject predefined alerts, bypassing the call to the NWS API. This feature is extremely useful for testing SkywarnPlus. @@ -910,11 +916,11 @@ If the spare time I put into the development of SkywarnPlus has helped you, plea # Frequently Asked Questions -### I just installed SkywarnPlus on my HAMVOIP node, why is it giving me errors? -HAMVOIP uses a very outdated version of Python which can cause some issues that ASL users do not experience. Carefully follow the installation inctructions line-by-line (do not copy/paste all commands at once) and try again. +### I just installed SkywarnPlus on my HamVoIP node, why is it giving me errors? +HamVoIP uses a very outdated version of Python which can cause some issues that ASL users do not experience. Carefully follow the installation inctructions line-by-line (do not copy/paste all commands at once) and try again. -### Why do I see depreciation warnings when installing SWP on my HAMVOIP node? -HAMVOIP uses a very outdated version of Python, and Python will display warnings asking you to update it. Unfortunately, Python cannot be upgraded on HAMVOIP and these warnings must be ignored. +### Why do I see depreciation warnings when installing SkywarnPlus on my HamVoIP node? +HamVoIP uses a very outdated version of Python, and Python will display warnings asking you to update it. Unfortunately, Python cannot be upgraded on HamVoIP and these warnings must be ignored. ### Can I change the crontab interval to something other than 60 seconds? Yes! You can run SkywarnPlus as frequently or infrequently as you wish. Be aware, whatever you set the interval to (X), there will be a delay of "up to" X minutes between the time an alert is issued by the NWS, and the time that SWP announces it. diff --git a/swp-install b/swp-install new file mode 100644 index 0000000..220eab4 --- /dev/null +++ b/swp-install @@ -0,0 +1,249 @@ +#!/bin/bash + +# swp-install by Mason Nelson +# =============================================================================== +# Script to install SkywarnPlus. This script will determine the system type (ASL1/2, ASL3, or HamVoIP), +# install the required dependencies, download the latest version of SkywarnPlus from GitHub, +# configure the necessary permissions, and set up a crontab entry to run SkywarnPlus at a specified interval. +# This script also checks if the SkywarnPlus directory already exists and asks for user confirmation to remove it before continuing. +# Please note that this script should be run as root. + +# This file is part of SkywarnPlus. +# SkywarnPlus 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. SkywarnPlus 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 SkywarnPlus. If not, see . + +clear + +print_divider() { + echo "========================================" +} + +print_notice() { + print_divider + echo "This script is designed to automate the installation of SkywarnPlus." + echo "Author: Mason Nelson" + echo "" + echo "This script will:" + echo " - Determine your system type (ASL1/2, ASL3, or HamVoIP)" + echo " - Install necessary dependencies" + echo " - Download the latest version of SkywarnPlus from GitHub" + echo " - Configure permissions" + echo " - Set up a crontab entry to run SkywarnPlus at specified intervals" + echo + echo "NOTE: This script is an installer only and will NOT automate configuration." + echo "Please edit the config.yaml file manually after installation." + print_divider + echo "Would you like to continue? (y/n) [y]:" + read -r CONTINUE + CONTINUE=${CONTINUE:-y} + if [ "$CONTINUE" != "y" ]; then + print_divider + echo "Installation aborted. Exiting." + print_divider + exit 1 + fi +} + +check_root() { + if [ "$EUID" -ne 0 ]; then + print_divider + echo "This script must be run as root. Exiting." + print_divider + exit 1 + fi +} + +determine_system_type() { + echo "Determining system type..." + if [ -f /etc/debian_version ]; then + . /etc/os-release + OS=$ID + VER=$VERSION_ID + ASTERISK_VERSION=$(asterisk -V) + if [[ "$ASTERISK_VERSION" =~ "Asterisk "([2-9][0-9]|[1-9][0-9]{2,}) ]]; then + SYSTEM_TYPE="ASL3" + else + SYSTEM_TYPE="ASL1/2" + fi + elif [ -f /etc/arch-release ]; then + OS=arch + VER=$(uname -r) + SYSTEM_TYPE="HamVoIP" + else + print_divider + echo "Unsupported OS. This script supports only Debian and Arch." + print_divider + exit 1 + fi +} + +confirm_system_type() { + print_divider + echo "Detected system type: $SYSTEM_TYPE." + print_divider + echo "Is this correct? Enter 'y' for yes or 'n' for no to override. [y]:" + read -r CONFIRMATION + CONFIRMATION=${CONFIRMATION:-y} + if [ "$CONFIRMATION" != "y" ]; then + print_divider + echo "Please enter the correct system type:" + echo "1 = ASL1/2" + echo "3 = ASL3" + echo "5 = HamVoIP" + print_divider + read -r SYSTEM_TYPE_INPUT + SYSTEM_TYPE_INPUT=${SYSTEM_TYPE_INPUT:-3} + case $SYSTEM_TYPE_INPUT in + 1) + SYSTEM_TYPE="ASL1/2" + ;; + 3) + SYSTEM_TYPE="ASL3" + ;; + 5) + SYSTEM_TYPE="HamVoIP" + ;; + *) + print_divider + echo "Invalid input. Exiting." + print_divider + exit 1 + ;; + esac + fi +} + +install_dependencies() { + print_divider + echo "Installing dependencies..." + if [ "$OS" = "debian" ]; then + apt update + if [ "$SYSTEM_TYPE" = "ASL1/2" ]; then + apt install -y unzip python3 python3-pip ffmpeg + pip3 install ruamel.yaml requests python-dateutil pydub + else + apt install -y unzip python3 python3-pip ffmpeg python3-ruamel.yaml python3-requests python3-dateutil python3-pydub + fi + elif [ "$OS" = "arch" ]; then + pacman -Syu --noconfirm + pacman -S --noconfirm ffmpeg + wget -q https://bootstrap.pypa.io/pip/3.5/get-pip.py + python get-pip.py + pip install requests python-dateutil pydub ruamel.yaml==0.15.100 + else + print_divider + echo "Unsupported OS version. Exiting." + print_divider + exit 1 + fi +} + +check_existing() { + if [ -d "/usr/local/bin/SkywarnPlus" ]; then + print_divider + echo "SkywarnPlus directory already exists. It must be removed to continue the installation." + echo "Do you want to remove it? Enter 'y' for yes or 'n' for no. [y]:" + print_divider + read -r REMOVE_CONFIRMATION + REMOVE_CONFIRMATION=${REMOVE_CONFIRMATION:-y} + if [ "$REMOVE_CONFIRMATION" != "y" ]; then + print_divider + echo "Installation aborted. Exiting." + print_divider + exit 1 + else + rm -rf /usr/local/bin/SkywarnPlus + fi + fi +} + +download_swp() { + print_divider + echo "Downloading SkywarnPlus..." + wget -q -P /usr/local/bin https://github.com/Mason10198/SkywarnPlus/releases/latest/download/SkywarnPlus.zip + unzip /usr/local/bin/SkywarnPlus.zip -d /usr/local/bin + rm /usr/local/bin/SkywarnPlus.zip +} + +configure_perms() { + print_divider + echo "Configuring permissions..." + chmod +x /usr/local/bin/SkywarnPlus/*.py + + if [ "$SYSTEM_TYPE" = "ASL3" ]; then + chown -R asterisk:asterisk /usr/local/bin/SkywarnPlus/ + chmod -R u+rwx /usr/local/bin/SkywarnPlus/ + fi +} + +setup_crontab() { + print_divider + echo "By default, a crontab entry will be added to trigger SkywarnPlus (check for alerts) every 1 minute." + echo + echo "If you would like to increase this interval, enter a different number of minutes." + echo "To disable the crontab entry and require manual execution, enter '0'." + echo "To keep the default 1 minute interval, press enter. [1]:" + print_divider + read -r CRONTAB_INTERVAL + CRONTAB_INTERVAL=${CRONTAB_INTERVAL:-1} + + if [ "$CRONTAB_INTERVAL" -eq 0 ]; then + if [ -f "/etc/cron.d/SkywarnPlus" ]; then + rm /etc/cron.d/SkywarnPlus + echo "Crontab entry removed. You will need to run SkywarnPlus manually." + else + echo "No existing crontab entry to remove. You will need to run SkywarnPlus manually." + fi + else + if [ "$SYSTEM_TYPE" = "ASL3" ]; then + CRONTAB_ENTRY="*/$CRONTAB_INTERVAL * * * * asterisk pgrep -f /usr/local/bin/SkywarnPlus/SkywarnPlus.py > /dev/null || /usr/local/bin/SkywarnPlus/SkywarnPlus.py" + else + CRONTAB_ENTRY="*/$CRONTAB_INTERVAL * * * * root pgrep -f /usr/local/bin/SkywarnPlus/SkywarnPlus.py > /dev/null || /usr/local/bin/SkywarnPlus/SkywarnPlus.py" + fi + + CRON_FILE="/etc/cron.d/SkywarnPlus" + if grep -Fxq "$CRONTAB_ENTRY" "$CRON_FILE" 2>/dev/null; then + echo "Crontab entry already exists. Skipping." + else + echo "$CRONTAB_ENTRY" > "$CRON_FILE" || { + print_divider + echo "Failed to create crontab entry. Exiting." + print_divider + exit 1 + } + fi + fi +} + +edit_config() { + print_divider + echo "Installation and configuration complete. Please edit the config.yaml file as per your needs." + print_divider + echo "Would you like to edit the config.yaml file now? (y/n) [y]:" + read -r EDIT_CONFIG + EDIT_CONFIG=${EDIT_CONFIG:-y} + if [ "$EDIT_CONFIG" = "y" ]; then + nano /usr/local/bin/SkywarnPlus/config.yaml + else + echo "You can edit the config.yaml file later using your preferred text editor." + fi +} + +main() { + check_root + print_notice + determine_system_type + confirm_system_type + install_dependencies + check_existing + download_swp + configure_perms + setup_crontab + edit_config +} + +main \ No newline at end of file