Home | Demo | Tutorial | Documentation | Installation | Get Pyaler

Pyaler's RESTful interface explained

The RESTful interface takes two kinds of URL and two queries methods :

/arduinos/reset

This URL query makes pyaler reread the configuration file on runtime and resets the connections to the arduinos. Once executed, the RESTful interface is updated with the new actions and the new arduinos.

/%arduino_name%/%action_name%

The methods given by Pyaler's API matches this pattern :
%arduino_name% : arduino's name set in configuration file
%action_name% : action's name set in configuration file.

Actions defined as 'read_actions' in configuration file are only accessible through GET requests, while actions defined as 'write_actions' are only accessible through POST queries using the field 'value' to give the value to the arduino.

Configuration file

The configuration file is working as the following example:

arduinos:
    arduino1: /dev/ttyUSB0
    arduino2: /dev/tty.usbserial-A800eIR3

read_actions:
    read: foo
    demo: bar

write_actions:
    write:
    demo: hello

Keyword 'arduinos:'

In this section, the host's serial ports are linked with arduinos names. In the previous example, the name 'arduino1' is linked to '/dev/ttyUSB0' (a serial port under linux) and 'arduino2' is linked to '/dev/tty.usbserial-A800eIR3' (serial port under OSX, where '-A800eIR3' is a unique arduino identifier).

Keyword 'read_actions:'

It defines the different actions that can be queried through HTTP GET. The left value is the name that will be used in the URL and the right value the string that will be sent to the arduino. In previous configuration example, a query of 'http://my.host/arduino1/read' will send 'foo' to the arduino.

Keyword 'write_actions'

This keyword defines the actions that can be queried through an HTTP POST query. The left value is the name that will be used in the URL and the right value is a string that will be sent to the arduino. It will be prepended to the string sent in the POST field 'value'. In the previous configuration example, if 'value=TEST' on 'http://my.host/arduino1/write', the arduino will get the string 'TEST' ; if 'value=WORLD' is sent on 'http://my.host/arduino1/demo', the arduino will get the string 'helloWORLD'.

Stand-alone execution

The Pyaler framework can be launched as standalone, so it will launch a local webserver, 'Paste'. Here are the recognized options to configure Pyaler :

Usage: pyaler -v -H HOST -p PORT -c file

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -H HOST, --host=HOST  Host to run the pyaler server as. Default: localhost
  -p PORT, --port=PORT  Port where run the pyaler server on. Default: 8080
  -c CONFIG, --conf=CONFIG
                        Path to configuration file. Default: conf.yaml
  -v, --verbose         Print logging messages to stdout.

To launche pyaler locally on a non-privileged port, execute :

 % pyaler -H 127.0.0.1 -p 8080 -c pyaler-config.yaml

In case you have issues, launch pyaler with option '-v' and report error messages on Bearstech's forge.

Apache server integration

You can integrated Pyaler with Apache configured with mod_wsgi ; to do so, you shall write a configuration file like the following one :

    ServerName yourdomain.com

    WSGIDaemonProcess pyaler user=www-data group=www-data processes=1 threads=5
    WSGIScriptAlias / /path/to/pyaler_home/pyaler/pyaler.wsgi

    
        WSGIProcessGroup pyaler
        WSGIApplicationGroup %{GLOBAL}
        Order deny,allow
        Allow from all
    

and create the pyaler.wsgi script so it is :

from pyaler import pyaler

application = pyaler.make_app({}, config=’conf.yaml’)

For more documentation on that feature, please refer to Bottle's documentation.

Hack pyaler !

To hack pyaler, get the sources on Bearstech's forge :

 % svn co svn://forge.bearstech.com/forge/Pyaler/ pyaler-svn/

Extend pyaler

It is possible to extend pyaler's API with RESTful methods by creating a new python module following this snippet :

# -*- coding: utf-8 -*-
from pyaler import app

@app.route('/')
def index():
    return '<html><title>live</title></html>'

To be done

If you like pyaler and want to add new features, we'd be glad to integrate them. If you want to know what needs to be done, refer to the wiki page on Bearstech forge.