SPARK MAX Software Resources

All of the software resources for the SPARK MAX can be found below.

Table of Contents


SPARK MAX Client Application

Update, configure, and test your SPARK MAX Motor Controller with the SPARK MAX Client application.

Latest SPARK MAX Client - Version 1.0.0

The SPARK MAX Client will not work with SPARK MAX beta units distributed by REV to the SPARK MAX beta testers. It is only compatible with units received after 12/21/2018.

System Requirements

  • Windows 10 recommended
  • Internet connection for automatic updates

Installation Instructions

  1. Download the SPARK MAX Client installer above.
  2. Run the installer. Windows may require approval to install the application.
  3. Once installed, run the application. If prompted, be sure to grant network access. Without network access, the client software won't be able to download the latest SPARK MAX firmware and client updates.

    windowsfirewall.png

Drivers

The SPARK MAX uses two sets of drivers to operate: one for normal operation and one for updating firmware/recovering a bricked device. The device firmware update (DFU) drivers can be downloaded and installed separately here if you are having trouble updating your SPARK MAX firmware:

Troubleshooting

As we get feedback from users and identify exact causes for issues, please look back here for troubleshooting help. If you are running into issues running the SPARK MAX Client try the following BEFORE contacting support@revrobotics.com:

  • Try running the SPARK MAX Client as an Administrator
  • Make sure that Windows is fully up-to-date. Some computers have Windows Update disabled and need to be updated manually.
  • Check the Device Manager and verify that the SPARK MAX shows up as one of the following two devices with no caution symbols:
    • Normal operating mode: Device Manager -> Ports (COM & LPT) -> USB Serial Device (COMx)
    • Recovery mode: Device Manager -> Universal Serial Bus Controllers -> STM Device in DFU Mode
      • If the device shows up with errors or as STM32 BOOTLOADER, try installing the DFU drivers separately.

 


SPARK MAX Firmware Updates

It is recommended to keep your SPARK MAX up-to-date with the latest firmware. The SPARK MAX Client application will automatically download the latest firmware, but you can also download the firmware manually below:

Latest Firmware - Version 1.4.0

MD5: cb55fafff7fa057cc118dabe9d204ec0

This firmware will not work with SPARK MAX beta hardware units distributed by REV to the SPARK MAX Beta testers. It is only compatible with units received after 12/20/2018.

Latest Firmware Change Log - Version 1.4.0

  • Version 1.4.0 Changes
    • Adds non-competition heartbeat command when not used with a roboRIO.
    • Adds Raspbian support using official WPILib tools.
    • Adds locking mechanism to prevent simultaneous USB and CAN commands.
    • Proportional blink codes now match inversion settings (i.e. positive input is always green, and negative input is always red).
    • Limit switch and soft limits now follow inversion settings.
    • Motor controller inversion now in the firmware instead of the API.
    • Adds a configurable range for absolute feedback devices (currently only applicable to an absolute mode analog sensor), which also prevents users from setting a setpoint out of range.
    • Adds ability to use both absolute and relative analog sensors as feedback devices
    • Adds filtering for Analog sensor with settings for velocity moving average filter
    • Adds ability to configure how errors are tracked and handled by the user.
      • Calls can be automatically registered and tracked, with any errors displayed to the DriverStation or users can use the GetLastError() after calls to determine if an error has been thrown. This is done by changing the error timeout through SetCANTimeout(), where a timeout of 0 means that the calls are non-blocking, and errors are checked in a separate thread and sent through to the driver station.
    • Other minor improvements and bug fixes.
  • Version 1.3.0 Changes
    • Ability to configure the feedback device for the PIDController.
    • Addition of CANAnalog which will function as a possible feedback device.
    • Added API for using encoders with brushed DC motors.
    • Adds API to enable and set soft limits.
    • All control modes now reset integrator on limit switch activation for long as the limit switch is held.
    • Smart Motion now honors acceleration rate after limit switch changes from triggered to not triggered.
    • Fixes issue where sticky faults can be cleared incorrectly when a new fault is set and the old fault is no longer present.
    • Adds status 3 periodic frame for analog sensor.
    • Other minor improvements and bug fixes.
  • Version 1.2.1 Changes
    • Adds initial CAN bootloading functionality.
      • Requires continuous power during update and requires USB recovery if the update fails after erasing the flash (i.e. power is lost during update).
      • This is not yet integrated into a formal tool, but is exposed in the API. Future versions will allow recovery over CAN.
    • Fix to bus voltage measurement, previous version reported a lower value.
    • Additional accuracy improvements to all ADC measurements.
    • Adds additional filtering to bus voltage.
    • Fix for Follow settings not being reapplied after power cycle.
    • Adds ability to change units for arbFF between voltage and percent bus voltage (or percent compensated voltage).

Previous Firmware Change Log - Version 1.1.33

  • Fixes issue that causes a Gate Driver Fault if the NEO is spinning at a certain speed during power up.
    • e.g. while still moving after a breaker trips for more than ~1.4s after breaker recovery.
  • Fixes issue where configuration data can be corrupted under a unique set of conditions, including loss of power while configuration settings are being saved to flash memory.
    • Issue symptoms: Controller cannot be controlled by a normal address and would report a firmware version of 0.0.0 in the Client, even after a successful firmware update. Updating a controller that is in this state to 1.1.33 will recover the controller.

Previous Firmware Change Log - Version 1.1.31

  • Adds new Smart Velocity mode - uses same constrains as the Smart Motion mode but outputs velocity instead of position. This is not a motion profiling mode, but rather provides acceleration limiting as opposed to simple ramp rates.
  • Improvements to heartbeat implementation.
  • CAN ID of 0 now considered 'unconfigured' and will not be enabled.
  • Changes the default output range for all PID slots to be [-1,1] instead of [0,0]
  • Changes setpoint commands to 'stick' instead of relying on periodic frames from the controller.
  • Follow mode can now persists through a power-cycle.
  • Periodic Status 2 (position data) frame rate default changed from 50ms to 20ms.
  • Watchdog changed to 220ms.
  • Proportional blink codes while driving now have a minimum blink rate (minimum is same as 10% applied output blink rate).
  • Fault flag 'over voltage' replaced with 'IWDT Reset'.
  • Velocity and Position conversion factors are now used for all internal PID calculations.

This firmware update requires an API update. Please see the API Information section for the latest updates. The table below outlines the compatibility between firmware versions and API versions:

  API
LabVIEW - 1.0.0-26
Java - 1.0.28
C++ - 1.0.27
LabVIEW - 1.1.8
Java - 1.1.8 (or newer)
C++ - 1.1.8 (or newer)
Firmware 1.1.26 (or newer) Not Compatible Compatible
1.0.385 (or older) Compatible Not Compatible

 

Previous Firmware Change Log - Version 1.1.26 (beta)

  • Adds new Smart Motion mode utilizing trapezoidal motion profiling
  • Improvements to velocity decoding for low speeds and associated PID control loops requiring control at low speeds
  • Improvements to gate driver fault handling
  • Adds voltage compensation mode
  • Adds ability to set the stored sensor position
  • Adds ability to set the maximum PID integral accumulator value to prevent integral windup
  • Adds ability to set the PID I accumulator value
  • Adds filter function to PID derivative value
  • Adds closed-loop current control
  • Adds closed-loop ramp rate separate from open-loop
  • Adds ability to follow Phoenix 4.11 motor controllers
    • Note: This feature depends on the firmware of the Phoenix controllers, and is not controlled by REV. We will do our best to build this functionality, but this is not an officially supported feature.
  • Adds ability to set a unit conversion for both velocity and position units
  • Adds ability to reset to factory defaults
  • Improvements to smart current limits
  • Improvements to current data sent over CAN
  • Improvements to internal settings table implementation
  • Calling the constructor no longer resets the encoder count. This must be done manually by running CANEncoder.setPosition()

Previous Firmware Change Log - Version 1.0.385

  • Fixes PWM control issue introduced by version 1.0.384.

Previous Firmware Change Log - Version 1.0.384

  • Fixes GetPostition() randomly returning 0.
  • Fixes momentary velocity spike when accelerating from 0 speed.
  • Fixes issue related to rapid control mode switching by the user.
  • Fixes issue related to extreme low voltage CAN bus operation.
  • Adds conversion for motor temperature.
  • Improvement to "Has Reset" flag.
  • Improvements to brownout fault indicator.
  • Improvements to brownout behavior.

Firmware Update Instructions

Follow the steps below to update the firmware on your SPARK MAX:

  1. Connect your SPARK MAX Motor Controller to your computer with a USB C cable.
  2. Open the REV SPARK MAX Client application.
  3. If your SPARK MAX is running outdated firmware, you will be notified with a pop-up window like the one pictured below:

    Outdated Firmware Warning

  4. Click OK and then navigate to the Firmware tab. The client application should display the current firmware version on the screen:

    firmwaretab.png

  5. Click Load Firmware and select the latest firmware file in the firmware directory that the client created on startup. If there isn't a firmware directory, you can also navigate to a file that was downloaded manually. Click Open once the appropriate firmware file is selected:

    firmwarefileselection.png

  6. If this is the first time updating firmware on your SPARK MAX, there will be additional instructions to follow in the grey window before the firmware can be updated (pictured below). Otherwise, the firmware will download and verify automatically.

    recoveryupdate.png

  7. Once completed, the new firmware version number will be displayed under Current Firmware:

    firstfirmwareupdatecomplete.png

Factory Images

When updating the SPARK MAX Firmware we recommend using the SPARK MAX Client and the latest firmware file listed above. When updating normally, key configuration parameters, such as the CAN ID, will be preserved through an update, preventing the need to reconfigure every time you update. In some rare instances it may be beneficial to completely reinstall the factory firmware and reset all configuration parameters. Factory images can be found below:


API Information

Below you will find information on how to download and install the SPARK MAX APIs for LabVIEW, Java, and C++.

Current API version by Language
LabVIEW 1.4.0
Java 1.4.0
C++ 1.4.0

 

Latest API Change Log - Version 1.4.0 - All Languages

  • Version 1.4.0 Changes
    • Adds non-competition heartbeat command when not used with a roboRIO.
    • Adds Raspbian support using official WPILib tools.
    • Adds locking mechanism to prevent simultaneous USB and CAN commands.
    • Motor controller inversion now in the firmware instead of the API.
    • Adds a configurable range for absolute feedback devices (currently only applicable to an absolute mode analog sensor), which also prevents users from setting a setpoint out of range.
    • Adds ability to use both absolute and relative analog sensors as feedback devices
    • Adds filtering for Analog sensor with settings for velocity moving average filter
    • Adds ability to configure how errors are tracked and handled by the user.
      • Calls can be automatically registered and tracked, with any errors displayed to the DriverStation or users can use the GetLastError() after calls to determine if an error has been thrown. This is done by changing the error timeout through SetCANTimeout(), where a timeout of 0 means that the calls are non-blocking, and errors are checked in a separate thread and sent through to the driver station.
    • Other minor improvements and bug fixes.
  • Version 1.3.0 Changes
    • Ability to configure the feedback device for the PIDController.
    • Addition of CANAnalog which will function as a possible feedback device.
    • Added API for using encoders with brushed DC motors.
    • Vendor dependencies now allows building Windowsx86-64 based build target.
    • Moves entire implementation to C level, C++ and Java libraries are now simple wrappers.
    • Adds API to enable and set soft limits.
    • Fixes possible driver set out of bounds if given a CAN ID less than 0.
    • CANSparkMaxLowLevel::SetEncPosition() and CANSparkMaxLowLevel::SetIAccum() have been moved to protected and should be accessed via their respective objects: CANEncoder.SetEncoderPosition() and CANPIDController::SetIAccum().
    • CANSparkMaxLowLevel::SetParameter* and GetParameter* are changed to private.
    • Adds status 3 periodic frame for analog sensor.
    • Other minor improvements and bug fixes.
  • Version 1.2.1 Changes
    • Adds initial CAN bootloading functionality.
      • Requires continuous power during update and requires USB recovery if the update fails after erasing the flash (i.e. power is lost during update).
      • This is not yet integrated into a formal tool, but is exposed in the API. Future versions will allow recovery over CAN.
    • Adds ability to change units for arbFF between voltage and percent bus voltage (or percent compensated voltage).
    • API adds check if its own version is too old based on major and minor revision numbers.
    • Adds version number of API.

Previous API Change Log - Version 1.1.9 - LabVIEW

  • Fixes potential hang in Follow.vi in the case that an error is on the input terminal. Java/C++ unaffected.

Previous API Change Log - Version 1.1.9 - Java/C++ Only

  • Fixes loop overrun issues in Java/C++. LabVIEW unaffected.

Previous API Change Log - Version 1.1.8 - All Languages

  • Adds Smart Velocity Mode
  • Fixes inversion issues for IMaxAccum and Output Range
  • Updates heartbeat implementation
  • Adds default slotID for setDFilter() functions
  • Update heartbeat rate from 50ms to 25ms
  • Changes fault flag for Overvoltage to IWDTReset

This API update also requires a firmware update. Please see the SPARK MAX Firmware Updates section for the latest updates. The table below outlines the compatibility between firmware versions and API versions:

  API
LabVIEW - 1.0.26
Java - 1.0.28
C++ - 1.0.27
LabVIEW - 1.1.8 (or newer)
Java - 1.1.8 (or newer)
C++ - 1.1.8 (or newer)
Firmware 1.1.26 (or newer) Not Compatible Compatible
1.0.385 (or older) Compatible Not Compatible

Previous API Change Log - Version 1.1.5 (beta) - Java/C++ - Version 1.1.4 (beta) - LabVIEW

  • Version 1.1.5
    • Adds method to stop any REV periodic frames before enabling heartbeat
    • Improvements to heartbeat protocol
    • Moved all heartbeat implementation into its own dependency called by C++ and Java through JNI
    • Removed setControlFrameRate() call and removed repeating packets
      • Updates to control frames are now as fast/slow as the user calls Set() or SetReference()
    • Updates to doxygen/javadocs comments
    • Maven artifacts now include source for both Java and C++
  • Version 1.1.3
    • Improvements to setInverted()
    • New API calls for new firmware features
    • Better error message in Java when CAN is not connected
    • Documentation updates are in progress.

LabVIEW API

Latest LabVIEW API - Version 1.4.0

LabVIEW API Installation Instructions

  1. Download the latest API package from the download link above.
  2. Make sure LabVIEW for FRC 2019 is installed and updated.
  3. Open the REV SPARK MAX LabVIEW Package. The NI Package Manager should automatically open.
  4. Click Next:

    nipackagemanager.png

  5. Once the installation is complete, you will be able to access the REV SPARK MAX VIs in the LabVIEW Functions Pallet -> WPI Robotics Library -> Third Party -> REV Robotics -> SPARK MAX.

    sparkmaxpallet.png

Java API

Java API Installation Instructions

Online Installation

You can use the online method to install the REV Robotics Java API if your development machine is connected to the internet:

  1. Open your robot project in VSCode.
  2. Click on the WPI icon in the corner to open the WPI Command Pallet.
  3. Select Manage Vendor Libraries.
  4. Select Install new library (online).
  5. Enter the following installation URL and press ENTER:

    https://www.revrobotics.com/content/sw/max/sdk/REVRobotics.json

Offline Installation

Latest Java API - Version 1.4.0

  1. Download and unzip the latest SPARK MAX Java API into the C:\Users\Public\frc2019\ directory.
  2. Follow the Adding an offline-installed Library instructions from WPI.

Java API Documentation

For a list and description of all classes:

C++ API

C++ API Installation Instructions

Online Installation

You can use the online method to install the REV Robotics C++ API if your development machine is connected to the internet:

  1. Open your robot project in VSCode.
  2. Click on the WPI icon in the corner to open the WPI Command Pallet.
  3. Select Manage Vendor Libraries.
  4. Select Install new library (online).
  5. Enter the following installation URL and press ENTER:

    https://www.revrobotics.com/content/sw/max/sdk/REVRobotics.json

Offline Installation

Latest C++ API - Version 1.4.0

  1. Download and unzip the latest SPARK MAX C++ API into the C:\Users\Public\frc2019\ directory.
  2. Follow the Adding an offline-installed Library instructions from WPI.

C++ API Documentation

For a list and description of all classes:


SPARK MAX Code Examples

At the link below you will find code examples in LabVIEW, Java, and C++ for common SPARK MAX control modes. We will be adding examples as we develop them, so please check back regularly. Examples included as of 2/6/19:

  • LabVIEW
    • Arcade Drive with CAN
    • Arcade Drive with PWM
    • Get and Set Parameters
    • Limit Switch
    • Position Closed-loop Control
    • Reading Encoder Values
    • Smart Motion Example
    • Velocity Closed-loop Control
  • Java
    • Get and Set Parameters
    • Limit Switch
    • Motor Follower
    • Position Closed-loop Control
    • Reading Encoder Values
    • Smart Motion Example
    • Tank Drive with CAN
    • Velocity Closed-loop Control
  • C++
    • Arcade Drive with CAN
    • Arcade Drive with PWM
    • Get and Set Parameters
    • Limit Switch
    • Position Closed-loop Control
    • Reading Encoder Values
    • Smart Motion Example
    • Velocity Closed-loop Control

Even though some examples may only exist in a particular language, they can be a good place to start as the APIs are very similar between languages.

Special Thanks

We appreciate the assistance from the community for feedback, contributing, and testing these new features, especially Team 195 The CyberKnights.