Skip to content
Browse files

Update/Write some documentation describing the overall project

  • Loading branch information
ConnorRigby committed Dec 18, 2019
1 parent 8f29577 commit 9da8477008e144244a3a0de4b4a75b4f7cc8ffa2
@@ -1,2 +1,4 @@
# Contributing
To get started, <a href="">sign the Contributor License Agreement</a>.

After that, read through the [documentation](docs/
@@ -49,14 +49,14 @@ _Refer to the [software documentation Configurator page](

## Problems?

See the [FAQ](docs/
If your problem isn't solved there please file an issue on [Github](
See the [FAQ](docs/target_development/
If your problem isn't solved there please file an issue on [Github](

## Security Concerns?

We take security seriously and value the input of independent researchers. Please see our [responsible disclosure guidelines](

## Want to Help?

[Low Hanging Fruit](
[Low Hanging Fruit](
File renamed without changes.
@@ -1,4 +1,5 @@
# CeleryScript

CeleryScript is an AST definition of commands, rpcs, and functions that
can all be executed by Farmbot. The basic syntax is as follows:

@@ -16,6 +17,7 @@ optional, `body` should be supplied when working with any and all modules
in this project.

## kind

`kind` is the identifier for a command. Examples include:
* `move_absolute`
* `sync`
@@ -26,6 +28,7 @@ Each `kind` will have it's own set of rules for execution. These rules will
define what is required inside of both `args` and `body`.

## args

`args` is arguments to be passed to `kind`. Each `kind` defines it's own
set of optional and required `args`. Args can any of the following types:
* `number`
@@ -42,6 +45,7 @@ executing the parent AST. Examples of `args` include:
* `milliseconds`

## body

`body` is the only way a `list` or `array` type is aloud in CeleryScript.
It may only contain _more CeleryScript nodes_. This is useful for
enumeration, scripting looping etc. Here's a syntacticly correct example:
@@ -0,0 +1,48 @@
# FarmBot OS Source Glossary

This file contains a basic glossary of commonly used terms

## FarmBot Specific Terms

* Asset - REST resource stored in Farmbot's database stored on the SD card
* Arduino Firmware - The code that runs on the Arduino.
* [Source](
* CelleryScript - FarmBot OS's scripting language
* FarmbBot API/Web App - The REST server FarmBot communicates with

## General Terms

* Elixir - Programming language FarmBot is developed in
* [More info](
* [Docs](
* Erlang - Programming language and VM that Elixir compiles down too
* [More info](
* [Even more info](#OTP-Terms)
* [Docs](
* UART - **U**niversal **A**synchronous **R**eceiver/**T**ransmitter. hardware based transport mechanism
* SSH - **S**ecure **S**hell.
* MQTT/AMQP - network protocols for pub/sub data transport
* HTTP - network protocol for accessing REST resource
## Nerves Specific Terms
* Nerves - Framework that allows cross compilation of Elixir code
* [More info](
* [Docs](
* NervesHub - Cloud based firmware management
* [More info](
* [Docs](
* Firmware - Usually refers to the code that gets deployed onto the Raspberry Pi
## OTP Terms
* Beam - Virtual machine that runs compiled Erlang bytecode
* OTP - Open Telecom Platform. Erlang's runtime libraries
* [More info](
* Supervisor - OTP `Process` responsible for supervising `Workers`
* Worker - OTP `Process` responsible for doing `work`. Usually `Supervised`
* Process - OTP concept responsible for sending/receiving messages. **everything** is a process in erlang
* Application - OTP concept responsible for containing many `Supervisor`s and `Worker`s
* Distribution - OTP concept of networking multiple Beam instances together
* ETS - **E**rlang **T**erm **S**torage. OTP application for storing data in memory
* DETS - **D**isk **E**rlang **T**erm **S**torage. OTP application for storing data on disk
File renamed without changes.
@@ -0,0 +1,38 @@
# FarmBot OS Documentation

This document will act as an index to available documentation.

## Glossary

* [FarmBot Source Code common terms](/docs/

## Hardware specifics

Most FarmBot development/testing is done on a standard desktop PC.

* [Developing on your local PC](/docs/host_development/
* [Deploying on Raspberry Pi](/docs/target_development/
* [Publishing Firmware (OTAs)](/docs/target_development/
* [Why doesn't my device boot after building firmware](docs/target_development/
* [Inspecting a running devicve](/docs/target_development/consoles/

## CeleryScript

CeleryScript is FarmBot's native scripting language. See the below
documentation for information about it as it relates to FarmBot OS.

* [CeleryScript intro](/docs/celery_script/
* [A list of all supported commands](/docs/celery_script/
* [Lua (embedded scripting inside CeleryScript)](/docs/celery_script/

## Project structure

The FarmBot OS application is broken into several sub applications.

* [Project structure overview](/docs/project/
* [farmbot_celery_script](/docs/project/
* [farmbot_core](/docs/project/
* [farmbot_ext](/docs/project/
* [farmbot_firmware](/docs/project/
* [farmbot_os](/docs/project/
* [farmbot_telemetry](/docs/project/
@@ -0,0 +1,12 @@
# FarmBot CeleryScript OTP App

`farmbot_celery_script` is responsible for implementing the
runtime that execute's [CeleryScript](/docs/celery_script/
It contains a handful of helpers, and several subsystems for working with CeleryScript.
The most important being:
* AST - definition of the AST as it relates to FarmBot OS
* Compiler - Compiles CeleryScript to Elixir AST.
* See the [Elixir Macro Docs](
* StepRunner - Process responsible for actually executing CeleryScript
* Scheduler - Process responsible for scheduling calls to the `StepRunner`
* SysCalls - module responsible for dispatching calls to the configured implementation
@@ -0,0 +1,58 @@
# FarmBot Core OTP App

`farmbot_core` is responsible for the core funcionality of the FarmBot application.
This contains things such as resource (asset) management, plugin (farmware) management,
central state, and schedule management. FarmBot specific network requests are not made
from the `farmbot_core` app. Below describes the important subsystems

## Asset storage subsystem

Sqlite database responsible for storing data needed for FarmBot to operate.
Most device specific REST resources are mirrored here.
* Device
* FarmEvent
* Regimen
* Sequence
* Peripheral

## Asset Worker subsystem

All assets that need to have a process assosiated with it will be found
in this subsystem. Examples of this include:
* FarmEvent scheduling
* Regimen scheduling
* PinBinding monitoring
* FbosConfig/FirmwareConfig

## Farmware subsystem

Farmbot's external plugin system. See the Farmware documentation for more details.

## BotState subsystem

Central in-memory state process/tracker. This process keeps a cache of
all the moving parts of FarmBot. Some examples of what is stored
in this cache:

* Firmware reporting
* current axis position
* encoder data
* arduino pin data
* currently configured firmware paramaters
* Current configuration
* mirror of `fbos_config` asset
* System info
* version info
* (nerves) firmware info
* memory usage
* disk usage
* Network info
* WiFi signal quality
* private ip address

## Logging subsystem

This is where the `Messages` panel gets it's data from. Calls to this subsystem
push data into an sqlite database. This data is collected on a timer and dispatched
over AMQP/MQTT when/if that subsystem is available. See [farmbot_ext](/docs/project/
for information on how that works.
@@ -0,0 +1,38 @@
# FarmBot Ext OTP App

the `farmbot_ext` OTP app contains extended FarmbotCore functionality. This includes
mostly network functionality that isn't possible to do in `farmbot_core`.

## Bootstrap subsystem

Subsystem responsible for bootstrapping a connection to the FarmBot network services.
This includes authenticating with the FarmBot API, connecting to AMQP/MQTT and syncing
the bare minimum resources to get up and running.

## HTTP/Sync subsystem

This is the subsystem that syncronizes FarmBot with the remote API. It uses HTTP to
download an index of all the data FarmBot cares about, and compares timestamps to
determine who has the most up to date data. The basic flow is whoever has the most
recent `updated_at` field will become the "most truthy". If FarmBot has a more recent
`updated_at` field, FarmBot will do an HTTP PUT of it's data. If the remote resource
does not exist, FarmBot will do an HTTP POST of it's data. If the remote data has a more
recent `updated_at` field, FarmBot will do an HTTP GET and replace it's own data.

## AMQP/MQTT substem

FarmBot maintains a connection to the API for real time communication. This real time communication
connection is multiplexed over multiple `channel`s. Below is a description of the channels

* bot_state - pushes a JSON encoded version of the `bot_state` process (from `farmbot_core`)
* celery_script - receives/sends JSON encoded celery_script. Used for controling FarmBot externally
* log - sends log messages from `farmbot_core`'s logger
* ping/pong - echos everything received. used for detecting active conncetion
* auto_sync - the API dispatches every REST resource change on this channel. Used to speed up HTTP requests
* telemetry - similar to the log channel, but sends consumable events, rather than human readable messages

## Image uploader subsystem

This subsystem watches a local directory, and as matching files appear in that directory,
it uploads them using the FarmBot image upload protocol. Basically an HTTP request to fetch
credentials that are used to preform another HTTP request to upload the photo.
@@ -0,0 +1,23 @@
# FarmBot Firmware OTP App

The `farmbot_firmware` OTP application is responsible for maintaining a connection to
the arduino-firmware.

## GCODE encoder/decoder subsystem

The official Farmbot-Arduino-Firmware communicates over UART using a ASCII based
protocol based on CNC GCODE. This subsystem is responsible for translating
the ASCII data into an intermediate representation that can be `transport`ed
proto agnostically.

## Transport subsystem

This subsystem is responsible for abstracting the details of transporting
FarmBot GCODEs to/from the firmware implementation. A `transport` will take
in the intermediate (farmbot specific) representation of a GCODE, and dispatch/handle
it in it's own specific manor. This keeps the usage of the overall application uniform
with or without a firmware plugged in.

## UART subsystem

Responsible for the official communication mechanism with the official arduino hardware.
@@ -0,0 +1,50 @@
# FarmBot OTP App

the `farmbot` OTP app is the container Nerves based application. It contains mostly
glue code between all the subsystems in the other applications along with it's own
platform specific subsystems.

## CeleryScript System Calls

The "official" implementation of all the CeleryScript syscalls. These calls are mostly
glue to other existing implementations from the other otp apps.

## Lua Subsystem

The implementation of the embedded scripting language inside CeleryScript.
Also contains glue code for glueing together the real implementation to the
Lua vm.

## Configurator Subsystem

HTTP server responsible for configuring the running FarmBot OS instance. Will
server a web page that allows a user to supply a username, password, network credentials

# Platform specific subsystems

the `farmbot_os` OTP app contains target/hardware specific systems. This code is
located in the `platform` directory.

## Network subsystem

Responsible for getting FarmBot connected to the (inter)net. If no network configuration is
available, FarmBot will create a captive portal access point to allow external devices to
configure it.

## GPIO subsystem

Responsible for implementing LED and Button support at the hardware level.

## RTC subsystem

Responsible for syncronizing network time to an attached hardware clock.

## Info Worker subsystem

Responsible for simple workers that handle things like

* CPU temperature
* CPU usage
* memory usage
* disk usage
No changes.
@@ -0,0 +1,33 @@
## FarmBot Source Project structure

The FarmBot OS application is broken into several sub OTP applications.

* [farmbot_celery_script](/docs/project/
* [farmbot_core](/docs/project/
* [farmbot_ext](/docs/project/
* [farmbot_firmware](/docs/project/
* [farmbot_os](/docs/project/
* [farmbot_telemetry](/docs/project/

## Commonality

All of these folders share a common structure.

├── lib/
│ ├── application.ex
│ └── some_file.ex
├── test/
| └── test_helper.exs
├── config/
| └── config.exs
├─── mix.exs
└─── mix.lock

* The `lib` folder contains Elixir source code
* the `test` folder contains Elixir scripts responsible for testing the `lib` code
* the `config` folder contains Elixir scripts responsible for configuring the **current** OTP app
* `mix.exs` and `mix.lock` files are responsible describing the OTP app, and managing external dependencies
File renamed without changes.
@@ -0,0 +1,26 @@
# Erlang Distribution Console

Accessing an Erlang Distribution console

## Setup

No additional setup is required for setting up erlang distribution on the target.
On your `host` machine, you need to have Erlang Distribution running. This can
usually be accomplished by starting `epmd`:

epmd --daemon

## Connecting

From your `host` terminal, connecting to a running device can be done by using the
`remsh` feature of elixir's built in console.

iex --name console --cookie democookie --remsh farmbot@farmbot-<SERIAL_NUMBER>.local

## Disconnecting

Issuing a `ctrl+c` to the `host` terminal should disconnect you from the session.

0 comments on commit 9da8477

Please sign in to comment.
You can’t perform that action at this time.