Team2890/allwpilib
4
0
Fork 0
mirror of https://github.com/wpilibsuite/allwpilib synced 2026-07-05 03:21:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Fix docs for SysID routine (#6164)

Browse Source
This commit is contained in:
Eli Barnett
2024-01-06 01:05:09 -05:00
committed by GitHub
parent 0a46a3a618
commit a2e4d0b15d
4 changed files with 298 additions and 220 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/sysid/SysIdRoutine.java
View File

@@ -151,10 +151,11 @@ public class SysIdRoutine extends SysIdRoutineLog {
* *
* @param drive Sends the SysId-specified drive signal to the mechanism motors during test * @param drive Sends the SysId-specified drive signal to the mechanism motors during test
* routines. * routines.
* @param log Returns measured data (voltages, positions, velocities) of the mechanism motors * @param log Returns measured data of the mechanism motors during test routines. To return
* during test routines. To return data, call `recordFrame` on the supplied * data, call `motor(string motorName)` on the supplied `SysIdRoutineLog` instance, and then
* `SysIdRoutineLog` instance. Multiple motors can return data within a single `log` * call one or more of the chainable logging handles (e.g. `voltage`) on the returned
* callback by calling `recordFrame` multiple times. * `MotorLog`. Multiple motors can be logged in a single callback by calling `motor`
* multiple times.
* @param subsystem The subsystem containing the motor(s) that is (or are) being characterized. * @param subsystem The subsystem containing the motor(s) that is (or are) being characterized.
* Will be declared as a requirement for the returned test commands. * Will be declared as a requirement for the returned test commands.
* @param name The name of the mechanism being tested. Will be appended to the log entry title * @param name The name of the mechanism being tested. Will be appended to the log entry title
@@ -178,10 +179,11 @@ public class SysIdRoutine extends SysIdRoutineLog {
* *
* @param drive Sends the SysId-specified drive signal to the mechanism motors during test * @param drive Sends the SysId-specified drive signal to the mechanism motors during test
* routines. * routines.
* @param log Returns measured data (voltages, positions, velocities) of the mechanism motors * @param log Returns measured data of the mechanism motors during test routines. To return
* during test routines. To return data, call `recordFrame` on the supplied * data, call `motor(string motorName)` on the supplied `SysIdRoutineLog` instance, and then
* `SysIdRoutineLog` instance. Multiple motors can return data within a single `log` * call one or more of the chainable logging handles (e.g. `voltage`) on the returned
* callback by calling `recordFrame` multiple times. * `MotorLog`. Multiple motors can be logged in a single callback by calling `motor`
* multiple times.
* @param subsystem The subsystem containing the motor(s) that is (or are) being characterized. * @param subsystem The subsystem containing the motor(s) that is (or are) being characterized.
* Will be declared as a requirement for the returned test commands. The subsystem's `name` * Will be declared as a requirement for the returned test commands. The subsystem's `name`
* will be appended to the log entry title for the routine's test state, e.g. * will be appended to the log entry title for the routine's test state, e.g.

396
wpilibNewCommands/src/main/native/include/frc2/command/sysid/SysIdRoutine.h
View File

@@ -1,196 +1,200 @@
// Copyright (c) FIRST and other WPILib contributors. // Copyright (c) FIRST and other WPILib contributors.
// Open Source Software; you can modify and/or share it under the terms of // Open Source Software; you can modify and/or share it under the terms of
// the WPILib BSD license file in the root directory of this project. // the WPILib BSD license file in the root directory of this project.
#pragma once #pragma once
#include <functional> #include <functional>
#include <string> #include <string>
#include <string_view> #include <string_view>
#include <utility> #include <utility>
#include <frc/Timer.h> #include <frc/Timer.h>
#include <frc/sysid/SysIdRoutineLog.h> #include <frc/sysid/SysIdRoutineLog.h>
#include "frc2/command/CommandPtr.h" #include "frc2/command/CommandPtr.h"
#include "frc2/command/Subsystem.h" #include "frc2/command/Subsystem.h"
namespace frc2::sysid { namespace frc2::sysid {
using ramp_rate_t = units::unit_t< using ramp_rate_t = units::unit_t<
units::compound_unit<units::volt, units::inverse<units::second>>>; units::compound_unit<units::volt, units::inverse<units::second>>>;
/** Hardware-independent configuration for a SysId test routine. */ /** Hardware-independent configuration for a SysId test routine. */
class Config { class Config {
public: public:
/// The voltage ramp rate used for quasistatic test routines. /// The voltage ramp rate used for quasistatic test routines.
ramp_rate_t m_rampRate{1_V / 1_s}; ramp_rate_t m_rampRate{1_V / 1_s};
/// The step voltage output used for dynamic test routines. /// The step voltage output used for dynamic test routines.
units::volt_t m_stepVoltage{7_V}; units::volt_t m_stepVoltage{7_V};
/// Safety timeout for the test routine commands. /// Safety timeout for the test routine commands.
units::second_t m_timeout{10_s}; units::second_t m_timeout{10_s};
/// Optional handle for recording test state in a third-party logging /// Optional handle for recording test state in a third-party logging
/// solution. /// solution.
std::function<void(frc::sysid::State)> m_recordState; std::function<void(frc::sysid::State)> m_recordState;
/** /**
* Create a new configuration for a SysId test routine. * Create a new configuration for a SysId test routine.
* *
* @param rampRate The voltage ramp rate used for quasistatic test routines. * @param rampRate The voltage ramp rate used for quasistatic test routines.
* Defaults to 1 volt per second if left null. * Defaults to 1 volt per second if left null.
* @param stepVoltage The step voltage output used for dynamic test routines. * @param stepVoltage The step voltage output used for dynamic test routines.
* Defaults to 7 volts if left null. * Defaults to 7 volts if left null.
* @param timeout Safety timeout for the test routine commands. Defaults to 10 * @param timeout Safety timeout for the test routine commands. Defaults to 10
* seconds if left null. * seconds if left null.
* @param recordState Optional handle for recording test state in a * @param recordState Optional handle for recording test state in a
* third-party logging solution. If provided, the test routine state will be * third-party logging solution. If provided, the test routine state will be
* passed to this callback instead of logged in WPILog. * passed to this callback instead of logged in WPILog.
*/ */
Config(std::optional<ramp_rate_t> rampRate, Config(std::optional<ramp_rate_t> rampRate,
std::optional<units::volt_t> stepVoltage, std::optional<units::volt_t> stepVoltage,
std::optional<units::second_t> timeout, std::optional<units::second_t> timeout,
std::optional<std::function<void(frc::sysid::State)>> recordState) { std::optional<std::function<void(frc::sysid::State)>> recordState) {
if (rampRate) { if (rampRate) {
m_rampRate = rampRate.value(); m_rampRate = rampRate.value();
} }
if (stepVoltage) { if (stepVoltage) {
m_stepVoltage = stepVoltage.value(); m_stepVoltage = stepVoltage.value();
} }
if (timeout) { if (timeout) {
m_timeout = timeout.value(); m_timeout = timeout.value();
} }
if (recordState) { if (recordState) {
m_recordState = recordState.value(); m_recordState = recordState.value();
} }
} }
}; };
class Mechanism { class Mechanism {
public: public:
/// Sends the SysId-specified drive signal to the mechanism motors during test /// Sends the SysId-specified drive signal to the mechanism motors during test
/// routines. /// routines.
std::function<void(units::volt_t)> m_drive; std::function<void(units::volt_t)> m_drive;
/// Returns measured data (voltages, positions, velocities) of the mechanism /// Returns measured data (voltages, positions, velocities) of the mechanism
/// motors during test routines. /// motors during test routines.
std::function<void(frc::sysid::SysIdRoutineLog*)> m_log; std::function<void(frc::sysid::SysIdRoutineLog*)> m_log;
/// The subsystem containing the motor(s) that is (or are) being /// The subsystem containing the motor(s) that is (or are) being
/// characterized. /// characterized.
frc2::Subsystem* m_subsystem; frc2::Subsystem* m_subsystem;
/// The name of the mechanism being tested. Will be appended to the log entry /// The name of the mechanism being tested. Will be appended to the log entry
/// title for the routine's test state, e.g. "sysid-test-state-mechanism". /// title for the routine's test state, e.g. "sysid-test-state-mechanism".
std::string m_name; std::string m_name;
/** /**
* Create a new mechanism specification for a SysId routine. * Create a new mechanism specification for a SysId routine.
* *
* @param drive Sends the SysId-specified drive signal to the mechanism motors * @param drive Sends the SysId-specified drive signal to the mechanism motors
* during test routines. * during test routines.
* @param log Returns measured data (voltages, positions, velocities) of the * @param log Returns measured data of the mechanism motors during test
* mechanism motors during test routines. To return data, call `RecordFrame` * routines. To return data, call `Motor(string motorName)` on the supplied
* on the supplied `MotorLog` instance. Multiple motors can return data * `SysIdRoutineLog` instance, and then call one or more of the chainable
* within a single `log` callback by calling `RecordFrame` multiple times. * logging handles (e.g. `voltage`) on the returned `MotorLog`. Multiple
* @param subsystem The subsystem containing the motor(s) that is (or are) * motors can be logged in a single callback by calling `Motor` multiple
* being characterized. Will be declared as a requirement for the returned * times.
* test commands. * @param subsystem The subsystem containing the motor(s) that is (or are)
* @param name The name of the mechanism being tested. Will be appended to the * being characterized. Will be declared as a requirement for the returned
* log entry * title for the routine's test state, e.g. * test commands.
* "sysid-test-state-mechanism". Defaults to the name of the subsystem if * @param name The name of the mechanism being tested. Will be appended to the
* left null. * log entry * title for the routine's test state, e.g.
*/ * "sysid-test-state-mechanism". Defaults to the name of the subsystem if
Mechanism(std::function<void(units::volt_t)> drive, * left null.
std::function<void(frc::sysid::SysIdRoutineLog*)> log, */
frc2::Subsystem* subsystem, std::string_view name) Mechanism(std::function<void(units::volt_t)> drive,
: m_drive{std::move(drive)}, std::function<void(frc::sysid::SysIdRoutineLog*)> log,
m_log{std::move(log)}, frc2::Subsystem* subsystem, std::string_view name)
m_subsystem{subsystem}, : m_drive{std::move(drive)},
m_name{name} {} m_log{std::move(log)},
m_subsystem{subsystem},
/** m_name{name} {}
* Create a new mechanism specification for a SysId routine. Defaults the
* mechanism name to the subsystem name. /**
* * Create a new mechanism specification for a SysId routine. Defaults the
* @param drive Sends the SysId-specified drive signal to the mechanism motors * mechanism name to the subsystem name.
* during test routines. *
* @param log Returns measured data (voltages, positions, velocities) of the * @param drive Sends the SysId-specified drive signal to the mechanism motors
* mechanism motors during test routines. To return data, call `recordFrame` * during test routines.
* on the supplied `MotorLog` instance. Multiple motors can return data * @param log Returns measured data of the mechanism motors during test
* within a single `log` callback by calling `recordFrame` multiple times. * routines. To return data, call `Motor(string motorName)` on the supplied
* @param subsystem The subsystem containing the motor(s) that is (or are) * `SysIdRoutineLog` instance, and then call one or more of the chainable
* being characterized. Will be declared as a requirement for the returned * logging handles (e.g. `voltage`) on the returned `MotorLog`. Multiple
* test commands. The subsystem's `name` will be appended to the log entry * motors can be logged in a single callback by calling `Motor` multiple
* title for the routine's test state, e.g. "sysid-test-state-subsystem". * times.
*/ * @param subsystem The subsystem containing the motor(s) that is (or are)
Mechanism(std::function<void(units::volt_t)> drive, * being characterized. Will be declared as a requirement for the returned
std::function<void(frc::sysid::SysIdRoutineLog*)> log, * test commands. The subsystem's `name` will be appended to the log entry
frc2::Subsystem* subsystem) * title for the routine's test state, e.g. "sysid-test-state-subsystem".
: m_drive{std::move(drive)}, */
m_log{std::move(log)}, Mechanism(std::function<void(units::volt_t)> drive,
m_subsystem{subsystem}, std::function<void(frc::sysid::SysIdRoutineLog*)> log,
m_name{m_subsystem->GetName()} {} frc2::Subsystem* subsystem)
}; : m_drive{std::move(drive)},
m_log{std::move(log)},
/** m_subsystem{subsystem},
* Motor direction for a SysId test. m_name{m_subsystem->GetName()} {}
*/ };
enum Direction {
/// Forward. /**
kForward, * Motor direction for a SysId test.
/// Reverse. */
kReverse enum Direction {
}; /// Forward.
kForward,
/** /// Reverse.
* A SysId characterization routine for a single mechanism. Mechanisms may have kReverse
* multiple motors. };
*
* A single subsystem may have multiple mechanisms, but mechanisms should not /**
* share test routines. Each complete test of a mechanism should have its own * A SysId characterization routine for a single mechanism. Mechanisms may have
* SysIdRoutine instance, since the log name of the recorded data is determined * multiple motors.
* by the mechanism name. *
* * A single subsystem may have multiple mechanisms, but mechanisms should not
* The test state (e.g. "quasistatic-forward") is logged once per iteration * share test routines. Each complete test of a mechanism should have its own
* during test execution, and once with state "none" when a test ends. Motor * SysIdRoutine instance, since the log name of the recorded data is determined
* frames are logged every iteration during test execution. * by the mechanism name.
* *
* Timestamps are not coordinated across data, so motor frames and test state * The test state (e.g. "quasistatic-forward") is logged once per iteration
* tags may be recorded on different log frames. Because frame alignment is not * during test execution, and once with state "none" when a test ends. Motor
* guaranteed, SysId parses the log by using the test state flag to determine * frames are logged every iteration during test execution.
* the timestamp range for each section of the test, and then extracts the motor *
* frames within the valid timestamp ranges. If a given test was run multiple * Timestamps are not coordinated across data, so motor frames and test state
* times in a single logfile, the user will need to select which of the tests to * tags may be recorded on different log frames. Because frame alignment is not
* use for the fit in the analysis tool. * guaranteed, SysId parses the log by using the test state flag to determine
*/ * the timestamp range for each section of the test, and then extracts the motor
class SysIdRoutine : public frc::sysid::SysIdRoutineLog { * frames within the valid timestamp ranges. If a given test was run multiple
public: * times in a single logfile, the user will need to select which of the tests to
/** * use for the fit in the analysis tool.
* Create a new SysId characterization routine. */
* class SysIdRoutine : public frc::sysid::SysIdRoutineLog {
* @param config Hardware-independent parameters for the SysId routine. public:
* @param mechanism Hardware interface for the SysId routine. /**
*/ * Create a new SysId characterization routine.
SysIdRoutine(Config config, Mechanism mechanism) *
: SysIdRoutineLog(mechanism.m_subsystem->GetName()), * @param config Hardware-independent parameters for the SysId routine.
m_config(config), * @param mechanism Hardware interface for the SysId routine.
m_mechanism(mechanism), */
m_recordState(config.m_recordState ? config.m_recordState SysIdRoutine(Config config, Mechanism mechanism)
: [this](frc::sysid::State state) { : SysIdRoutineLog(mechanism.m_subsystem->GetName()),
this->RecordState(state); m_config(config),
}) {} m_mechanism(mechanism),
m_recordState(config.m_recordState ? config.m_recordState
frc2::CommandPtr Quasistatic(Direction direction); : [this](frc::sysid::State state) {
frc2::CommandPtr Dynamic(Direction direction); this->RecordState(state);
}) {}
private:
Config m_config; frc2::CommandPtr Quasistatic(Direction direction);
Mechanism m_mechanism; frc2::CommandPtr Dynamic(Direction direction);
units::volt_t m_outputVolts{0};
std::function<void(frc::sysid::State)> m_recordState; private:
frc::Timer timer; Config m_config;
}; Mechanism m_mechanism;
} // namespace frc2::sysid units::volt_t m_outputVolts{0};
std::function<void(frc::sysid::State)> m_recordState;
frc::Timer timer;
};
} // namespace frc2::sysid

78
wpilibc/src/main/native/include/frc/sysid/SysIdRoutineLog.h
View File

@@ -46,46 +46,112 @@ class SysIdRoutineLog {
using LogEntries = wpi::StringMap<MotorEntries>; using LogEntries = wpi::StringMap<MotorEntries>;
public: public:
/** Logs data from a single motor during a SysIdRoutine. */
class MotorLog { class MotorLog {
public: public:
MotorLog(std::string_view motorName, std::string_view logName, /**
LogEntries* logEntries); * Log a generic data value from the motor.
*
* @param name The name of the data field being recorded.
* @param value The numeric value of the data field.
* @param unit The unit string of the data field.
* @return The motor log (for call chaining).
*/
MotorLog& value(std::string_view name, double value, std::string_view unit); MotorLog& value(std::string_view name, double value, std::string_view unit);
/**
* Log the voltage applied to the motor.
*
* @param voltage The voltage to record.
* @return The motor log (for call chaining).
*/
MotorLog& voltage(units::volt_t voltage) { MotorLog& voltage(units::volt_t voltage) {
return value("voltage", voltage.value(), voltage.name()); return value("voltage", voltage.value(), voltage.name());
} }
/**
* Log the linear position of the motor.
*
* @param position The linear position to record.
* @return The motor log (for call chaining).
*/
MotorLog& position(units::meter_t position) { MotorLog& position(units::meter_t position) {
return value("position", position.value(), position.name()); return value("position", position.value(), position.name());
} }
/**
* Log the angular position of the motor.
*
* @param position The angular position to record.
* @return The motor log (for call chaining).
*/
MotorLog& position(units::turn_t position) { MotorLog& position(units::turn_t position) {
return value("position", position.value(), position.name()); return value("position", position.value(), position.name());
} }
/**
* Log the linear velocity of the motor.
*
* @param velocity The linear velocity to record.
* @return The motor log (for call chaining).
*/
MotorLog& velocity(units::meters_per_second_t velocity) { MotorLog& velocity(units::meters_per_second_t velocity) {
return value("velocity", velocity.value(), velocity.name()); return value("velocity", velocity.value(), velocity.name());
} }
/**
* Log the angular velocity of the motor.
*
* @param velocity The angular velocity to record.
* @return The motor log (for call chaining).
*/
MotorLog& velocity(units::turns_per_second_t velocity) { MotorLog& velocity(units::turns_per_second_t velocity) {
return value("velocity", velocity.value(), velocity.name()); return value("velocity", velocity.value(), velocity.name());
} }
/**
* Log the linear acceleration of the motor.
*
* @param acceleration The linear acceleration to record.
* @return The motor log (for call chaining).
*/
MotorLog& acceleration(units::meters_per_second_squared_t acceleration) { MotorLog& acceleration(units::meters_per_second_squared_t acceleration) {
return value("acceleration", acceleration.value(), acceleration.name()); return value("acceleration", acceleration.value(), acceleration.name());
} }
/**
* Log the angular acceleration of the motor.
*
* @param acceleration The angular acceleration to record.
* @return The motor log (for call chaining).
*/
MotorLog& acceleration(units::turns_per_second_squared_t acceleration) { MotorLog& acceleration(units::turns_per_second_squared_t acceleration) {
return value("acceleration", acceleration.value(), acceleration.name()); return value("acceleration", acceleration.value(), acceleration.name());
} }
/**
* Log the current applied to the motor.
*
* @param current The current to record.
* @return The motor log (for call chaining).
*/
MotorLog& current(units::ampere_t current) { MotorLog& current(units::ampere_t current) {
return value("current", current.value(), current.name()); return value("current", current.value(), current.name());
} }
private: private:
friend class SysIdRoutineLog;
/**
* Create a new SysId motor log handle.
*
* @param motorName The name of the motor whose data is being logged.
* @param logName The name of the SysIdRoutineLog that this motor belongs
* to.
* @param logEntries The DataLog entries of the SysIdRoutineLog that this
* motor belongs to.
*/
MotorLog(std::string_view motorName, std::string_view logName,
LogEntries* logEntries);
std::string m_motorName; std::string m_motorName;
std::string m_logName; std::string m_logName;
LogEntries* m_logEntries; LogEntries* m_logEntries;
@@ -110,6 +176,12 @@ class SysIdRoutineLog {
*/ */
void RecordState(State state); void RecordState(State state);
/**
* Log data from a motor during a SysId routine.
*
* @param motorName The name of the motor.
* @return Handle with chainable callbacks to log individual data fields.
*/
MotorLog Motor(std::string_view motorName); MotorLog Motor(std::string_view motorName);
static std::string StateEnumToString(State state); static std::string StateEnumToString(State state);

26
wpilibj/src/main/java/edu/wpi/first/wpilibj/sysid/SysIdRoutineLog.java
View File

@@ -73,7 +73,7 @@ public class SysIdRoutineLog {
} }
} }
/** Allows logging of data for a single motor during a SysIdRoutine. */ /** Logs data from a single motor during a SysIdRoutine. */
public class MotorLog { public class MotorLog {
private final String m_motorName; private final String m_motorName;
@@ -88,7 +88,7 @@ public class SysIdRoutineLog {
} }
/** /**
* Record a generic data value from this motor. * Log a generic data value from the motor.
* *
* @param name The name of the data field being recorded. * @param name The name of the data field being recorded.
* @param value The numeric value of the data field. * @param value The numeric value of the data field.
@@ -111,7 +111,7 @@ public class SysIdRoutineLog {
} }
/** /**
* Record a voltage value from this motor. * Log the voltage applied to the motor.
* *
* @param voltage The voltage to record. * @param voltage The voltage to record.
* @return The motor log (for call chaining). * @return The motor log (for call chaining).
@@ -121,7 +121,7 @@ public class SysIdRoutineLog {
} }
/** /**
* Record a linear position value from this motor. * Log the linear position of the motor.
* *
* @param position The linear position to record. * @param position The linear position to record.
* @return The motor log (for call chaining). * @return The motor log (for call chaining).
@@ -131,7 +131,7 @@ public class SysIdRoutineLog {
} }
/** /**
* Record an angular position value from this motor. * Log the angular position of the motor.
* *
* @param position The angular position to record. * @param position The angular position to record.
* @return The motor log (for call chaining). * @return The motor log (for call chaining).
@@ -141,7 +141,7 @@ public class SysIdRoutineLog {
} }
/** /**
* Record a linear velocity value from this motor. * Log the linear velocity of the motor.
* *
* @param velocity The linear velocity to record. * @param velocity The linear velocity to record.
* @return The motor log (for call chaining). * @return The motor log (for call chaining).
@@ -151,7 +151,7 @@ public class SysIdRoutineLog {
} }
/** /**
* Record an angular velocity value from this motor. * Log the angular velocity of the motor.
* *
* @param velocity The angular velocity to record. * @param velocity The angular velocity to record.
* @return The motor log (for call chaining). * @return The motor log (for call chaining).
@@ -161,7 +161,7 @@ public class SysIdRoutineLog {
} }
/** /**
* Record a linear acceleration value from this motor. * Log the linear acceleration of the motor.
* *
* @param acceleration The linear acceleration to record. * @param acceleration The linear acceleration to record.
* @return The motor log (for call chaining). * @return The motor log (for call chaining).
@@ -174,7 +174,7 @@ public class SysIdRoutineLog {
} }
/** /**
* Record an angular acceleration value from this motor. * Log the angular acceleration of the motor.
* *
* @param acceleration The angular acceleration to record. * @param acceleration The angular acceleration to record.
* @return The motor log (for call chaining). * @return The motor log (for call chaining).
@@ -187,7 +187,7 @@ public class SysIdRoutineLog {
} }
/** /**
* Record a current value for this motor. * Log the current applied to the motor.
* *
* @param current The current to record. * @param current The current to record.
* @return The motor log (for call chaining). * @return The motor log (for call chaining).
@@ -199,10 +199,10 @@ public class SysIdRoutineLog {
} }
/** /**
* Returns the logging handle for a given motor. * Log data from a motor during a SysId routine.
* *
* @param motorName The name of the motor to log data from. * @param motorName The name of the motor.
* @return The logging handle for the specified motor. * @return Handle with chainable callbacks to log individual data fields.
*/ */
public MotorLog motor(String motorName) { public MotorLog motor(String motorName) {
return new MotorLog(motorName); return new MotorLog(motorName);