bvaic.com

Asterisk Tells Me About the Weather in Dallas

โ€”

by

Ben Vaiciulis
in

Using my Yealink VoIP phone, I can dial 789 and my server will respond with a Google TTS message about the weather in Dallas. The message contains a short forecast like “mostly sunny,” the current temperature, the current windspeed, and the forecast for the next period of the day like “tonight.” The creation of this Asterisk feature involved three main parts: figuring out how to interact with weather.gov‘s weather API, installing pyst2 (a Python library used to interact with Asterisk) and writing the Python application, and finally adding a few lines into the Asterisk dialplan to trigger my Python application when a call comes in for 789.

What is Asterisk and What are Features?

Before diving into the project, I want to take some time to cover these concepts so that the rest of this blog is easier to understand.

Asterisk, put simply, is open-source software that is used to build PBX systems that manage incoming and outgoing calls. I am interacting with Asterisk for this project because it comes with the FreePBX installation. I have used it already to connect Cisco VoIP phones together. FreePBX is a easy way to manage Asterisk through a web-based GUI, or Graphical User Interface, meaning that for the most part, the creation of the PBX system is done by clicking buttons and navigating a locally-hosted website. Since I am configuring Asterisk directly, everything will be done using the command line.

Features are essentially services provided by Asterisk that can be called or used during calls. For example, voicemail is a feature and so is call forwarding. Asterisk has a list of available features on their website. Here, I am making my own.

The Weather API

The main URL for accessing weather information about Dallas is https://api.weather.gov/points/32.7767,-96.797. This returns a lot of JSON data but the most important part is in “properties.” There, the URLs for the weekly forecast and hourly forecast can be found.

These lead to even more JSON where the useful parts are. Most of my weather information comes from the hourly forecast. Below is the hourly forecast JSON but only containing the data I needed to access.

JSON
{
  "properties": {
    "periods": [
      {
        temperature: 47,
        windSpeed: "0 mph",
        shortForecast: "Mostly Sunny"
      }
    ]
  }
}

In the hourly forecast JSON, the first period is the current hour.

Then there is the weekly forecast for which I again only needed the first period. Here, the first period is the time of day such as “This Afternoon” or “Overnight.”

JSON
{
  "properties": {
    "periods": [
      {
        "name": "This Afternoon",
        "detailedForecast": "Sentence describing the weather."
      }
    ]
  }
}

The data from these two will eventually be strung together in the Python script.

The Python Script

The Python script relies on just three libraries:

  1. The pyst2 library for interacting with Asterisk using the AGI, or Asterisk Gateway Interface which allows external programs like Python scripts to interact with Asterisk
  2. The urllib library for downloading the JSON from the weather API
  3. The json library for parsing the JSON and turning it into a usable Python dictionary

The fundamental library here is pyst2. The AGI() object within pyst2 allows the Python script to answer the incoming call, playback audio files, read caller input, and much more before also hanging up the call. In this case however, the Python script is only responsible for constructing a weather info paragraph that will be passed to the dialplan via a variable so that the dialplan can play it to the caller using Google TTS. The python script could have done everything but there was a small issue that caused some of the responsibility to shift back to the dialplan.

This is the format from which the Python scripts creates the weather information paragraph:

The current weather in Dallas is as follows: {shortForecast}. The temperature is {temperature} degrees fahrenheit. The wind speed is {windSpeed}. For {name}: {detailedForecast}

The curly braces contain the names of the JSON variables from the weather API.

In Asterisk, there is a dedicated directory for AGI applications that can be called by the dialplan. The directory is /var/lib/asterisk/agi-bin.

Below is what the final Python script looked like.

Python
#!/usr/bin/python3

from asterisk.agi import AGI
import urllib.request, json

agi = AGI()

with urllib.request.urlopen("http://api.weather.gov/gridpoints/FWD/89,104/forecast") as url:
    forecast_weekly_data = json.load(url)
    
with urllib.request.urlopen("http://api.weather.gov/gridpoints/FWD/89,104/forecast/hourly") as url:
    forecast_hourly_data = json.load(url)

current_hour = forecast_hourly_data["properties"]["periods"][0]

current_short_forecast = current_hour["shortForecast"]

current_temperature_f = current_hour["temperature"]

current_wind_speed = current_hour["windSpeed"]

weather_info = "The current weather in Dallas is as follows: " + current_short_forecast + ". The temperature is " + str(current_temperature_f) + " degrees fahrenheit. The wind speed is " + str(current_wind_speed) + ". "

current_period = forecast_weekly_data["properties"]["periods"][0]

detailed_forecast = current_period["detailedForecast"]
sentence = "For " + current_period["name"] + ", " + detailed_forecast + " "
weather_info += sentence

agi.set_variable("weather_info", weather_info)

The #!/usr/bin/python3 at the top is necessary. It will not work without it. Another part of the code to note is the last line:

agi.set_variable("weather_info", weather_info)

This code is setting a channel variable named weather_info to the weather info paragraph put together earlier in the code. This is important because once the Python script finished, the dialplan will require the created paragraph and it will be able to access it through the channel variable ${weather_info}.

File Permissions

In order for Asterisk to be able to access the Python script, it needs to have its permissions changed. In the /var/lib/asterisk/agi-bin directory, run the following commands.

$ chown asterisk:asterisk script.py
$ chmod 755 script.py

The first command sets the owner and group of the file to asterisk. The second command gives the owner (asterisk) read, write, and execute permissions; the group (asterisk) read and execute permissions; and everyone else read and execute permissions.

The Dialplan

In the Python section, I mentioned that some of the functionality of the feature resides with the dialplan. The dialplan, according to the Asterisk docs, is a “scripting language specific to Asterisk.” The dialplan has an application AGI() that can be used to “launch external programs.” For this project, I used two AGI calls, one to my Python script and the other to a Google TTS AGI application also within /var/lib/asterisk/agi-bin. I had to install this using its GitHub page and place it in the agi-bin directory.

The main Asterisk dialplan is located at /etc/asterisk/extensions.conf.

Below is the functional dialplan snippet.

Plaintext
exten => 789,1,AGI(dallas-weather.py)
 same => n,AGI(googletts.agi,"${weather_info}",en)
 same => n,Hangup()

In dialplan scripting, exten => is telling Asterisk what to do when a call is being made to this destination, or extension. The 1 is a priority number and lets Asterisk know where to start executing. The n is short for the next priority number after the previous one. In the second AGI() call, the channel variable set by the Python script is being used as input to Google TTS which will speak the weather information over the phone.

Conclusion

This project made me realize the potential of Python in dialplan scripting. So much so that I went back and redid one of my other features using Python instead of the dialplan. In that feature, Python does everything and the dialplan entry is just one line pointing to the Python script. I am looking forward to creating more interesting things using Python for dialplan scripting.

WordPress Appliance - Powered by TurnKey Linux