@ -30,6 +30,56 @@ SkywarnPlus is a sophisticated software solution that works hand-in-hand with yo
Whether you wish to auto-link to a Skywarn net during severe weather, program your node to control an external device like a siren during a tornado warning, or simply want to stay updated on changing weather conditions, SkywarnPlus offers a comprehensive, efficient, and customizable solution for your weather alert needs.
Whether you wish to auto-link to a Skywarn net during severe weather, program your node to control an external device like a siren during a tornado warning, or simply want to stay updated on changing weather conditions, SkywarnPlus offers a comprehensive, efficient, and customizable solution for your weather alert needs.
# Comprehensive Information
SkywarnPlus supports all 128 alert types included in the [NWS v1.2 API](https://www.weather.gov/documentation/services-web-api).
@ -58,6 +108,7 @@ Follow the steps below to install:
wget https://bootstrap.pypa.io/pip/3.5/get-pip.py
wget https://bootstrap.pypa.io/pip/3.5/get-pip.py
python get-pip.py
python get-pip.py
pip install pyyaml requests python-dateutil pydub
pip install pyyaml requests python-dateutil pydub
pip install ruamel.yaml==0.15.100
```
```
2. **Download SkywarnPlus**
2. **Download SkywarnPlus**
@ -77,31 +128,30 @@ Follow the steps below to install:
```bash
```bash
cd SkywarnPlus
cd SkywarnPlus
chmod +x SkywarnPlus.py
chmod +x *.py
chmod +x SkyControl.py
```
```
4. **Edit Configuration**
4. **Edit Configuration**
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.
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.
```bash
```bash
nano config.yaml
nano config.yaml
```
```
You can find your area code(s) at https://alerts.weather.gov/. Select `County List` to the right of your state, and use the `County Code` associated with the area(s) you want SkywarnPlus to poll for WX alerts.
You can find your area code(s) at https://alerts.weather.gov/. Select `County List` to the right of your state, and use the `County Code` associated with the area(s) you want SkywarnPlus to poll for WX alerts.
## **IMPORTANT**: YOU WILL MISS ALERTS IF YOU USE A **ZONE** CODE. DO NOT USE **ZONE** CODES UNLESS YOU KNOW WHAT YOU ARE DOING.
## **IMPORTANT**: YOU WILL MISS ALERTS IF YOU USE A **ZONE** CODE. DO NOT USE **ZONE** CODES UNLESS YOU KNOW WHAT YOU ARE DOING.
According to the official [NWS API documentation](https://www.weather.gov/documentation/services-web-api):
According to the official [NWS API documentation](https://www.weather.gov/documentation/services-web-api):
> "For large scale or longer lasting events, such as snow storms, fire threat, or heat events, alerts are issued
> "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
> by NWS public forecast zones or fire weather zones. These zones differ in size and can cross county
> boundaries."
> boundaries."
> "...county based alerts are not mapped to zones but zone based alerts are mapped to counties."
> "...county based alerts are not mapped to zones but zone based alerts are mapped to counties."
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.
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.
5. **Crontab Entry**
5. **Crontab Entry**
@ -124,7 +174,7 @@ SkywarnPlus can automatically create, manage, and remove a tailmessage whenever
SkywarnPlus can automatically change the node ID whenever certain weather alerts are active. The configuration for this is based on your `rpt.conf` file setup. Here's an example:
SkywarnPlus can automatically change the node ID whenever certain weather alerts are active. This requires creating your own audio files; one for the `NORMAL` ID, and one for the `WX` ID. The configuration for this is based on your `rpt.conf` file setup. Here's an example:
@ -158,7 +210,7 @@ SkywarnPlus can use the free Pushover API to send WX alert notifications and deb
3. Scroll down and create an Application/API key for your node
3. Scroll down and create an Application/API key for your node
4. Add UserKey & API Key to `config.yaml`
4. Add UserKey & API Key to `config.yaml`
# Control Script
# SkyControl
SkywarnPlus comes with a powerful control script (`SkyControl.py`) that can be used to enable or disable certain SkywarnPlus functions via shell, without manually editing `config.yaml`. This script is particularly useful when you want to map DTMF control codes to these functions. An added advantage is that the script provides spoken feedback upon execution, making it even more suitable for DTMF control.
SkywarnPlus comes with a powerful control script (`SkyControl.py`) that can be used to enable or disable certain SkywarnPlus functions via shell, without manually editing `config.yaml`. This script is particularly useful when you want to map DTMF control codes to these functions. An added advantage is that the script provides spoken feedback upon execution, making it even more suitable for DTMF control.
@ -213,16 +265,17 @@ Upon the successful execution of a control command, the `SkyControl.py` script w
You can map the `SkyControl.py` script to DTMF commands in the `rpt.conf` file of your node. Here is an example of how to do this:
You can map the `SkyControl.py` script to DTMF commands in the `rpt.conf` file of your node. Here is an example of how to do this:
In the examples above, `<NODE_NUMBERS>` are the nodes where you want the DTMF command to be dispatched, `<DTMF_COMMAND>` is the command to be executed, and `<ALERTS>` are the alerts to trigger this command. Likewise, for bash commands, `<BASH_COMMAND>` is the script to be executed and `<ALERTS>` are the alerts to trigger this script. Note that wildcards (`*`) can be used in `<ALERTS>` for broader matches.
## Matching
The `Match:` parameter tells `AlertScript` how to handle the triggers. If `Match: ANY`, then only 1 of the triggers needs to be matched for the command(s) to execute. If `Match: ALL`, then all of the triggers must be matched for the command(s) to execute. If `Match:` is not defined, then `ANY` is used by default.
## The Power of YOU
## The Power of YOU
@ -268,6 +375,75 @@ Fancy activating a siren when a tornado warning is received? You can do that. Wa
In essence, `AlertScript` unleashes a world of customization possibilities, empowering you to add new capabilities to SkywarnPlus, create your own extensions, and modify your setup to align with your specific requirements and preferences. By giving you the authority to dictate how your system should react to various weather alerts, `AlertScript` makes SkywarnPlus a truly powerful tool for managing weather alerts on your node.
In essence, `AlertScript` unleashes a world of customization possibilities, empowering you to add new capabilities to SkywarnPlus, create your own extensions, and modify your setup to align with your specific requirements and preferences. By giving you the authority to dictate how your system should react to various weather alerts, `AlertScript` makes SkywarnPlus a truly powerful tool for managing weather alerts on your node.
# SkyDescribe
`SkyDescribe` is a powerful and flexible tool that works in tandem with SkywarnPlus. It enables the system to provide a spoken detailed description of weather alerts, adding depth and clarity to the basic information broadcasted by default.
The `SkyDescribe.py` script works by fetching a specific alert from the stored data (maintained by SkywarnPlus) based on the title or index provided. The script then converts the description to audio using a free text-to-speech service and broadcasts it using Asterisk on the defined nodes.
## Usage
To use `SkyDescribe.py`, you simply execute the script with the title or index of the alert you want to be described. The index of the alert is the place it holds in the alert announcement or tailmessage (depending on blocking sonfiguration).
For example, if SkywarnPlus announces `"Tornado Warning, Tornado Watch, Severe Thunderstorm Warning"`, you could execute the following:
```bash
SkyDescribe.py 1 # Describe the 1st alert (Tornado Warning)
SkyDescribe.py 2 # Describe the 2nd alert (Tornado Watch)
SkyDescribe.py 3 # Describe the 3rd alert (Severe Thunderstorm Warning)
```
or, you can use the title of the alert instead of the index:
```bash
SkyDescribe.py "Tornado Warning"
SkyDescribe.py "Tornado Watch"
SkyDescribe.py "Severe Thunderstorm Warning"
```
## Integration with AlertScript
`SkyDescribe.py` can be seamlessly integrated with `AlertScript`, enabling automatic detailed description announcements for specific alerts. This can be accomplished by mapping the alerts to a bash command that executes `SkyDescribe.py` with the alert title as a parameter.
Here's an example of how to achieve this in the `config.yaml` file:
```yaml
AlertScript:
Enable: true
Mappings:
# This is an example entry that will automatically execute SkyDescribe and
# announce the full details of a Tornado Warning when it is detected.
For added flexibility, `SkyDescribe.py` can also be linked to DTMF commands, allowing alert descriptions to be requested over-the-air.
```ini
; SkyDescribe DTMF Commands
841 = cmd,/usr/local/bin/SkywarnPlus/SkyDescribe.py 1 ; SkyDescribe the 1st alert
842 = cmd,/usr/local/bin/SkywarnPlus/SkyDescribe.py 2 ; SkyDescribe the 2nd alert
843 = cmd,/usr/local/bin/SkywarnPlus/SkyDescribe.py 3 ; SkyDescribe the 3rd alert
844 = cmd,/usr/local/bin/SkywarnPlus/SkyDescribe.py 4 ; SkyDescribe the 4th alert
845 = cmd,/usr/local/bin/SkywarnPlus/SkyDescribe.py 5 ; SkyDescribe the 5th alert
846 = cmd,/usr/local/bin/SkywarnPlus/SkyDescribe.py 6 ; SkyDescribe the 6th alert
847 = cmd,/usr/local/bin/SkywarnPlus/SkyDescribe.py 7 ; SkyDescribe the 7th alert
848 = cmd,/usr/local/bin/SkywarnPlus/SkyDescribe.py 8 ; SkyDescribe the 8th alert
849 = cmd,/usr/local/bin/SkywarnPlus/SkyDescribe.py 9 ; SkyDescribe the 9th alert
```
## **NOTE:**
If you have SkywarnPlus set up to monitor multiple counties, it will, by design, only store **ONE** instance of each alert type in order to prevent announcing duplicate messages. Because of this, if SkywarnPlus checks 3 different counties and finds a `"Tornado Warning"` in each one, only the first description will be saved. Thus, executing `SkyControl.py "Tornado Warning"` will broadcast the description of the `"Tornado Warning"` for the first county **ONLY**.
In _most_ cases, any multiple counties that SkywarnPlus is set up to monitor will be adjacent to one another, and any duplicate alerts would actually be the **_same_** alert with the **_same_** description, so this wouldn't matter.
# Customizing the Audio Files
# Customizing the Audio Files
SkywarnPlus comes with a library of audio files that can be replaced with any 8kHz mono PCM16 WAV files you want. These are found in the `SOUNDS/` directory by default, along with `DICTIONARY.txt` which explains audio file assignments.
SkywarnPlus comes with a library of audio files that can be replaced with any 8kHz mono PCM16 WAV files you want. These are found in the `SOUNDS/` directory by default, along with `DICTIONARY.txt` which explains audio file assignments.
@ -285,9 +461,9 @@ To enable this option, modify the following settings in the `[DEV]` section of y
INJECT: false
INJECT: false
# List the test alerts to inject. Use a case-sensitive list. One alert per line for better readability.
# List the test alerts to inject. Use a case-sensitive list. One alert per line for better readability.
INJECTALERTS:
INJECTALERTS:
- Tornado Warning
- Tornado Warning
- Tornado Watch
- Tornado Watch
- Severe Thunderstorm Warning
- Severe Thunderstorm Warning
```
```
# Debugging
# Debugging
@ -347,4 +523,4 @@ SkywarnPlus is open-sourced software licensed under the [MIT license](LICENSE).