Verison 1.0.3 Release

Based on Buildbotics 0.4.14

docs/development.md

@@ -0,0 +1,106 @@
+# Buildbotics CNC Controller Development Guide
+
+This document describes how to setup your environment for Buildbotics CNC
+controller development on Debian Linux.  Development on systems other than
+Debian Linux are not supported.
+
+## Installing the Development Prerequisites
+
+On a Debian Linux (9.6.0 stable) system install the required packages:
+
+    sudo apt-get update
+    sudo apt-get install -y build-essential git wget binfmt-support qemu \
+      parted gcc-avr avr-libc avrdude pylint3 python3 python3-tornado curl \
+      unzip python3-setuptools gcc-arm-linux-gnueabihf bc sudo
+    curl -sL https://deb.nodesource.com/setup_13.x | sudo -E bash -
+    sudo apt-get install -y nodejs
+
+## Getting the Source Code
+
+    git clone https://github.com/buildbotics/bbctrl-firmware
+
+## Build the Firmware
+
+    cd bbctrl-firmware
+    make
+
+## Build GPlan Module
+
+GPlan is a Python module written in C++.  It must be compiled for ARM so that
+it can be used on the Raspberry Pi.  This is accomplished using a chroot, qemu
+and binfmt to create an emulated ARM build environment.  This is faster and
+more convenient than building on the RPi itself.  All of this is automated.
+
+    make gplan
+
+The first time this is run it will take quite awhile as it setups up the build
+environment.  You can run the above command again later to build the latest
+version.
+
+## Build the Firmware Package
+
+    make pkg
+
+The resulting package will be a ``.tar.bz2`` file in ``dist``.
+
+## Upload the Firmware Package to a Buildbotics CNC Controller
+If you have a Buildbotics CNC controller at ``bbctrl.local``, the default
+address, you can upgrade it with the new package like this:
+
+    make update HOST=bbctrl.local PASSWORD=<pass>
+
+Where ``<pass>`` is the controller's admin password.
+
+## Updating the Pwr Firmware
+
+The Pwr firmware must be uploaded manually using an ISP programmer.  With the
+programmer attached to the pwr chip ISP port on the Builbotics controller's
+main board run the following:
+
+    make -C src/pwr program
+
+## Initializing the main AVR firmware
+
+The main AVR must also be programmed manually the first time.  Later it will be
+automatically programmed by the RPi as part of the firmware install.  To perform
+the initial AVR programming connec the ISP programmer to the main AVR's ISP port
+on the Buildbotics controller's main board and run the following:
+
+    make -C src/avr init
+
+This will set the fuses, install the bootloader and program the firmware.
+
+## Installing the RaspberryPi base system
+
+Download the latest Buildbotics CNC controller base image and decompress it:
+
+    wget \
+      https://buildbotics.com/upload/2018-05-15-raspbian-stretch-bbctrl.img.xz
+    xz -d 2018-05-15-raspbian-stretch-bbctrl.img.xz
+
+Now copy the base system to an SD card.  You need a card with at least 8GiB.
+After installing the RPi system all data on the SD card will be lost.  So make
+sure you back up the SD card if there's anything important on it.
+
+In the command below, make sure you have the correct device or you can
+**destroy your Linux system** by overwriting the disk.  One way to do this is
+to run ``sudo tail -f /var/log/syslog`` before inserting the SD card.  After
+inserting the card look for log messages containing ``/dev/sdx`` where ``x`` is
+a letter.  This should be the device name of the SD card.  Hit ``CTRL-C`` to
+stop following the system log.
+
+    sudo dd bs=4M if=2015-05-05-raspbian-wheezy.img of=/dev/sde
+    sudo sync
+
+The first command takes awhile and does not produce any output until it's done.
+
+Insert the SD card into your RPi and power it on.  Plug in the network
+connection, wired or wireless.
+
+## Logging into the Buildbotics Controller
+
+You can ssh in to the Buildbotics Controller like so:
+
+    ssh bbmc@bbctrl.local
+
+The default password is ``buildbotics``.  It's best if you change this.