From 3342258bbef3f26b9be79109a0dc500f3171774e Mon Sep 17 00:00:00 2001 From: Rick Carlino Date: Tue, 27 Dec 2016 15:02:42 -0600 Subject: [PATCH] Fix links, typos. --- BUILDING.md | 27 ++++++++---- CONTRIBUTING.md | 113 ++++++++++++++++++++++-------------------------- FAQ.md | 45 +++++++++++-------- 3 files changed, 96 insertions(+), 89 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 578381d0..940f60ef 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,9 +1,11 @@ # Advanced Things that you shouldn't need to worry about. ## Documentation -Documentation isn't stored in source control, because it is large and changes frequently. -to view documentation do: -if there is enough intersest they can be published on HEX. + +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 @@ -11,7 +13,9 @@ MIX_ENV=dev mix docs ``` ## Tests -Tests aren't quite at the coverage we want, please help us! + +Tests coverage is a work in progress and all help is appreciated! + ```bash export MIX_ENV=test mix deps.get @@ -19,9 +23,12 @@ mix test ``` ## Code Styling and Consistency -Credo doesn't work very well on umbrella projects, so i only enforce credo on + +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 @@ -32,6 +39,7 @@ mix credo --strict ## Building the Linux RootFS + ```bash cd ~/farmbot/os # this should set up the environment needed to build the system @@ -83,16 +91,17 @@ MIX_ENV=prod NERVES_SYSTEM=~/farmbot/os/apps/NERVES_SYSTEM_* mix firmware MIX_ENV=prod bash scripts/burn.sh ``` -## Porting a new system -If You want to use a different device for farmbot you will need to do several things: +## 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: -You can use the RPI3 system as a template to see what you will need ```bash cd ~/os/farmbot/os/apps mix new nerves_system_newboard ``` -now that needs to be populated. at bare minimum you will need several files. Use the RPI3 system as a template. +At bare minimum you will need the following files files, using the RPI3 system as a template: + ``` nerves_system_newboard ├── rootfs-additions diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0052fb2b..79721fd3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,40 +1,46 @@ # HOW TO CONTRIBUTE + * Fork the official [Farmbot Master branch](https://github.com/farmbot/farmbot_os/tree/master) -* set up your [development environment](#Development) +* Set up a [development environment](https://github.com/FarmBot/farmbot_os#installation) * Make your changes. * Run tests, make sure you didn't break anything. -* pull request the official [Farmbot Master Branch](https://github.com/FarmBot/farmbot_os/pull/new/master) -* give a detailed description of what changed. +* Create a pull request to the official [Farmbot Master Branch](https://github.com/FarmBot/farmbot_os/pull/new/master) +* Provide a detailed description of what changed. # Development + The project is developed in Elixir, and builds a full Linux operating system. -That being said, you will need Linux, or a Linux Virtual Machine to build the system. -The following assumes you are on a Ubuntu Based distribution. Also when building code for the OS (this project) +That being said, you will need Linux, or a Linux Virtual Machine to build the system. +The following assumes you are on a Ubuntu Based distribution. When building code for the OS (this project) you will NEED the rest of the stack set up locally. ## Note -if someone wants to set up a vagrant file for doing this, it would be greatly appreciated -When set up you should end up with a folder structure like this: + +A vagrant file would be greatly appreciated. + +Upon completion you will have the following folder structure: + ``` farmbot -├── farmbot_web_api +├── farmbot_web_api ├── farmbot_mqtt_broker ├── farmbot_web_frontend -└── farmbot_os +└── farmbot_os ``` ## Dependencies -We need quite a few dependencies to build the system. + ```bash -sudo apt-get update +sudo apt-get update sudo apt-get upgrade -sudo apt-get -y install build-essential m4 autoconf git libncurses5-dev +sudo apt-get -y install build-essential m4 autoconf git libncurses5-dev ``` ## ASDF-VM -I use ASDF-VM to handle managing Erlang, Elixir, and Node versions. -You can substitute your own, just make sure you have the correct versions. + +FarmBot OS uses ASDF-VM to manage Erlang, Elixir, and Node versions. +You can substitute your own versions assuming you have the correct versions. ```bash # For Ubuntu or other linux distros @@ -60,13 +66,16 @@ asdf global node 7.0.0 ``` # Ruby -I use `rvm` to manage ruby. + +FarmBot OS uses `rvm` to manage Ruby versions. + ```bash rvm use 2.3.2 --default gem install bundler ``` -# The rest +# Others + ```bash # Set up directories and what not. cd ~/ @@ -74,33 +83,35 @@ mkdir farmbot cd farmbot # clone all the upstream repositories. -mkdir -p api mqtt frontend os -cd api +mkdir -p api mqtt frontend os +cd api git init git remote add upstream https://github.com/FarmBot/farmbot-web-api.git git pull upstream master -cd ../mqtt -git init +cd ../mqtt +git init git remote add upstream https://github.com/FarmBot/mqtt-gateway.git git pull upstream master -cd ../frontend -git init +cd ../frontend +git init git remote add upstream https://github.com/FarmBot/farmbot-web-frontend.git git pull upstream master -cd ../os -git init +cd ../os +git init git remote add upstream https://github.com/FarmBot/farmbot_os.git git pull upstream master ``` then make sure to add your own remote to whichever repository you plan on contributing too. -```bash +```bash git remote add origin https://github.com/MyCoolUserName/farmbot_os.git ``` -# Common Stuff + +# Common ENV Variabls + ```bash export IP_ADDR= export API_HOST=$IP_ADDR @@ -112,47 +123,25 @@ export FW_UPDATE_SERVER=https://api.github.com/repos/Farmbot/farmbot-arduino-fir export WEB_API_URL=http://$IP_ADDR:$API_PORT ``` -# Set up the API. +# REST API Setup + +[See API documentation](https://github.com/FarmBot/Farmbot-Web-API) + +# MQTT Setup + +[See MQTT documentation](https://github.com/FarmBot/mqtt-gateway) + +# OS Setup + +For advanced usage see [BUILDING.md](https://github.com/FarmBot/farmbot_os/blob/master/BUILDING.md) + ```bash -cd ~/farmbot/api -# pull any updates from upstream -git pull upstream master - -# Should only need to do this command once. -bundle install - -# Should only need to do this command once. -rake db:migrate -rails s -b 0.0.0.0 -``` - -# Set up MQTT -```bash -cd ~/farmbot/mqtt -git pull upstream master -# Should only need to do this command once. -npm install -npm start -``` - -# Set up the Frontend -```bash -cd ~/farmbot/frontend -git pull upstream master -# Should only need to do this command once. -npm install -npm start -``` - -# Set up the OS -For advanced stuff see [this](BUILDING.md) -```bash -cd ~/farmbot/os +cd ~/farmbot/os git pull upstream master MIX_ENV=prod mix do deps.get,mix farmbot.firmware # If you want to burn the image to an sdcard: MIX_ENV=prod bash scripts/burn.sh -# If you want to upload the build to a RUNNING bot you can do +# If you want to upload the build to a RUNNING bot you can do MIX_ENV=prod BOT_IP_ADDR= mix farmbot.firmware --upload ``` diff --git a/FAQ.md b/FAQ.md index e5a68ba3..b9661c1b 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,5 +1,7 @@ # 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. * Is the power LED flashing? If yes you need more amps. * Is the Green LED flashing? If no you need more amps. @@ -11,35 +13,42 @@ 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? -Yes you can starting with 2.1.1 of the OS we added SSH. The user is root and there is no password. -This is subject to change so look back if you update and your ssh no longer workds. +# Can I SSH into the Farmbot? -# Why are my ssh keys invalid? -Long story short this is because Farmbot's rootfs is read only so keys have to be stored elsewhere. They occasionally get lost if you pull the power to your Farmbot. Just do what the shell tells you to fix it. +Yes, starting with version 2.1.1. The user is root and there is no password. This may change in future versions. -# Can the shell be on HDMI rather than only SSH? -No. HDMI should display an IEX (elixir shell) session.You can interact with the system in this way if you want. If you want you can `ctrl+c` out of IEX, but this will kill Farmbot's main software. It will give you a linux shell though. +# Why are my SSH keys invalid? -# When I ssh there is no Linux Utilities. -Farmbot is built using Buildroot. Which uses a very 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`. +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? + +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. + +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? -See the above answer. If you believe we need a package please open an issue and we can discuss adding it. There is talk of adding a plugin system, where the user could supply their own packages. it is not implemented yet. + +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? -Yes. When you log into the Farmbot Configurator wifi ssid, you can select `Use Ethernet`. [NOTE]: This can not be changed without a factory reset. -# How do i factory reset my bot? +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? + This is not as trivial as you would think right now. (We are working on it.) -You can use SSH: + +** EASY: ** Flash the SD card +** Via HDMI monitor / IEx: ** `Farmbot.factory_reset()` + +** Via SSH: ** + ```bash ssh root@ rm /data/* -rf /usr/sbin/reboot ``` -Or if you have a hdmi monitor plugged into your RPI you can use IEX -```elixir -Farmbot.factory_reset() -``` -Or (probably the easiest) you can just flash a new SD Card.