diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Code_Overview.md | 93 | ||||
| -rw-r--r-- | docs/Debugging.md | 90 | ||||
| -rw-r--r-- | docs/Installation.md | 118 | ||||
| -rw-r--r-- | docs/Overview.md | 8 |
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. |