SAMD Cortex M0 device support (Zero, MKR1000, etc)

Compilation improvements by adding variant as other obj but not working on device

Arduino Zero devices with OpenOCD working

Created ARM_TOOLS_DIR and define arm toolchain executables in Sam.mk

Check avr-gcc on last AVR_TOOLS_DIR detect and indenting formatting

GDB debugging and programming added

Documentation updates and define ARDMK_VENDOR rather than include Sam.mk

Expand all parse_boards when defined rather than when used

Trim extra defines regex working on both macOS and Linux but need better fix

Print USB ids and added debug usage to readme

Add note on Arduino package dir and made board.txt work

Do ARM ARDUINO_ARCH define in Arduino.mk]

Add MZeroBlink to non-testable examples for now

Remove \B from extra defines grep

Add ARDUINO_PACKAGE_DIR for board support files

Fix a typo in the README

Fix typo in arduino-mk-vars.md

Prevent re-including Arduino.mk from Sam.mk when make restarts for upload

Add catrina to ARD_REST_OPTS if/else

Remove realpath in Sam.mk for cygwin compatability

SAMD bootloader support in ard-reset using --zero

Enters bootloader using open/close of port at 1200 BAUD, then polls the
attached devices for new port enumerating (bootloader). This is how the
Arduino IDE operates

Bossa support for Zero, MKR1000 etc

Re-word Arm README section after Native USB development

Reset for zero refactored like IDE

Zero bootloader reset tested on macOS and comments added

Re-word ARM bootloader and remove imports from testing

Patch changes ARDMK_VENDOR->ARCHITECHTURE, show_config_vars, ignore CORE_VER if emtpy

Common.mk header guard, openocd/bossac avoid separator, typos

Documentation update for patch changes

Move ARM tools to Sam.mk and auto-detect include

Correct accidental commit of Blink Makefile change

Lib fix with alternative core and documentation

Append zero to ARD_RESET_OPTS rather than set

Prioritise package ARM upload tools over path installed

Add note in README on ARM tools versions

Move openocd variant config script flag to OPTS

1 files changed, 69 insertions, 2 deletions

diff --git a/README.md b/README.md
index 953d067..f3b5e20 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,8 @@ This is a very simple Makefile which knows how to build Arduino sketches. It def
 - Very robust
 - Highly customizable
 - Supports all official AVR-based Arduino boards
+- Supports official ARM-based Arduino boards using Atmel SAM chip family
+  (Cortex M0) and includes on-device debugging targets.
 - Supports chipKIT
 - Supports Teensy 3.x (via Teensyduino)
 - Works on all three major OS (Mac, Linux, Windows)
@@ -313,6 +315,72 @@ See examples/BlinkOpenCM for example usage.
 
 For large Robotis projects, [libmaple](https://github.com/Rhoban/Maple) may be more appropriate, as the OpenCM IDE uses a very old compiler release.
 
+## Arduino ARM Boards
+
+For Arduino boards using ARM architechure, specifically the Atmel SAM series
+(Arduino M0 [Pro], Zero, MKR1000, Feather M0, etc.), first
+install the board support package from the IDE or other distribution channels.
+
+Define`ARDUINO_PACKAGE_DIR` as the root path containing the ARM support
+package (the manufacturer folder) and the `BOARD_TAG` (see `make show_boards`
+for help) within your project Makefile. Include 'Sam.mk' rather than
+  'Arduino.mk' at the end of your file - see examples/ZeroBlink and
+  examples/MZeroBlink for example usage.
+
+**Note**: The Arduino IDE does not install board support packages to
+the base Arduino installation directory (the directory that will work with AVR
+Makefiles). They are generally installed to a '.arduino15/packages' folder in
+the users home directory. This is the reason for the new `ARDUINO_PACKAGE_DIR`
+define. On Windows, the package directory is often in the user home directory
+so advice is to create a symblic link to avoid slash/space in path problems.
+You can also manually install support packages in your Sketchbook 'hardware'
+folder, then define ARDUINO_PACKAGE_DIR as this path.
+
+If using a SAM board from a manufacturer other than Arduino, one must still
+install the Arduino board support as above (unless using externally defined
+toolchain) and then define the location of the manufacturer board support core
+using the ALTERNATIVE_CORE_PATH define. For example: `ALTERNATE_CORE_PATH =
+$(ARDUINO_SKETCHBOOK)/hardware/sparkfun/samd`
+
+The programing method will auto-detect based on the `BOARD_TAG` settings read
+from boards.txt:
+
+Programming using OpenOCD CMSIS-DAP with the Programming/debug USB is
+currently supported (the same method used by the IDE), including burning
+bootloaders. External CMSIS tools such as Atmel Ice will also work with this
+method. Black Magic Probe (BMP) support is also included using GDB for both
+uploading and debugging.
+
+Native USB programing using Bossa (Zero, MKR1000, Feather style bootloaders)
+and avrdude (M0 bootloaders) is supported. The bootloaders on these devices
+requires a double press of the reset button or open/closing the serial port at
+1200 BAUD. The automatic entry of the bootloader is attempted using
+`ard-reset-arduino` when using the general `make upload` target by polling
+attached devices until the bootloader port re-attaches (same method as the
+IDE). On Windows, the USB enumerates as differnt COM ports for the CDC Serial
+and bootloader and these must be defined. On encountering problems, one can
+manually enter the bootloader then upload using the `make raw_upload` target.
+Note that the `make reset` target will enter the bootloader on these devices;
+there is no way to reset over USB.
+
+If using system installed tools, be aware that `openocd` and `bossa` were
+orginally forked for Arduino support and system distributions may not be up
+to date with merged changes. `bossa` must be version 1.7->. `openocd` should
+work but there may be problems at run time
+[ref](https://github.com/pda/arduino-zero-without-ide). Ideally, use the
+support packaged version or compile and install the Arduino fork.
+
+With the ARM chipset and using a CMSIS-DAP tool, on-device debugging is made available:
+
+* `debug_init` and `debug` targets for on-device debugging using GDB. To use
+  this, one must start the GDB server with `make debug_init &`, followed by
+  connecting to the target with `make debug`. If using a Black Magic Probe,
+  one can just use `make debug`. At the moment, a system wide `arm-none-eabi-gdb` must be
+  installed as the one supplied with the Arduino toolchain
+  does not appear to work. 
+* Example usage: https://asciinema.org/a/Jarz7Pr3gD6mqaZvCACQBzqix
+* See the examples/MZeroBlink Makefile for a commented example.
+
 ## Versioning
 
 The current version of the makefile is `1.6.0`. You can find the full history in the [HISTORY.md](HISTORY.md) file
@@ -332,9 +400,8 @@ Also checkout the [contribution guide](CONTRIBUTING.md) for more details.
 
 If you are looking for ideas to work on, then check out the following TODO items or the [issue tracker](https://github.com/sudar/Arduino-Makefile/issues/).
 
-## Limitations / Know Issues / TODO's
+## Limitations / Known Issues / TODO's
 
-- Doesn't support SAM boards yet.
 - Since it doesn't do any pre processing like Arduino IDE, you have to declare all methods before you use them ([issue #59](https://github.com/sudar/Arduino-Makefile/issues/59))
 - More than one .ino or .pde file is not supported yet ([issue #49](https://github.com/sudar/Arduino-Makefile/issues/49))
 - When you compile for the first time, it builds all libs inside Arduino directory even if it is not needed. But while linking only the relevant files are linked. ([issue #29](https://github.com/sudar/Arduino-Makefile/issues/29)). Even Arduino IDE does the same thing though.