SPARK MAX Client Application

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

Latest SPARK MAX Client - Version 2.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 64-bit
  • Windows 7 64-bit might work but it is not supported.

  Installation Instructions

  1. Download the SPARK MAX Client installer above.
  2. Run the installer. Windows may require approval to install the application.
  3. During the installation process, separate driver installation windows may appear. Some driver installations may fail if you already have the driver installed from a previously installed Client, this is expected.
  4. 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.

  

  Error During First-time Firmware Update

  If this is the first time installing the SPARK MAX Client or connecting a SPARK MAX in Recovery Mode, you may see an error the first time you try to update firmware on your computer. The DFU driver is one of two drivers installed by the Client and is used for updating firmware. It may not install completely until a SPARK MAX in DFU Mode (Recovery Mode) is plugged in to the computer.

  If you see an error during your first firmware update, please do the following:

  1. Close the Client application.
  2. Unplug the SPARK MAX from the computer.
  3. Plug the SPARK MAX back into the computer.
  4. Open the Client application.

  Alternatively, you can preemptively finalize the DFU driver installation by following the Recovery Mode steps before using the Client for the first time.

  We are aware of this issue and will be releasing a fix in a future update of the SPARK MAX Client.

  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.5.1

      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.5.1

      • Improvements to BLDC commutation timing.
        • Most noticeable at high RPMs only achievable by the NEO 550.

        Previous Firmware Change Log - Version 1.5.0

        • Version 1.5.0 Changes
          • Adds a unique hash key to the firmware. This key is a hashed value based on the unique 96-bit device ID guaranteed to be unique for every STM32 device. The hash value itself is 32-bits to make transmission/reception and on-board comparison easier. It is unlikely for a key collision especially since most buses have only a small number of devices.
          • Adds ID Query command to have all devices which match the CAN ID sent to return their unique hash key. This is typically used to identify all devices with CAN ID 0 but can be used to identify devices with conflicting CAN IDs.
          • Adds ID Assign command, which sends a unique hash key and a CAN ID, which is received by any device whose CAN ID matches the ID field. The device whose unique hash matches has their own CAN ID set to the desired value. This is for initial or automatic provisioning, or to re-address devices with the same CAN ID.
          • Adds identify command which flashes the LED blue/magenta. This command uses the CAN ID, or the unique hash if CAN overhaul of USB interface, creating a generic USB-to-CAN driver connection to act as the bridge to the interface.
          • Adds Alternate Encoder Mode for BLDC external encoder support.
          • Adds device manufacturing info to firmware frame.
          • Adds retry frame to CAN bootloader if there is an issue.
          • Fixes issue where creating a CANSparkMax object would cause the SensorType parameter to be set to NoSensor.

          Previous 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.
              • 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.
              • 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.

                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.
                  • 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.

                    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. The Client should automatically scan and connect to your SPARK MAX. If your SPARK MAX is running outdated firmware, you will be notified with a pop-up window like the one pictured below:

                    

                    Click Open Network Tab & Scan Bus and proceed to the next step.

                    If your SPARK MAX is running firmware older than 1.4.0, you may not see a pop-up and will need to proceed directly to the Network tab and click Scan Bus manually. If your SPARK MAX is listed and you are unable to click the checkbox next to it, you must put your SPARK MAX into Recovery Mode.

                    

                    Once in recovery mode, click Scan Bus in the Network tab and proceed on to the next step.

                    

                    

                    

                    

                    Updating Multiple Devices with the USB-to-CAN Bridge

                    SPARK MAX Firmware Version 1.5.0 includes a USB-to-CAN Bridge feature that allows a single USB-connected SPARK MAX to act as a bridge to the entire CAN bus it is connected to. This allows for configuration and simultaneous updating of multiple SPARK MAX controllers without having to connect to each one individually. Using this feature requires the following:

                    • A USB-connected SPARK MAX that is updated to firmware version 1.5.0 or newer to act as the Bridge.
                    • Other SPARK MAXs connected on the CAN bus must be individually updated to firmware version 1.4.0 before they are able to receive mass-updates from the Bridging SPARK MAX.

                    Once these requirements are satisfied, navigate to the Network tab, select the controllers you wish to update, and follow the same firmware update procedure described above starting at Step 4.

                    

                    When complete, the Client will display the number of successfully updated controllers.

                    

                    If a controller fails to update it is usually due to the process being interrupted by a bad power or CAN connection. Severe interruptions can cause the firmware update to be corrupted. A corrupted controller can no longer be updated over the USB-to-CAN Bridge, however, it can be recovered by connecting to the controller directly over USB and putting it in Recovery Mode.

                    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:

                    • Factory Image Version 1.1.33
                    • Factory Image Version 1.1.31
                    • Factory Image Version 1.0.385
                    • Factory Image Version 1.0.381

                    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.5.1
                    Java	1.5.1
                    C++	1.5.1

                    Latest API Change Log - Version 1.5.1 - LabVIEW

                    • Update to LabVIEW 2019 (FRC 2020)

                    Latest API Change Log - Version 1.5.1 - Java/C++

                    • Updated dependencies for WPILib 2020.1.2
                    • Removed extra thread for setpoint calls.
                      • Set calls now directly call CAN, reducing CAN latency.

                      Previous API Change Log - Version 1.5.0 - All Languages

                      • Adds the ability to use an alternate encoder as a feedback device when connected to the SPARK MAX Data Port. When using an alternate encoder, Hard Limit Switches cannot be used on that SPARK MAX.
                      • Adds the ability to send telemetry data back from a SPARK MAX. This is done by opening a Telemetry Stream for a particular subset of telemetry data (categorized by TelemetryIDs). A TelemetryMessage contains the ID, value, timestamp, name, units, and bounds of a particular TelemetryID. Additionally, users can list what subset of telemetry data is available for each SPARK MAX.
                      • Adds a DeviceScanner that will scan the CANBus for other CAN Devices. Will filter what devices to look for, and users can specify filters to let through different devices.
                      • Addresses bug with CANEncoder backwards compatibility.
                      • Addresses bug with the Java Control Frame Period not being properly set.

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

                      • Fixes issue in Java/C++ where creating a CANSparkMax object causes the Sensor Type parameter to be set to NoSensor. Desired behavior is to leave the existing setting.

                      Previous 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.
                          • 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.
                          • 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.

                            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()
                                • 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.5.1

                                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:

                                

                                

                                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:

                                Offline Installation

                                Latest Java API - Version 1.5.1

                                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:

                                • Online SPARK MAX Java Documentation
                                • Offline SPARK MAX Java Documentation (pdf)

                                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:

                                Offline Installation

                                Latest C++ API - Version 1.5.1

                                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:

                                • Online SPARK MAX C++ Documentation
                                • Offline SPARK MAX C++ Documentation (pdf)

                                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
                                  • 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
                                  • 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.