From 5518fbbbcb51db7ce25718cbe39386a14e0d447f Mon Sep 17 00:00:00 2001 From: connor rigby Date: Wed, 16 May 2018 16:00:32 -0700 Subject: [PATCH] Doc updates --- CHANGELOG.md | 2 ++ CONTRIBUTING.md | 1 + README.md | 14 +++++++------- docs/BUILDING.md | 19 ++++++++++--------- docs/FAQ.md | 31 ++++++------------------------- 5 files changed, 26 insertions(+), 41 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5adfa781..21328790 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,5 @@ +# Changelog + # 6.4.2 * Remove `hostapd` * Remove a lot of custom Logger code. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47244280..3e315c7d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1,2 @@ +# Contributing To get started, sign the Contributor License Agreement. diff --git a/README.md b/README.md index 648d0590..fea7d1a2 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,14 @@ [![Built with Nerves](http://nerves-project.org/images/badge/nerves-badge_75x39_black.png)](http://nerves-project.org/) --- +# FarmBot OS +The "brains" of the FarmBot Project + # :floppy_disk: LATEST OS IMAGE DOWNLOADS -## _*Important*_ +# _*Important*_ For now we are only building and supporting Raspberry Pi 3. Pull Requests are very welcome if you spot a bug or fix, but for now we suggest obtaining a Raspberry Pi 3 for the best support. @@ -17,9 +20,6 @@ if you spot a bug or fix, but for now we suggest obtaining a Raspberry Pi 3 for | :star: **[RPi 3 (Ships with FarmBot.io kits)](https://github.com/FarmBot/farmbot_os/releases/download/v6.4.1/farmbot-rpi3-6.4.1.img)**| --- -# Farmbot OS -The "brains" of the FarmBot Project - ## Installation Installation should be fairly straight forward, you will need a computer for this step. (everything after this can be set up on a mobile device.) @@ -50,16 +50,16 @@ _Refer to the [software documentation Configurator page](https://software.farm.b \* If you are using a smartphone you may need to disable cellular data to allow your phone's browser to connect to the configurator. -# Problems? +## Problems? See the [FAQ](docs/FAQ.md) If your problem isn't solved there please file an issue on [Github](https://github.com/FarmBot/farmbot_os/issues/new) -# Security Concerns? +## Security Concerns? We take security seriously and value the input of independent researchers. Please see our [responsible disclosure guidelines](https://farm.bot/responsible-disclosure-of-security-vulnerabilities/). -# Want to Help? +## Want to Help? [Low Hanging Fruit](https://github.com/FarmBot/farmbot_os/search?utf8=%E2%9C%93&q=TODO) [Development](CONTRIBUTING.md) diff --git a/docs/BUILDING.md b/docs/BUILDING.md index 0d9d3dc9..69674b36 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -1,8 +1,9 @@ +# Building FarmBot OS # Building an Image from source This project is written in the programming language Elixir and built using the Nerves Project framework. -# Cloning +## 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` @@ -13,12 +14,12 @@ git submodule update --init --recursive ``` To initialize the repository. -# Before you begin +## 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 +## Install dependencies If you have the above set up you will need some software dependencies: * Erlang * Elixir @@ -32,7 +33,7 @@ If you have the above set up you will need some software dependencies: Following [this](http://embedded-elixir.com/post/2017-05-23-using-asdf-vm/) guide will get you mostly setup. -# Development +## 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. @@ -55,12 +56,12 @@ to configure (at least) two different environment/target combos. where: * `host` - For development. * `rpi3` - Run on Farmbot's intended hardware. -## Note about setup +### Note about setup You will need to configure your Farmbot API, Frontend, and MQTT services for the below commands to work. You _can_ however use the default `my.farmbot.io` servers. see `config/host/auth_secret_template.exs` for more information. -# Running unit tests +## Running unit tests Tests should be ran while developing features. You should have a *local* Farmbot stack up and running and configured for this to work. `config/host/auth_secret_template.exs` will have more full instructions. @@ -70,7 +71,7 @@ MIX_ENV=test mix deps.get # Fetch test env specific deps. mix test ``` -# Feature development +## 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: ```bash @@ -78,7 +79,7 @@ mix deps.get # You should only need to do this once. iex -S mix # This will start an interactive shell. ``` -# Development on device +## 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 @@ -92,7 +93,7 @@ MIX_TARGET=rpi3 mix firmware # Produce a firmware image. MIX_TARGET=rpi3 mix firmware.burn # Burn the sdcard. You may be asked for a password here. ``` -## Local firmware updates +### 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. diff --git a/docs/FAQ.md b/docs/FAQ.md index d12979eb..c4682e06 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,11 +1,11 @@ # Frequently Asked Questions -# What ports oputbound does Farmbot OS use? +## What ports oputbound does Farmbot OS use? * AMQP: 5673 * 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 @@ -20,40 +20,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. -# Non genuine Arduino boards not detected -There was a bug between 6.0.1 until 6.2.1 that caused Farmbot to ignore -devices that presented themselves as anything other than `/dev/ttyACM0`. This -has since been fixed, but you will have to upgrade your device before configuring -your Arduino. So first make sure your Arduino board is _not_ plugged into your -Rasbperry Pi, then follow the following steps: - * Flash the release image [6.0.1](https://github.com/FarmBot/farmbot_os/releases/download/v6.0.1/farmbot-rpi3-6.0.1.img) - * Upgrade your bot until there are no updates available leaving your Arduino unplugged. - * When your bot settles on 6.2.1 or above plug your Arduino board in. - * Wait a few seconds. It will likely fail due to firmware not being installed or old firmware. - * Now you can do one of: - * Select `Arduino` from the `Firmware` dropdown on the [Device](https://my.farmbot.io/app/device) panel. - * Factory reset your bot. This will force Farmbot to reflash your firmware to the correct version. - -## Can I still use a custom arduino firmware? -Yes. During configuration you can disable the default actions -during configuration. This means you will need to maintain your Arduino Firmware -manually. - -# Can the shell run on HDMI +## Can the shell run on HDMI No. Farmbot is designed to operate without the use of a monitor. -# Can I SSH into the Farmbot? +## Can I SSH into the Farmbot? No. Farmbot does not run `raspbain` as many users are used too. There are no normal `linux` utilities (such as `apt`, `sudo`, `bash` etc). -# 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.