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

Fix links, typos.

pull/220/head
Rick Carlino 2016-12-27 15:02:42 -06:00
parent 96629354a1
commit 3342258bbe
3 changed files with 96 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
BUILDING.md
View File

@ -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

113
CONTRIBUTING.md
View File

@ -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=<INSERT_IP_ADDRESS_HERE>
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=<FARMBOT_IP_ADDRESS!!!@> mix farmbot.firmware --upload
```

45
FAQ.md
View File

@ -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@<MY FARMBOT IP ADDRESS>
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.