This firmware is intended to be a fully object-oriented highly modular control program for
RepRap self-replicating 3D printers.

It owes a lot to Marlin and to the original RepRap FiveD_GCode.

This is the version for the RepRap Duet: 

  http://blog.think3dprint3d.com/2013/12/Duet-Arduino-Due-compatible-3DPrinter-controller.html  

To edit and compile this you will also need the Arduino board files from

  https://github.com/reprappro/RepRapFirmware/tree/master/Hardware

A complete uploadable executable version is in the directory Release/RepRapFirmware.bin in this
repository.  For details of how to flash it to a Duet see here:

  https://reprappro.com/documentation/commissioning-introduction/maintenance-duet/#Installation_8211_Flashing_the_Firmware

For details of how to compile the source code, see below.


General design principles:

  * Control by RepRap G Codes.  These are taken to be machine independent, though some may be unsupported.
  * Full use of C++ OO techniques,
  * Make classes hide their data,
  * Make everything except the Platform class (see below) as stateless as possible,
  * No use of conditional compilation except for #include guards - if you need that, you should be
       forking the repository to make a new branch - let the repository take the strain,
  * Concentration of all machine-dependent definitions and code in Platform.h and Platform.cpp,
  * No specials for (X,Y) or (Z) - all movement is 3-dimensional,
  * Except in Platform.h, use real units (mm, seconds etc) throughout the rest of the code wherever possible,
  * Try to be efficient in memory use, but this is not critical,
  * Labour hard to be efficient in time use, and this is critical,
  * Don't abhor floats - they work fast enough if you're clever,
  * Don't avoid arrays and structs/classes,
  * Don't avoid pointers,
  * Use operator and function overloading where appropriate.


Naming conventions:

  * #defines are all CAPITALS_WITH_OPTIONAL_UNDERSCORES_BETWEEN_WORDS
  * No underscores in other names - MakeReadableWithCapitalisation
  * Class names and functions start with a CapitalLetter
  * Variables start with a lowerCaseLetter
  * Use veryLongDescriptiveNames


Structure:

There are nine main classes:

  * RepRap
  * GCodes
  * Heat
  * Move
  * Platform
  * Network
  * Webserver
  * Roland, and
  * PrintMonitor

RepRap:

  This is just a container class for the single instances of all the others, and otherwise does very little.

GCodes:

  This class is fed GCodes, either from the web interface, or from GCode files, or from a serial interface,
  Interprets them, and requests actions from the RepRap machine via the other classes.

Heat:

  This class implements all heating and temperature control in the RepRap machine.

Move:

  This class controls all movement of the RepRap machine, both along its axes, and in its extruder drives.

Platform:

  This is the only class that knows anything about the physical setup of the RepRap machine and its
  controlling electronics.  It implements the interface between all the other classes and the RepRap machine.
  All the other classes are completely machine-independent (though they may declare arrays dimensioned
  to values #defined in Platform.h).

Network:

  This class implements a basic TCP interface for the Webserver classes using LWIP.

Webserver:

  This class talks to the network (via Platform) and implements a simple webserver to give an interactive
  interface to the RepRap machine. It uses the Knockout and Jquery Javascript libraries to achieve this.
  In addition, FTP and Telnet servers are provided for easier SD card file management and G-Code handling.

Roland:

  This class can interface with a Roland mill (e.g. Roland MDX-20/15) and allows the underlying hardware
  to act as a G-Code proxy, which translates G-Codes to internal Roland commands.

PrintMonitor:

  This class provides methods to obtain statistics (height, filament usage etc.) from generated G-Code
  files and to calculate estimated print end-times for a live print.


When the software is running there is one single instance of each main class, and all the memory allocation is
done on initialization.  new/malloc should not be used in the general running code, and delete is never
used.  Each class has an Init() function that resets it to its boot-up state; the constructors merely handle
that memory allocation on startup.  Calling RepRap.Init() calls all the other Init()s in the right sequence.

There are other ancillary classes that are declared in the .h files for the master classes that use them.  For
example, Move has a DDA class that implements a Bresenham/digital differential analyser.


Timing:

There is a single interrupt chain entered via Platform.Interrupt().  This controls movement step timing, and
this chain of code should be the only place that volatile declarations and structure/variable-locking are
required.  All the rest of the code is called sequentially and repeatedly as follows:

As of version 057r-dc42 the tick interrupt (which is set up by the Arduino core) is also used to set up ADC conversions,
read the result of the last conversion, and shut down heaters when temperature errors are detected.

All the main classes have a Spin() function.  These are called in a loop by the RepRap.Spin() function and implement
simple timesharing.  No class does, or ever should, wait inside one of its functions for anything to happen or call
any sort of delay() function.  The general rule is:

  Can I do a thing?
    Yes - do it
    No - set a flag/timer to remind me to do it next-time-I'm-called/at-a-future-time and return.

The restriction this strategy places on almost all the code in the firmware (that it must execute quickly and
never cause waits or delays) is balanced by the fact that none of that code needs to worry about synchronization,
locking, or other areas of code accessing items upon which it is working.  As mentioned, only the interrupt
chain needs to concern itself with such problems.  Unlike movement, heating (including PID controllers) does
not need the fast precision of timing that interrupts alone can offer.  Indeed, most heating code only needs
to execute a couple of times a second.

Most data is transferred bytewise, with classes' Spin() functions typically containing code like this:

  Is a byte available for me?
    Yes
      read it and add it to my buffer
      Is my buffer complete?
         Yes
           Act on the contents of my buffer
         No
           Return
  No
    Return

Note that it is simple to raise the "priority" of any class's activities relative to the others by calling its
Spin() function more than once from RepRap.Spin().

-------------

Compiling from Source

Although the firmware was originally developed using Eclipse Juno, the latest version of the Arduino toolkit (1.6.4) breaks compatibility
with the Arduino Eclipse Plugin. Hence a Makefile has been introduced to compile the firmware easily on OS X and Linux. For Windows there
is also a Windows PowerShell script available.

As a prerequisite you must install Arduino IDE and the necessary board files. Refer to the README file in the Hardware directory for
basic instructions on how this can be achieved.

Compiling the firmware is fairly easy on *nix-based operating systems. All you need to do is to run

  make all

in the source code folder. On Windows, you can use the corresponding PowerShell script instead:

  powershell.exe -ExecutionPolicy Unrestricted -FileName .\Make.ps1

Once a firmware binary has been generated, both Makefiles can be further used to upload the generated output file to the erased electronics
board:

  make upload

or on Windows

  powershell.exe -ExecutionPolicy Unrestricted -FileName .\Make.ps1 upload

In order to take advantage of more sophisticated development conditions, a clang configuration file is included in this directory. It may be used,
for example, with vim-clang. If you decide to use it, just don't forget to set your clang C options to '-std=gnu99' and your CPP flags to '-std=gnu++11'.


-------------
Note on dc42 fork of this firmware:

As well as containing various bug fixes and performance improvements, I have added various functionality compared to the original RepRapPro version.
The major changes are:

- Z probe reading is included in the web server poll response
- Homed status (i.e. whether homes since reset) is maintained for all 3 axes and included in the web server poll response
- Once the X and Y axes have been homed, movement is limited to the range of the axis, except when the G0 or G1 command includes
  the check endstops (S1) parameter. Use the M208 command to set axis travel if the default values in the firmware are incorrect for your machine.
- Implemented M301 (hot end PID parameters) and M304 (bed PID parameters) commands. Extended these commands to allow setting of thermistor
  resistance at 25C (R parameter) and thermistor beta (B parameter). A negative P parameter means don't use PID, use bang-bang control.
- Implemented M999. This resets the Duet.
- Added temperature (T) and temperature coefficient of height (C) parameters to the G31 command
- Added support for modulated IR sensor (M558 P2) and ultrasonic sensor (M558 P3)
- Various parameters are now saved to flash memory (Z-probe parameters, network parameters, PID parameters)
- FAN0 line is driven at 25kHz and pin 25 on the expansion header (Duet) can utilise the tacho line of 4-pin PWM fans

-------------
Note on zpl fork of this firmware:

Based on dc42's long-time proven Duet firmware fork, I have implemented a couple more features and (partially) merged in features from RepRapPro's development firmware branch.
The most significant changes are:

- FTP and Telnet support
- Reliable low-level networking and implementation of the internal EMAC ISR
- Internal G-Code queuing to execute non-movement codes just-in-time and not ~20 moves too early (due to the look-ahead)
- M25: SD-card prints are paused as soon as the current move finishes
- M0 does no longer disable any stepper motors or heaters if the print is paused. This shall simplify print restarts (requires my web interface fork)
- Implemented cold retracts, minimum temperature is 90C
- Flash usage is optional; only one line needs to be commented out to disable it

See the "Changes in ... fork" text files for complete lists of all the changes dc42 and zpl have contributed.

-------------

Version 1.09

Started: 2012-11-18
This README dated: 2015-10-14

Adrian Bowyer
RepRap Professional Ltd
http://reprappro.com

Licence: GPL