update docs
connor rigby
parent
d09d4885f2
commit
22b54c800b
157
BUILDING.md
157
BUILDING.md
|
|
@ -1,157 +0,0 @@
|
|||
# Advanced Things that you shouldn't need to worry about.
|
||||
|
||||
## Building an image
|
||||
Building a `*.img` file is rather simple, its one step farther than the regular build.
|
||||
|
||||
```bash
|
||||
cd ~/farmbot/os/apps/farmbot
|
||||
export MIX_ENV=prod
|
||||
export NERVES_TARGET=<MY_BOARD_CHOICE_REPLACEME>
|
||||
# THIS COULD TAKE A WHILE DEPENDING ON YOUR MACHINE
|
||||
mix firmware
|
||||
# this is the actual .img generation, it should go pretty quick.
|
||||
fwup -a -d _images/farmbot/<MY_BOARD_CHOICE_REPLACEME>/farmbot.img -i \
|
||||
_images/farmbot/<MY_BOARD_CHOICE_REPLACEME>/farmbot.fw -t complete
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
Documentation isn't stored in source control, because it is large and changes frequently. [Raise an issue](https://github.com/FarmBot/farmbot_os/issues/new) if you would like them published on HEX.
|
||||
|
||||
To view documentation:
|
||||
|
||||
```bash
|
||||
cd ~/farmbot/os
|
||||
MIX_ENV=dev mix deps.get
|
||||
MIX_ENV=dev mix docs
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
Tests coverage is a work in progress and all help is appreciated!
|
||||
|
||||
```bash
|
||||
export MIX_ENV=test
|
||||
mix deps.get
|
||||
mix test
|
||||
```
|
||||
|
||||
## Code Styling and Consistency
|
||||
|
||||
Credo doesn't work very well on umbrella projects, so I only enforce credo on
|
||||
the main application.
|
||||
|
||||
Note: this will show all #TODOS in the application.
|
||||
|
||||
```bash
|
||||
cd ~/farmbot/os/apps/farmbot
|
||||
export MIX_ENV=dev
|
||||
mix deps.get
|
||||
mix credo --strict
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Building the Linux RootFS
|
||||
|
||||
```bash
|
||||
cd ~/farmbot/os
|
||||
# this should set up the environment needed to build the system
|
||||
export NERVES_TARGET=<MY_BOARD_CHOICE>
|
||||
make create-build-${NERVES_TARGET}
|
||||
|
||||
# Now that the environment is set up you should change into the new dir it told you too.
|
||||
cd apps/NERVES_SYSTEM_${NERVES_TARGET}
|
||||
# from this dir we have a few different things we can configure in buildroot.
|
||||
|
||||
# To add/remove linux packages.
|
||||
make menuconfig
|
||||
|
||||
# To add/remove busybox packages.
|
||||
make busybox-menuconfig
|
||||
|
||||
# To add/enable/disable features in the kernel.
|
||||
make linux-menuconfig
|
||||
|
||||
# Save those configs
|
||||
|
||||
# For buildroot packages
|
||||
make savedefconfig
|
||||
|
||||
# For busybox config
|
||||
cp build/busybox*/.config ../nerves_system_*/busybox_defconfig
|
||||
|
||||
# for linux config
|
||||
cp build/linux*/.config ../nerves_system_*/linux-*.defconfig
|
||||
|
||||
# To make your configuration
|
||||
make
|
||||
|
||||
# that will take a while depending on your machine. You will see the build output in your terminal.
|
||||
# on a core i7, 32 gigs or ram, nvme ssd machine, it takes about 15-20 minutes depending on if ccache is enabled.
|
||||
|
||||
# when the rootfs build finishes to use said rootfs in building firmware:
|
||||
cd ../farmbot
|
||||
|
||||
mix firmware
|
||||
# to burn to an sdcard. (this requires sudo)
|
||||
mix firmware.burn
|
||||
|
||||
```
|
||||
|
||||
## Porting to a New System
|
||||
|
||||
There are several options for porting FarmBot to non-Raspberry Pi systems. One option is to use the RPI3 system as a template:
|
||||
|
||||
```bash
|
||||
cd ~/os/farmbot/os/apps
|
||||
mix new nerves_system_newboard
|
||||
```
|
||||
|
||||
At bare minimum you will need the following files files, using the RPI3 system as a template:
|
||||
|
||||
```
|
||||
nerves_system_newboard
|
||||
├── rootfs-additions
|
||||
├── busybox_defconfig
|
||||
├── fwup.conf
|
||||
├── linux-VERSION.defconfig
|
||||
├── mix.exs
|
||||
├── nerves.exs
|
||||
└── nerves_defconfig
|
||||
```
|
||||
|
||||
Lets go thru those files and folders and explain what each one is.
|
||||
|
||||
* `rootfs-additions`
|
||||
thechnically this is optional but that will never happen. there is usually some prop files needed like wireless firmware, erlinit config etc.
|
||||
* `busybox_defconfig`
|
||||
This file has extra configs for Farmbot System. We require a few extra packages in busybox to be enabled.
|
||||
* mkfs.ext
|
||||
* `fwup.conf`
|
||||
[FwUp](https://github.com/fhunleth/fwup) is how farmbot updates and builds its firmware. This can be configured how ever your platfrom requires, but we require a few basic things
|
||||
* one squashfs system partition which will ALWAYS read only.
|
||||
* one data partition. This can be any filesystem as long as it supports symbolic links. It will be mounted read only MOST of the time
|
||||
* `linux.defconfig`
|
||||
The configuration for the Linux Kernel on this board.
|
||||
* `mix.exs`
|
||||
a description of this project. requires a bit of configuration. see rpi3 system for example.
|
||||
* `nerves.exs`
|
||||
configures a nerves target. See RPI3 System for examples.
|
||||
* `nerves_defconfig`
|
||||
The buildroot configuration. Needs a bit of specifics.
|
||||
```
|
||||
buildroot
|
||||
├── packages
|
||||
| ├── networking
|
||||
| | ├── hostapd
|
||||
| | ├── dnsmasq
|
||||
| | ├── dropbear
|
||||
| | └── iw
|
||||
| |
|
||||
| └── hardware handling
|
||||
| └── avrdude
|
||||
|
|
||||
└── filesystem
|
||||
└── squashfs
|
||||
```
|
||||
24
CHANGELOG.md
24
CHANGELOG.md
|
|
@ -9,3 +9,27 @@
|
|||
|
||||
# 2.1.10
|
||||
* a few minor bug fixes to the previous release.
|
||||
|
||||
# 3.0.0
|
||||
* Makefile
|
||||
|
||||
# 3.0.1
|
||||
* implement bot state migrations
|
||||
* logger fixes.
|
||||
|
||||
# 3.0.2
|
||||
* Farmware initial concepts.
|
||||
|
||||
# 3.0.3
|
||||
* Farmware fixes
|
||||
|
||||
# 3.0.4
|
||||
* Logger bug fixes
|
||||
|
||||
# 3.0.5
|
||||
* Configurator got a facelift + a few extra features.
|
||||
|
||||
# 3.0.6
|
||||
* Syncing is now a multiple request action and is now much faster and safer.
|
||||
* change folder structure
|
||||
* begin adding redis support.
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ To update the firmware on the Raspberry Pi (Only version 3 for now) and the Ardu
|
|||
|
||||
# Problems?
|
||||
|
||||
See the [FAQ](FAQ.md)
|
||||
See the [FAQ](faq.html)
|
||||
If your problem isn't solved there please file an issue on [Github](https://github.com/FarmBot/farmbot_os/issues/new)
|
||||
|
||||
# Want to Help?
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@ use Mix.Config
|
|||
target = Mix.Project.config[:target]
|
||||
env = Mix.env()
|
||||
mqtt_transport = Farmbot.Transport.GenMqtt
|
||||
redis_transport = Farmbot.Transport.Redis
|
||||
|
||||
config :logger, utc_log: true
|
||||
|
||||
|
|
@ -16,12 +17,12 @@ config :iex, :colors, enabled: true
|
|||
config :farmbot, auth_callbacks: [mqtt_transport]
|
||||
|
||||
# frontend <-> bot transports.
|
||||
config :farmbot, transports: [mqtt_transport]
|
||||
config :farmbot, transports: [mqtt_transport, redis_transport]
|
||||
|
||||
config :farmbot, redis_port: 6379
|
||||
|
||||
config :nerves, :firmware,
|
||||
rootfs_additions: "config/hardware/#{target}/rootfs-additions-#{env}"
|
||||
# give the ability to start a redis server instance in dev mode.
|
||||
config :farmbot, :redis,
|
||||
server: System.get_env("REDIS_SERVER") || false,
|
||||
port: System.get_env("REDIS_SERVER_PORT") || 6379
|
||||
|
||||
# This is usually in the `priv` dir of :tzdata, but our fs is read only.
|
||||
config :tzdata, :data_dir, "/tmp"
|
||||
|
|
@ -33,3 +34,5 @@ import_config "#{env}.exs"
|
|||
# import config specific to our nerves_target
|
||||
IO.puts "using #{target} - #{env} configuration."
|
||||
import_config "hardware/#{target}/hardware.exs"
|
||||
config :nerves, :firmware,
|
||||
rootfs_additions: "config/hardware/#{target}/rootfs-additions-#{env}"
|
||||
|
|
|
|||
|
|
@ -4,3 +4,7 @@ config :farmbot,
|
|||
config_file_name: "default_config_rpi.json",
|
||||
configurator_port: 80,
|
||||
streamer_port: 4040
|
||||
|
||||
config :farmbot, :redis,
|
||||
server: true,
|
||||
port: 6379
|
||||
|
|
|
|||
|
|
@ -4,3 +4,7 @@ config :farmbot,
|
|||
config_file_name: "default_config_rpi2.json",
|
||||
configurator_port: 80,
|
||||
streamer_port: 4040
|
||||
|
||||
config :farmbot, :redis,
|
||||
server: true,
|
||||
port: 6379
|
||||
|
|
|
|||
|
|
@ -4,3 +4,7 @@ config :farmbot,
|
|||
config_file_name: "default_config_rpi3.json",
|
||||
configurator_port: 80,
|
||||
streamer_port: 4040
|
||||
|
||||
config :farmbot, :redis,
|
||||
server: true,
|
||||
port: 6379
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
defmodule Farmbot.BotState.Supervisor do
|
||||
@moduledoc """
|
||||
Supervises the state tracker modules and an event manager that other
|
||||
things can subscribe too.
|
||||
Supervises the state tracker modules and an event manager that other
|
||||
things can subscribe too.
|
||||
"""
|
||||
|
||||
use Supervisor
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
defmodule Farmbot.Sync do
|
||||
@moduledoc """
|
||||
There is a quite a bit of macros going on here.
|
||||
* `defdatabase` comes from `Amnesia`
|
||||
* defindes a database. This should only show up once.
|
||||
* syncable comes from `Syncable` and defines a database table.
|
||||
* defdatabase comes from Amnesia
|
||||
* defindes a database. This should only show up once.
|
||||
* syncable comes from Syncable and defines a database table.
|
||||
"""
|
||||
|
||||
use Amnesia
|
||||
|
|
|
|||
|
|
@ -1,13 +1,6 @@
|
|||
defmodule Syncable do
|
||||
@moduledoc ~s"""
|
||||
Creates a syncable object from Farmbots rest api.
|
||||
Example:
|
||||
iex> defmodule BubbleGum do
|
||||
...> use Syncable, name: __MODULE__, model: [:flavors, :brands]
|
||||
...> end
|
||||
iex> BubbleGum.create!(%{"flavors" => ["mint", "berry"],
|
||||
..> "brands" => ["BigRed"]})
|
||||
{:ok, %BubbleGum{flavors: ["mint", "berry"], brands: ["BigRed"]}}
|
||||
Defines the structs and amnesia tables for a Farmbot Syncable object
|
||||
"""
|
||||
use Amnesia
|
||||
|
||||
|
|
@ -149,7 +142,7 @@ defmodule Syncable do
|
|||
end
|
||||
|
||||
@doc """
|
||||
Same as `enter_into_db/1` but will raise errors if
|
||||
Same as enter_into_db/1 but will raise errors if
|
||||
problems are encountered.
|
||||
"""
|
||||
def enter_into_db!(list_or_object)
|
||||
|
|
|
|||
|
|
@ -48,9 +48,10 @@ defmodule Farmbot do
|
|||
end
|
||||
|
||||
@doc """
|
||||
Starts the Farmbot Application
|
||||
Entry Point to Farmbot
|
||||
"""
|
||||
@spec start(atom, [any]) :: {:ok, pid}
|
||||
def start(type, args)
|
||||
def start(_, [args]) do
|
||||
Logger.info ">> init!"
|
||||
Amnesia.start
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
defmodule Mix.Tasks.CS.New do
|
||||
@moduledoc false
|
||||
use Mix.Task
|
||||
@shortdoc "Creates a new celery script command"
|
||||
def run([new_cs]) do
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
defmodule Mix.Tasks.Farmbot.Upload do
|
||||
@moduledoc false
|
||||
use Mix.Task
|
||||
alias Mix.Tasks.Firmware.Push
|
||||
@shortdoc "Uploads a file to a url"
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
defmodule Mix.Tasks.Farmbot.Warning do
|
||||
@moduledoc false
|
||||
use Mix.Task
|
||||
def run(_), do: Mix.raise("Please export a MIX_TARGET")
|
||||
end
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@ defmodule Farmbot.System.Supervisor do
|
|||
Supervises Platform specific stuff for Farmbot to operate
|
||||
"""
|
||||
use Supervisor
|
||||
@redis_config Application.get_all_env(:farmbot)[:redis]
|
||||
|
||||
def start_link(args) do
|
||||
Supervisor.start_link(__MODULE__, [args], name: __MODULE__)
|
||||
|
|
@ -12,11 +13,19 @@ defmodule Farmbot.System.Supervisor do
|
|||
children = [
|
||||
worker(Farmbot.System.FS, [target], restart: :permanent),
|
||||
worker(Farmbot.System.FS.Worker, [target], restart: :permanent),
|
||||
worker(Redis.Server, [], restart: :permanent),
|
||||
worker(Farmbot.System.FS.ConfigStorage, [], restart: :permanent),
|
||||
worker(Farmbot.System.Network, [target], restart: :permanent),
|
||||
]
|
||||
worker(Farmbot.System.Network, [target], restart: :permanent)
|
||||
] ++ maybe_redis()
|
||||
opts = [strategy: :one_for_one]
|
||||
supervise(children, opts)
|
||||
end
|
||||
|
||||
@spec maybe_redis :: [Supervisor.Spec.spec]
|
||||
defp maybe_redis do
|
||||
if @redis_config[:server] do
|
||||
[worker(Redis.Server, [], restart: :permanent)]
|
||||
else
|
||||
[]
|
||||
end
|
||||
end
|
||||
end
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@ defmodule Redis.Server do
|
|||
@moduledoc """
|
||||
Port for a redis server
|
||||
"""
|
||||
@port Application.get_env(:farmbot, :redis_port)
|
||||
@config Application.get_all_env(:farmbot)[:redis]
|
||||
|
||||
if Mix.env() == :dev do
|
||||
def should_bind, do: "bind 0.0.0.0"
|
||||
|
|
@ -13,7 +13,7 @@ defmodule Redis.Server do
|
|||
def config(path: dir), do: ~s"""
|
||||
#{should_bind()}
|
||||
protected-mode yes
|
||||
port #{@port}
|
||||
port #{@config[:port]}
|
||||
tcp-backlog 511
|
||||
unixsocket /tmp/redis.sock
|
||||
unixsocketperm 700
|
||||
|
|
|
|||
|
|
@ -14,6 +14,8 @@ defmodule Farmbot.Mixfile do
|
|||
|
||||
def project do
|
||||
[app: :farmbot,
|
||||
description: "The Brains of the Farmbot Project",
|
||||
package: package(),
|
||||
test_coverage: [tool: ExCoveralls],
|
||||
version: @version,
|
||||
target: @target,
|
||||
|
|
@ -34,11 +36,20 @@ defmodule Farmbot.Mixfile do
|
|||
source_url: "https://github.com/Farmbot/farmbot_os",
|
||||
homepage_url: "http://farmbot.io",
|
||||
docs: [main: "Farmbot",
|
||||
logo: "priv/static/farmbot_logo.png",
|
||||
extras: ["../../README.md", "../../BUILDING.md"]]
|
||||
logo: "../../docs/farmbot_logo.png",
|
||||
extras: ["../../docs/BUILDING.md",
|
||||
"../../docs/FAQ.md",
|
||||
"../../docs/ENVIRONMENT.md",
|
||||
"../../README.md"]]
|
||||
]
|
||||
end
|
||||
|
||||
def package do
|
||||
[name: "Farmbot OS",
|
||||
maintainers: "Farmbot.io",
|
||||
licenses: "MIT"]
|
||||
end
|
||||
|
||||
def application do
|
||||
[mod:
|
||||
{Farmbot,
|
||||
|
|
@ -144,7 +155,7 @@ defmodule Farmbot.Mixfile do
|
|||
# this is for cross compilation to work
|
||||
# New version of nerves might not need this?
|
||||
defp aliases("host"), do: [
|
||||
"firmware": ["farmbot.warning"],
|
||||
"firmware": ["compile"],
|
||||
"firmware.push": ["farmbot.warning"],
|
||||
"credo": ["credo list --only readability,warning,todo,inspect,refactor --ignore-checks todo,spec"],
|
||||
"test": ["test", "credo"]]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,39 @@
|
|||
# Building an Image from source
|
||||
This project is written in the programming language Elixir and built using the
|
||||
Nerves Project framework.
|
||||
|
||||
## Before you begin
|
||||
You will need a number of things before we start.
|
||||
* A Linux machine
|
||||
* A x64 bit machine
|
||||
* probably about 16 gigs of ram
|
||||
* about ~30 gigs of hard drive space
|
||||
* a fairly recent cpu
|
||||
|
||||
## Install dependencies
|
||||
If you have the above set up you will need some software dependencies.
|
||||
* Elixir found [here](http://elixir-lang.org/install.html)
|
||||
* Nerves Bootstrapper found [here](https://hexdocs.pm/nerves/installation.html#Linux)
|
||||
* NodeJS found [here](https://nodejs.org/en/download/)
|
||||
|
||||
## Set up environment
|
||||
We are going to set up the environment for building Farmbot OS
|
||||
```bash
|
||||
mkdir farmbot
|
||||
cd farmbot
|
||||
git clone https://github.com/FarmBot/farmbot_os.git os
|
||||
cd os
|
||||
npm install
|
||||
```
|
||||
|
||||
## Compile the application
|
||||
From here you will have to choose your own adventure. You get to choose if you
|
||||
want development mode or production mode, and you get to choose the target you
|
||||
want to build the executables for. see the [ENVIRONMENT](environment.html) for more details
|
||||
This will take a while depending on you machine.
|
||||
```bash
|
||||
export MIX_ENV=prod
|
||||
export MIX_TARGET=rpi3
|
||||
mix deps.get
|
||||
mix firmware
|
||||
```
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
# Farmbot Build Environment
|
||||
There are a number of things that can (and should) be configured at compile time
|
||||
via shell environment variables.
|
||||
|
||||
## Mix Environment
|
||||
you can set `MIX_ENV=prod` or `MIX_ENV=dev` (default) to change the environment
|
||||
of the farmbot application.
|
||||
|
||||
## Mix Target
|
||||
When building firmware you can set the target.
|
||||
`MIX_TARGET=rpi2`
|
||||
|
||||
## Webpack
|
||||
Farmbot's `Configurator` application uses Webpack to compile a TypeScript Project
|
||||
into a static website that gets served by `Plug`
|
||||
|
||||
Webpack is configured via a package called `ex_webpack`. Default behavior it to
|
||||
watch the web source files for changes and recompile. This adds extra time to the
|
||||
initial compile of the application and can be just generally annoying. to disable
|
||||
this export `USE_WEBPACK=false`
|
||||
|
||||
## Configurator
|
||||
The Configurator app is started by default on port `5000` and the image streamer
|
||||
is on port `5050`. these can be changed by exporting in development mode only:
|
||||
```bash
|
||||
CONFIGURATOR_PORT=4000
|
||||
STREAMER_PORT=4040
|
||||
```
|
||||
|
||||
## Redis Server
|
||||
In development mode you can export
|
||||
```bash
|
||||
REDIS_SERVER=true
|
||||
REDIS_SERVER_PORT=6379
|
||||
```
|
||||
|
|
@ -1,4 +1,5 @@
|
|||
# My bot doesn't boot on a fresh SD card!
|
||||
# Frequently Asked Questions
|
||||
## 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.
|
||||
|
||||
|
|
@ -13,32 +14,32 @@ This could be one of a few things. These things are in order of probability.
|
|||
* You have a bad SD Card.
|
||||
* You aren't using a Raspberry Pi 3 (Porting Farmbot is relatively simple).
|
||||
|
||||
# Can I SSH into the Farmbot?
|
||||
## Can I SSH into the Farmbot?
|
||||
|
||||
Yes, starting with version 2.1.1. The user is root and there is no password. This may change in future versions.
|
||||
Yes, starting with version `2.1.1`. The user is root and there is no password. This may change in future versions.
|
||||
|
||||
# Why are my SSH keys invalid?
|
||||
## Why are my SSH keys invalid?
|
||||
|
||||
Farmbot's `rootfs` file system is read only. SSH keys must be stored elsewhere. They may get lost if you pull the power to your Farmbot. Follow the directions in the shell to resolve the issue.
|
||||
|
||||
# Can the shell run on HDMI rather than SSH?
|
||||
## Can the shell run on HDMI rather than SSH?
|
||||
|
||||
Yes and no. HDMI will display an IEX (Elixir shell) session. You may access the shell via `ctrl+c` but this will kill Farmbot's main software.
|
||||
|
||||
# SSH Has No Linux Utilities.
|
||||
## SSH Has No Linux Utilities.
|
||||
|
||||
Farmbot is built using Buildroot, Which uses a very small Linux environment to minimize boot time and overhead. This gives us a Linux shell of `sh` and most utilities are provided by `busybox`.
|
||||
|
||||
# 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.
|
||||
|
||||
# Does Farmbot support Ethernet rather than WIFI?
|
||||
## Does Farmbot support Ethernet rather than WIFI?
|
||||
|
||||
Yes. When you log into the Farmbot Configurator wifi SSID, select `Use Ethernet`.
|
||||
**NOTE**: This can not be changed without a factory reset.
|
||||
|
||||
# How do I factory reset my bot?
|
||||
## How do I factory reset my bot?
|
||||
|
||||
This is not as trivial as you would think right now. (We are working on it.)
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Loading…
Reference in New Issue