Initial commit of source code.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

4 files changed, 309 insertions, 0 deletions

diff --git a/docs/Code_Overview.md b/docs/Code_Overview.md
new file mode 100644
index 00000000..34550e25
--- /dev/null
+++ b/docs/Code_Overview.md
@@ -0,0 +1,93 @@
+This document describes the overall code layout and major code flow of
+Klipper.
+
+Directory Layout
+================
+
+The **src/** directory contains the C source for the micro-controller
+code. The **src/avr/** directory contains specific code for Atmel
+ATmega micro-controllers. The **src/simulator/** contains code stubs
+that allow the micro-controller to be test compiled on other
+architectures.
+
+The **klippy/** directory contains the C and Python source for the
+host part of the firmware.
+
+The **config/** directory contains example printer configuration
+files.
+
+The **scripts/** directory contains build-time scripts useful for
+compiling the micro-controller code.
+
+During compilation, the build may create an **out/** directory. This
+contains temporary build time objects. The final micro-controller
+object that is built is in **out/klipper.elf.hex**
+
+Micro-controller code flow
+==========================
+
+Execution of the micro-controller code starts in **src/avr/main.c**
+which calls sched_main() located in **src/sched.c**. The sched_main()
+code starts by running all functions that have been tagged with the
+DECL_INIT() macro. It then goes on to repeatedly run all functions
+tagged with the DECL_TASK() macro.
+
+One of the main task functions is command_task() located in
+**src/command.c**. This function processes incoming serial commands
+and runs the associated command function for them. Command functions
+are declared using the DECL_COMMAND() macro.
+
+Task, init, and command functions always run with interrupts enabled
+(however, they can temporarily disable interrupts if needed). These
+functions should never pause, delay, or do any work that lasts more
+than a few micro-seconds. These functions schedule work at specific
+times by scheduling timers.
+
+Timer functions are scheduled by calling sched_timer() (located in
+**src/sched.c**). The scheduler code will arrange for the given
+function to be called at the requested clock time. Timer interrupts
+are initially handled in an interrupt handler in **src/avr/timer.c**,
+but this just calls sched_timer_kick() located in **src/sched.c**. The
+timer interrupt leads to execution of schedule timer functions.  Timer
+functions always run with interrupts disabled. The timer functions
+should always complete within a few micro-seconds. At completion of
+the timer event, the function may choose to reschedule itself.
+
+In the event an error is detected the code can invoke shutdown() (a
+macro which calls sched_shutdown() located in **src/sched.c**).
+Invoking shutdown() causes all functions tagged with the
+DECL_SHUTDOWN() macro to be run. Shutdown functions always run with
+interrupts disabled.
+
+Much of the functionality of the micro-controller involves working
+with General-Purpose Input/Output pins (GPIO). In order to abstract
+the low-level architecture specific code from the high-level task
+code, all GPIO events are implemented via wrappers. These wrappers are
+located in **src/avr/gpio.c**. The code is compiled with gcc's "-flto
+-fwhole-program" optimization which does an excellent job of inlining
+functions across compilation units, so most of these tiny gpio
+functions are inlined into their callers, and there is no run-time
+cost to using them.
+
+Klippy code overview
+====================
+
+The host code (Klippy) is intended to run on a low-cost computer (such
+as a Raspberry Pi) paired with the micro-controller. The code is
+primarily written in Python, however it does use CFFI to implement
+some functionality in C code.
+
+Initial execution starts in **klippy/klippy.py**. This reads the
+command-line arguments, opens the printer config file, instantiates
+the main printer objects, and starts the serial connection. The main
+execution of gcode commands is in the process_commands() method in
+**klippy/gcode.py**. This code translates the gcode commands into
+printer object calls, which frequently translate the actions to
+commands to be executed on the micro-controller (as declared via the
+DECL_COMMAND macro in the micro-controller code).
+
+There are three threads in the Klippy host code. The main thread
+handles incoming gcode commands. A second thread (which resides
+entirely in the **klippy/serialqueue.c** C code) handles low-level IO
+with the serial port. The third thread is used to process response
+messages from the micro-controller in the Python code.
diff --git a/docs/Debugging.md b/docs/Debugging.md
new file mode 100644
index 00000000..ed2d92c9
--- /dev/null
+++ b/docs/Debugging.md
@@ -0,0 +1,90 @@
+The Klippy host code has some tools to help in debugging the firmware.
+
+Testing with simulavr
+=====================
+
+The [simulavr](http://www.nongnu.org/simulavr/) tool enables one to
+simulate an Atmel ATmega micro-controller. This section describes how
+one can run test gcode files through simulavr. It is recommended to
+run this on a desktop class machine (not a Raspberry Pi) as it does
+require significant cpu to run efficiently.
+
+To use simulavr, download the simulavr package and compile with python
+support:
+
+```
+git clone git://git.savannah.nongnu.org/simulavr.git
+cd simulavr
+./bootstrap
+./configure --enable-python
+make
+```
+
+Note that the build system may need to have some packages (such as
+swig) installed in order to build the python module. Make sure the
+file **src/python/_pysimulavr.so** is present after the above
+compilation.
+
+To compile Klipper for use in simulavr, run:
+
+```
+cd /patch/to/klipper
+make menuconfig
+```
+
+and compile the firmware for an AVR atmega644p, disable the AVR
+watchdog timer, set the MCU frequency to 20000000, and set the serial
+baud rate to 115200. Then one can compile Klipper (run `make`) and
+then start the simulation with:
+
+```
+PYTHONPATH=/path/to/simulavr/src/python/ ./scripts/avrsim.py -m atmega644 -s 20000000 -b 115200 out/klipper.elf
+```
+
+It may be necessary to create a python virtual environment to run
+Klippy on the target machine. To do so, run:
+
+```
+virtualenv ~/klippy-env
+~/klippy-env/bin/pip install cffi==1.6.0 pyserial==2.7
+```
+
+Then, with simulavr running in another window, one can run the
+following to read gcode from a file (eg, "test.gcode"), process it
+with Klippy, and send it to Klipper running in simulavr:
+
+```
+~/klippy-env/bin/python ./klippy/klippy.py config/avrsim.cfg -i test.gcode -v
+```
+
+Using simulavr with gtkwave
+---------------------------
+
+One useful feature of simulavr is its ability to create signal wave
+generation files with the exact timing of events. To do this, follow
+the directions above, but run avrsim.py with a command-line like the
+following:
+
+```
+PYTHONPATH=/path/to/simulavr/src/python/ ./scripts/avrsim.py -m atmega644 -s 20000000 -b 115200 out/klipper.elf -t PORTA.PORT,PORTC.PORT
+```
+
+The above would create a file **avrsim.vcd** with information on each
+change to the GPIOs on PORTA and PORTB. This could then be viewed
+using gtkwave with:
+
+```
+gtkwave avrsim.vcd
+```
+
+Manually sending commands to the micro-controller
+-------------------------------------------------
+
+Normally, Klippy would be used to translate gcode commands to Klipper
+commands. However, it's also possible to manually send Klipper
+commands (functions marked with the DECL_COMMAND() macro in the
+Klipper source code). To do so, run:
+
+```
+~/klippy-env/bin/python ./klippy/console.py /tmp/pseudoserial 115200
+```
diff --git a/docs/Installation.md b/docs/Installation.md
new file mode 100644
index 00000000..aae13511
--- /dev/null
+++ b/docs/Installation.md
@@ -0,0 +1,118 @@
+Klipper is currently in an experimental state. These instructions
+assume the software will run on a Raspberry Pi computer in conjunction
+with OctoPrint. Klipper supports only Atmel ATmega based
+micro-controllers at this time.
+
+It is recommended that a Raspberry Pi 2 or Raspberry Pi 3 computer be
+used as the host. The software will run on a first generation
+Raspberry Pi, but the combined load of OctoPrint, Klipper, and a web
+cam (if applicable) can overwhelm its CPU leading to print stalls.
+
+Prepping an OS image
+====================
+
+Start by installing [OctoPi](https://github.com/guysoft/OctoPi) on the
+Raspberry Pi computer. Use version 0.13.0 or later - see the
+[octopi releases](https://github.com/guysoft/OctoPi/releases) for
+release information. One should verify that OctoPi boots, that the
+OctoPrint web server works, and that one can ssh to the octopi server
+(ssh pi@octopi -- password is "raspberry") before continuing.
+
+After installing OctoPi, ssh into the target machine and run the
+following commands:
+
+```
+sudo apt-get update
+sudo apt-get install avrdude gcc-avr binutils-avr avr-libc libncurses-dev
+```
+
+The host software (Klippy) requires a one-time setup - run as the
+regular "pi" user:
+
+```
+virtualenv ~/klippy-env
+~/klippy-env/bin/pip install cffi==1.6.0 pyserial==2.7
+```
+
+Building Klipper
+================
+
+To obtain Klipper, run the following command on the target machine:
+
+```
+git clone https://github.com/KevinOConnor/klipper
+cd klipper/
+```
+
+To compile the micro-controller code, start by configuring it:
+
+```
+make menuconfig
+```
+
+Select the appropriate micro-controller and serial baud rate. Once
+configured, run:
+
+```
+make
+```
+
+Ignore any warnings you may see about "misspelled signal handler" (it
+is due to a bug fixed in gcc v4.8.3).
+
+Installing Klipper on a micro-controller
+----------------------------------------
+
+The avrdude package can be used to install the micro-controller code
+on an AVR ATmega chip. The exact syntax of the avrdude command is
+different for each micro-controller. The following is an example
+command for atmega2560 chips:
+
+```
+example-only$ avrdude -C/etc/avrdude.conf -v -patmega2560 -cwiring -P/dev/ttyACM0 -b115200 -D -Uflash:w:/home/pi/klipper/out/klipper.elf.hex:i
+```
+
+Setting up the printer configuration
+====================================
+
+It is necessary to configure the printer. This is done by modifying a
+configuration file that resides on the host. Start by copying an
+example configuration and editing it.  For example:
+
+```
+cp ~/klipper/config/example.cfg ~/printer.cfg
+nano printer.cfg
+```
+
+Make sure to look at and update each setting that is appropriate for
+the hardware.
+
+Configuring OctoPrint to use Klippy
+===================================
+
+The OctoPrint web server needs to be configured to communicate with
+the Klippy host software. Using a web-browser, login to the OctoPrint
+web page, and navigate to the Settings tab. Then configure the
+following items:
+
+Under "Serial Connection" in "Additional serial ports" add
+"/tmp/printer". Then click "Save".
+
+Enter the Settings tab again and under "Serial Connection" change the
+"Serial Port" setting to "/tmp/printer".
+
+Under the "Features" tab, unselect "Enable SD support". Then click
+"Save".
+
+Running the host software
+=========================
+
+The host software is executed by running the following as the regular
+"pi" user:
+
+```
+~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -l /tmp/klippy.log < /dev/null > /tmp/klippy-errors.log 2>&1 &
+```
+
+Once Klippy is running, use a web-browser and navigate to the
+OctoPrint web site. Click on "Connect" under the "Connection" tab.
diff --git a/docs/Overview.md b/docs/Overview.md
new file mode 100644
index 00000000..05311c27
--- /dev/null
+++ b/docs/Overview.md
@@ -0,0 +1,8 @@
+See [installation](Installation.md) for information on compiling,
+installing, and running Klipper.
+
+See [code overview](Code_Overview.md) for developer information on the
+structure and layout of the Klipper code.
+
+See [debugging](Debugging.md) for developer information on how to test
+and debug Klipper.