spacecruft
/
farmbot_os
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Update docs to conform with mdl spec

pull/1090/head
Connor Rigby 2019-12-18 12:01:55 -08:00 committed by Connor Rigby
parent 9da8477008
commit 836c8b3841
20 changed files with 337 additions and 212 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

145
docs/celery_script/all_nodes.md
View File

@ -1,73 +1,88 @@
# All CeleryScript Nodes
This list is split into three categories.
* RPC Nodes - Nodes that control Farmbot's state, but don't don't command
a real world side effect. This includes:
* updating configuration data.
* syncing.
* starting/stopping a process of some sort.
* rebooting
* Command Nodes - Nodes that physically do something. This includes:
* moving the gantry.
* writing or reading a GPIO.
* Data Nodes - Nodes that simply contain data. They are not to be executed.
This includes:
* explanation
* location data
## RPC Nodes
| Name | Args | Body |
|:-------------------------------|:-------------------------------------:|:-------------------------:|
| `check_updates` | `package` | --- |
| `config_update` | `package` | `pair` |
| `uninstall_farmware` | `package` | --- |
| `update_farmware` | `package` | --- |
| `rpc_request` | `label` | more command or rpc nodes |
| `rpc_ok` | `label` | --- |
| `rpc_error` | `label` | `explanation` |
| `install farmware` | `url` | --- |
| `read_status` | --- | --- |
| `sync` | --- | --- |
| `power_off` | --- | --- |
| `reboot` | --- | --- |
| `factory_reset` | --- | --- |
| `set_usr_env` | --- | `pair` |
| `install_first_party_farmware` | --- | --- |
| `change_ownership` | --- | `pair` |
| `dump_info` | --- | --- |
Nodes that control Farmbot's state, but don't don't command
a real world side effect. This includes:
* updating configuration data.
* syncing.
* starting/stopping a process of some sort.
* rebooting
### RPC Node Table
| Name | Args | Body |
|:-: | :--:|:--:|
| `check_updates`| `package`| ---|
| `config_update`| `package`| `pair`|
| `uninstall_farmware`| `package`| ---|
| `update_farmware`| `package`| ---|
| `rpc_request`| `label`| `command` or `rpc` nodes|
| `rpc_ok`| `label`| ---|
| `rpc_error`| `label`| `explanation`|
| `install farmware`| `url`| ---|
| `read_status`| --- | ---|
| `sync`| --- | ---|
| `power_off`| --- | ---|
| `reboot`| --- | ---|
| `factory_reset`| --- | ---|
| `set_usr_env`| --- | `pair`|
| `install_first_party_farmware`|---|---|
| `change_ownership`| --- | `pair`|
| `dump_info`| --- | ---|
## Command Nodes
| Name | Args | Body |
|:-------------------------------|:-------------------------------------:|:-------------------------:|
| `_if` | `lhs`, `op`, `rhs`, `_then`, `_else` | `pair` |
| `write_pin` | `pin_number`, `pin_value`, `pin_mode` | --- |
| `read_pin` | `pin_number`, `pin_value`, `pin_mode` | --- |
| `move_absolute` | `location`, `speed`, `offset` | --- |
| `set_servo_angle` | `pin_number`, `pin_value` | --- |
| `send_message` | `message`, `message_type` | `channel` |
| `move_relative` | `speed`, `x`, `y`, `z` | --- |
| `sequence` | `version`, `locals` | more command nodes |
| `home` | `speed`, `axis` | --- |
| `find_home` | `speed`, `axis` | --- |
| `wait` | `milliseconds` | --- |
| `execute` | `sequence_id` | --- |
| `toggle_pin` | `pin_number` | --- |
| `execute_script` | `package` | `pair` |
| `zero` | `axis` | --- |
| `calibrate` | `axis` | --- |
| `emergency_lock` | --- | --- |
| `emergency_unlock` | --- | --- |
| `take_photo` | --- | --- |
Nodes that physically do something. This includes:
* moving the gantry.
* writing or reading a GPIO.
### Command Node Table
| Name | Args | Body |
|:-: | :--:|:--:|
| `_if`| `lhs`, `op`, `rhs`, `_then`, `_else`| `pair`|
| `write_pin`| `pin_number`, `pin_value`, `pin_mode`| ---|
| `read_pin`| `pin_number`, `pin_value`, `pin_mode`| ---|
| `move_absolute`| `location`, `speed`, `offset`| ---|
| `set_servo_angle`| `pin_number`, `pin_value`| ---|
| `send_message`| `message`, `message_type`| `channel`|
| `move_relative`| `speed`, `x`, `y`, `z`| ---|
| `sequence`| `version`, `locals`| `any command node`|
| `home`| `speed`, `axis`| ---|
| `find_home`| `speed`, `axis`| ---|
| `wait`| `milliseconds`| ---|
| `execute`| `sequence_id`| ---|
| `toggle_pin`| `pin_number`| ---|
| `execute_script`| `package`| `pair`|
| `zero`| `axis`| ---|
| `calibrate`| `axis`| ---|
| `emergency_lock`| ---| ---|
| `emergency_unlock`| ---| ---|
| `take_photo`| ---| ---|
## Data Nodes
| Name | Args | Body |
|:-------------------------------|:-------------------------------------:|:-------------------------:|
| `point` | `pointer_type`, `pointer_id` | --- |
| `named_pin` | `pin_type`, `pin_id` | --- |
| `pair` | `label`, `value` | --- |
| `channel` | `channel_name` | --- |
| `coordinate` | `x`, `y`, `z` | --- |
| `tool` | `tool_id` | --- |
| `explanation` | `message` | --- |
| `identifier` | `label` | --- |
| `nothing` | --- | --- |
| `scope_declaration` | --- | `parameter_decleration`, `variable_decleration` |
Nodes that simply contain data. They are not to be executed. This includes:
* explanation
* location data
### Data Node Table
| Name | Args | Body |
|:-: | :--:|:--:|
| `point`| `pointer_type`, `pointer_id`| ---|
| `named_pin`| `pin_type`, `pin_id`| ---|
| `pair`| `label`, `value`| ---|
| `channel`| `channel_name`| ---|
| `coordinate`| `x`, `y`, `z`| ---|
| `tool`| `tool_id`| ---|
| `explanation`| `message`| ---|
| `identifier`| `label`| ---|
| `nothing`| ---| ---|
| `scope_declaration`| ---| `parameter_decleration` or `variable_decleration`|

13
docs/celery_script/assert_expressions.md
View File

@ -1,12 +1,13 @@
# CeleryScript Assert expressions.
# CeleryScript Assert expressions
The CeleryScript `if` block takes a possible left hand side value of
`expression` which allows an arbitrary string to be evaluated. This
expression is evaluated against a lua 5.2 interpreter.
`expression` which allows an arbitrary string to be evaluated. This
expression is evaluated against a lua 5.2 interpreter.
## Lua API
The following functions are available for usage along with [Lua's
standard library](https://www.lua.org/manual/5.2/).
The following functions are available for usage along with
[Lua's standard library](https://www.lua.org/manual/5.2/).
```lua
-- Comments are ignored by the interpreter
@ -139,8 +140,10 @@ update_firmware_config({encoder_enabled_z = 1.0});
```
## Expression contract
Expressions are expected to be evaluated in a certain way. The evaluation will fail
if this contract is not met. An expression should return one of the following values:
* `true`
* `false`
* `("error", "string reason signaling an error happened")`

7
docs/celery_script/celery_script.md
View File

@ -19,6 +19,7 @@ in this project.
## kind
`kind` is the identifier for a command. Examples include:
* `move_absolute`
* `sync`
* `read_status`
@ -31,6 +32,7 @@ define what is required inside of both `args` and `body`.
`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`
* `string` (with possible enum types)
* `boolean`
@ -38,6 +40,7 @@ set of optional and required `args`. Args can any of the following types:
in the case of another AST, that AST will likely need to be evaluated before
executing the parent AST. Examples of `args` include:
* `x`
* `y`
* `z`
@ -49,6 +52,7 @@ executing the parent AST. Examples of `args` include:
`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:
```elixir
%{
kind: :script,
@ -63,6 +67,7 @@ enumeration, scripting looping etc. Here's a syntacticly correct example:
Note there is nesting limit for CeleryScript body nodes, and nodes can
even be self referential. Example:
```elixir
%{
kind: :self_referencing_script,
@ -71,4 +76,4 @@ even be self referential. Example:
%{kind: :execute_self_referencing_script, args: %{id: 1}, body: []}
]
}
```
```

14
docs/glossary.md
View File

@ -19,8 +19,9 @@ This file contains a basic glossary of commonly used terms
* [More info](https://elixir-lang.org/)
* [Even more info](#OTP-Terms)
* [Docs](https://www.erlang.org/docs)
* UART - **U**niversal **A**synchronous **R**eceiver/**T**ransmitter. hardware based transport mechanism
* SSH - **S**ecure **S**hell.
* 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
@ -41,8 +42,11 @@ This file contains a basic glossary of commonly used terms
* [More info](https://erlang.org/doc/design_principles/des_princ.html)
* 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
* 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
* 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

18
docs/host_development/host_development.md
View File

@ -1,29 +1,31 @@
# Starting FarmbotOS in `host` env.
# Starting FarmbotOS in `host` env
Certain behaviour is slightly different when developing on `host` compared to
deploying on target environments such as `rpi` or `rpi3`.
## Firmware
By default, an Arduino does _not_ need to be connected to your `host` pc when
doing development. See the `FarmbotFirmware.Transport` module for more info
on this topic. If you want to use a real Arduino in `host` mode, you can
export a `FARMBOT_TTY` environment variable in your `host` environment.
```bash
$ cd farmbot_os
$ export FARMBOT_TTY=/dev/ttySomeDeviceFile
$ mix compile --force
cd farmbot_os
export FARMBOT_TTY=/dev/ttySomeDeviceFile
mix compile --force
```
If you're device moves ttys, you will have to redo this step.
## Configurator
Currently configurator does not run on the `host` enviornment. To connect to
your FarmBot account, export the following variables:
```bash
$ cd farmbot_os
$ export FARMBOT_EMAIL=test@test.com
$ export FARMBOT_PASSWORD=password123
$ export FARMBOT_SERVER=http://localhost:3000
cd farmbot_os
export FARMBOT_EMAIL=test@test.com
export FARMBOT_PASSWORD=password123
export FARMBOT_SERVER=http://localhost:3000
```

6
docs/index.md
View File

@ -8,7 +8,7 @@ This document will act as an index to available documentation.
## Hardware specifics
Most FarmBot development/testing is done on a standard desktop PC.
Most FarmBot development/testing is done on a standard desktop PC.
* [Developing on your local PC](/docs/host_development/host_development.md)
* [Deploying on Raspberry Pi](/docs/target_development/building_target_firmware.md)
@ -18,7 +18,7 @@ Most FarmBot development/testing is done on a standard desktop PC.
## CeleryScript
CeleryScript is FarmBot's native scripting language. See the below
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/celery_script.md)
@ -27,7 +27,7 @@ documentation for information about it as it relates to FarmBot OS.
## Project structure
The FarmBot OS application is broken into several sub applications.
The FarmBot OS application is broken into several sub applications.
* [Project structure overview](/docs/project/structure.md)
* [farmbot_celery_script](/docs/project/farmbot_celery_script.md)

9
docs/project/farmbot_celery_script.md
View File

@ -1,11 +1,12 @@
# FarmBot CeleryScript OTP App
`farmbot_celery_script` is responsible for implementing the
runtime that execute's [CeleryScript](/docs/celery_script/celery_script.md).
It contains a handful of helpers, and several subsystems for working with CeleryScript.
`farmbot_celery_script` is responsible for implementing the
runtime that execute's [CeleryScript](/docs/celery_script/celery_script.md).
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.
* Compiler - Compiles CeleryScript to Elixir AST.
* See the [Elixir Macro Docs](https://hexdocs.pm/elixir/Macro.html)
* StepRunner - Process responsible for actually executing CeleryScript
* Scheduler - Process responsible for scheduling calls to the `StepRunner`

28
docs/project/farmbot_core.md
View File

@ -2,13 +2,14 @@
`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
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
@ -19,6 +20,7 @@ Most device specific REST resources are mirrored here.
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
@ -35,20 +37,20 @@ 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 axis position
encoder data
arduino pin data
currently configured firmware paramaters
* Current configuration
* mirror of `fbos_config` asset
mirror of `fbos_config` asset
* System info
* version info
* (nerves) firmware info
* memory usage
* disk usage
version info
(nerves) firmware info
memory usage
disk usage
* Network info
* WiFi signal quality
* private ip address
WiFi signal quality
private ip address
## Logging subsystem

47
docs/project/farmbot_ext.md
View File

@ -1,38 +1,47 @@
# 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`.
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
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
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
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
* 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
* 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.
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.

12
docs/project/farmbot_firmware.md
View File

@ -1,22 +1,22 @@
# FarmBot Firmware OTP App
The `farmbot_firmware` OTP application is responsible for maintaining a connection to
the arduino-firmware.
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.
protocol agnostically.
## Transport subsystem
This subsystem is responsible for abstracting the details of transporting
FarmBot GCODEs to/from the firmware implementation. A `transport` will take
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.
with or without a firmware plugged in.
## UART subsystem

26
docs/project/farmbot_os.md
View File

@ -1,46 +1,48 @@
# FarmBot OTP App
## Normal Subsystems
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
glue code between all the subsystems in the other applications along with it's own
platform specific subsystems.
## CeleryScript System Calls
### 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
### 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
### 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
etc.
# Platform specific subsystems
## Platform specific subsystems
the `farmbot_os` OTP app contains target/hardware specific systems. This code is
located in the `platform` directory.
## Network subsystem
### 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.
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
### GPIO subsystem
Responsible for implementing LED and Button support at the hardware level.
## RTC subsystem
### RTC subsystem
Responsible for syncronizing network time to an attached hardware clock.
## Info Worker subsystem
### Info Worker subsystem
Responsible for simple workers that handle things like

9
docs/project/farmbot_telemetry.md
View File

@ -0,0 +1,9 @@
# FarmBot Telemetry OTP App
The `farmbot_telemetry` OTP application is responsible for
storage of telemetry events. Every major OTP app in the project
uses this application as a dependency. Telemetry events are
stored in a `DETS` table, and are polled occasionally
by an AMQP/MQTT worker. When the events are successfully
dispatched over the network, they are removed from the
database

14
docs/project/structure.md
View File

@ -1,6 +1,6 @@
## FarmBot Source Project structure
# FarmBot Source Project structure
The FarmBot OS application is broken into several sub OTP applications.
The FarmBot OS application is broken into several sub OTP applications.
* [farmbot_celery_script](/docs/project/farmbot_celery_script.md)
* [farmbot_core](/docs/project/farmbot_core.md)
@ -13,7 +13,9 @@ The FarmBot OS application is broken into several sub OTP applications.
All of these folders share a common structure.
<OTP APP ROOT>
```bash
$ tree $OTP_APP_ROOT
$OTP_APP_ROOT
├── lib/
│ ├── application.ex
│ └── some_file.ex
@ -29,5 +31,7 @@ All of these folders share a common structure.
* 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
* 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

53
docs/target_development/building_target_firmware.md
View File

@ -1,27 +1,38 @@
# Building FarmBot OS
# Building an Image from source
# Building FarmBot OS from source
This project is written in the programming language Elixir and built using the
Nerves Project framework.
## Cloning
Farmbot OS now bundles and builds the [Arduino Firmware](https://github.com/farmbot/farmbot-arduino-firmware).
This is bundled as a `git` submodule. You can choose to do one of:
`git clone https://github.com/FarmBot/farmbot_os.git --recursive`
```bash
git clone https://github.com/FarmBot/farmbot_os.git --recursive
```
or
```bash
git clone https://github.com/FarmBot/farmbot_os.git
git submodule update --init --recursive
cd farmbot_os
```
To initialize the repository.
## Before you begin
You will need a number of things before we start:
* A x64 bit non windows machine
* We suggest the latest OSX or Ubuntu LTS.
## Install dependencies
If you have the above set up you will need some software dependencies:
* Erlang
* Elixir
* Nerves Bootstrapper found [here](https://hexdocs.pm/nerves/installation.html#Linux)
@ -29,6 +40,7 @@ If you have the above set up you will need some software dependencies:
* git
## Optional dependencies
* python
* opencv-python
@ -36,12 +48,14 @@ Following [this](http://embedded-elixir.com/post/2017-05-23-using-asdf-vm/) guid
will get you mostly setup.
## Development
Most development will be done in "host" environment. This means that rather than
making a change on your computer, then pushing it to the device, we can rapidly
develop things from the luxury of our own machine.
See [The Nerves getting started guide](https://hexdocs.pm/nerves/getting-started.html)
for more information about this. But as a side effect, we will need to be able
to configure (at least) two different environment/target combos. where:
* `environment` - is one of:
* `prod` - The production environment.
* No developer features enabled (such as logs, local fw updates etc).
@ -59,37 +73,56 @@ to configure (at least) two different environment/target combos. where:
* `rpi3` - Run on Farmbot's intended hardware.
## Feature development
If you plan on developing features, you will probably want to develop them with
the `dev` and `host` combo. These are both the default values, so you can simply do:
the `dev` and `host` combo. These are both the default values,
so you can simply do:
```bash
export FARMBOT_EMAIL="email@server.com" FARMBOT_PASSWORD="supersecret" FARMBOT_SERVER="https://my.farm.bot" CONFIGURATOR_PORT=4000 # you should only need to do this once
export FARMBOT_EMAIL="email@server.com"
export FARMBOT_PASSWORD="supersecret"
export FARMBOT_SERVER="https://my.farm.bot"
export CONFIGURATOR_PORT=4000 # you should only need to do this once
mix deps.get # You should only need to do this once.
iex -S mix # This will start an interactive shell.
```
## Development on device
Sometimes features will need to be developed and tested on the device itself.
This is accomplished with the `dev` and `rpi3` combo.
It is *highly* recommended that you have an FTDI cable for this such as
[this](https://www.digikey.com/product-detail/en/ftdi/TTL-232R-RPI/768-1204-ND) one
Get deps for the rpi3 target. You should only need to do this once:
```bash
MIX_TARGET=rpi3 mix deps.get # Get deps for the rpi3 target. You should only need to do this once.
MIX_TARGET=rpi3 mix firmware # Produce a firmware image.
# Make sure you SDCard is plugged in before the following command.
MIX_TARGET=rpi3 mix firmware.burn # Burn the sdcard. You may be asked for a password here.
MIX_TARGET=rpi3 mix deps.get
```
Produce a firmware image:
```bash
MIX_TARGET=rpi3 mix firmware
```
Make sure you SDCard is plugged in before the following command:
```bash
MIX_TARGET=rpi3 mix firmware.burn
```
### Local firmware updates
If you're bot is connected to your local network, you should be able to
push updates over the network to your device.
```bash
# make some changes to the code...
MIX_TARGET=rpi3 mix firmware # Build a new fw.
MIX_TARGET=rpi3 mix firmware.gen.script # this should onlye be ran once
MIX_TARGET=rpi3 ./upload.sh <your device ip address> # Push the new fw to the device.
```
Your device should now reboot into that new code. As long as you don't cause
a factory reset somehow, (bad init code, typo, etc) you should be able
continuously push updates to your device.

2
docs/target_development/consoles/erlang_distribution.md
View File

@ -23,4 +23,4 @@ iex --name console --cookie democookie --remsh farmbot@farmbot-<SERIAL_NUMBER>.l
## Disconnecting
Issuing a `ctrl+c` to the `host` terminal should disconnect you from the session.
Issuing a `ctrl+c` to the `host` terminal should disconnect you from the session.

11
docs/target_development/consoles/ssh.md
View File

@ -5,11 +5,12 @@ Accessing an SSH console.
## Setup
FarmBot can be configured to start an SSH server to aid in debugging and development.
During configuration of Network, select `Advanced Settings` and paste your [ssh
public key](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key) into the
optional input section labeled: `id_rsa.pub`. FarmBot requires a public key and
will not allow a username + password combination. If you followed the documentation
described in [building target firmware](/docs/target_development/building_target_firmware.md)
During configuration of Network, select `Advanced Settings` and paste your
[ssh public key](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key)
into the optional input section labeled: `id_rsa.pub`.
FarmBot requires a public key and will not allow a username + password combination.
If you followed the documentation described in
[building target firmware](/docs/target_development/building_target_firmware.md)
then your SSH key will be automatically added to the device.
## Connecting

9
docs/target_development/consoles/target_console.md
View File

@ -9,17 +9,19 @@ terminal.
If you are on `target` mode (IE: deployed to the raspberry pi), there will
be a console available in 3 locations:
* UART (except on RPI0 since the on-board UART is used for the arduino-firmware)
* [Connect to a UART console](/docs/target_development/consoles/uart.md)
[Connect to a UART console](/docs/target_development/consoles/uart.md)
* SSH
* [Connect to an SSH console](/docs/target_development/consoles/ssh.md)
[Connect to an SSH console](/docs/target_development/consoles/ssh.md)
* Erlang Distribution
* [Connect to an Erlang Distribution console](/docs/target_development/consoles/erlang_distribution.md)
[Connect to an Erlang Distribution console](/docs/target_development/consoles/erlang_distribution.md)
## Console Usage
The console a user will be presented with is _not_ a Linux console. There are
pretty much no Linux Utilities built-in. This includes but is not limited to:
* `bash`
* `apt-get`
* `make`
@ -35,6 +37,7 @@ What is available is a console to the FarmBot OS runtime. You will need to be
familiar with the FarmBotOS Source code for this to be helpful.
If all you are looking for is Logs, you will probably want to do:
```elixir
RingLogger.tail()
```

16
docs/target_development/consoles/uart.md
View File

@ -9,16 +9,18 @@ No additional setup is required for setting up the UART console on the target.
On your `host` machine, you need to have a console cable, as well as a console client.
The console cable must be 3.3 volts, **not** 5 volts. a 5 volt cable will harm your
Raspberry Pi. Here are some known working cables:
* https://www.amazon.com/Converter-Terminated-Galileo-BeagleBone-Minnowboard/dp/B06ZYPLFNB
* https://www.amazon.com/DSD-TECH-Adapter-FT232RL-Compatible/dp/B07BBPX8B8
* https://www.amazon.com/JANSANE-PL2303TA-Serial-Console-Raspberry/dp/B07D9R5JFK
The most common client is probably `screen` on *Nix based systems or `putty` on windows.
See your distribution's package manager for installation and usage instructions.
* <https://www.amazon.com/Converter-Terminated-Galileo-BeagleBone-Minnowboard/dp/B06ZYPLFNB/>
* <https://www.amazon.com/DSD-TECH-Adapter-FT232RL-Compatible/dp/B07BBPX8B8/>
* <https://www.amazon.com/JANSANE-PL2303TA-Serial-Console-Raspberry/dp/B07D9R5JFK/>
The most common client is probably `screen` on *Nix based
systems or `putty` on windows. See your distribution's package manager
for installation and usage instructions.
## Connecting
Connecting to a console is dependent on your particular client. Here is an example
Connecting to a console is dependent on your particular client. Here is an example
`screen` command:
```bash
@ -27,5 +29,5 @@ screen /dev/ttyUSB0 115200
## Disconnecting
Disconnecting is also dependent on your particular client. To exit screen,
Disconnecting is also dependent on your particular client. To exit screen,
issue a `ctrl+\+y` sequence to escape the console.

90
docs/target_development/releasing_target_firmware.md
View File

@ -1,54 +1,67 @@
## Provisioning the Release System
# Provisioning the Release System
Publishing a FarmBotOS release requires coordination of a few different systems.
* FarmBot Web App
* FarmBot OS
* NervesHub
* CircleCI
* GitHub branches and releases
## Legacy System
## Legacy Release System
The legacy system is somewhat simpiler. It goes as follows:
### Pull request into `master` branch.
```
### Pull request into `master` branch
```bash
git checkout master
git merge staging
git push origin master
```
Obviously this will not actually work because of testing and things, but that
is what happens behind the scenes on GitHub.
### CircleCI builds release
Once merged into master CircleCI will create a `draft` release on GitHub. This
must be QA'd and confirmed manually before publishing. Once published, FarmBot
will check the `OS_AUTO_UPDATE_URL` in the JWT.
### Beta updates
Users may opt into beta updates by settings `os_beta_updates: true` on their
device's `FbosConfig` endpoint.
Beta releases are constructed by creating a tag off of the `staging` branch.
1) update `VERSION`.
* Should follow `X.Y.Z-rcN`
Should follow `X.Y.Z-rcN`
2) update `CHANGELOG.md`.
* Topmost version should contain: `vX.Y.Z`
Topmost version should contain: `vX.Y.Z`
3) Commit release.
* Message should follow format: `Release vX.Y.Z-rcN`
Message should follow format: `Release vX.Y.Z-rcN`
4) push `staging`
* `git push origin staging`
`git push origin staging`
5) tag
* `git tag v$(cat VERSION)`
* `git push origin v$(cat VERSION)`
`git tag v$(cat VERSION)`
`git push origin v$(cat VERSION)`
## NervesHub System
The NervesHub system is simpiler to use, but more complex to setup.
### User registration
Create a admin user. This should be the same `ADMIN_EMAIL` used in
the WebApp configuration.
```
```bash
mix nerves_hub.user register
Email address: admin@farmbot.io
Name: farmbot
@ -56,41 +69,44 @@ NervesHub password: *super secret*
Local password: *super duper secret*
```
```
```bash
mix nerves_hub.product create
name: farmbot
Local password: *super duper secret*
```
### Signing keys
Now a choice will need to be made.
If fwup signing keys existed beforehand (they did for FarmBot Inc) do:
```
```bash
mix nerves_hub.key import <PATH/TO/PUBLIC/KEY> <PATH/TO/PRIVATE/KEY>
Local password: *super duper secret*
```
If new keys are required (probably named "prod") do:
```
```bash
mix nerves_hub.key create <NAME>
Local password: *super duper secret*
```
### Exporting certs and keys
The API and CI need copies of these keys and certs.
These certs need to be updated before they expire. By default they are good for
1 year
```
```bash
mix nerves_hub.user cert export
Local password: *super duper secret*
User certs exported to: <PATH/TO/EXPORTED_CERTS.tar.gz>
tar -xf <PATH/TO/EXPORTED_CERTS.tar.gz> -C nerves-hub/
```
```
```bash
mix nerves_hub.key export prod
Local password: *super duper secret*
Fwup keys exported to: <PATH/TO/EXPORTED_KEYS.tar.gz>
@ -99,18 +115,24 @@ tar -xf <PATH/TO/EXPORTED_KEYS.tar.gz> -C nerves-hub/
You will also need the CA cert bundle for the WebApp:
(this may only work for BASH)
```bash
{ curl -s https://raw.githubusercontent.com/nerves-hub/nerves_hub_cli/master/priv/ca_certs/root-ca.pem | head -20 \
&& curl -s https://raw.githubusercontent.com/nerves-hub/nerves_hub_cli/master/priv/ca_certs/intermediate-server-ca.pem | head -20 \
&& curl -s https://raw.githubusercontent.com/nerves-hub/nerves_hub_cli/master/priv/ca_certs/intermediate-user-ca.pem | head -20;
REPO_URL=https://raw.githubusercontent.com/nerves-hub/nerves_hub_cli/master/priv/master/priv/ca_certs
{ \
curl -s $REPO_URL/root-ca.pem | head -20 \
&& curl -s $REPO_URL/intermediate-server-ca.pem | head -20 \
&& curl -s $REPO_URL/intermediate-user-ca.pem | head -20; \
} > nerves-hub/nerves-hub-ca-certs.pem
```
Now the FarmBot API needs the values of in it's environment:
* `NERVES_HUB_KEY` -> `heroku config:set NERVES_HUB_KEY="$(cat nerves-hub/key.pem)" --app $APP`
* `NERVES_HUB_CERT` -> `heroku config:set NERVES_HUB_CERT="$(cat nerves-hub/cert.pem)" --app $APP`
* `NERVES_HUB_CA` -> `heroku config:set NERVES_HUB_CA="$(cat nerves-hub/ca.pem)" --app $APP`
* `NERVES_HUB_KEY` ->
`heroku config:set NERVES_HUB_KEY="$(cat nerves-hub/key.pem)" --app $APP`
* `NERVES_HUB_CERT` ->
`heroku config:set NERVES_HUB_CERT="$(cat nerves-hub/cert.pem)" --app $APP`
* `NERVES_HUB_CA` ->
`heroku config:set NERVES_HUB_CA="$(cat nerves-hub/ca.pem)" --app $APP`
CircleCI will need:
@ -134,10 +156,12 @@ NOTE: the tags **NOT** json objects, they are simple strings
split by a `:` character. This is done _only_ for readability.
where `MIX_ENV` will be one of:
* `dev`
* `prod`
and `CHANNEL` will be one of:
* `beta`
* `stable`
@ -145,25 +169,25 @@ There should be at least one deployment matching the following
tags:
* `["application:dev", "channel:stable"]`
* a development FBOS release on the `stable` channel
a development FBOS release on the `stable` channel
* `["application:prod", "channel:stable"]`
* a production FBOS release on the `stable` channel
a production FBOS release on the `stable` channel
* `["application:dev", "channel:beta"]`
* a development FBOS release on the `beta` channel
a development FBOS release on the `beta` channel
* `["application:prod", "channel:beta"]`
* a production FBOS release on the `beta` channel
a production FBOS release on the `beta` channel
* `["application:dev", "channel:stable"]`
* a development FBOS release on the `stable` channel
a development FBOS release on the `stable` channel
* `["application:prod", "channel:stable"]`
* a production FBOS release on the `stable` channel
a production FBOS release on the `stable` channel
* `["application:dev", "channel:beta"]`
* a development FBOS release on the `beta` channel
a development FBOS release on the `beta` channel
* `["application:prod", "channel:beta"]`
* a production FBOS release on the `beta` channel
a production FBOS release on the `beta` channel
### First time setup
```
```bash
heroku config:set NERVES_HUB_CERT="$NERVES_HUB_CERT" --app=$HEROKU_APPNAME
heroku config:set NERVES_HUB_KEY="$NERVES_HUB_KEY" --app=$HEROKU_APPNAME
heroku config:set NERVES_HUB_CA="$NERVES_HUB_CA" --app=$HEROKU_APPNAME

20
docs/target_development/target_faq.md
View File

@ -1,15 +1,17 @@
# Frequently Asked Questions
## What ports oputbound does Farmbot OS use?
## What ports oputbound does Farmbot OS use
* AMQP: 5672
* HTTP(S): 80 + 443 (this is configurable)
* NTP: UDP 123
## My bot doesn't boot on a fresh SD card!
## My bot doesn't boot on a fresh SD card
This could be one of a few things. These things are in order of probability.
* Your farmbot doesn't have enough power. You NEED a good power supply at
least 5 volts and 2.5 Amps for farmbot to boot reliably.
least 5 volts and 2.5 Amps for farmbot to boot reliably.
* Is the power LED flashing? If yes you need more amps.
* Is the Green LED flashing? If no you need more amps.
* Your Arduino wasn't detected.
@ -20,17 +22,21 @@ least 5 volts and 2.5 Amps for farmbot to boot reliably.
* You have a bad SD Card.
* You aren't using a Raspberry Pi 3.
## Why can't I update my Arduino Firmware?
## Why can't I update my Arduino Firmware
As of version 3.8.0 we decided to bundle the arduino firmware into farmbot os.
There was a couple reasons for this.
* There is no more version conflicts between the firmware and operating system.
* Applying updates during farmbot os runtime can be dangerous and was leaving
peoples bot's unusable because of broken firmwares.
peoples bot's unusable because of broken firmwares.
## Can the shell run on HDMI
No. Farmbot is designed to operate without the use of a monitor.
## Why aren't [X] or [Y] packages included?
## Why aren't [X] or [Y] packages included
See the above answer. [Raise an issue](https://github.com/FarmBot/farmbot_os/issues/new)
to request a package. Future versions of FarmBotOS may provide a plugin system.
It is not implemented yet.
It is not implemented yet.