Developing Custom Applications
We now have a set of tutorials that walk you through creating custom applications that interact with cameras and drive your Amiga from the brain!
Check them out at Brain App Tutorials.
Quick Tipsβ
- The Amiga user is able to install APT packages.
- Edit the "entry.sh" script in the sample git repository.
- We leverage a venv per application.
- The contents of requirements.txt will be installed by the bootstrap.sh script.
- If you've updated the requirements remove the hidden ".lock" before relaunching the app from the Brain UI.
- You may use VSCode remote development/containers to edit directly on the Amiga brain as well.
Prerequisitesβ
- Linux/WSL
- MacOs
apt install wget
brew install wget
Prepare an appβ
Follow the instructions below to select a Brain App Example
prepared by farm-ng or create an app from the
amiga-app-template
repository.
Select an appβ
To test the app deployment process of a fully made app developed by farm-ng, you can choose either the camera-streamer
example or the virtual-joystick example from Brain App Example. To clone one
of the examples 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.
Now in the terminal enter the following commands, but where it says git clone http...
and replace the https..
part with your copied text.
cd <to-your-base-directory>
git clone https://github.com/farm-ng/camera-streamer.git # To clone the camera-streamer repo or other.
Now you can follow the instructions below as though you were developing a custom application
and simply replace any <YOUR-USERNAME/YOUR-REPOSITORY>
placeholder with that of the
path to the prepared app's Git repository, e.g., farm-ng/virtual-joystick
.
You can skip any sections specific to setting up a new project, including Create an app and Customizing an app.
Create an appβ
Create a repository from the templateβ
To create your own custom application navigate to the amiga-app-template
repository on GitHub.
You need to be signed into your GitHub account to see the option to Use this template
.
Written instructions (same as video above):
- Click on green Use this template button (top right) to create a new repository based on this repo
- Fill out:Done!
- 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]
Now that you are done creating your repository, you have two options:
- Work in your local workspace.
- 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 https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git
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/
| βββ ops.py # e.g a operators submodule
| βββ project_name_subpackage/
| βββ utils.py # 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
| βββ main.py # Is the main entry point for the gui application.
βββ test/ # Contains code for test of the private libs.
| βββ test_dummy.py # sets of unit test.
βββ entry.sh
| # 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: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html
How to setup the projectβ
Before any changes, lets see if we can run this app locally on your system.
cd YOUR_REPOSITORY/
./entry.sh # 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:
- 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 thename
field, and must match with the directory name right under thelibs/
directory.- I.e., change both the
name
field and the directory name underlibs/
to your new app name. - VScode should prompt you to change the import names in
test_dummy.py
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
- If not, manually change:
- I.e., change both the
- For advanced users, you can modify as much is compliant with Python
setuptools
.
- For basic users, the package name (
- 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.
- Include whatever extra dependency you need in the
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.
- Make changes in the code.
- Run the code with the play button in vs-code.
- [Optionally] Add a breakpoint to any line and use the Debug Console to interact.
- 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/test_dummy.py::TestDummy::test_add
How to SSH into the Amigaβ
If this is your very first time ssh into Amiga follow the instructions under Initial SSH set up
otherwise follow the steps at SSH Configuration.
Initial SSH set upβ
Follow the steps listed below and then continue on to SSH Configuration to complete the process.
To set up ssh, make sure the Amiga and your computer are on the same network (check the Wifi on the Amiga and adjust accordingly).
Then check if a file
~/.ssh/config
exists on your workstation with the steps below.~/
is the home folder on your workstation.
- To check if this file exists put the commands below in your terminal. If this file does not exist, you'll have to create it.
cd ~ # Navigate to your home folder
ls -a # Check for a folder called `.ssh/`
- If
~/.ssh/
does not exist, run:
ssh-keygen # create ~/.ssh/ folder
- Create a file called
config
(no extension) in~/.ssh
- Linux/WSL
- MacOs
touch ~/.ssh/config
cd .ssh
cat > config # Then press control D on your keyboard
SSH Configurationβ
Now it is time to configure your config file to ssh into your Amiga.
- Linux/WSL
- MacOs
gedit ~/.ssh/config
cd .ssh
open config # Then edit directly in the text editor that pops up and save your changes
Edit your .ssh/config file to include the below information.
Host amiga
HostName <ip address>
Port 22
User amiga
StrictHostKeyChecking no
<ip address>
can be found on the bottom right of the Amiga Brain screen- Remove the
<
&>
symbols. - Your development station and your Amiga should be on the same network.
This utilizes the IP address displayed on the bottom right of the brain display:
Letβs copy our keys to the robot as well (you may need to do this any time you are working with a new robot)
ssh-copy-id amiga
Now you are all set up to ssh into the Amiga
SSH Amigaβ
ssh amiga
# When prompted for a user name and password enter the following :
# password: amiga
exit # If you want to exit the ssh
If, after a docker image update, you cannot ssh
into your amiga or run the sync.sh
script,
you may have an error similar to:
# $ ssh amiga
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the ECDSA key sent by the remote host is
SHA256:QsdOvROYuKMa5NqaPTFHwF3kfPCwKaTzgBAj9N/eKCI.
Please contact your system administrator.
Add correct host key in /home/<YOUR_NAME>/.ssh/known_hosts to get rid of this message.
Offending ECDSA key in /home/<YOUR_NAME>/.ssh/known_hosts:29
remove with:
ssh-keygen -f "/home/<YOUR_NAME>/.ssh/known_hosts" -R "192.168.XX.XX"
ECDSA host key for 192.168.XX.XX has changed and you have requested strict checking.
Host key verification failed.
Follow the instructions they provide and run:
# With correct values for <YOUR_NAME> and IP Address XX.XX
ssh-keygen -f "/home/<YOUR_NAME>/.ssh/known_hosts" -R "192.168.XX.XX"
You should now be able to ssh
into your amiga and/or run the sync.sh
script
Develop and test in the robotβ
In order to test your app in the robot, we require to push the changes to the remote repository created before and clone it to the robot.
We recommend to follow the next steps:
Make sure you are on the Linux tab when you go to the GitHub docs (links below). The page defaults to the system you are on and doesn't know you are SSH'd into a Linux machine, which the Amiga is.
- ssh to robot
ssh amiga
(if have not configured ssh do so here) - Create an ssh key for github on the amiga
ssh-keygen
- Copy and add the key to your github user
- Set your username in git config
git config --global user.email "YOUR_EMAIL"
git config --global user.name "YOUR-USERNAME"
- Clone your repository
cd apps/
# Replace 'YOUR-USERNAME/YOUR-REPOSITORY' below with the correct link to your new repo
# You can get this path from the SSH tab on the green '<> code' button of your new repo
git clone git@github.com:YOUR-USERNAME/YOUR-REPOSITORY.git
If you cannot clone with SSH, you can try https:
# You can get this path from the HTTPS tab on the green '<> code' button of your new repo
git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git
- Run the app on your Amiga
The first time you launch will take a while, as the requirements have to install.
If your brain is on the launcher screen, your new app should appear! You can launch it by clicking your the app on the screen, and it should begin loading.
Alternatively, you can launch from the command line:
cd YOUR_REPOSITORY/
./entry.sh # install and run
If you launch your app with the command line, it is currently possible to have touch interactions with the launcher behind. This will cause other installed apps to unexpectedly launch over the app you are trying to use.
Please see instructions for a workaround under: FAQ - Brain App Development