///////////////////////////////////////////////////////////////////////////
//
//   AutoCap Arduino Firmware
//   Version 1.5
//
//   Motor configuration examples.
//
//   License: GNU General Public License Version 3.0.
//    
//   Copyright (C) 2014-2016 by Matthew K. Roberts, KK5JY. All rights reserved.
//
//   This program is free software: you can redistribute it and/or modify
//   it under the terms of the GNU General Public License as published by
//   the Free Software Foundation, either version 3 of the License, or
//   (at your option) any later version.
//    
//   This program is distributed in the hope that it will be useful, but
//   WITHOUT ANY WARRANTY; without even the implied warranty of
//   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
//   General Public License for more details.
//    
//   You should have received a copy of the GNU General Public License
//   along with this program.  If not, see: http://www.gnu.org/licenses/
//
///////////////////////////////////////////////////////////////////////////


CONFIGURING THE FIRMWARE

This firmware source package is distributed with a default configuration in
place.  That configuration matches an Arduino UNO R3, with an official
Arduino Motor Shield R3 installed, attached to one or two normally-
commutated (brushed) DC motors.  This is the easiest and fastest way to use
the AutoCap firmware.

Many other motor configurations are possible:
  1. A generic H-bridge interface (IN1/IN2/ENABLE) driving a DC motor.
  2. A generic ENABLE/DIRECTION interface driving a DC motor.
  3. A stepper motor attached to a double generic H-bridge.
  4. A stepper motor attached to a double ENABLE/DIRECTION interface.
  5. A stepper motor connected to a dedicated stepper controller, with
     a DIR/STEP/ENABLE interface.

And the list goes on.

Many motor configurations are directly supported by the current firmware,
while others can be easily added with a small amount of programming.  This
document will explain how motor control ports are added to the firmware,
in general, and several simple examples will be provided.

The firmware communicates with motors through one or more MOTOR OBJECTS.
Each of these objects has a standard interface, and all motor objects are
identical from the standpoint of the bulk of the firmware.  The main part
of the firmware doesn't know whether the motor port is an H-bridge, or a
stepper controller.  Both types of motor objects "look the same" to the
Arduino when the program is running.

There are currently two different types of motor objects included with
the firmware source.  One is MotorDC, for supporting normal DC motors,
and the other is MotorAccel, for supporting stepper motors.  If you are
comfortable writing Arduino sketches, you can define your own custom
motor object type, as well.

The main sketch must create at least one motor object.  This object can
be of any valid motor object type, and configured appropriately.  In the
section of the sketch marked "REQUIRED: Motor Objects", you should place
whatever motor objects you need to support your motor interface hardware.

Below, there are several examples of motor objects that have been tested
with the firmware for basic functionality.


CREATING CUSTOM MOTOR OBJECT TYPES

The Interfaces.h file contains an abstract interface class that all motor
objects must implement.  This interface has methods for constant movement,
time-based impulse generation, step-based impulse generation, and some
other support items.  Any new motor objects must conform to this interface.
If you wish to implement your own custom motor objects, see the header file
Interfaces.h for interface details, and also MotorDC.h and MotorAccel.h for
examples of the stock motor types.


EXAMPLES

Each motor object will have a type (e.g., MotorDC or MotorAccel), and a
name (e.g., MOTOR1).  The motor objects also take a number of additional
arguments, most of which are Arduino pin numbers.  These areguments are
placed between the parenthesis next to the motor name, as shown in the
examples below.

Each motor object you create must be added to the list called 'motors.'
This is a C++ array that holds a reference to all of the motors that
the firmware is able to control.  Each motor must be listed once, the
name prefixed by an ampersand (&), and the list is separated by commas.
The order in which the motors are listed is the order in which port
numbers will be assigned; the first motor is port zero, the second is
port one, and so on.

These examples only show one motor in the list of motors, but up to
255 motor ports can be created and added, as long as your Arduino
board has enough memory to support them.


EXAMPLE: ARDUINO MOTOR SHIELD R3 - DC MOTORS

Here are several examples of motor object definitions.  The first is the
standard configuration for an Arduino Motor Shield R3, connected to one
or two normal DC motors.

Note that unused pins are typically disabled by setting their value to
(-1) or 0xFF.  In this example, the UP, DOWN and PORT SELECT LED lines
are disabled.  You can assign these functions to custom Arduino pins by
setting them here.

	//
	// EXAMPLE: Create a new DC motor port.
	//
	//
	MotorDC MOTOR1(
		3,      // PWM/ENABLE output pin - MUST be a PWM-capable pin
		12,     // DIRECTION output pin
		(-1),   // UP/IN1 output pin
		(-1),   // DOWN/IN2 output pin
		0,      // SENSE input A/D pin (0 = A0 pin)
		(-1),   // LED output pin
		9,      // BRAKE output pin
		true    // BRAKE PWM Enable (must be true or false)
	);

	//
	// EXAMPLE: Create a second DC motor port for the same shield.
	//
	MotorDC MOTOR2(
		11,     // PWM/ENABLE output pin - MUST be a PWM-capable pin
		13,     // DIRECTION output pin
		(-1),   // UP/IN1 output pin
		(-1),   // DOWN/IN2 output pin
		1,      // SENSE input A/D pin (1 = A1 pin)
		(-1),   // LED output pin
		8,      // BRAKE output pin
		true    // BRAKE PWM Enable (must be true or false)
	);

	//
	//  MOTOR LIST: each motor defined above must be listed here.
	//
	static IMotor * const motors[] = {
		& MOTOR1,
		& MOTOR2
	};


EXAMPLE: STEPPER MOTOR PORT - SIMPLE DUAL H-BRIDGE

This example defines a stepper motor object, connected to a dual H-bridge that
has four input pins.  Both H-bridge circuits use the IN1/IN2 configuration
for control of the motor windings.  This is typical of a two-phase stepper
connected to a circuit such as the L298N.  The IN* pins are tied to Arduino
pins 2, 3, 4, and 5.

	//
	// EXAMPLE: Create a stepper motor object, based on the AccelStepper library.
	//
	MotorAccel MOTOR1(
	    AccelStepper::FULL4WIRE,      // 4-wire controller (H-bridge)
	    2,                            // first control pin (Bridge 1, IN1)
	    3,                            // second control pin (Bridge 1, IN2)
	    4,                            // third control pin (Bridge 2, IN1)
	    5                             // fourth control pin (Bridge 2, IN2)
	);

	//
	//  MOTOR LIST: each motor defined above must be listed here.
	//
	static IMotor * const motors[] = {
		& MOTOR1
	};


EXAMPLE: STEPPER MOTOR PORT - DUAL H-BRIDGE WITH VARIABLE PWM SUPPORT

This example is like the previous one, but it adds a single PWM output that
can be used to limit the maximum voltage/current/effort of the motor windings.

This example has both bridges' ENABLE pins tied to pin 11, which pulses the
motor with a one duty cycle when running, and a lower duty cycle when the
motor is stopped.  Use care when using PWM with stepper motors - you must
select a PWM output that generates sufficient PWM frequency to prevent the
motor from stuttering as it runs.  On the UNO R3, pins 3 and 11 provide the
highest PWM output frequency by default.

Two objects are created here, the first is an ENABLE pin definition, and the
second is the motor object itself, which takes the ENABLE pin definition as
an argument.

PWM values are specified between 0 and 255 (0 and 0xFF hex).

	//
	// EXAMPLE: Create a stepper motor object, based on the AccelStepper library.
	//

	// first, create the ENABLE pin configuration object
	EnablePin enablePin(
		11,							// ENABLE/PWM pin
		true,						// ENABLE line is PWM
		0xB0,						// PWM value when running
		true,						// disable-on-stop flag
		0x80						// PWM value when stopped
	);

	// then create the actual motor object
	MotorAccel MOTOR1(
		AccelStepper::FULL4WIRE,	// 4-wire controller (H-bridge)
		2,							// first control pin
		3,							// second control pin
		4,							// third control pin
		5,							// fourth control pin
		400.0,						// maximum step speed (steps/sec)
		&enablePin,					// ENABLE pin definitions
		1,							// number of ENABLE pins
		0xFF						// DISABLE delay (msec)
	);

	//
	//  MOTOR LIST: each motor defined above must be listed here.
	//
	static IMotor * const motors[] = {
		& MOTOR1
	};


EXAMPLE: STEPPER MOTOR CONNECTED TO ARDUINO MOTOR SHIELD R3

This example motor object describes a bipolar stepper motor attached
to an Arduino Motor Shield R3.

Two objects are created here, the first is an array of ENABLE pin
definitions, and the second is the motor object itself, which takes the
ENABLE pin definitions as an argument.  There are four different ENABLE
pin definitions because the Motor Shield R3 has four different pins that
must be set to specific values in order for the shield to operate a
stepper motor.  Stepping is done with just the shield's DIR pins, but
the others must be properly configured to drive the motor.

This example is a bit complicated because of the way the Motor Shield R3
is wired.  The shield is designed to support normal DC motors, which is why
it has the DIRECTION/BRAKE logic, instead of the traditional IN1/IN2 inputs.
Using it with a stepper motor requires that we interact with in a specific
way.  Since the ENABLE lines are brought out directly, we can still use
these with PWM output, to control the maximum motor drive level.

	//
	// EXAMPLE: Create a stepper motor object, based on the AccelStepper library.
	//

	// first, define the ENABLE pins
	EnablePin enablePins [] = {
		EnablePin(	// PWM/ENABLE #1
			11,		// pin #
			true,	// line is PWM
			0xFF,	// PWM value when running
			true,	// disable-on-stop flag
			0x00	// PWM value when stopped
		),
		EnablePin(	// PWM/ENABLE #2
			3,		// pin #
			true,	// line is PWM
			0xFF,	// PWM value when running
			true,	// disable-on-stop flag
			0x00	// PWM value when stopped
		),
		EnablePin(	// BRAKE #1
			8,		// pin #
			false,	// line is GPIO
			LOW		// ENABLE value is LOW (brake disabled)
		),
		EnablePin(	// BRAKE #2
			9,		// pin #
			false,	// line is GPIO
			LOW		// ENABLE value is LOW (brake disabled)
		)
	};

	// then define the actual motor
	MotorAccel MOTOR1(
		AccelStepper::FULL2WIRE,	// 2-wire controller
		12,							// first control pin
		13,							// second control pin
		0xFF,						// unused pin #3
		0xFF,						// unused pin #4
		400.0,						// maximum step speed (steps/sec)
		enablePins,					// ENABLE pins
		4							// ENABLE pin count
	);

	//
	//  MOTOR LIST: each motor defined above must be listed here.
	//
	static IMotor * const motors[] = {
		& MOTOR1
	};


EXAMPLE: STEPPER MOTOR CONNECTED TO BIG EASY DRIVER

This example motor object assumes the setup described in the bildr.org
tutorial, which includes a BigEasy stepper driver board, with only the
DIRECTION and STEP pins connected to pins 2 and 3.

http://bildr.org/2012/11/big-easy-driver-arduino/

This is probably the simplest stepper motor configuration, because the
driver board provides the other logic required to drive the motor.

	//
	// EXAMPLE: Create a stepper motor object, based on the AccelStepper library.
	//
	MotorAccel MOTOR1(
		AccelStepper::DRIVER, // AccelStepper mode; use DRIVER for BigEasy
		3,                    // Arduino pin connected to BigEasy's STEP pin
		2                     // Arduino pin connected to BigEasy's DIR pin
	);

	//
	//  MOTOR LIST: each motor defined above must be listed here.
	//
	static IMotor * const motors[] = {
		& MOTOR1
	};


EXAMPLE: STEPPER MOTOR WITH BIG EASY DRIVER AND ENABLE LINE

This example creates a stepper motor object like the previous example, but
this one adds a single inverted ENABLE line, to control the ENA pin on the
BigEasyDriver.  This configuration will pull the ENA line HIGH about 250ms
after the motor stops, which will power down the motor windings to save power.

Note that the driver board requires a HIGH value on the ENA line to disable
the motor outputs.

	//
	// EXAMPLE: Create a stepper motor object, based on the AccelStepper library.
	//

	// first, create the ENABLE pin configuration object
	EnablePin enablePin(
		7,						// ENABLE/PWM pin, tied to driver's ENA pad
		false,					// ENABLE line is simple GPIO, *not* PWM
		LOW,					// ENABLE value, when motor running
		true,					// ENABLE line changes when motor stopped
		HIGH					// DISABLE value, when motor stopped
	);

	// now create the motor object
	MotorAccel MOTOR1(
		AccelStepper::DRIVER,	// AccelStepper mode; use DRIVER for BigEasy
		3,						// Arduino pin connected to BigEasy's STEP pin
		2,						// Arduino pin connected to BigEasy's DIR pin
		4,						// third control pin
		5,						// fourth control pin
		400.0,					// maximum step speed (steps/sec)
		&enablePin,				// enable pin array (just a single one here)
		1,						// number of enable pins
		0xFF					// DISABLE delay (msec)
	);

	//
	//  MOTOR LIST: each motor defined above must be listed here.
	//
	static IMotor * const motors[] = {
		& MOTOR1
	};

# END: README.txt
