In this series of tutorials, we'll take a look at how you can automate your Awasu through the use of the Awasu API.

The Awasu API runs over HTTP, so you can actually use it directly from a browser. For example, if we want to get information about what version of Awasu is running, enter this URL in a browser:

http://localhost:2604/buildInfo

And you should get something like the screenshot on the right.

If you get a "Missing HTTP API token." error, this means that your Awasu has been configured to require a token (i.e. a password) to be specified in every call.

One will have been generated automatically for you, and you can get it from the Advanced tab of the Program Options:

Then add it to the URL e.g.
http://localhost:2604/buildInfo?token=xyz

For simplicity, these tutorials will assume that no API token is required.

Awasu can return the information in different formats, so if you prefer JSON, simply add a format=json parameter to the URL.

If you are running Awasu Server, there is even a nice HTML version ^[1]We will talk later about how you can add your own customized data return formats.

However, the purpose of the Awasu API library is to hide all these details and make it much easier to communicate with your Awasu, so let's take a look at how that works.

Installing the awasu_api library

The Awasu API library is available in Python and PHP. This tutorial will be using the Python version, but the PHP version is almost identical.

If you're online, the easiest way to install the library is to get it directly from PyPI:

    pip install awasu-api # nb: has a hyphen, not an underscore

Querying Awasu

To query Awasu, we first need to create an AwasuApi object:

from awasu_api import AwasuApi

api = AwasuApi()

The constructor takes optional parameters that specify which Awasu you want to connect to ^[2]Awasu Server allows remote connections, otherwise connections need to be made from the same computer that Awasu is running on. and the API token, but since we're connecting to Awasu running on the same machine, without an API token, we don't need to specify anything.

build_info = api.get_awasu_build_info()
print( build_info )

This gives us the result shown to the right.

We have received a dictionary of key/value pairs with information about the Awasu build.

It's a bit hard to read, so let's reformat it:

build_info = api.get_awasu_build_info()
for key, val in build_info.items():
    print( key, "=", val )

With just a few lines of code, we've connected to Awasu and got it tell us what version it's running. It really is that easy!

Listing the channels in your Awasu

Let's take a look at a slightly more involved example, getting a list of all the channels in your Awasu:

import pprint
from awasu_api import AwasuApi

api = AwasuApi()
channels = api.get_channels()
for i, channel in enumerate( channels ):
    print( "=== Channel #{} ===".format( 1+i ) )
    pprint.pprint( channel )
    print()

The important bit is the call to get_channels(), which returns us an array of dictionaries, one for each channel in my Awasu (screenshot).

By default, Awasu will only return the most important information about each channel, but if you want everything, just add a verbose=True to the call i.e.

channels = api.get_channels( verbose=True )

If you want only some of the channels, you can specify their ID's:

channels = api.get_channels( ids=[21,23] )

Download the source code here.

Tutorial index

Configuring Awasu »