Table of Contents

Appendices

1. Configuration Parameters

1 - SPARK MAX Overview

The REV Robotics SPARK MAX Motor Controller is an all-in-one USB, CAN, and PWM enabled motor controller that can drive both 12 V brushed and 12 V brushless DC motors. SPARK MAX is designed for use in the FIRST Robotics Competition (FRC), incorporating advanced motor control in a small, easy-to-use, and affordable package. Configure and run the SPARK MAX through its built-in USB interface without needing a full control system.

1.1 - Feature Summary

• Brushed and sensored-brushless motor control
• PWM, CAN, and USB control interfaces
• PWM/CAN - Locking and keyed 4-pin JST-PH
• USB - USB type C
• USB configuration and control
• Rapid configuration with a PC
• Smart control modes
• Closed-loop velocity control
• Closed-loop position control
• Follower mode
• Encoder port
• Locking and keyed 6-pin JST-PH
• 3-phase hall-sensor encoder input
• Motor temperature sensor input
• Data port
• Limit switch input
• Quadrature encoder input with index
• Multi-function pin
• Mode button
• On-board motor type and idle behavior configuration
• RGB status LED
• Detailed mode and operation feedback
• Integrated power and motor wires
• 12 AWG ultra-flexible silicone wire
• Passive cooling

1.2 - Kit Contents

The following items are included with each SPARK MAX Motor Controller

• 1 - SPARK MAX Motor Controller
• 1 - USB-A male to USB-C cable
• 1 - 4-pin JST-PH to CAN cable
• 1 - 4-pin JST-PH to single PWM cable
• 1 - PWM/CAN cable retention clip
• 1 - Data port protection cap

1.3 - Specifications

The following tables provide the operating and mechanical specifications for the SPARK MAX motor controller.

2 - Feature Description

The REV Robotics SPARK MAX Motor Controller includes a range of features designed specifically for use on FIRST Robotics Competition robots. Each feature is described in detail throughout the following sections.

2.1 - Power and Motor Connections

SPARK MAX is designed to drive 12V brushed and brushless DC motors at currents up to 60A continuously. Power and motor connections are made through the two sets of wires built into the SPARK MAX. The wires are 12AWG ultra-flexible silicone-coated wire. Each wire runs approximately 15cm from the end faces of the controller. Be sure to take care when cutting and stripping the wires as not to cut them too short. The figure below shows these connections in detail.

2.1.1 - Motor Output

Motor output wires are labeled as A, B, and C with red, black, and white wires. Brushed motors must be connected to the A and B wires, while brushless motors must be connected to all three. It is critical that the order of the brushless motor wires match the SPARK MAX or the motor will not spin and could be damaged. Additional details are below in Table 2.1.

SPARK MAX cannot detect which motor type it is connected to. Be sure to configure the SPARK MAX to run the type of motor you have connected. See the Motor Type - Brushed/Brushless Mode section for more details on configuring the appropriate motor type.

2.1.2 - Power Input

Power input wires are labeled as V+ and V- with red and black wires. The SPARK MAX is intended to operate in a 12 V DC robot system, however it is compatible with any DC power source between 5.5 V and 24 V.

When using high current motors, it is recommended to use a power source that is capable of handling large surge currents, e.g. a 12V lead-acid battery. If the supply voltage drops below 5.5V the SPARK MAX will brown out, resulting in unexpected behavior. It is also highly recommended to incorporate a fuse or circuit-breaker in series with the SPARK MAX between it an the power source to prevent exceeding the maximum current rating.

2.2 - Control Connections

The SPARK MAX can be controlled by three different interfaces, servo-style PWM, controller area network (CAN), and USB. The following sections describe the physical connections to these interfaces in detail. For details on the operation and protocols of the PWM, CAN, and USB interfaces, please see the Section 3.3 - Control Interfaces.

2.2.1 - CAN/PWM Port

The CAN/PWM Port is located on the power input side of the SPARK MAX. This port can be connected to either a servo-style PWM signal or a CAN bus with other devices. Connector details can be found below.

Identical-function pins are electrically connected inside the SPARK MAX, therefore the CAN daisy-chain is completed internally and any two signal and ground pairs can be used for PWM. 

2.2.2 - USB-C Port

The USB-C Port is located on the power input side of the SPARK MAX. It supports USB 2.0 and 5V power for the SPARK MAX's internal microcontroller. While you can configure the SPARK MAX without main power, you will not be able to spin a motor.

2.3 - Encoder Port

Located on the motor output side of the SPARK MAX is a 6-pin Encoder Port. This port is designed to accept the built-in hall-encoder from the NEO Brushless Motor, but it can also connect to other external encoders when running in Brushed Mode. The connector details can be found below.

2.4 - Data Port

Located on the top of the SPARK MAX, the Data Port allows for extra sensor input and future feature development. The connector details can be found below.

2.4.1 - Limit Switch Inputs

SPARK MAX has two limit switch inputs that, when triggered, can independently prevent motion in both the forward and reverse directions. By default, when the pin for the corresponding direction is grounded, SPARK MAX will override any input commands for that direction and force the output into the neutral state. Input commands for the opposite direction will still be processed unless the corresponding limit signal is also triggered.

The default polarity is compatible with Normally Open (NO) style limit switches, who's contacts are shorted together when the switch is pressed. The Limit Switch Inputs can be configured for the opposite polarity using the USB or CAN interfaces. When configured for the opposite polarity, Normally Closed (NC), the limit will be triggered when the pin is left disconnected from ground. In other words, connecting the pin to ground will release the limit. The following table shows these configurations in detail:

REV Robotics will be releasing a selection of breakout boards and data cables that are compatible with the SPARK MAX Data Port. Stay tuned for updates.

2.4.2 - Quadrature Encoder Input

The Quadrature Encoder Input on the Data Port is compatible with standard quadrature encoder signals, usually labeled as channel A, channel B, and Index. SPARK MAX shares these signals with the Encoder Port on the output side of the controller, therefore the Index signal is shared with the third brushless encoder signal C. When in Brushless Mode, these Data Port pins cannot be used with an external encoder. See Alternate Encoder Mode for information on how to configure the SPARK MAX to accept an alternative encoder source when running in Brushless Mode.

When in Brushed Mode, an external encoder can be connected through either the Data Port or the Encoder Port.

The SPARK MAX encoder signals are not pulled high internally. This is to ensure the maximum compatibility with different types of encoders.

2.4.3 - Analog Input

The Analog Port on the SPARK MAX can measure voltages up to 3.3V with 12-bit resolution. The SPARK MAX Data Port Breakout (coming soon) includes a 5V to 3.3V amplifier circuit so that 5V signals can be sensed with the Analog Input pin.

Current SPARK MAX firmware does not support reading the Analog Input, but this feature will be rolled out soon. For more information, please take a look at our SPARK MAX Feature Roadmap.

2.4.4 - Multi-function Pin

Default behavior of this pin outputs an incremental encoder signal that is the one-wire interpretation of the 3-phase brushless hall-sensors when in brushless mode. This pin is reconfigured when the SPARK MAX is configured in Alternate Encoder Mode.

2.4.5 - Power Rails

The SPARK MAX Data Port can provide both 3.3V and 5V power to connected devices. Please check Table 1.3 - Data Port Specifications for details on the supply current capabilities of both rails.

3 - Operating Modes

SPARK MAX can be configured to control both brushed and brushless DC motors with several different smart features designed to provide the best control with as little effort as possible. The following sections describe each operating mode in detail. Please check back occasionally as we add additional details and new features to these sections.

3.1 - Motor Type - Brushed/Brushless Mode

Brushed and brushless DC motors require different motor control schemes based on the differences in their technology. It is possible to damage the SPARK MAX, the motor, or both if the appropriate motor type isn't configured properly. At the moment, the NEO Brushless Motor is the only brushless motor compatible with the SPARK MAX, so choosing the correct operating mode should be straightforward.

Brushed or brushless motor types can be configured using the Mode Button, CAN, and USB interfaces.

3.1.1 - Configuration with Mode Button

Follow the steps below to switch motor types with the Mode Button. It is recommended that the motor be left disconnected until the correct mode is selected.

1. Connect the SPARK MAX to main power, not just USB Power.
2. The Status LED will indicate which motor type is configured by blinking yellow or blue for Brushed Mode, or blinking magenta or cyan for Brushless Mode.
   
   Please see the Status LED Colors and Patterns in the SPARK MAX Quick Start Guide for more details on the Brushed and Brushless Mode colors.
   
   
3. Press and hold the Mode Button for approximately 3 seconds.
   
   Use a small screwdriver, straightened paper clip, pen, or other small implement to press the button. Do not use any type of pencil as the pencil lead can break off inside the SPARK MAX.
   
   
4. After the button has been held for enough time, the Status LED will change and indicate the different motor type.
5. Release the mode button.

3.1.2 - Configuration with USB

Follow the steps below to switch motor types with the USB and the SPARK MAX Client application. Be sure to download and install the SPARK MAX Client application from the SPARK MAX Software Resources page before continuing.

1. Connect the SPARK MAX to your computer using a USB-C cable.
2. Open the SPARK MAX Client application and verify that the application is connected to your SPARK MAX.
3. On the Basic tab, select the appropriate motor type under the Select Motor Type menu.
4. Click Update Configuration and confirm the change.

3.1.3 - Configuration with CAN

Please see the API Information on the SPARK MAX Software Resources page for information on how to configure the SPARK MAX using the CAN interface. 

3.2 - Idle Mode - Brake/Coast Mode

When the SPARK MAX is receiving a neutral command the idle behavior of the motor can be handled in two different ways: Braking or Coasting.

When in Brake Mode, the SPARK MAX will effectively short all motor wires together. This quickly dissipates any electrical energy within the motor and brings it to a quick stop.

When in Coast Mode, the Spark MAX will effectively disconnect all motor wires. This allows the motor to spin down at its own rate.

The Idle Mode can be configured using the Mode Button, CAN, and USB interfaces.

3.2.1 - Configuration with Mode Button

Follow the steps below to switch the Idle Mode between Brake and Coast with the Mode Button.

1. Connect the SPARK MAX to main power, not just USB Power.
2. The Status LED will indicate which Idle Mode is currently configured by blinking blue or cyan for Brake and yellow or magenta for Coast depending on the motor type.
   
   Please see the Status LED Colors and Patterns in the SPARK MAX Quick Start Guide for more details on the Brushed and Brushless Mode colors.
   
   
3. Press and release the Mode Button
   
   Use a small screwdriver, straightened paper clip, pen, or other small implement to press the button. Do not use any type of pencil as the pencil lead can break off inside the SPARK MAX.
   
   
4. You should see the Status LED change to indicate the selected Idle Mode.

3.2.2 - Configuration with USB

Follow the steps below to switch the Idle Mode between Brake and Coast with the USB and the SPARK MAX Client application. Be sure to download and install the SPARK MAX Client application from the SPARK MAX Software Resources page before continuing.

1. Connect the SPARK MAX to your computer using a USB-C cable.
2. Open the SPARK MAX Client application and verify that the application is connected to your SPARK MAX.
3. On the Basic tab, select the desired mode with the Idle Mode switch.
4. Click Update Configuration and confirm the change.

3.2.3 - Configuration with CAN

Please see the API Information on the SPARK MAX Software Resources page for information on how to configure the SPARK MAX using the CAN interface. 

3.3 - Control Interfaces

The SPARK MAX can be controlled by three different interfaces, servo-style PWM, controller area network (CAN), and USB. The following sections describe the operation and protocols of these interfaces. For more details on the physical connections, see Section 2.2 - Control Connections. 

3.3.1 - PWM Interface

The SPARK MAX can accept a standard servo-style PWM signal as a control for the output duty cycle. Even though the PWM port is shared with the CAN port, SPARK MAX will automatically detect the incoming signal type and respond accordingly. For details on how to connect a PWM cable to the SPARK MAX, see Section 2.2.1 - CAN/PWM Port.

The SPARK MAX responds to a factory default pulse range of 1000µs to 2000µs. These pulses correspond to full-reverse and full-forward rotation, respectively, with 1500µs (±5% default input deadband) as the neutral position, i.e. no rotation. The input deadband is configurable with the SPARK MAX Client Application or the CAN interface. The table below describes how the default pulse range maps to the output behavior.

If a valid signal isn't received within a 60ms window, the SPARK MAX will disable the motor output and either brake or coast the motor depending on the configured Idle Mode. For details on the Idle Mode, see Section 3.2 - Idle Mode - Brake/Coast Mode.

3.3.2 - CAN Interface

The SPARK MAX can be connected to a robot CAN network. CAN is a bi-directional communications bus that enables advanced features within the SPARK MAX. SPARK MAX must be connected to a CAN network that has the appropriate termination resistors at both endpoints. Please see the FIRST Robotics Competition Robot Rules for the CAN bus wiring requirements. Even though the CAN port is shared with the PWM port, SPARK MAX will automatically detect the incoming signal type and respond accordingly. SPARK MAX uses standard CAN frames with an extended ID (29 bits), and utilizes the FRC CAN protocol for defining the bits of the extended ID:

Each device on the CAN bus must be assigned a unique CAN ID number. Out of the box, SPARK MAX is assigned a device ID of 0. It is highly recommended to change all SPARK MAX CAN IDs from 0 to any unused ID from 1 to 62. CAN IDs can be changed by connecting the SPARK MAX to a Windows computer and using the SPARK MAX Client Application. For details on other SPARK MAX configuration parameters, see Appendix A - Configuration Parameters.

Additional information about the CAN accessible features and how to access them can be found in the SPARK MAX API Information section of the SPARK MAX Software Resources page.

3.3.2.1 - Periodic Status Frames

The SPARK MAX sends data periodically back to the roboRIO. Frequently accessed data, like motor position and temperature, can be accessed using several APIs. Data is broken up into several CAN "frames" which are sent at a periodic rate. This rate can be changed manually in code, but unlike other parameters, this setting does not persist through a power cycle. The rate can be set anywhere from a minimum 1ms to a maximum 65535ms period. The table below describes each status frame and its available data.

Use-case Examples

Position Control on the roboRIO

A user wants to implement their own PID loop on the roboRIO to hold a position. They want to run this loop at 100Hz (every 10ms), but the motor position data in Periodic Status 2 is sent at 20Hz (every 50ms).

The user can change this rate to 10ms by calling:

setPeriodicFrameRate(PeriodicFrame.kStatus2, 10);

High CAN Utilization

A user has many connected CAN devices and wishes to minimize the CAN bus utilization. They do not need any telemetry feedback, and have several follower devices that are only checked for faults.

The user can set the telemetry frame rates low, and set the Periodic Status 0 frame rate low on the follower devices:

leader.setPeriodicFrameRate(PeriodicFrame.kStatus1, 500);
leader.setPeriodicFrameRate(PeriodicFrame.kStatus2, 500);
follower.setPeriodicFrameRate(PeriodicFrame.kStatus0, 100);
follower.setPeriodicFrameRate(PeriodicFrame.kStatus1, 500);
follower.setPeriodicFrameRate(PeriodicFrame.kStatus2, 500);

Faster Follower Bandwidth

The user wants the follower devices to update at a faster rate: 200Hz (every 5ms).

The Periodic Status 0 frame can be increased to achieve this.

leader.setPeriodicFrameRate(PeriodicFrame.kStatus0, 5);

3.3.3 - USB Interface

The SPARK MAX can be configured and controlled through a USB connection to a computer running the SPARK MAX Client Application. The USB interface utilizes a standard CDC (USB to Serial) driver. The command interface is similar to CAN, using the same ID and data structure, but always sends and receives a full 12-byte packet. The CAN ID is omitted (DNC) whn talking directly to the device. However, the three MSB of the ID allow selection of alternate commands:

• 0b000 - Standard command - CAN ID omitted (DNC)
• 0b001 - Extended command - USB specific

All commands sent over USB receive a response. In the case that the corresponding CAN command does not receive a response, the USB interface receives an Ack command.

3.4 - Closed-loop Control

SPARK MAX can operate in several closed-loop control modes, using sensor input to tightly control the motor velocity or position. The internal control loop follows a standard PID algorithm with a feed-forward (F) term to compensate for known system offsets. Below is a diagram and the firmware implementation of the internal SPARK MAX PIDF.

//Synchronous PID, call at desired frequency
float pid_run(pid_instance_t* pid, float setpoint, float pv,
        const pid_constants_t* constants)
{
    float error = setpoint - pv;

    float p = error * constants->kP;

    if(fabsf(error) <= constants->iZone || constants->iZone == 0.0f) {
        pid->iState = pid->iState + (error * constants->kI);
    } else {
        pid->iState = 0;
    }

    float d = (error - pid->prev_err);
    pid->prev_err = error;
    d *= constants->kD;

    float f = setpoint * constants->kF;

    float output = p + pid->iState + d + f;
    pid->output = fminf(fmaxf(output,constants->kMinOutput),constants->kMaxOutput);

    return output;
}

For more information on utilizing the built-in closed-loop control modes, please take a look at our SPARK MAX Code Examples.

3.5 - Recovery Mode

When updating the firmware on the SPARK MAX, it is possible for the process to be interrupted or for the firmware to be corrupted by a bad download. In this state, the Status LED will be dark and the SPARK MAX will fail to operate. SPARK MAX has a built-in recovery mode that can force it to accept new firmware even if the controller seems to be bricked. The following procedure requires a small tool, like a straightened paper clip, to press the Mode Button, a USB C cable, and a computer with the SPARK MAX Client Application installed:

1. With the SPARK MAX powered off completely, press and hold the Mode Button.
2. While still holding the Mode Button, connect the SPARK MAX to the computer using the USB cable. The Status LED will not illuminate, this is expected.
3. Wait a few seconds for the computer to recognize the connected device, then release the Mode Button.
4. Open the SPARK MAX Client Application. The SPARK MAX will remain dark and it will not connect to the Client, this is expected.
5. Navigate to the Network tab and click Scan Bus.
6. The SPARK MAX will be listed under Devices in Recovery Mode. Click the checkbox next to the device.
7. Click the Load Firmware button.
8. Select the latest firmware file and click Open.
9. The firmware should load successfully and the SPARK MAX will now connect to the Client.

3.6 - Alternate Encoder Mode

The SPARK MAX can be configured to run in Alternate Encoder Mode, which reconfigures the Data Port on the top of the controller to accept an alternative encoder, separate from the default encoder inputs shared between the front Encoder Port and the default quadrature encoder Data Port pins.

This feature is designed for use in low-RPM mechanisms such as drivetrains, arms, and other manipulators. For high RPM applications it is recommended to use the built-in motor sensor for brushless motors or the default encoder inputs for brushed motors. 

When configured for Alternate Encoder Mode, a quadrature encoder connected to the reconfigured Data Port pins can be used as a feedback device by the SPARK MAX. Please note, the limit switch inputs cannot be used at the same time as an alternate encoder. The limit switch pins are repurposed for the alternate encoder and are thus disabled. Please see 3.6.1 - Connecting an Alternate Encoder for for more information.

3.6.1 - Connecting an Alternate Encoder

Connecting an alternate encoder will likely require a custom wiring harness to connect the necessary encoder power, ground, and signals to the reconfigured Data Port. When configured in Alternate Encoder Mode, the Data Port has the following pinout:

The SPARK MAX Data Port Breakout Board can be used to wire an alternate encoder to the Data Port. The following table describes which pads on the breakout should be used for which signals coming from the alternate encoder. 

3.6.2 - Configuring and Using the Alternate Encoder Mode

Below you will find the steps required to set up and use the Alternate Encoder Mode on the SPARK MAX, starting with configuration through either the SPARK MAX Client or the SPARK MAX APIs.

3.6.2.1 - Configuration Using the SPARK MAX Client

Using the SPARK MAX Client, navigate to the Advanced Tab and scroll to the Alternate Encoder parameter section. Enable the alternate encoder by setting the kDataPortConfig parameter to '1'. You can also set the other Alternate Encoder parameters at this time.

3.6.2.2 - Configuring Using the SPARK MAX APIs

If using the SPARK MAX APIs, the Alternate Encoder is automatically configured when the Alternate Encoder object is instantiated. An Alternate Encoder is created the same as a CANEncoder, either by directly using the constructor or calling GetALternateEncoder() on a previously constructed CANSparkMax.

Currently, quadrature it eh only available type of configuration for an alternate encoder. This is differentiated from the other types of encoder configurations available for an encoder connected through the front facing Encoder Port on the SPARK MAX.

3.6.2.3 - Configuration Conflicts

Since the elternate encoder inputs and the default digital inputs are shared on the Data Port, the user cannot use both the alternate encoder and a digital inputs in code. Therefore, a std::invalid_argument (C++), IllegalArgumentException (Java), or an Error on the Error Out terminal (LabVIEW) will be thrown if a user tries to construct both types objects in code simultaneously.

3.6.2.4 - Closed-Loop Control

The alternate encoder can be used with the different closed-loop control modes available on the SPARK MAX. The feedback device used by a CANPIDController must be set to use the alternate encoder through SetFeedbackDevice().

3.6.2.5 - Initial Bring-up

Unlike the built-in sensor on the NEO Brushless motors, the 'phase' of the alternate encoder is unknown to the SPARK MAX. Before enabling any closed-loop control, it is critical that the phase is configured correctly. To verify:

1. Configure and connect the sensor as a quadrature alternate encoder, but do not run a closed-loop mode.
2. Plot the output signal of the motor using GetAppliedOutput() and the output of the encoder using altEncoder.GetVelocity(). Confirm that the sensor is behaving as expected. This can be done on the SmartDashboard:
   
3. Verify that the sign of the sensor is correct relative to the motor direction when driving it forward and backward. If it is not, the sensor must be inverted by calling altEncoder.SetInverted(true).

Appendix A - Configuration Parameters

Below is a list of all the configurable parameters within the SPARK MAX. Parameters can be set through the CAN or USB interfaces. The parameters are saved in a different region of memory from the device firmware and persist through a firmware update.