Waterloop Cosa
==============

Waterloop Cosa is a commandline tool used to help create, build, and
upload AVR projects built using Cosa, an object-oriented platform for
Arduino. This project is built on top of
`arduino-cmake <https://github.com/arduino-cmake/arduino-cmake>`__ to
provide a CMake toolchain for Cosa, and wrapped in a Python script.

Cosa
----

`Cosa <https://github.com/mikaelpatel/Cosa>`__ boasts better performance
and lower power consumption, while more powerful but complex than
standard Arduino libraries. Cosa, being object oriented integrates well
with other C++ program written in OOP style.

WCosa
-----

This project provides ``wcosa``, a build script written in Python. The
script allows user to ``create``, ``build``, ``upload``, and ``monitor``
AVR projects. This tool uses the ``cmake`` toolchain behind the scenes.
Running the creation scripts generates a project with the structure

::

    project/
        lib/
        src/
        wcosa/
            bin/
            CMakeLists.txt
        .gitignore
        config.json
        CMakeLists.txt
        CMakeListsPrivate.txt

Sources files should be placed in the ``src`` directory, and libraries
should be placed in folders inside the ``lib`` directory. Build files
are contained in ``wcosa`` and needs to be generated for each
environment that is running the WCosa project.

Commands and Usage
------------------

Using commands has the format ``wcosa [action]`` where ``[action]`` is
one of ``create``, ``update``, ``build``, ``clean``, ``upload``.

Here is an example of creating a project:

.. code:: bash

    mkdir wcosa-project
    cd wcosa-project
    wcosa create --board uno --ide clion

The ``--board`` flag specifies the desired target board for project
build, and ``--ide clion`` tells WCosa to generate files to enable
project import into ``CLion`` for code suggestion and completion. Use
``wcosa boards`` to see the list of available boards, supported Cosa.
This command will generate environment-specific files such as
``CMakeListsPrivate.txt`` and the ``wcosa`` folder.

To build the project, creating uploadable binaries, use ``wcosa build``,
and to clean the project, run ``wcosa clean``. If a microcontroller is
plugged into your PC, running ``wcosa upload`` will attempt to
autodetect the port and upload the program. If you have multiple
microcontrollers or if WCosa cannot detect the port, use
``wcosa upload --port [port_name]`` to specify the desired upload port.

The command ``wcosa update`` can be used to update the target board with
``wcosa update --board [new_board]`` or if ``config.json`` is modified.
To add build definitions to the main project or to submodules, modify
``build-flags`` to something as

.. code:: json

    {
        "build-flags": "MAX_ALLOCATORS=4u STATIC_MEMORY"
    }

To specify definitions for modules added under ``lib``,

.. code:: json

    {
        "build-flags": "...",
        "module-flags": {
            "wlib": "BLOCK_SIZE=64u NUM_BLOCKS=400u"
        }
    }

Then run ``wcosa update`` to update the internal config.

The command ``wcosa update`` should also be called when checking out a
project from source control to create the environment files. For
example,

.. code:: bash

    git clone --recursive https://github.com/teamwaterloop/goose-sensors.git
    cd goose-sensors
    wcosa update

Installation
------------

.. code:: bash

    pip install wcosa

WCosa requires either ``gcc-avr`` or the Arduino SDK to be installed.
**CMake** is also required to build projects.

Windows
~~~~~~~

We recommend installing the Arduino SDK. 1. Download and install the
`Arduino IDE <https://www.arduino.cc/en/Main/Software>`__ 2. Add the
Arduino installation directory and the subdirectory
``\hardware\tools\avr\bin`` to your System PATH; these may look like \*
``C:\Program Files (x86)\Arduino`` \*
``C:\Program Files (x86)\Arduino\hardware\tools\bin``

There are some `avr-gcc <http://blog.zakkemble.co.uk/avr-gcc-builds/>`__
builds available for Windows but these are untested.

Linux
~~~~~

You may choose to install the Arduino SDK or the required tools and
binaries from the commandline.

**Ubuntu**

.. code:: bash

    sudo apt-get install gcc-avr avr-libc avrdude

**Arch**

.. code:: bash

    sudo pacman -S avr-gcc avr-libc avrdude

MacOS
~~~~~

You may install the Arduino SDK or build ``avr-gcc`` using ``brew``.
Keep in mind that building ``avr-gcc`` may take some time.

.. code:: bash

    xcode-select --install
    brew tap osx-cross/avr
    brew install avr-gcc
    brew install avrdude

Committers
----------

Deep Dhillon (@dhillondeep) Jeff Niu (@mogball)
