A Farmware generally includes Python code that is run by FarmBot OS. During development, you may first write and run the Python code on your local computer. To run it with FarmBot OS, the code must be hosted on a server from which FarmBot OS can download it.

All of the following methods require a minimum of two files:

  • A Farmware manifest: manifest.json. (see the Farmware manifest for general info)
  • The Farmware code: a .py file that contains or runs the code you’ve written. (See Farmware.)

For example Farmware files, see Hello Farmware.

Farmware code filenames

The following examples use my_farmware_code.py, but a different name should be chosen for your main Farmware code file.

Farmware is downloaded by FarmBot OS by installing it via the Web App FarmBot OS is connected to, which can either be self-hosted or at the public my.farm.bot. The manifest.json file URL is used for installation. See Installing Farmware in the user documentation for basic UI operation.

Farmware can be run via the Web App by selecting it on the Farmware page and pressing run. (See Farmware in the user documentation for basic UI operation.)

Troubleshooting tips can be found on the Common Farmware Problems page.

A typical heavy development workflow might include all of the following options in order. If a Linux system is not available, one might skip options 2 and 3 (which require running a server or building FarmBot OS). If Python is not available, one might skip options 1-3 and write a Farmware directly on GitHub. Published Farmware are usually hosted in a GitHub repository.

For the examples below, you can assume you want your Farmware to tell your FarmBot to say “Hi!” and so my_farmware_code.py contains the following code:

from farmware_tools import device
device.log('Hi!')

Option 1: Python (without FarmBot OS)

Run the Python code on your computer.

Pros:

  • Fastest updates and most robust debugging for the code itself.

Cons:

  • Does not reflect the FarmBot OS environment where the code will eventually be run.

Process

  1. Write some Python code.
  2. Run it via Python.

Note: To run code that imports farmware_tools on your computer (without FarmBot OS), you will need to install the package via pip install --user farmware_tools. FarmBot OS already has the package built in.

Option 2: Localhost (run FarmBot OS locally)

Run FarmBot OS on your computer.

This option is not recommended unless you are familiar with Linux and building Elixir apps.

Pros:

  • Allows direct editing of Farmware code.

Cons:

  • Must be able to compile FarmBot OS on a compatible system. (see FarmBot OS).

Process

  1. Follow the instructions for setting up a local development environment for FarmBot OS.
  2. Create a Farmware manifest and zip file containing your Python code and start an HTTP server on your computer. (e.g., python3 -m http.server 8000 --bind 127.0.0.1). Alternatively, use one of the other hosting methods.

manifest.json:


 "package": "my-farmware",
 "language": "python",
 "author": "me",
 "description": "A description of my Farmware.",
 "version": "1.0.0",
 "min_os_version_major": 6,
 "url": "http://localhost:8000/manifest.json",
 "zip": "http://localhost:8000/zipped_farmware.zip",
 "executable": "python",
 "args": ["my_farmware_code.py"]
  1. Install the Farmware via the manifest.json file url at the HTTP server address. (e.g., http://localhost:8000/manifest.json if using the locally hosted method)
  2. Open the Farmware code (e.g., my_farmware_code.py) in the FarmBot OS farmbot_os/tmp/farmware directory.
  3. Edit the Farmware. Once changes are saved, running the Farmware will run the updated version.

Option 3: HTTP server host method

Host the Farmware from your own server.

Pros:

  • Faster updates.

Cons:

  • More involved process and limited hosting availability.

Process

  1. Create a Farmware manifest and zip file containing your Python code.

manifest.json:


 "package": "my-farmware",
 "language": "python",
 "author": "me",
 "description": "A description of my Farmware.",
 "version": "1.0.0",
 "min_os_version_major": 6,
 "url": "http://192.168.0.100:8000/manifest.json",
 "zip": "http://192.168.0.100:8000/zipped_farmware.zip",
 "executable": "python",
 "args": ["my_farmware_code.py"]

(where 192.168.0.100 is the IP address of your computer running the file server and zipped_farmware.zip is the name of the zip file containing my_farmware_code.py)

  1. Start an HTTP server on your computer. (e.g., python3 -m http.server 8000)
  2. Install the Farmware via the manifest.json file url at the HTTP server address. (e.g., http://192.168.0.100:8000/manifest.json, where 192.168.0.100 is the IP address of your computer running the file server.)
  3. After editing the Farmware, the code must be re-zipped and the Farmware either re-installed or updated by bumping the version value in manifest.json and pressing the UPDATE button in the Web App.

Option 4: GitHub host methods

Host Farmware code on GitHub for download and running by FarmBot OS installed on a Raspberry Pi.

Pros:

  • Easy hosting.
  • .zip file is created automatically.

Cons:

  • Updates to served files can be slow.

Process

  1. Create a new GitHub repository or Gist.
  2. Add a manifest.json file.

manifest.json (GitHub):


 "package": "my-farmware",
 "language": "python",
 "author": "me",
 "description": "A description of my Farmware.",
 "version": "1.0.0",
 "min_os_version_major": 6,
 "url": "https://raw.githubusercontent.com/gh_username/repo-name/master/manifest.json",
 "zip": "https://github.com/gh_username/repo-name/archive/master.zip",
 "executable": "python",
 "args": ["repo-name-master/my_farmware_code.py"]

(where gh_username is your GitHub username and repo-name is the GitHub repository name) See Farmware for a real-world example.

manifest.json (Gist):


 "package": "my-farmware",
 "language": "python",
 "author": "me",
 "description": "A description of my Farmware.",
 "version": "1.0.0",
 "min_os_version_major": 6,
 "url": "",
 "zip": "https://gist.github.com/gh_username/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/archive/master.zip",
 "executable": "python",
 "args": ["xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-master/my_farmware_code.py"]

(where xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx is the Gist ID found in the URL)

  1. Install via the raw manifest.json file url and run.
  2. After editing the Farmware,
    • if using GitHub, it can be updated by bumping the version value in manifest.json and pressing the UPDATE button in the Web App.
    • if using Gist, the Farmware must be uninstalled and re-installed. (Bumping the version is not necessary when using Gist).

What’s next?