Skip to main content

Developing Custom Applications

In this tutorial we will show you how to develop a custom Kivy application for the Amiga Brain.



Make sure that you have ssh access to the brain. If you don't have ssh access, please follow the SSH Access tutorial.

apt install wget

Follow the instructions below to select a Kivy app prepared by farm-ng or create an app from the amiga-app-template-kivy repository.

Select an existing app

To test the app deployment process of a fully made app developed by farm-ng, e.g you can choose the camera-streamer-kivy example.

To clone the example click on one of the links in the previous sentence and click the green code button in GitHub and then copy the text highlighted in yellow.

Create a new templated repository

Run from the command line

Open a terminal and navigate to the directory where you cloned the amiga-app-template-kivy repository.

cd <to-your-app-directory>
DISPLAY=:0 ./ # install and run

If all goes well, you'll see an dummy Kivy application on your brain screen.

Run from the brain screen

In order to run the app from the brain screen, you need to copy the app to the brain. To do so, you need to navigate to your app directory and run the script.

cd <to-your-app-directory>

You should now see your app on the brain screen. Click on it to launch it.

Screenshot from 2023-12-01 17-43-59

Create a new app

To create your own custom application navigate to the amiga-app-template-kivy repository on GitHub.


You need to be signed into your GitHub account to see the option to Use this template.

Create a new templated repository

Written instructions (same as video above):

  1. Click on green Use this template button (top right) to create a new repository based on this repo
  2. Fill out:
    • Owner: (your_username)
    • Repository Name: whatever-you-want
      • Should be between between 4-17 characters, and
      • Use underscores (_) or dashes (-) for separating words (no spaces!) -Select Public box -Click [Create repository from template] Done!

Now that you are done creating your repository, you have two options:

  1. Work in your local workspace.
  2. Work in a remote Remote-SSH session using in vs-code.

In both cases you will have to clone the repository you created above by following the commands below.

cd <to-your-base-directory>
git clone

Project structure

In vs-code, you can see the project structure on the left side in the EXPLORER:

Below are listed the most important components.

repository-name/  # Root level of the project.
├── libs/ # Contains private libraries.
| └── project_name/
| ├── # e.g a operators submodule
| └── project_name_subpackage/
| └── # e.g a utilities submodule
├── src/ # Contains all code needed to run the main gui application.
| ├── assets/ # Contains files needed to run the application
| | └── app_logo.png # static images or images for buttons.
| ├── res/ # Contains the layout files and UI strings.
| | └── main.kv # main ui layout in Kivy languague
| └── # Is the main entry point for the gui application.
├── test/ # Contains code for test of the private libs.
| └── # sets of unit test.
| # The script to install the app on the brain.
| # The script to uninstall the app from the brain.
├── manifest.json
| # The file containing the metadata of the app to register it on the brain.
| # The script to setup the project, create a virtual env. and install dependencies.
└── setup.cfg
# The file containing the metadata of the package, including the name, versioning, etc. Learn more here:

How to setup the project

Before any changes, lets see if we can run this app locally on your system.

./ # install and run

When running the above script, a virtual environment venv will be created and any dependencies will be installed.

If all goes well, you'll see an dummy kivy application on your screen.

Customizing an app

In order to customize an app we leverage the setup.cfg that contains all the metadata and package configuration. More can be found here!

The most important first steps are to modify the metadata of the project and dependencies:

  1. Inside the setup.cfg file, adjust the fields under the tag [metadata]
    • For basic users, the package name (project_name in the project structure above) goes in the name field, and must match with the directory name right under the libs/ directory.
      • I.e., change both the name field and the directory name under libs/ to your new app name.
      • VScode should prompt you to change the import names in once you change the directory name.
        • If not, manually change:
          from amiga_package import __version__
          from amiga_package import ops
        • To:
          from <project_name> import __version__
          from <project_name> import ops
    • For advanced users, you can modify as much is compliant with Python setuptools.
  2. Adjust the package dependencies
    • Include whatever extra dependency you need in the install_requires field.
    • Our only requirements are:
      • wheel: for packaging the app.
      • kivy: to generate the graphical user interface (GUI).
      • farm-ng-amiga: the Farm-ng Amiga public SDK.

Update the manifest.json

In this file, you can find the metadata of the app. This file is used by the launcher and has the following structure:

"services": {
"example-app": {
"name": "example-app-kivy",
"type": "app",
"exec_cmd": "",
"display_name": "Example App"
"autostart": false

Learn more about the manifest file here.

In case you face issues, connect with us and the community on Discourse

Development and Debug an app

The workflow for development is pretty much the same as any standard gui application.

  1. Make changes in the code.
  2. Run the code with the play button in vs-code.
    • [Optionally] Add a breakpoint to any line and use the Debug Console to interact.
  3. Go to step 1)

[Optional] Test your application

In order to validate your functionality, we suggest to add test cases for the internal libs/[package_name] located under test/test_[test_name].py.

To launch the tests: pytest test/ To run specific tests: pytest test/