farmbot_os: the Elixir system behind a FarmBot's Raspberry Pi

An operating system for one specific robot, not a general robotics stack

The repository description is precise: the operating system and all related software that runs on FarmBot's Raspberry Pi. That is the scope, and the primary language of the repository is Elixir.

That framing matters, because a reader coming from robotics generally might expect something like a ROS distribution. What is here is the software stack for a particular product: a small agricultural robot whose body is a Raspberry Pi, and whose job is to move a gantry, plant seeds, water, and sense the soil. The topics list names elixir, farmbot and nerves, and the Nerves reference is the key architectural fact. Nerves is the Elixir framework for building embedded systems, and the presence of a rootfs_overlay/ directory alongside priv/, rel/ and platform/ in the repository tree is the signature of that approach: an overlay of files layered onto a base root filesystem, so the image is a real filesystem image rather than an application installed on top of a general-purpose Linux distribution.

The consequence is that this is not a distribution you install alongside other software. It is the system. The image is what the device runs, and the repository is where that image's contents are built.

The audience is therefore narrower than the topic tags might suggest. It is the FarmBot hardware owner who wants to install or reflash the OS, and the developer writing software that talks to the robot's own services and needs to know what those services are called and which version introduced them. The README separates these two audiences explicitly, pointing end users to the official documentation for installing FBOS on a device and developers to a separate developer documentation site.

The licence is MIT, the default branch is staging, and the last push was on 2026-10-15, so the work is current.

The release channel, and why a staging default matters

The release cadence is where this project differs from an ordinary software repository, and the recent tag list shows it clearly.

The three most recent tags are v15.5.3-rc10 on 2026-10-15, v15.5.3-rc1 on 2026-07-22, and v15.5.2 on 2026-06-02. Two things stand out. The version scheme is a major number tied to the hardware generation, with a minor and a patch, so 15.5.x is a specific line rather than a rolling release. And release candidates are published as first class tags, with an rc1 and then an rc10 for the same 15.5.3, which is a pattern you would expect from a product where a bad image bricks a device rather than a service where a bad deploy rolls back.

The default branch is staging, and the build status table in the README has separate columns for main and staging with their own CircleCI badges, plus a test coverage badge pointed at the staging branch. The codecov badge and the coveralls.json file indicate two coverage services are in use, and COVERAGE.md sits in the repository as a readable coverage report alongside the.luacov file that configures the Elixir coverage tool.

So the branch structure is a promotion pipeline: work lands on staging, is built and tested there, and the release images come from that pipeline. For a contributor this matters, because pull requests target staging, and the CI you satisfy is the staging CI.

The README also has a note that end users should not install from the repository at all. The FarmBot OS release page has moved to my.farm.bot/os, and older versions of FarmBot OS are found on the GitHub releases page. That separation is deliberate: the repository is the source, and the release page is the distribution channel for images.

FEATURE_MIN_VERSIONS.json, the file that decides what your code can assume

Among the top-level entries, one filename is unusual enough to deserve its own explanation: FEATURE_MIN_VERSIONS.json.

The name says what it is. For each feature the system provides, the file records the minimum OS version in which that feature is available. It is a compatibility table, machine readable, checked into the repository next to the source.

This is the mechanism that resolves the central problem of an OS-versioned product. A developer writing an integration against a FarmBot service faces the question of which OS versions they can assume. Without an answer, the choices are to support everything back to the first release, which is expensive, or to guess, which is worse. A feature-to-minimum-version table turns it into a lookup.

Consider what a feature means here. The FarmBot OS is not a monolith of generic services, it is a set of specific capabilities, the ability to read a soil moisture sensor, to drive a stepper motor, to stream a camera feed, to run a sequence of garden actions, to talk to the FarmBot API over the local network. Each of those was added at some version. The table records when.

This is the single most useful thing in the repository for an adopter, and it is worth pairing with the support policy note. The README states plainly that FarmBot does not provide support for old versions of FBOS, and links the support policy. In practice that means a device on an old image receives no help, so a feature table and a support window have to be read together: the table tells you what a feature needs, and the support policy tells you how long you can stay on the version you have.

The file also suggests something about how the project is designed. A feature that cannot be dated is a feature nobody can safely depend on, and a project that supports a fleet of devices in the field needs every feature to be datable. The table is the discipline that makes the rest of the API stable enough to build against.

The repository layout, and what each directory is for

The tree tells you what kind of project this is, and the directory names carry most of the meaning.

The Elixir side is conventional. mix.exs and mix.lock are the Mix project definition and its dependency lock, lib/ holds the application code, config/ the configuration, priv/ the private assets and data, test/ the test suite, and fixtures/ the test data. The.busted file configures Busted, a test framework the project also uses, and.formatter.exs is the Elixir formatter configuration, which is what keeps a large Elixir codebase consistent under a single opinionated style.

The embedded side is the interesting part. rootfs_overlay/ holds the files layered onto the base root filesystem, which is how you get your own configuration, scripts and services onto the device image without forking the base. platform/ holds the platform-specific build definitions, the target and its configuration. rel/ is the release directory, the artefacts that become the actual image. The VERSION file holds the version, and ELIXIR_VERSION pins the Elixir version the project builds against, with.tool-versions doing the same job for a toolchain manager. run_all.sh sits at the top level as a convenience script for running the whole suite.

The documentation side is equally telling. CHANGELOG.md and RELEASE_NOTES.md are separate files, which is a distinction worth noticing: the changelog records what changed, the release notes record what a user should do about it. RELEASE_NOTES.md is what you would read before flashing a new image to a field device, because it is the part that tells you whether the update changes anything you depend on.

SECURITY.md and the responsible disclosure guidelines linked from the README show the same seriousness about the other axis. The README says they take security seriously and value the input of independent researchers, which for a device that sits on a home network and holds credentials for a cloud service is a reasonable stance to state plainly.

Getting an image, and the honest limits of this repository

There is no install command in this repository, and pretending otherwise would be inventing a fact. The README routes installation elsewhere: end users are pointed to the official documentation at software.farm.bot/docs/farmbot-os, and the release page for images is my.farm.bot/os. Old versions remain on the GitHub releases page.

That is the correct arrangement for this product. Flashing an OS image onto a device is a procedure with hardware-specific steps, a recovery story, and a set of preconditions about which Pi model and which storage you have. Documenting it as a set of shell commands in a source repository would be the wrong place for it, and the split keeps the code repository about code.

So for an evaluator, the practical first step is to read the developer documentation at developer.farm.bot/docs/farmbot-os, and the second is to look at what a release actually contains by examining the repository's own artefacts. The rel/ directory holds the release build output, and the top-level scripts and configuration directories are where the packaging is assembled.

Two limits deserve naming. The first is that the image is the product and the source is the means of producing it, so there is no way to get a running system from this repository alone without the platform tooling and the base image. The second is the support boundary. The README is explicit that FarmBot does not provide support for old versions of FBOS, which means an operator running a fleet of devices needs a policy for how far behind they let them drift, and this repository gives them the data to write that policy rather than a way to avoid it.

For developers who want to help, the README points at a TODO search for low hanging fruit, at CONTRIBUTING.md for the development workflow, and at a GitHub issue form for anything else.

farmbot_os against the alternatives

The comparison that makes sense here is not with other robotics operating systems in the abstract, it is with the two ways you might otherwise get software onto a FarmBot's Raspberry Pi.

The first alternative is a general-purpose embedded Linux distribution with your own application layered on top. You would use something like Raspberry Pi OS, install a services manager, write your own startup orchestration, and own the whole stack. The difference in approach is that farmbot_os makes the image itself the deliverable, so the configuration, the services and the recovery behaviour are versioned together and delivered as one artefact. The cost of that approach is that you take what the project provides, and you are on the version schedule the project sets.

The second alternative is writing the whole robot stack yourself on the same Raspberry Pi, in whatever language you prefer, with Nerves or without it. FarmBot OS is derived from Nerves, so the embedded runtime concerns, the image build, the supervised process model and the over-the-air update path are the parts you would otherwise design. The parts you would still build are the domain logic, the garden behaviours and the integrations.

A third comparison is with a hosted service. FarmBot also runs a cloud side, and the OS is the device half of that pairing. The interesting property of the local half is that the robot keeps working on your network, and the things it does not need the cloud for, it does not need the cloud for.

The decision, then, comes down to whether you want a supported product with a version schedule and a support policy, or you want to own the entire stack. A team that is building a garden robot for its own use and has Elixir experience will get a lot from the image, the process supervision, the release pipeline and the compatibility table. A team that needs to run an old image forever, or that has no interest in the product's own feature set, is better served by the general-purpose path.

Editorial conclusion

Adopt farmbot_os if you are building on FarmBot hardware or writing software for a garden robot, and you want an Elixir codebase with a real image-based release process rather than a script you install onto a card yourself. Do not adopt it as a general-purpose robotics stack, because the versioning and the minimum-feature table are tied to FarmBot's own hardware and support policy. Verify first that the OS image you install matches the features your software depends on, by reading FEATURE_MIN_VERSIONS.json, and that you are on a release FarmBot still supports, since the support policy explicitly excludes older versions of FBOS.

Frequently asked questions

Official sources

1. FarmBot/farmbot_os on GitHub
2. Issues
3. License: MIT
4. README
5. Releases