001/* Copyright (C) Cross The Road Electronics 2024 */ 002package com.ctre.phoenix.motorcontrol; 003 004import com.ctre.phoenix.ErrorCode; 005import com.ctre.phoenix.ParamEnum; 006import com.ctre.phoenix.motion.MotionProfileStatus; 007import com.ctre.phoenix.motion.TrajectoryPoint; 008import com.ctre.phoenix.motorcontrol.can.BaseTalon; 009 010/** 011 * Interface for motor controllers 012 */ 013public interface IMotorController 014 extends com.ctre.phoenix.signals.IOutputSignal, com.ctre.phoenix.signals.IInvertable, IFollower { 015 // ------ Set output routines. ----------// 016 /** 017 * Sets the appropriate output on the talon, depending on the mode. 018 * @param Mode The output mode to apply. 019 * In PercentOutput, the output is between -1.0 and 1.0, with 0.0 as stopped. 020 * In Current mode, output value is in amperes. 021 * In Velocity mode, output value is in position change / 100ms. 022 * In Position mode, output value is in encoder ticks or an analog value, 023 * depending on the sensor. 024 * In Follower mode, the output value is the integer device ID of the talon to 025 * duplicate. 026 * 027 * @param demand The setpoint value, as described above. 028 * 029 * 030 * Standard Driving Example: 031 * _talonLeft.set(ControlMode.PercentOutput, leftJoy); 032 * _talonRght.set(ControlMode.PercentOutput, rghtJoy); 033 */ 034 public void set(ControlMode Mode, double demand); 035 036 /** 037 * @param Mode Sets the appropriate output on the talon, depending on the mode. 038 * @param demand0 The output value to apply. 039 * such as advanced feed forward and/or auxiliary close-looping in firmware. 040 * In PercentOutput, the output is between -1.0 and 1.0, with 0.0 as stopped. 041 * In Current mode, output value is in amperes. 042 * In Velocity mode, output value is in position change / 100ms. 043 * In Position mode, output value is in encoder ticks or an analog value, 044 * depending on the sensor. See 045 * In Follower mode, the output value is the integer device ID of the talon to 046 * duplicate. 047 * 048 * @param demand1Type The demand type for demand1. 049 * Neutral: Ignore demand1 and apply no change to the demand0 output. 050 * AuxPID: Use demand1 to set the target for the auxiliary PID 1. 051 * ArbitraryFeedForward: Use demand1 as an arbitrary additive value to the 052 * demand0 output. In PercentOutput the demand0 output is the motor output, 053 * and in closed-loop modes the demand0 output is the output of PID0. 054 * @param demand1 Supplmental output value. Units match the set mode. 055 * 056 * 057 * Arcade Drive Example: 058 * _talonLeft.set(ControlMode.PercentOutput, joyForward, DemandType.ArbitraryFeedForward, +joyTurn); 059 * _talonRght.set(ControlMode.PercentOutput, joyForward, DemandType.ArbitraryFeedForward, -joyTurn); 060 * 061 * Drive Straight Example: 062 * Note: Selected Sensor Configuration is necessary for both PID0 and PID1. 063 * _talonLeft.follow(_talonRght, FollwerType.AuxOutput1); 064 * _talonRght.set(ControlMode.PercentOutput, joyForward, DemandType.AuxPID, desiredRobotHeading); 065 * 066 * Drive Straight to a Distance Example: 067 * Note: Other configurations (sensor selection, PID gains, etc.) need to be set. 068 * _talonLeft.follow(_talonRght, FollwerType.AuxOutput1); 069 * _talonRght.set(ControlMode.MotionMagic, targetDistance, DemandType.AuxPID, desiredRobotHeading); 070 */ 071 public void set(ControlMode Mode, double demand0, DemandType demand1Type, double demand1); 072 073 /** 074 * Neutral the motor output by setting control mode to disabled. 075 */ 076 public void neutralOutput(); 077 078 /** 079 * Sets the mode of operation during neutral throttle output. 080 * 081 * @param neutralMode 082 * The desired mode of operation when the Controller output 083 * throttle is neutral (ie brake/coast) 084 **/ 085 public void setNeutralMode(NeutralMode neutralMode); 086 087 // ------ Invert behavior ----------// 088 /** 089 * Sets the phase of the sensor. Use when controller forward/reverse output 090 * doesn't correlate to appropriate forward/reverse reading of sensor. 091 * Pick a value so that positive PercentOutput yields a positive change in sensor. 092 * After setting this, user can freely call SetInverted() with any value. 093 * 094 * @param PhaseSensor 095 * Indicates whether to invert the phase of the sensor. 096 */ 097 public void setSensorPhase(boolean PhaseSensor); 098 099 /** 100 * Inverts the hbridge output of the motor controller. 101 * 102 * This does not impact sensor phase and should not be used to correct sensor polarity. 103 * 104 * This will invert the hbridge output but NOT the LEDs. 105 * This ensures.... 106 * - Green LEDs always represents positive request from robot-controller/closed-looping mode. 107 * - Green LEDs correlates to forward limit switch. 108 * - Green LEDs correlates to forward soft limit. 109 * 110 * @param invert 111 * Invert state to set. 112 */ 113 public void setInverted(boolean invert); 114 115 /** 116 * Inverts the hbridge output of the motor controller in relation to the master if present 117 * 118 * This does not impact sensor phase and should not be used to correct sensor polarity. 119 * 120 * This will allow you to either: 121 * - Not invert the motor 122 * - Invert the motor 123 * - Always follow the master regardless of master's inversion 124 * - Always oppose the master regardless of master's inversion 125 * 126 * @param invertType 127 * Invert state to set. 128 */ 129 public void setInverted(InvertType invertType); 130 131 /** 132 * @return invert setting of motor output. 133 */ 134 public boolean getInverted(); 135 136 // ----- general output shaping ------------------// 137 /** 138 * Configures the open-loop ramp rate of throttle output. 139 * 140 * @param secondsFromNeutralToFull 141 * Minimum desired time to go from neutral to full throttle. A 142 * value of '0' will disable the ramp. 143 * @param timeoutMs 144 * Timeout value in ms. If nonzero, function will wait for 145 * config success and report an error if it times out. 146 * If zero, no blocking or checking is performed. 147 * @return Error Code generated by function. 0 indicates no error. 148 */ 149 public ErrorCode configOpenloopRamp(double secondsFromNeutralToFull, int timeoutMs); 150 151 /** 152 * Configures the closed-loop ramp rate of throttle output. 153 * 154 * @param secondsFromNeutralToFull 155 * Minimum desired time to go from neutral to full throttle. A 156 * value of '0' will disable the ramp. 157 * @param timeoutMs 158 * Timeout value in ms. If nonzero, function will wait for 159 * config success and report an error if it times out. 160 * If zero, no blocking or checking is performed. 161 * @return Error Code generated by function. 0 indicates no error. 162 */ 163 public ErrorCode configClosedloopRamp(double secondsFromNeutralToFull, int timeoutMs); 164 165 /** 166 * Configures the forward peak output percentage. 167 * 168 * @param percentOut 169 * Desired peak output percentage. [0,1] 170 * @param timeoutMs 171 * Timeout value in ms. If nonzero, function will wait for 172 * config success and report an error if it times out. 173 * If zero, no blocking or checking is performed. 174 * @return Error Code generated by function. 0 indicates no error. 175 */ 176 public ErrorCode configPeakOutputForward(double percentOut, int timeoutMs); 177 178 /** 179 * Configures the reverse peak output percentage. 180 * 181 * @param percentOut 182 * Desired peak output percentage. 183 * @param timeoutMs 184 * Timeout value in ms. If nonzero, function will wait for 185 * config success and report an error if it times out. 186 * If zero, no blocking or checking is performed. 187 * @return Error Code generated by function. 0 indicates no error. 188 */ 189 public ErrorCode configPeakOutputReverse(double percentOut, int timeoutMs); 190 191 /** 192 * Configures the forward nominal output percentage. 193 * 194 * @param percentOut 195 * Nominal (minimum) percent output. [0,+1] 196 * @param timeoutMs 197 * Timeout value in ms. If nonzero, function will wait for 198 * config success and report an error if it times out. 199 * If zero, no blocking or checking is performed. 200 * @return Error Code generated by function. 0 indicates no error. 201 */ 202 public ErrorCode configNominalOutputForward(double percentOut, int timeoutMs); 203 204 /** 205 * Configures the reverse nominal output percentage. 206 * 207 * @param percentOut 208 * Nominal (minimum) percent output. [-1,0] 209 * @param timeoutMs 210 * Timeout value in ms. If nonzero, function will wait for 211 * config success and report an error if it times out. 212 * If zero, no blocking or checking is performed. 213 * @return Error Code generated by function. 0 indicates no error. 214 */ 215 public ErrorCode configNominalOutputReverse(double percentOut, int timeoutMs); 216 217 /** 218 * Configures the output deadband percentage. 219 * 220 * @param percentDeadband 221 * Desired deadband percentage. Minimum is 0.1%, Maximum is 25%. 222 * Pass 0.04 for 4% (factory default). 223 * @param timeoutMs 224 * Timeout value in ms. If nonzero, function will wait for 225 * config success and report an error if it times out. 226 * If zero, no blocking or checking is performed. 227 * @return Error Code generated by function. 0 indicates no error. 228 */ 229 public ErrorCode configNeutralDeadband(double percentDeadband, int timeoutMs); 230 231 // ------ Voltage Compensation ----------// 232 /** 233 * Configures the Voltage Compensation saturation voltage. 234 * 235 * @param voltage 236 * This is the max voltage to apply to the hbridge when voltage 237 * compensation is enabled. For example, if 10 (volts) is specified 238 * and a TalonSRX is commanded to 0.5 (PercentOutput, closed-loop, etc) 239 * then the TalonSRX will attempt to apply a duty-cycle to produce 5V. 240 * @param timeoutMs 241 * Timeout value in ms. If nonzero, function will wait for 242 * config success and report an error if it times out. 243 * If zero, no blocking or checking is performed. 244 * @return Error Code generated by function. 0 indicates no error. 245 */ 246 public ErrorCode configVoltageCompSaturation(double voltage, int timeoutMs); 247 248 /** 249 * Configures the voltage measurement filter. 250 * 251 * @param filterWindowSamples 252 * Number of samples in the rolling average of voltage 253 * measurement. 254 * @param timeoutMs 255 * Timeout value in ms. If nonzero, function will wait for 256 * config success and report an error if it times out. 257 * If zero, no blocking or checking is performed. 258 * @return Error Code generated by function. 0 indicates no error. 259 */ 260 public ErrorCode configVoltageMeasurementFilter(int filterWindowSamples, int timeoutMs); 261 262 /** 263 * Enables voltage compensation. If enabled, voltage compensation works in 264 * all control modes. 265 * 266 * Be sure to configure the saturation voltage before enabling this. 267 * 268 * @param enable 269 * Enable state of voltage compensation. 270 **/ 271 public void enableVoltageCompensation(boolean enable); 272 273 // ------ General Status ----------// 274 275 /** 276 * Gets the bus voltage seen by the device. 277 * 278 * @return The bus voltage value (in volts). 279 */ 280 public double getBusVoltage() ; 281 282 /** 283 * Gets the output percentage of the motor controller. 284 * 285 * @return Output of the motor controller (in percent). 286 */ 287 public double getMotorOutputPercent() ; 288 289 /** 290 * @return applied voltage to motor in volts. 291 */ 292 public double getMotorOutputVoltage() ; 293 294 /** 295 * Gets the temperature of the motor controller. 296 * 297 * @return Temperature of the motor controller (in 'C) 298 */ 299 public double getTemperature() ; 300 301 // ------ sensor selection ----------// 302 /** 303 * Select the remote feedback device for the motor controller. 304 * Most CTRE CAN motor controllers will support remote sensors over CAN. 305 * 306 * @param feedbackDevice 307 * Remote Feedback Device to select. 308 * @param pidIdx 309 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. 310 * @param timeoutMs 311 * Timeout value in ms. If nonzero, function will wait for 312 * config success and report an error if it times out. 313 * If zero, no blocking or checking is performed. 314 * @return Error Code generated by function. 0 indicates no error. 315 */ 316 public ErrorCode configSelectedFeedbackSensor(RemoteFeedbackDevice feedbackDevice, int pidIdx, int timeoutMs); 317 318 /** 319 * The Feedback Coefficient is a scalar applied to the value of the 320 * feedback sensor. Useful when you need to scale your sensor values 321 * within the closed-loop calculations. Default value is 1. 322 * 323 * Selected Feedback Sensor register in firmware is the decoded sensor value 324 * multiplied by the Feedback Coefficient. 325 * 326 * @param coefficient 327 * Feedback Coefficient value. Maximum value of 1. 328 * Resolution is 1/(2^16). Cannot be 0. 329 * @param pidIdx 330 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. 331 * @param timeoutMs 332 * Timeout value in ms. If nonzero, function will wait for 333 * config success and report an error if it times out. 334 * If zero, no blocking or checking is performed. 335 * @return Error Code generated by function. 0 indicates no error. 336 */ 337 public ErrorCode configSelectedFeedbackCoefficient(double coefficient, int pidIdx, int timeoutMs); 338 339 /** 340 * Select what remote device and signal to assign to Remote Sensor 0 or Remote Sensor 1. 341 * After binding a remote device and signal to Remote Sensor X, you may select Remote Sensor X 342 * as a PID source for closed-loop features. 343 * 344 * @param deviceID 345 * The device ID of the remote sensor device. 346 * @param remoteSensorSource 347 * The remote sensor device and signal type to bind. 348 * @param remoteOrdinal 349 * 0 for configuring Remote Sensor 0, 350 * 1 for configuring Remote Sensor 1 351 * @param timeoutMs 352 * Timeout value in ms. If nonzero, function will wait for 353 * config success and report an error if it times out. 354 * If zero, no blocking or checking is performed. 355 * @return Error Code generated by function. 0 indicates no error. 356 */ 357 public ErrorCode configRemoteFeedbackFilter(int deviceID, RemoteSensorSource remoteSensorSource, int remoteOrdinal, 358 int timeoutMs); 359 360 /** 361 * Select what remote device and signal to assign to Remote Sensor 0 or Remote Sensor 1. 362 * After binding a remote device and signal to Remote Sensor X, you may select Remote Sensor X 363 * as a PID source for closed-loop features. 364 * 365 * @param talonRef 366 * Talon device reference to use. 367 * @param remoteOrdinal 368 * 0 for configuring Remote Sensor 0, 369 * 1 for configuring Remote Sensor 1 370 * @param timeoutMs 371 * Timeout value in ms. If nonzero, function will wait for 372 * config success and report an error if it times out. 373 * If zero, no blocking or checking is performed. 374 * @return Error Code generated by function. 0 indicates no error. 375 */ 376 public ErrorCode configRemoteFeedbackFilter(BaseTalon talonRef, int remoteOrdinal, 377 int timeoutMs); 378 379 /** 380 * Select what sensor term should be bound to switch feedback device. 381 * Sensor Sum = Sensor Sum Term 0 - Sensor Sum Term 1 382 * Sensor Difference = Sensor Diff Term 0 - Sensor Diff Term 1 383 * The four terms are specified with this routine. Then Sensor Sum/Difference 384 * can be selected for closed-looping. 385 * 386 * @param sensorTerm Which sensor term to bind to a feedback source. 387 * @param feedbackDevice The sensor signal to attach to sensorTerm. 388 * @param timeoutMs 389 * Timeout value in ms. If nonzero, function will wait for 390 * config success and report an error if it times out. 391 * If zero, no blocking or checking is performed. 392 * @return Error Code generated by function. 0 indicates no error. 393 */ 394 public ErrorCode configSensorTerm(SensorTerm sensorTerm, FeedbackDevice feedbackDevice, int timeoutMs); 395 396 // ------- sensor status --------- // 397 /** 398 * Get the selected sensor position (in raw sensor units). 399 * 400 * @param pidIdx 401 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. See 402 * Phoenix-Documentation for how to interpret. 403 * 404 * @return Position of selected sensor (in raw sensor units). 405 */ 406 public double getSelectedSensorPosition(int pidIdx); 407 408 /** 409 * Get the selected sensor velocity. 410 * 411 * @param pidIdx 412 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. 413 * @return selected sensor (in raw sensor units) per 100ms. 414 * See Phoenix-Documentation for how to interpret. 415 */ 416 public double getSelectedSensorVelocity(int pidIdx); 417 418 /** 419 * Sets the sensor position to the given value. 420 * 421 * @param sensorPos 422 * Position to set for the selected sensor (in raw sensor units). 423 * @param pidIdx 424 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. 425 * @param timeoutMs 426 * Timeout value in ms. If nonzero, function will wait for 427 * config success and report an error if it times out. 428 * If zero, no blocking or checking is performed. 429 * @return Error Code generated by function. 0 indicates no error. 430 */ 431 public ErrorCode setSelectedSensorPosition(double sensorPos, int pidIdx, int timeoutMs); 432 433 // ------ status frame period changes ----------// 434 /** 435 * Sets the period of the given control frame. 436 * 437 * @param frame 438 * Frame whose period is to be changed. 439 * @param periodMs 440 * Period in ms for the given frame. 441 * @return Error Code generated by function. 0 indicates no error. 442 */ 443 public ErrorCode setControlFramePeriod(ControlFrame frame, int periodMs); 444 445 /** 446 * Sets the period of the given status frame. 447 * 448 * User ensure CAN Bus utilization is not high. 449 * 450 * This setting is not persistent and is lost when device is reset. If this 451 * is a concern, calling application can use hasResetOccurred() to determine if the 452 * status frame needs to be reconfigured. 453 * 454 * @param frame 455 * Frame whose period is to be changed. 456 * @param periodMs 457 * Period in ms for the given frame. 458 * @param timeoutMs 459 * Timeout value in ms. If nonzero, function will wait for config 460 * success and report an error if it times out. If zero, no 461 * blocking or checking is performed. 462 * @return Error Code generated by function. 0 indicates no error. 463 */ 464 public ErrorCode setStatusFramePeriod(StatusFrame frame, int periodMs, int timeoutMs); 465 466 /** 467 * Gets the period of the given status frame. 468 * 469 * @param frame 470 * Frame to get the period of. 471 * @param timeoutMs 472 * Timeout value in ms. If nonzero, function will wait for 473 * config success and report an error if it times out. 474 * If zero, no blocking or checking is performed. 475 * @return Period of the given status frame. 476 */ 477 public int getStatusFramePeriod(StatusFrame frame, int timeoutMs); 478 479 //----- velocity signal conditionaing ------// 480 /* not supported */ 481 482 //------ remote limit switch ----------// 483 /** 484 * Configures the forward limit switch for a remote source. For example, a 485 * CAN motor controller may need to monitor the Limit-F pin of another Talon 486 * or CANifier. 487 * 488 * @param type 489 * Remote limit switch source. User can choose between a remote 490 * Talon SRX, CANifier, or deactivate the feature. 491 * @param normalOpenOrClose 492 * Setting for normally open, normally closed, or disabled. This 493 * setting matches the Phoenix Tuner drop down. 494 * @param deviceID 495 * Device ID of remote source (Talon SRX or CANifier device ID). 496 * @param timeoutMs 497 * Timeout value in ms. If nonzero, function will wait for config 498 * success and report an error if it times out. If zero, no 499 * blocking or checking is performed. 500 * @return Error Code generated by function. 0 indicates no error. 501 */ 502 public ErrorCode configForwardLimitSwitchSource(RemoteLimitSwitchSource type, LimitSwitchNormal normalOpenOrClose, 503 int deviceID, int timeoutMs); 504 505 /** 506 * Configures the reverse limit switch for a remote source. For example, a 507 * CAN motor controller may need to monitor the Limit-R pin of another Talon 508 * or CANifier. 509 * 510 * @param type 511 * Remote limit switch source. User can choose between a remote 512 * Talon SRX, CANifier, or deactivate the feature. 513 * @param normalOpenOrClose 514 * Setting for normally open, normally closed, or disabled. This 515 * setting matches the Phoenix Tuner drop down. 516 * @param deviceID 517 * Device ID of remote source (Talon SRX or CANifier device ID). 518 * @param timeoutMs 519 * Timeout value in ms. If nonzero, function will wait for config 520 * success and report an error if it times out. If zero, no 521 * blocking or checking is performed. 522 * @return Error Code generated by function. 0 indicates no error. 523 */ 524 public ErrorCode configReverseLimitSwitchSource(RemoteLimitSwitchSource type, LimitSwitchNormal normalOpenOrClose, 525 int deviceID, int timeoutMs); 526 527 /** 528 * Sets the enable state for limit switches. 529 * 530 * @param enable 531 * Enable state for limit switches. 532 **/ 533 public void overrideLimitSwitchesEnable(boolean enable); 534 535 // ------ local limit switch ----------// 536 /* not supported */ 537 538 // ------ soft limit ----------// 539 /** 540 * Configures the forward soft limit threhold. 541 * 542 * @param forwardSensorLimit 543 * Forward Sensor Position Limit (in raw sensor units). 544 * @param timeoutMs 545 * Timeout value in ms. If nonzero, function will wait for 546 * config success and report an error if it times out. 547 * If zero, no blocking or checking is performed. 548 * @return Error Code generated by function. 0 indicates no error. 549 */ 550 public ErrorCode configForwardSoftLimitThreshold(double forwardSensorLimit, int timeoutMs); 551 552 /** 553 * Configures the reverse soft limit threshold. 554 * 555 * @param reverseSensorLimit 556 * Reverse Sensor Position Limit (in raw sensor units). 557 * @param timeoutMs 558 * Timeout value in ms. If nonzero, function will wait for 559 * config success and report an error if it times out. 560 * If zero, no blocking or checking is performed. 561 * @return Error Code generated by function. 0 indicates no error. 562 */ 563 public ErrorCode configReverseSoftLimitThreshold(double reverseSensorLimit, int timeoutMs); 564 565 /** 566 * Configures the forward soft limit enable. 567 * 568 * @param enable 569 * Forward Sensor Position Limit Enable. 570 * @param timeoutMs 571 * Timeout value in ms. If nonzero, function will wait for 572 * config success and report an error if it times out. 573 * If zero, no blocking or checking is performed. 574 * @return Error Code generated by function. 0 indicates no error. 575 */ 576 public ErrorCode configForwardSoftLimitEnable(boolean enable, int timeoutMs); 577 578 /** 579 * Configures the reverse soft limit enable. 580 * 581 * @param enable 582 * Reverse Sensor Position Limit Enable. 583 * @param timeoutMs 584 * Timeout value in ms. If nonzero, function will wait for config 585 * success and report an error if it times out. If zero, no 586 * blocking or checking is performed. 587 * @return Error Code generated by function. 0 indicates no error. 588 */ 589 public ErrorCode configReverseSoftLimitEnable(boolean enable, int timeoutMs); 590 591 /** 592 * Can be used to override-disable the soft limits. 593 * This function can be used to quickly disable soft limits without 594 * having to modify the persistent configuration. 595 * 596 * @param enable 597 * Enable state for soft limit switches. 598 */ 599 public void overrideSoftLimitsEnable(boolean enable); 600 601 // ------ Current Lim ----------// 602 /* not supported */ 603 604 // ------ General Close loop ----------// 605 /** 606 * Sets the 'P' constant in the given parameter slot. 607 * This is multiplied by closed loop error in sensor units. 608 * Note the closed loop output interprets a final value of 1023 as full output. 609 * So use a gain of '0.25' to get full output if err is 4096u (Mag Encoder 1 rotation) 610 * 611 * @param slotIdx 612 * Parameter slot for the constant. 613 * @param value 614 * Value of the P constant. 615 * @param timeoutMs 616 * Timeout value in ms. If nonzero, function will wait for 617 * config success and report an error if it times out. 618 * If zero, no blocking or checking is performed. 619 * @return Error Code generated by function. 0 indicates no error. 620 */ 621 public ErrorCode config_kP(int slotIdx, double value, int timeoutMs); 622 623 /** 624 * Sets the 'I' constant in the given parameter slot. 625 * This is multiplied by accumulated closed loop error in sensor units every PID Loop. 626 * Note the closed loop output interprets a final value of 1023 as full output. 627 * So use a gain of '0.00025' to get full output if err is 4096u for 1000 loops (accumulater holds 4,096,000), 628 * [which is equivalent to one CTRE mag encoder rotation for 1000 milliseconds]. 629 * 630 * @param slotIdx 631 * Parameter slot for the constant. 632 * @param value 633 * Value of the I constant. 634 * @param timeoutMs 635 * Timeout value in ms. If nonzero, function will wait for 636 * config success and report an error if it times out. 637 * If zero, no blocking or checking is performed. 638 * @return Error Code generated by function. 0 indicates no error. 639 */ 640 public ErrorCode config_kI(int slotIdx, double value, int timeoutMs); 641 642 /** 643 * Sets the 'D' constant in the given parameter slot. 644 * 645 * This is multiplied by derivative error (sensor units per PID loop, typically 1ms). 646 * Note the closed loop output interprets a final value of 1023 as full output. 647 * So use a gain of '250' to get full output if derr is 4096u (Mag Encoder 1 rotation) per 1000 loops (typ 1 sec) 648 * 649 * @param slotIdx 650 * Parameter slot for the constant. 651 * @param value 652 * Value of the D constant. 653 * @param timeoutMs 654 * Timeout value in ms. If nonzero, function will wait for 655 * config success and report an error if it times out. 656 * If zero, no blocking or checking is performed. 657 * @return Error Code generated by function. 0 indicates no error. 658 */ 659 public ErrorCode config_kD(int slotIdx, double value, int timeoutMs); 660 661 /** 662 * Sets the 'F' constant in the given parameter slot. 663 * 664 * See documentation for calculation details. 665 * If using velocity, motion magic, or motion profile, 666 * use (1023 * duty-cycle / sensor-velocity-sensor-units-per-100ms). 667 * 668 * @param slotIdx 669 * Parameter slot for the constant. 670 * @param value 671 * Value of the F constant. 672 * @param timeoutMs 673 * Timeout value in ms. If nonzero, function will wait for 674 * config success and report an error if it times out. 675 * If zero, no blocking or checking is performed. 676 * @return Error Code generated by function. 0 indicates no error. 677 */ 678 public ErrorCode config_kF(int slotIdx, double value, int timeoutMs); 679 680 /** 681 * Sets the Integral Zone constant in the given parameter slot. If the 682 * (absolute) closed-loop error is outside of this zone, integral 683 * accumulator is automatically cleared. This ensures than integral wind up 684 * events will stop after the sensor gets far enough from its target. 685 * 686 * @param slotIdx 687 * Parameter slot for the constant. 688 * @param izone 689 * Value of the Integral Zone constant (closed loop error units X 690 * 1ms). 691 * @param timeoutMs 692 * Timeout value in ms. If nonzero, function will wait for config 693 * success and report an error if it times out. If zero, no 694 * blocking or checking is performed. 695 * @return Error Code generated by function. 0 indicates no error. 696 */ 697 public ErrorCode config_IntegralZone(int slotIdx, double izone, int timeoutMs); 698 699 /** 700 * Sets the allowable closed-loop error in the given parameter slot. 701 * 702 * @param slotIdx 703 * Parameter slot for the constant. 704 * @param allowableCloseLoopError 705 * Value of the allowable closed-loop error in sensor units (or sensor units per 100ms for velocity). 706 * @param timeoutMs 707 * Timeout value in ms. If nonzero, function will wait for 708 * config success and report an error if it times out. 709 * If zero, no blocking or checking is performed. 710 * @return Error Code generated by function. 0 indicates no error. 711 */ 712 public ErrorCode configAllowableClosedloopError(int slotIdx, double allowableCloseLoopError, int timeoutMs); 713 714 /** 715 * Sets the maximum integral accumulator in the given parameter slot. 716 * 717 * @param slotIdx 718 * Parameter slot for the constant. 719 * @param iaccum 720 * Value of the maximum integral accumulator (closed loop error 721 * units X 1ms). 722 * @param timeoutMs 723 * Timeout value in ms. If nonzero, function will wait for config 724 * success and report an error if it times out. If zero, no 725 * blocking or checking is performed. 726 * @return Error Code generated by function. 0 indicates no error. 727 */ 728 public ErrorCode configMaxIntegralAccumulator(int slotIdx, double iaccum, int timeoutMs); 729 730 /** 731 * Sets the peak closed-loop output. This peak output is slot-specific and 732 * is applied to the output of the associated PID loop. 733 * This setting is seperate from the generic Peak Output setting. 734 * 735 * @param slotIdx 736 * Parameter slot for the constant. 737 * @param percentOut 738 * Peak Percent Output from 0 to 1. This value is absolute and 739 * the magnitude will apply in both forward and reverse directions. 740 * @param timeoutMs 741 * Timeout value in ms. If nonzero, function will wait for 742 * config success and report an error if it times out. 743 * If zero, no blocking or checking is performed. 744 * @return Error Code generated by function. 0 indicates no error. 745 */ 746 public ErrorCode configClosedLoopPeakOutput(int slotIdx, double percentOut, int timeoutMs); 747 748 /** 749 * Sets the loop time (in milliseconds) of the PID closed-loop calculations. 750 * Default value is 1 ms. 751 * 752 * @param slotIdx 753 * Parameter slot for the constant. 754 * @param loopTimeMs 755 * Loop timing of the closed-loop calculations. Minimum value of 756 * 1 ms, maximum of 64 ms. 757 * @param timeoutMs 758 * Timeout value in ms. If nonzero, function will wait for 759 * config success and report an error if it times out. 760 * If zero, no blocking or checking is performed. 761 * @return Error Code generated by function. 0 indicates no error. 762 */ 763 public ErrorCode configClosedLoopPeriod(int slotIdx, int loopTimeMs, int timeoutMs); 764 765 /** 766 * Configures the Polarity of the Auxiliary PID (PID1). 767 * 768 * Standard Polarity: 769 * Primary Output = PID0 + PID1, 770 * Auxiliary Output = PID0 - PID1, 771 * 772 * Inverted Polarity: 773 * Primary Output = PID0 - PID1, 774 * Auxiliary Output = PID0 + PID1, 775 * 776 * @param invert 777 * If true, use inverted PID1 output polarity. 778 * @param timeoutMs 779 * Timeout value in ms. If nonzero, function will wait for config 780 * success and report an error if it times out. If zero, no 781 * blocking or checking is performed. 782 * @return Error Code 783 */ 784 public ErrorCode configAuxPIDPolarity(boolean invert, int timeoutMs); 785 786 //------ Close loop State ----------// 787 /** 788 * Sets the integral accumulator. Typically this is used to clear/zero the 789 * integral accumulator, however some use cases may require seeding the 790 * accumulator for a faster response. 791 * 792 * @param iaccum 793 * Value to set for the integral accumulator (closed loop error 794 * units X 1ms). 795 * @param pidIdx 796 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. 797 * @param timeoutMs 798 * Timeout value in ms. If nonzero, function will wait for config 799 * success and report an error if it times out. If zero, no 800 * blocking or checking is performed. 801 * @return Error Code generated by function. 0 indicates no error. 802 */ 803 public ErrorCode setIntegralAccumulator(double iaccum, int pidIdx, int timeoutMs); 804 805 /** 806 * Gets the closed-loop error. The units depend on which control mode is in 807 * use. 808 * 809 * If closed-loop is seeking a target sensor position, closed-loop error is the difference between target 810 * and current sensor value (in sensor units. Example 4096 units per rotation for CTRE Mag Encoder). 811 * 812 * If closed-loop is seeking a target sensor velocity, closed-loop error is the difference between target 813 * and current sensor value (in sensor units per 100ms). 814 * 815 * If using motion profiling or Motion Magic, closed loop error is calculated against the current target, 816 * and not the "final" target at the end of the profile/movement. 817 * 818 * See Phoenix-Documentation information on units. 819 * 820 * @param pidIdx 821 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. 822 * @return Closed-loop error value. 823 */ 824 public double getClosedLoopError(int pidIdx); 825 826 /** 827 * Gets the iaccum value. 828 * 829 * @param pidIdx 830 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. 831 * @return Integral accumulator value (Closed-loop error X 1ms). 832 */ 833 public double getIntegralAccumulator(int pidIdx) ; 834 835 /** 836 * Gets the derivative of the closed-loop error. 837 * 838 * @param pidIdx 839 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. 840 * @return The error derivative value. 841 */ 842 public double getErrorDerivative(int pidIdx) ; 843 844 /** 845 * Selects which profile slot to use for closed-loop control. 846 * 847 * @param slotIdx 848 * Profile slot to select. 849 * @param pidIdx 850 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. 851 **/ 852 public void selectProfileSlot(int slotIdx, int pidIdx); 853 854 /** 855 * Gets the current target of a given closed loop. 856 * 857 * @param pidIdx 858 * 0 for Primary closed-loop. 1 for auxiliary closed-loop. 859 * @return The closed loop target. 860 */ 861 public double getClosedLoopTarget(int pidIdx); // will be added to JNI 862 863 /** 864 * Gets the active trajectory target position for pid0 using 865 * MotionMagic/MotionProfile control modes. 866 * 867 * @return The Active Trajectory Position in sensor units. 868 */ 869 public double getActiveTrajectoryPosition(); 870 871 /** 872 * Gets the active trajectory target velocity for pid0 using 873 * MotionMagic/MotionProfile control modes. 874 * 875 * @return The Active Trajectory Velocity in sensor units per 100ms. 876 */ 877 public double getActiveTrajectoryVelocity(); 878 879 // ------ Motion Profile Settings used in Motion Magic and Motion Profile 880 /** 881 * Sets the Motion Magic Cruise Velocity. This is the peak target velocity 882 * that the motion magic curve generator can use. 883 * 884 * @param sensorUnitsPer100ms 885 * Motion Magic Cruise Velocity (in raw sensor units per 100 ms). 886 * @param timeoutMs 887 * Timeout value in ms. If nonzero, function will wait for config 888 * success and report an error if it times out. If zero, no 889 * blocking or checking is performed. 890 * @return Error Code generated by function. 0 indicates no error. 891 */ 892 public ErrorCode configMotionCruiseVelocity(double sensorUnitsPer100ms, int timeoutMs); 893 894 /** 895 * Sets the Motion Magic Acceleration. This is the target acceleration that 896 * the motion magic curve generator can use. 897 * 898 * @param sensorUnitsPer100msPerSec 899 * Motion Magic Acceleration (in raw sensor units per 100 ms per 900 * second). 901 * @param timeoutMs 902 * Timeout value in ms. If nonzero, function will wait for config 903 * success and report an error if it times out. If zero, no 904 * blocking or checking is performed. 905 * @return Error Code generated by function. 0 indicates no error. 906 */ 907 public ErrorCode configMotionAcceleration(double sensorUnitsPer100msPerSec, int timeoutMs); 908 909 /** 910 * Sets the Motion Magic S Curve Strength. 911 * Call this before using Motion Magic. 912 * Modifying this during a Motion Magic action should be avoided. 913 * 914 * @param curveStrength 915 * 0 to use Trapezoidal Motion Profile. [1,8] for S-Curve (greater value yields greater smoothing). 916 * @param timeoutMs 917 * Timeout value in ms. If nonzero, function will wait for config 918 * success and report an error if it times out. If zero, no 919 * blocking or checking is performed. 920 * @return Error Code generated by function. 0 indicates no error. 921 */ 922 public ErrorCode configMotionSCurveStrength(int curveStrength, int timeoutMs); 923 924 /** 925 * When trajectory points are processed in the motion profile executer, the MPE determines 926 * how long to apply the active trajectory point by summing baseTrajDurationMs with the 927 * timeDur of the trajectory point (see TrajectoryPoint). 928 * 929 * This allows general selection of the execution rate of the points with 1ms resolution, 930 * while allowing some degree of change from point to point. 931 * @param baseTrajDurationMs The base duration time of every trajectory point. 932 * This is summed with the trajectory points unique timeDur. 933 * @param timeoutMs 934 * Timeout value in ms. If nonzero, function will wait for 935 * config success and report an error if it times out. 936 * If zero, no blocking or checking is performed. 937 * @return Error Code generated by function. 0 indicates no error. 938 */ 939 public ErrorCode configMotionProfileTrajectoryPeriod(int baseTrajDurationMs, int timeoutMs); 940 941 // ------ Motion Profile Buffer ----------// 942 /** 943 * Clear the buffered motion profile in both controller's RAM (bottom), and in the 944 * API (top). 945 * 946 * @return Error Code generated by function. 0 indicates no error 947 */ 948 public ErrorCode clearMotionProfileTrajectories(); 949 /** 950 * Retrieve just the buffer count for the api-level (top) buffer. This 951 * routine performs no CAN or data structure lookups, so its fast and ideal 952 * if caller needs to quickly poll the progress of trajectory points being 953 * emptied into controller's RAM. Otherwise just use GetMotionProfileStatus. 954 * 955 * @return number of trajectory points in the top buffer. 956 */ 957 public int getMotionProfileTopLevelBufferCount(); 958 /** 959 * Push another trajectory point into the top level buffer (which is emptied 960 * into the motor controller's bottom buffer as room allows). 961 * @param trajPt to push into buffer. 962 * The members should be filled in with these values... 963 * 964 * targPos: servo position in sensor units. 965 * targVel: velocity to feed-forward in sensor units 966 * per 100ms. 967 * profileSlotSelect0 Which slot to get PIDF gains. PID is used for position servo. F is used 968 * as the Kv constant for velocity feed-forward. Typically this is hardcoded 969 * to the a particular slot, but you are free gain schedule if need be. 970 * Choose from [0,3] 971 * profileSlotSelect1 Which slot to get PIDF gains for auxiliary PId. 972 * This only has impact during MotionProfileArc Control mode. 973 * Choose from [0,1]. 974 * isLastPoint set to nonzero to signal motor controller to keep processing this 975 * trajectory point, instead of jumping to the next one 976 * when timeDurMs expires. Otherwise MP executer will 977 * eventually see an empty buffer after the last point 978 * expires, causing it to assert the IsUnderRun flag. 979 * However this may be desired if calling application 980 * never wants to terminate the MP. 981 * zeroPos set to nonzero to signal motor controller to "zero" the selected 982 * position sensor before executing this trajectory point. 983 * Typically the first point should have this set only thus 984 * allowing the remainder of the MP positions to be relative to 985 * zero. 986 * timeDur Duration to apply this trajectory pt. 987 * This time unit is ADDED to the exising base time set by 988 * configMotionProfileTrajectoryPeriod(). 989 * @return CTR_OKAY if trajectory point push ok. ErrorCode if buffer is 990 * full due to kMotionProfileTopBufferCapacity. 991 */ 992 public ErrorCode pushMotionProfileTrajectory(TrajectoryPoint trajPt); 993 /** 994 * Retrieve just the buffer full for the api-level (top) buffer. This 995 * routine performs no CAN or data structure lookups, so its fast and ideal 996 * if caller needs to quickly poll. Otherwise just use 997 * GetMotionProfileStatus. 998 * 999 * @return number of trajectory points in the top buffer. 1000 */ 1001 public boolean isMotionProfileTopLevelBufferFull(); 1002 /** 1003 * This must be called periodically to funnel the trajectory points from the 1004 * API's top level buffer to the controller's bottom level buffer. Recommendation 1005 * is to call this twice as fast as the execution rate of the motion 1006 * profile. So if MP is running with 20ms trajectory points, try calling 1007 * this routine every 10ms. All motion profile functions are thread-safe 1008 * through the use of a mutex, so there is no harm in having the caller 1009 * utilize threading. 1010 */ 1011 public void processMotionProfileBuffer(); 1012 /** 1013 * Retrieve all status information. 1014 * For best performance, Caller can snapshot all status information regarding the 1015 * motion profile executer. 1016 * 1017 * @param statusToFill Caller supplied object to fill. 1018 * 1019 * The members are filled, as follows... 1020 * 1021 * topBufferRem: The available empty slots in the trajectory buffer. 1022 * The robot API holds a "top buffer" of trajectory points, so your applicaion 1023 * can dump several points at once. The API will then stream them into the 1024 * low-level buffer, allowing the motor controller to act on them. 1025 * 1026 * topBufferRem: The number of points in the top trajectory buffer. 1027 * 1028 * btmBufferCnt: The number of points in the low level controller buffer. 1029 * 1030 * hasUnderrun: Set if isUnderrun ever gets set. 1031 * Can be manually cleared by clearMotionProfileHasUnderrun() or automatically cleared by startMotionProfile(). 1032 * 1033 * isUnderrun: This is set if controller needs to shift a point from its buffer into 1034 * the active trajectory point however 1035 * the buffer is empty. 1036 * This gets cleared automatically when is resolved. 1037 * 1038 * activePointValid: True if the active trajectory point is not empty, false otherwise. The members in activePoint are only valid if this signal is set. 1039 * 1040 * isLast: is set/cleared based on the MP executer's current 1041 * trajectory point's IsLast value. This assumes 1042 * IsLast was set when PushMotionProfileTrajectory 1043 * was used to insert the currently processed trajectory 1044 * point. 1045 * 1046 * profileSlotSelect: The currently processed trajectory point's 1047 * selected slot. This can differ in the currently selected slot used 1048 * for Position and Velocity servo modes 1049 * 1050 * outputEnable: The current output mode of the motion profile 1051 * executer (disabled, enabled, or hold). When changing the set() 1052 * value in MP mode, it's important to check this signal to 1053 * confirm the change takes effect before interacting with the top buffer. 1054 * @return Error Code generated by function. 0 indicates no error. 1055 */ 1056 public ErrorCode getMotionProfileStatus(MotionProfileStatus statusToFill); 1057 /** 1058 * Clear the "Has Underrun" flag. Typically this is called after application 1059 * has confirmed an underrun had occured. 1060 * 1061 * @param timeoutMs 1062 * Timeout value in ms. If nonzero, function will wait for config 1063 * success and report an error if it times out. If zero, no 1064 * blocking or checking is performed. 1065 * @return Error Code generated by function. 0 indicates no error. 1066 */ 1067 public ErrorCode clearMotionProfileHasUnderrun(int timeoutMs); 1068 /** 1069 * Calling application can opt to speed up the handshaking between the robot 1070 * API and the controller to increase the download rate of the controller's Motion 1071 * Profile. Ideally the period should be no more than half the period of a 1072 * trajectory point. 1073 * 1074 * @param periodMs 1075 * The transmit period in ms. 1076 * @return Error Code generated by function. 0 indicates no error. 1077 */ 1078 public ErrorCode changeMotionControlFramePeriod(int periodMs); 1079 1080 // ------ error ----------// 1081 /** 1082 * Gets the last error generated by this object. Not all functions return an 1083 * error code but can potentially report errors. This function can be used 1084 * to retrieve those error codes. 1085 * 1086 * @return Last Error Code generated by a function. 1087 */ 1088 public ErrorCode getLastError(); 1089 1090 // ------ Faults ----------// 1091 /** 1092 * Polls the various fault flags. 1093 * 1094 * @param toFill 1095 * Caller's object to fill with latest fault flags. 1096 * @return Last Error Code generated by a function. 1097 */ 1098 public ErrorCode getFaults(Faults toFill) ; 1099 1100 /** 1101 * Polls the various sticky fault flags. 1102 * 1103 * @param toFill 1104 * Caller's object to fill with latest sticky fault flags. 1105 * @return Last Error Code generated by a function. 1106 */ 1107 public ErrorCode getStickyFaults(StickyFaults toFill) ; 1108 1109 /** 1110 * Clears all sticky faults. 1111 * 1112 * @param timeoutMs 1113 * Timeout value in ms. If nonzero, function will wait for config 1114 * success and report an error if it times out. If zero, no 1115 * blocking or checking is performed. 1116 * @return Last Error Code generated by a function. 1117 */ 1118 public ErrorCode clearStickyFaults(int timeoutMs); 1119 1120 // ------ Firmware ----------// 1121 /** 1122 * Gets the firmware version of the device. 1123 * 1124 * @return Firmware version of device. For example: version 1-dot-2 is 1125 * 0x0102. 1126 */ 1127 public int getFirmwareVersion(); 1128 1129 /** 1130 * Returns true if the device has reset since last call. 1131 * 1132 * @return Has a Device Reset Occurred? 1133 */ 1134 public boolean hasResetOccurred(); 1135 1136 // ------ Custom Persistent Params ----------// 1137 /** 1138 * Sets the value of a custom parameter. This is for arbitrary use. 1139 * 1140 * Sometimes it is necessary to save calibration/limit/target information in 1141 * the device. Particularly if the device is part of a subsystem that can be 1142 * replaced. 1143 * 1144 * @param newValue 1145 * Value for custom parameter. 1146 * @param paramIndex 1147 * Index of custom parameter [0,1] 1148 * @param timeoutMs 1149 * Timeout value in ms. If nonzero, function will wait for config 1150 * success and report an error if it times out. If zero, no 1151 * blocking or checking is performed. 1152 * @return Error Code generated by function. 0 indicates no error. 1153 */ 1154 public ErrorCode configSetCustomParam(int newValue, int paramIndex, int timeoutMs); 1155 1156 /** 1157 * Gets the value of a custom parameter. 1158 * 1159 * @param paramIndex 1160 * Index of custom parameter [0,1]. 1161 * @param timeoutMs 1162 * Timeout value in ms. If nonzero, function will wait for config 1163 * success and report an error if it times out. If zero, no 1164 * blocking or checking is performed. 1165 * @return Value of the custom param. 1166 */ 1167 public int configGetCustomParam(int paramIndex, int timeoutMs); 1168 1169 //------ Generic Param API, typically not used ----------// 1170 /** 1171 * Sets a parameter. Generally this is not used. This can be utilized in - 1172 * Using new features without updating API installation. - Errata 1173 * workarounds to circumvent API implementation. - Allows for rapid testing 1174 * / unit testing of firmware. 1175 * 1176 * @param param 1177 * Parameter enumeration. 1178 * @param value 1179 * Value of parameter. 1180 * @param subValue 1181 * Subvalue for parameter. Maximum value of 255. 1182 * @param ordinal 1183 * Ordinal of parameter. 1184 * @param timeoutMs 1185 * Timeout value in ms. If nonzero, function will wait for config 1186 * success and report an error if it times out. If zero, no 1187 * blocking or checking is performed. 1188 * @return Error Code generated by function. 0 indicates no error. 1189 */ 1190 public ErrorCode configSetParameter(ParamEnum param, double value, int subValue, int ordinal, int timeoutMs); 1191 /** 1192 * Sets a parameter. 1193 * 1194 * @param param 1195 * Parameter enumeration. 1196 * @param value 1197 * Value of parameter. 1198 * @param subValue 1199 * Subvalue for parameter. Maximum value of 255. 1200 * @param ordinal 1201 * Ordinal of parameter. 1202 * @param timeoutMs 1203 * Timeout value in ms. If nonzero, function will wait for 1204 * config success and report an error if it times out. 1205 * If zero, no blocking or checking is performed. 1206 * @return Error Code generated by function. 0 indicates no error. 1207 */ 1208 public ErrorCode configSetParameter(int param, double value, int subValue, int ordinal, int timeoutMs); 1209 1210 /** 1211 * Gets a parameter. 1212 * 1213 * @param paramEnum 1214 * Parameter enumeration. 1215 * @param ordinal 1216 * Ordinal of parameter. 1217 * @param timeoutMs 1218 * Timeout value in ms. If nonzero, function will wait for 1219 * config success and report an error if it times out. 1220 * If zero, no blocking or checking is performed. 1221 * @return Value of parameter. 1222 */ 1223 public double configGetParameter(ParamEnum paramEnum, int ordinal, int timeoutMs) ; 1224 /** 1225 * Gets a parameter. 1226 * 1227 * @param paramEnum 1228 * Parameter enumeration. 1229 * @param ordinal 1230 * Ordinal of parameter. 1231 * @param timeoutMs 1232 * Timeout value in ms. If nonzero, function will wait for 1233 * config success and report an error if it times out. 1234 * If zero, no blocking or checking is performed. 1235 * @return Value of parameter. 1236 */ 1237 public double configGetParameter(int paramEnum, int ordinal, int timeoutMs) ; 1238 1239 //------ Misc. ----------// 1240 /** 1241 * @return BaseID of device 1242 */ 1243 public int getBaseID(); 1244 /** 1245 * Returns the Device ID 1246 * 1247 * @return Device number. 1248 */ 1249 public int getDeviceID(); 1250 /** 1251 * @return control mode motor controller is in 1252 */ 1253 public ControlMode getControlMode(); 1254 // ----- Follower ------// 1255 /* in parent interface */ 1256}