PedalPi-Application 0.2.0

Framework for manager the Pedal Pi

Pedal Pi - Application
======================

.. image:: https://travis-ci.org/PedalPi/Application.svg?branch=master
:target: https://travis-ci.org/PedalPi/Application
:alt: Build Status

.. image:: https://readthedocs.org/projects/pedalpi-application/badge/?version=latest
:target: http://pedalpi-application.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status

.. image:: https://codecov.io/gh/PedalPi/Application/branch/master/graph/badge.svg
:target: https://codecov.io/gh/PedalPi/Application
:alt: Code coverage

.. image:: https://landscape.io/github/PedalPi/Application/master/landscape.svg?style=flat
:target: https://landscape.io/github/PedalPi/Application/master
:alt: Code Health

Pedal Pi - Application is a framework for manager the Pedal Pi.
Through it is possible loads `Pedal Pi Components`_
to provide a Human Machine Interface (HMI) or even have an opening for other software
to consume the features of the Pedal Pi.

The components developed use the API (available through `Controllers <controller.html>`__) to manage the resources of the Pedal Pi.

.. _Pedal Pi Components: https://github.com/PedalPi/Components

**Documentation:**
http://pedalpi-application.readthedocs.io/

**Code:**
https://github.com/PedalPi/Application

**Python Package Index:**
https://pypi.org/project/PedalPi-Application

**License:**
`Apache License 2.0`_

.. _Apache License 2.0: https://github.com/PedalPi/Application/blob/master/LICENSE


Running Application
-------------------

Following are the steps required to set up and run Pedal Pi - Application.

Prepare ambient
***************

Install with pip

.. code-block:: bash

pip3 install PedalPi-Application

Create the script file that contains the code to run the application (as example ``start.py``)

.. code-block:: python

from application.application import Application

application = Application(path_data="data/", address='localhost')

application.start()

from signal import pause
pause()

Download, compile and install `mod-host`_. Mod-host is a *LV2 host for Jack controllable via socket or command line*.
It is developed by `Mod Devices`_, a company that also develops professional equipment for musicians.

.. _mod-host: https://github.com/moddevices/mod-host
.. _Mod Devices: https://moddevices.com/

.. code-block:: bash

git clone https://github.com/moddevices/mod-host
cd mod-host
make
make install

Run Application
***************

Start audio process. The required settings for your audio card can vary greatly.
I recommend that you try different possibilities in order to minimize the latency and number of *xruns*.

If you do not have any experience with JACK, is recommend the lecture of
`Demystifying JACK – A Beginners Guide to Getting Started with JACK`_ from **Linux Music Production**.

.. _Demystifying JACK – A Beginners Guide to Getting Started with JACK: http://libremusicproduction.com/articles/demystifying-jack-%E2%80%93-beginners-guide-getting-started-jack

.. code-block:: bash

# In this example, is starting a Zoom g3 series audio interface
jackd -R -P70 -t2000 -dalsa -dhw:Series -p256 -n3 -r44100 -s &
mod-host &

Finally, start the application

.. code-block:: bash

python3 start.py


Extending
---------

It's possible add or extends the Pedal Pi with addiction of :class:`Component`. A component can
provides a Human Machine Interface (HMI) - like `Raspberry P0`_ - or even have an opening for other software
to consume the features of the Pedal Pi - like `WebService`_ plugin.

See the `github Components Project`_ for complete components list.

To add a component in your configuration file, download it and register it before starting the application (``application.start()``):

.. code-block:: bash

pip3 install PedalPi-<component name>

.. code-block:: python
:emphasize-lines: 5, 6

from application.Application import Application
application = Application(data_pedalboard="data/", address='localhost')

# Loading component
from raspberry_p0.raspberry_p0 import RaspberryP0
application.register(RaspberryP0(application))

# Start application
application.start()

Each component needs a configuration to work.
Pay attention to your documentation for details on how to set it up and use it.

.. _github Components Project: https://github.com/PedalPi/Components
.. _Raspberry P0: https://github.com/PedalPi/Raspberry-P0
.. _WebService: https://github.com/PedalPi/WebService


Delegating audio processing to other equipment
----------------------------------------------

The connection with `mod-host`_ is over `TCP`_. So it's possible to place a
machine to perform the processing and another to provide the control services.

For example, you have a **Raspberry Pi B+** and a **PC**.
* The PC in http://10.0.0.100 will process the audio, then it will execute `jack` process,
`mod-host` process and the audio interface will be connected to it.
* The *RPi* will executes :class:`Application` with :class:`Component`, like `Raspberry P0 component`_.
Raspberry P0 disposes a simple current pedalboard control.

.. code-block:: python

application = Application(data_pedalboard="data/", address='10.0.0.100')

.. _Raspberry P0 component: https://github.com/PedalPi/Raspberry-P0
.. _TCP: https://en.wikipedia.org/wiki/Transmission_Control_Protocol

Creating a component
--------------------

Subsequently you will be added in the documentation details on how to create a component for the Pedal Pi.
It is currently recommended to view the API documentation.

Maintenance
-----------

Test
****

The purpose of the tests is:

* Check if the notifications are working, since the module plugins manager is responsible for testing the models;
* Serve as a sample basis.

.. code-block:: bash

coverage3 run --source=application setup.py test
coverage3 report
coverage3 html
firefox htmlcov/index.html

Generate documentation
**********************

This project uses `Sphinx`_ + `Read the Docs`_.

You can generate the documentation in your local machine:

.. code-block:: bash

pip3 install sphinx

cd docs
make html

firefox build/html/index.html

.. _Sphinx: http://www.sphinx-doc.org/
.. _Read the Docs: http://readthedocs.org