Developing Custom Applications

Create an app

Create a repository from the template

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

tip

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

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 have created a new git repository, you have two options:

1. Work in your local workspace (for development)
2. Work in a Remote-SSH session on your robot (deployment on a brain)

If you have not yet established a Remote-SSH connection, refer to this documentation: https://amiga.farm-ng.com/docs/ssh/

For this example, we recommend option 2 and clone the repository directly onto the brain.

After you have established connection:

cd <to-your-base-directory>
git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git

Project structure

Understand the structure of an app

Every modern app typically consists of two main parts: the backend and the frontend. Let's dive into what each of these components does and how they interact with each other.

Backend:

The backend is like the brain of your app. It processes data, makes calculations, communicates with databases, and performs all the logical operations. When you hear terms like "server," "API," or "database," they're usually related to the backend.

In our example, we're using FastAPI to build our backend. FastAPI is a modern, high-performance web framework for building APIs. Coupled with the farm-ng brain services, our backend will fetch and serve data efficiently and securely to the frontend.

Key Points:

1. Handles data processing, storage, and retrieval.
2. Communicates with other services and databases.
3. Secures data and ensures only authorized users can access it.

Frontend:

The frontend is the part of the app users see and interact with. Think of it as the face of your app which includes everything that you can touch, click, or interact with: buttons, images, text inputs, animations, and more.

For our frontend, we're using ReactJS. ReactJS is a popular JavaScript library for building user interfaces. It allows developers to create responsive and interactive UI components easily.

Repository 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.
├── ts/ # Contains ReactJS frontend code.
|   ├── index.html  # The HTML template of the app frontend.
|   ├── package.json  # The file containing the dependencies of the project frontend.
|   └── src/
|       ├── components/  # Contains ReactJS components.
|       |   ├── TopicMonitor.tsx  # The component that displays the topic monitor.
|       |   └── App.tsx  # The main entry point of the app frontend.
|       └── main.tsx  # The main entry point of the app frontend.
├── main.py
|   # The main entry point of the app backend.
├── manifest.json
|   # The file containing the metadata of the project.
├── install.sh
|   # The script to register the app in the launcher.
├── uninstall.sh
|   # The script to unregister the app from the launcher.
└── requirements.txt
    # The file containing the dependencies of the project backend.

The manifest.json file

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

In order to run the application, you will need to update YOUR_USER_HERE to reflect your user from fleet manager.

{
  "services": {
    "example-app": {
      "name": "example-app",
      "type": "app",
      "exec_cmd": "/mnt/managed_home/farm-ng-user-YOUR_USER_HERE/amiga-app-template/venv/bin/python3
                   /mnt/managed_home/farm-ng-user-YOUR_USER_HERE/amiga-app-template/main.py",
      "args": [
        "--config /opt/farmng/config.json", "--port 8042"
      ],
      "autostart": true,
      "http_gui_port": 8042,
      "display_name": "Monitor App"
    }
  }
}

This might look something like:

/mnt/managed_home/farm-ng-user-jane/...

note

Learn more about the manifest file here.

How to setup the project

1. Begin by installing node version manager (nvm) in the /ts directory.

cd ts/
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

Once this has finished running, you should see the following message:

=> Close and reopen your terminal to start using nvm or run the following to use it now:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

2. Verify installation by closing and re-opening the terminal and running:

nvm --version
    0.34.0

You should see a version >= 0.34.0.

3. Prepare the frontend and compile the typescript code to javascript within the ts/ folder of your custom app

cd ts/
nvm install --lts
npm install
npm run build  # build the frontend

4. Prepare the backend

Install the dependencies of the backend

cd ..
python3 -m venv venv  # create a virtual environment
source venv/bin/activate  # activate the virtual environment
python -m pip install --upgrade pip # make sure pip is updated
pip install -r requirements.txt  # install dependencies

How to run the project

Run the backend in a terminal

python main.py --config /opt/farmng/config.json

Optionally, you can run into debug mode to use the local frontend instead of the one served by the launcher.

python main.py --config /opt/farmng/config.json --debug

info

If when running main.py, a port error occurs:

[Errno 98] error while attempting to bind on address ('0.0.0.0', 8042): address already in use

This can occur while developing and can be resolved with:

sudo reboot

To visualize the app in your browser, go to http://localhost:8042

Run the app in the launcher

1. Register the app in the launcher

./install.sh

2. Now you should be able to see the app in the launcher and run it.

3. If for some reason you need to remove your app from the launcher

./uninstall.sh