Skip to content
This repository
Browse code

README: shorten drastically to avoid documentation duplication.

  • Loading branch information...
commit 64072dfd03339b5f7d3e1e5999845355375743fe 1 parent 1906606
Traumflug authored

Showing 1 changed file with 21 additions and 230 deletions. Show diff stats Hide diff stats

  1. 251  README
251  README
... ...
@@ -1,246 +1,37 @@
1  
-
2  
-For installation instructions, see
3  
-http://reprap.org/wiki/Teacup_Firmware#Simple_Installation
4  
-
5  
-##############################################################################
6  
-#                                                                            #
7  
-# Teacup (formely FiveD on Arduino) firmware                                 #
8  
-#                                                                            #
9  
-##############################################################################
10  
-
11  
-Rewrite of Reprap Mendel firmware:
12  
-
13  
-* 100% integer computations
14  
-* serial transmit buffer
15  
-* can fit onto atmega168 depending on selected options
16  
-* works on atmega328p
17  
-* works on atmega644p
18  
-* works on at90usb1287 with direct USB serial
19  
-* porting to atmega1280 in progress
20  
-* will work on larger atmegas with minor porting
21  
-
22  
-Forum Thread: http://forums.reprap.org/read.php?147
23  
-Post all queries, comments, etc here
24  
-
25  
-Github: http://github.com/triffid/Teacup_Firmware
26  
-patches, issues go here
27  
-
28 1
 ##############################################################################
29 2
 #                                                                            #
30  
-# How to use                                                                 #
31  
-#                                                                            #
32  
-##############################################################################
33  
-
34  
-1) COPY config.YOURBOARDHERE.h to config.h and edit to suit your electronics
35  
-2) check programming settings in Makefile (chip type, avrdude settings, etc)
36  
-3) make
37  
-4) make program
38  
-4a) if programming blank chip, make program-fuses
39  
-5) ./sender.sh (or use a GUI G-code sender, like Pronterface)
40  
-6) have a play, go to 1) if not right
41  
-7) try printing something!
42  
-
43  
-##############################################################################
44  
-#                                                                            #
45  
-# Requirements                                                               #
46  
-#                                                                            #
47  
-##############################################################################
48  
-
49  
-Compile:
50  
-	gnu make
51  
-	binutils, gcc, etc built for avr target (avr-gcc, avr-as, etc)
52  
-	avr-libc
53  
-Program:
54  
-	avrdude
55  
-	something that avrdude supports: bootloader, separate programmer, whatever
56  
-
57  
-##############################################################################
  3
+# Teacup - lean and efficient firmware for RepRap printers                   #
58 4
 #                                                                            #
59  
-# License                                                                    #
  5
+# by Triffid Hunter, Traumflug, jakepoz, Markus Hitter, many others          #
60 6
 #                                                                            #
61 7
 ##############################################################################
62 8
 
63  
-This firmware is Copyright (C) 2009-2010 Michael Moon aka Triffid_Hunter
64  
-
65  
-This program is free software; you can redistribute it and/or modify
66  
-it under the terms of the GNU General Public License as published by
67  
-the Free Software Foundation; either version 2 of the License, or
68  
-(at your option) any later version.
  9
+For installation instructions, see
  10
+http://reprap.org/wiki/Teacup_Firmware#Simple_Installation and/or
  11
+http://reprap.org/wiki/Teacup_Firmware#Developer_Installation
69 12
 
70  
-This program is distributed in the hope that it will be useful,
71  
-but WITHOUT ANY WARRANTY; without even the implied warranty of
72  
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
73  
-GNU General Public License for more details.
  13
+For documentation, see
  14
+http://reprap.org/wiki/Teacup_Firmware
74 15
 
75  
-You should have received a copy of the GNU General Public License
76  
-along with this program; if not, write to the Free Software
77  
-Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
78 16
 
79 17
 ##############################################################################
80 18
 #                                                                            #
81  
-# Rationale and History                                                      #
  19
+# This firmware is Copyright (c) ...                                         #
  20
+#   2009 - 2010 Michael Moon aka Triffid_Hunter                              #
  21
+#   2010 - 2013 Markus "Traumflug" Hitter <mah@jump-ing.de>                  #
82 22
 #                                                                            #
83  
-##############################################################################
84  
-
85  
-I started building my electronics with only a regular arduino to test with.
86  
-This was perfectly sufficient for playing with the pololu stepper controllers and the max6675 I bought after reading about all the issues with thermistors that people were having. After a while I decided to check out the official firmware but it required an atmega644. I wondered why.
87  
-So, I decided to skim through the code to see what took up so much space. From what I could see, it was written by someone who was familiar with programming desktop systems and larger embedded devices, but didn't have much experience with small devices such as the atmega168 and atmega644.
88  
-This showed in the use of C++ which served only to make the code harder to read, and the prolific use of floating-point math, with some appearing even in interrupt context!
89  
-I came to the conclusion that there was no reason that the main body of code couldn't fit onto an atmega168 except for the burdensome and unnecessary overheads from object-oriented code and floating point math. A quick count assured me that the atmega168 had enough pins, but only barely, and I started reading the official firmware properly, with an eye to rewriting as much as possible in a fashion suitable for small microcontrollers.
90  
-
91  
-Starting with an arduino skeleton library I had assembled over time, some of my test code and the official firmware, I hacked up a passable integer-only, straight C implementation of the dda, and wrote my own gcode parser from scratch which processed each character as it arrived (with some buffering of course) instead of waiting for a whole line and then trying to process it all at once.
92  
-
93  
-As soon as my new firmware was able to run a few consecutive moves, I released it for peer review.
94  
-
95  
-The forum thread http://forums.reprap.org/read.php?147,33082 has much of the history from this point on.
96  
-
97  
-Markus Hitter was the first to send patches, and has done a significant amount of work on a number of different parts of this firmware, particularly math and sequencing.
98  
-Jake Poznanski did the initial port to official gen3 electronics with separate extruder board
99  
-Cefiar posted me some thermistors to sponsor addition of thermistor-reading code
100  
-Markus Amsler has done a significant amount of work on the new intercom protocol and the latest timer code, as well as tons of test results in the forum
101  
-Stephen Walter provided the excellent simulation code, plus some fascinating preprocessor abuse which makes configuration significantly easier
102  
-
103  
-Many others have given patches, encouragement and suggestions without which this firmware may never be what it is today.
104  
-
105  
-
106  
-##############################################################################
  23
+# This program is free software; you can redistribute it and/or modify       #
  24
+# it under the terms of the GNU General Public License as published by       #
  25
+# the Free Software Foundation; either version 2 of the License, or          #
  26
+# (at your option) any later version.                                        #
107 27
 #                                                                            #
108  
-# Architectural Overview                                                     #
  28
+# This program is distributed in the hope that it will be useful,            #
  29
+# but WITHOUT ANY WARRANTY; without even the implied warranty of             #
  30
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the              #
  31
+# GNU General Public License for more details.                               #
109 32
 #                                                                            #
110  
-##############################################################################
111  
-
112  
-Teacup is quite similar to the official FiveD firmware in some ways, and markedly different in others. Teacup has as much modularity as I could get away with without sacrificing efficiency.
113  
-
114  
-// FIXME: make next paragraph easier to read
115  
-At startup, the code in mendel.c is run first. This initialises all the modules that need it, then starts polling the clock flags and feeding incoming serial characters to the gcode parser. The gcode parser processes each character individually, keeping track via internal state rather than buffering a line and skipping back and forth. The gcode parser converts floating values to integer or fixed-point representations as soon as it encounters a non-numeric character. It calls many module functions directly, but the most interesting part is move creation, where it passes a target position and speed to enqueue()[dda_queue.c] which adds it to the queue, and fires up dda_start()[dda.c] if the queue was empty. dda_start initialises the dda, figures out the stepper directions and first step timeout and a few other bits of housekeeping, then sets the timer for the appropriate timeout. When the timer fires, it calls dda_step()[dda.c] which sends all the step signals then figures out the next step timeout based on acceleration and speed settings. When the last step has been made, the dda "dies" (sets 'live' property to 0) after which queue_step[dda_queue.c] advances the queue read pointer and starts the next dda.
116  
-
117  
-It is necessary to keep interrupts very short on small microcontrollers, and I have endeavoured to keep them all as short as possible. Unfortunately, dda_step[dda.c] is fairly large. I simply hope that it doesn't take so much time that it interferes with the other interrupts too much.
118  
-
119  
-
120  
-##############################################################################
121  
-#                                                                            #
122  
-# Interesting code sections                                                  #
  33
+# You should have received a copy of the GNU General Public License          #
  34
+# along with this program; if not, write to the Free Software                #
  35
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA #
123 36
 #                                                                            #
124 37
 ##############################################################################
125  
-
126  
-The serial ringbuffers are critical for good communication, but for some reason the official arduino libraries don't implement a tx queue, all but preventing sending stuff from interrupt context. As long as the queues have a length of 2^n, we can use bitwise operations rather than numerical comparison to trim the read and write pointers. The serial send function (serial_writechar[serial.c]) is necessarily careful about checking if it's in an interrupt and only waiting for space in the queue if it's not.
127  
-The dda queue is also a ringbuffer, although its implementation is harder to see as it's embedded in lots of other stuff.
128  
-
129  
-The gcode parser shows how to parse each character as it comes in, so 99% of a command can be processed before the EOL is even received. It started off as a simple state machine, which then grew and shrank and morphed until it was both smaller and more functional. (FIXME: obsoleted by input-float branch if we ever merge it)
130  
-
131  
-The fixed-point stuff is fun, although we have to manually ensure that the decimal point stays in the right spot. decfloat_to_int[gcode.h] is used to convert incoming floats to integer implementations by starting off with a (very!) crude floating point implementation, then choosing appropriate scaling factors within the gcode parser itself. This allows us to do a little stuff that looks like floating-point math without the burdensome overhead of a full fp implementation.
132  
-
133  
-The PID code in heater.c is probably quite generalisable, and seems to work well when tuned. Google knows of plenty of PID tuning guides.
134  
-
135  
-##############################################################################
136  
-#                                                                            #
137  
-# Resources                                                                  #
138  
-#                                                                            #
139  
-##############################################################################
140  
-
141  
-Forum thread: http://forums.reprap.org/read.php?147,33082
142  
-Source Repository: http://github.com/triffid/Teacup_Firmware
143  
-Wiki Page: http://objects.reprap.org/wiki/Teacup_Firmware
144  
-
145  
-##############################################################################
146  
-#                                                                            #
147  
-# File descriptions                                                          #
148  
-#                                                                            #
149  
-##############################################################################
150  
-
151  
-*** analog.[ch]
152  
-This is the analog subsystem. Only used if you have a thermistor or ad595
153  
-
154  
-*** arduino.h, arduino_[chip].h
155  
-Pin mappings and helper functions for various atmegas
156  
-
157  
-*** clock.[ch]
158  
-Regular functions that run in main loop rather than an interrupt
159  
-
160  
-*** config.h, config.*.h
161  
-Configuration for your electronics and hardware and a bunch of templates to create your own. Copy the template closest to your hardware to config.h and edit it further
162  
-
163  
-*** copier.[ch]
164  
-A totally untested and currently unused chunk of code for copying firmware to another identical chip
165  
-
166  
-*** crc.[ch]
167  
-block crc16 routine
168  
-
169  
-*** createTemperatureLookup.py
170  
-A python script to generate your TemperatureTable.h
171  
-
172  
-*** dda.[ch]
173  
-A rather complex block of math that figures out when to step each axis according to speed and acceleration profiles and received moves
174  
-
175  
-*** dda_queue.[ch]
176  
-The queue of moves received from the host.
177  
-
178  
-*** debug.[ch]
179  
-Debugging aids
180  
-
181  
-*** delay.h
182  
-Delay functions
183  
-
184  
-*** Teacup.pde
185  
-Allows firmware to be built in arduino ide
186  
-
187  
-*** func.sh
188  
-Lots of host-side shell scripts for talking to firmware
189  
-
190  
-*** gcode_parse.[ch]
191  
-Gcode parser. Scaling of factors to internally used integer or fixed point happens here too.
192  
-
193  
-*** gcode_process.[ch]
194  
-Gcodes actually get executed here after being parsed.
195  
-
196  
-*** graycode.c
197  
-routines to drive stepper h-bridges directly instead of step/dir
198  
-
199  
-*** heater.[ch]
200  
-Heater management, including PID and PWM algorithms, and some configuration parameters
201  
-
202  
-*** home.[ch]
203  
-Home using endstop routines
204  
-
205  
-*** intercom.[ch]
206  
-Gen3 serial link control and communication
207  
-
208  
-*** LICENSE
209  
-Gnu GPL2 license
210  
-
211  
-*** Makefile
212  
-instructions for make on how to build firmware. has a list of modules to build which may need to be updated every so often
213  
-
214  
-*** mendel.c
215  
-Firmware startup and main loop code
216  
-
217  
-*** pinio.h
218  
-A few I/O primitives
219  
-
220  
-*** README
221  
-this file
222  
-
223  
-*** sender.sh
224  
-A simple talker
225  
-
226  
-*** serial.[ch]
227  
-Serial management and buffers
228  
-
229  
-*** sermsg.[ch]
230  
-Functions for sending primitive messages and values to host
231  
-
232  
-*** sersendf.[ch]
233  
-A small, crude printf implementation
234  
-
235  
-*** temp.[ch]
236  
-Temperature sensor management, includes some configuration parameters
237  
-
238  
-*** ThermistorTable.h
239  
-linear interpolation table for your thermistor, maps analog reading -> temperature
240  
-
241  
-*** timer.[ch]
242  
-Timer management, used primarily by dda.c for timing steps
243  
-
244  
-*** watchdog.[ch]
245  
-Watchdog management. resets chip if firmware locks up or does something strange
246  
-

0 notes on commit 64072df

Please sign in to comment.
Something went wrong with that request. Please try again.