From 061900a8e38df2d16edc025ffb87b52b50ed49fb Mon Sep 17 00:00:00 2001 From: vivi-o Date: Sun, 24 Aug 2025 11:06:24 -0700 Subject: [PATCH 1/8] appending sim article with new links and details --- Docs/2_Architecture/2.8_Simulation.md | 55 ++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/Docs/2_Architecture/2.8_Simulation.md b/Docs/2_Architecture/2.8_Simulation.md index 94bac2c..777f319 100644 --- a/Docs/2_Architecture/2.8_Simulation.md +++ b/Docs/2_Architecture/2.8_Simulation.md @@ -2,11 +2,15 @@ ## Simulation is the process of running our robot code on a computer other than the robot to test it without being limited by physical hardware +### overview + Generally speaking, simulation depends on sending the inputs we would like to test to a model of a system (mechanism) and analyzing the simulated results. There are several ways to do this, depending on what you’re simulating. This could be something small, like simulated readings of an encoder, or something more complex, like a physics simulation of an arm. Simulation is important for a couple of reasons—we can test something without risking breaking an actual physical part, as well as being able to concurrently develop code as those physical components are being built (which is often the case during the build season). +### sim GUI + We have a number of tools at our disposal for simulation. One is WPILib’s built in desktop simulation. This handles the process of sending inputs (from joysticks, widgets in the sim dashboard, etc) and running robot code on a computer. @@ -45,24 +49,71 @@ We tend to use one or two of these per robot for major mechanisms. If you want to learn more about this sort of modeling, look at the [control theory for FRC book](https://file.tavsys.net/control/controls-engineering-in-frc.pdf). Note that the topics covered by this book are largely far more advanced than high schoolers have the math background for, and it is not required reading. +### AdvantageScope + Running a model is useful, but even more useful is being able to visualize the output of the model. There are several dashboards you can use to do this, but we mainly use AdvantageScope. [AdvantageScope](https://github.com/Mechanical-Advantage/AdvantageScope) is a tool developed by Team 6328 to visualize data from live robots, simulated robots, and robot logs. -It provides a variety of formats to visualize data from line graphs to 3d field models to tables and more. +It provides a variety of formats to visualize data. These applications include things like line graphs, 2d field modeling, 3d robot modeling, tables, timeline plots, custom widgets, and more. Screenshot of Advantagescope +This way we can run autonomous routines, drive around in sim, test mechanisms, and even run 3d calcultions like localizing with april tags, all without requiring the robot. + +3d modeling requires us to import and configure any 3d CAD robot models and field components we want to use. Our team prefers this approach because it's helpful to visualise and test the full robot and all its components. In the simulator, both 2D and 3D geometry types are supported, such as, Pose2d, Pose3d, Translation2d, and Translation3d. + It is closely integrated with AdvantageKit, a logging framework also from Team 6328, but does not require it. +- [general advantagescope documentation](https://docs.advantagescope.org/) +- [more details about the 3d field](https://docs.advantagescope.org/tab-reference/3d-field) +- [custom assets](https://docs.advantagescope.org/more-features/custom-assets) +- in order to implement these custom models CAD models with have to be converted into the gITF format, as cad isn't supported [tutorial](https://docs.advantagescope.org/more-features/gltf-convert) + +### MapleSim +Our team also integrates MapleSim into the robot code. Maple sim supports more complex physics simulations. Maple sim allows us to represent motors, encoder, and senors, instead of just modeling kinematics. This lets us test and tune the robot behavior in a more realistic way. + +[more details](https://shenzhen-robotics-alliance.github.io/maple-sim/) + +### WPIlib Sim Classes +WPILib provides sim classes such as ElevatorSim and SingledJointedArmSIm. These require parameters such as gear ratios, mass, and motor types so the simulation knows how to behave. Once we set up the simulation we can use it to test our code against a virtual mechanism. + +Go [here](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/simulation/package-summary.html) to check out the specific classes and methods + +take a look at this quick example: +```Java +new ElevatorSim( + DCMotor.getKrakenX60Foc(1), //gear box: type of motor and number of motors + ElevatorSubsystem.GEAR_RATIO, //gearing: gear ratio + Units.lbsToKilograms(7.0 + (3.25 / 2)), //carriage mass: mass of elevator carriage + ElevatorSubsystem.DRUM_RADIUS_METERS, // drumRadiusMeters: radius of the drum the elevator spool is wrapped around + 0.0, // minHeightMeters: the minimum height + ElevatorSubsystem.MAX_EXTENSION_METERS, // maxHeightMeters: the maxium height + true, // simumateGravity: should gravity be simulated? + 0.0); //measurementStdDevs: standard deviation of measurements +``` + +### sim vs real + The final major tool is being able to swap between simulated inputs and outputs (IO) and real IO easily and correctly. We will cover what this looks like with AdvantageKit [here](AdvantageKit.md), but at a high level, this means that we have both a sim and real version of each mechanism in our code. This is so we can easily test our code in sim and have minimal work to move it to real hardware. +
+More details on Sim vs Real immplementation + +The real IO layer controls the actual motors, sensors, and hardware on the robot. Sim IO replaces those with the simulated versions that approximate how the robot component should behave. The code structure differs because the real code deals with initializing, configuring, and driving hardware like Talons or CANcoders, while sim code uses simulation classes, like ELevatorSIm, to mimic their behavior. + +As you look through the code, you'll notice that real handles initializing motors, configurations, and hardware based commands, whereas sim uses methods from the sim classes. + +if you want to take a closer look at what the specific code looks like follow along with [this tutorial](Docs/2_Architecture/2.9_KitbotExampleWalkthroughSim.md) for kitBot sim +--- +
### Resources - Read through the [WPILib docs intro to simulation](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/introduction.html). - Optional additional reading on [state space modeling](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/state-space/state-space-intro.html) +- [WPILib simulations](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/simulation/package-summary.html) ### Examples @@ -71,7 +122,7 @@ This is so we can easily test our code in sim and have minimal work to move it t ### Exercises - Download and install [AdvantageScope](https://github.com/Mechanical-Advantage/AdvantageScope). -- Follow [this tutorial](KitbotExampleWalkthroughSim.md) to convert your kitbot code to AdvantageKit and simulation. +- Follow [this tutorial](Docs/2_Architecture/2.9_KitbotExampleWalkthroughSim.md) to convert your kitbot code to AdvantageKit and simulation. ### Notes From b2b0ff6989559aa839669568fa472072fb09609f Mon Sep 17 00:00:00 2001 From: vivi-o Date: Thu, 28 Aug 2025 19:57:04 -0700 Subject: [PATCH 2/8] fixing typos/misspellings --- Docs/2_Architecture/2.8_Simulation.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Docs/2_Architecture/2.8_Simulation.md b/Docs/2_Architecture/2.8_Simulation.md index 777f319..918af3d 100644 --- a/Docs/2_Architecture/2.8_Simulation.md +++ b/Docs/2_Architecture/2.8_Simulation.md @@ -12,7 +12,7 @@ Simulation is important for a couple of reasons—we can test something without ### sim GUI We have a number of tools at our disposal for simulation. -One is WPILib’s built in desktop simulation. +One is WPILib’s built-in desktop simulation. This handles the process of sending inputs (from joysticks, widgets in the sim dashboard, etc) and running robot code on a computer. This is the backbone of our simulation. @@ -58,7 +58,7 @@ It provides a variety of formats to visualize data. These applications include t Screenshot of Advantagescope -This way we can run autonomous routines, drive around in sim, test mechanisms, and even run 3d calcultions like localizing with april tags, all without requiring the robot. +This way we can run autonomous routines, drive around in sim, test mechanisms, and even run 3d calculations like localizing with april tags, all without requiring the robot. 3d modeling requires us to import and configure any 3d CAD robot models and field components we want to use. Our team prefers this approach because it's helpful to visualise and test the full robot and all its components. In the simulator, both 2D and 3D geometry types are supported, such as, Pose2d, Pose3d, Translation2d, and Translation3d. @@ -70,7 +70,7 @@ It is closely integrated with AdvantageKit, a logging framework also from Team 6 - in order to implement these custom models CAD models with have to be converted into the gITF format, as cad isn't supported [tutorial](https://docs.advantagescope.org/more-features/gltf-convert) ### MapleSim -Our team also integrates MapleSim into the robot code. Maple sim supports more complex physics simulations. Maple sim allows us to represent motors, encoder, and senors, instead of just modeling kinematics. This lets us test and tune the robot behavior in a more realistic way. +Our team also integrates MapleSim into the robot code. Maple sim supports more complex physics simulations. Maple sim allows us to represent motors, encoder, and sensors, instead of just modeling kinematics. This lets us test and tune the robot behavior in a more realistic way. [more details](https://shenzhen-robotics-alliance.github.io/maple-sim/) @@ -99,13 +99,14 @@ We will cover what this looks like with AdvantageKit [here](AdvantageKit.md), bu This is so we can easily test our code in sim and have minimal work to move it to real hardware.
-More details on Sim vs Real immplementation +More details on Sim vs Real implementation The real IO layer controls the actual motors, sensors, and hardware on the robot. Sim IO replaces those with the simulated versions that approximate how the robot component should behave. The code structure differs because the real code deals with initializing, configuring, and driving hardware like Talons or CANcoders, while sim code uses simulation classes, like ELevatorSIm, to mimic their behavior. As you look through the code, you'll notice that real handles initializing motors, configurations, and hardware based commands, whereas sim uses methods from the sim classes. if you want to take a closer look at what the specific code looks like follow along with [this tutorial](Docs/2_Architecture/2.9_KitbotExampleWalkthroughSim.md) for kitBot sim + ---
@@ -126,7 +127,7 @@ if you want to take a closer look at what the specific code looks like follow al ### Notes -- Structuring a codebase to be simulateable is not an easy task. +- Structuring a codebase to be simulatable is not an easy task. It is important to be familiar with the tools we have and stick to a clean structure to make it easy to simulate our code. - Code that has been tested in sim does not necessarily work on the robot. Be sure to stay safe and prepare for unexpected behavior when testing, especially for the first time. \ No newline at end of file From 794b1bdbd0ebb3fc68db97e93e02bc0a27188842 Mon Sep 17 00:00:00 2001 From: vivi-o Date: Thu, 28 Aug 2025 20:05:55 -0700 Subject: [PATCH 3/8] making it one sentence per line --- Docs/2_Architecture/2.8_Simulation.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/Docs/2_Architecture/2.8_Simulation.md b/Docs/2_Architecture/2.8_Simulation.md index 918af3d..2c37a48 100644 --- a/Docs/2_Architecture/2.8_Simulation.md +++ b/Docs/2_Architecture/2.8_Simulation.md @@ -60,7 +60,9 @@ It provides a variety of formats to visualize data. These applications include t This way we can run autonomous routines, drive around in sim, test mechanisms, and even run 3d calculations like localizing with april tags, all without requiring the robot. -3d modeling requires us to import and configure any 3d CAD robot models and field components we want to use. Our team prefers this approach because it's helpful to visualise and test the full robot and all its components. In the simulator, both 2D and 3D geometry types are supported, such as, Pose2d, Pose3d, Translation2d, and Translation3d. +3d modeling requires us to import and configure any 3d CAD robot models and field components we want to use. +Our team prefers this approach because it's helpful to visualise and test the full robot and all its components. +In the simulator, both 2D and 3D geometry types are supported, such as, Pose2d, Pose3d, Translation2d, and Translation3d. It is closely integrated with AdvantageKit, a logging framework also from Team 6328, but does not require it. @@ -70,12 +72,16 @@ It is closely integrated with AdvantageKit, a logging framework also from Team 6 - in order to implement these custom models CAD models with have to be converted into the gITF format, as cad isn't supported [tutorial](https://docs.advantagescope.org/more-features/gltf-convert) ### MapleSim -Our team also integrates MapleSim into the robot code. Maple sim supports more complex physics simulations. Maple sim allows us to represent motors, encoder, and sensors, instead of just modeling kinematics. This lets us test and tune the robot behavior in a more realistic way. +Our team also integrates MapleSim into the robot code. +Maple sim supports more complex physics simulations. +Maple sim allows us to represent motors, encoder, and sensors, instead of just modeling kinematics. +This lets us test and tune the robot behavior in a more realistic way. [more details](https://shenzhen-robotics-alliance.github.io/maple-sim/) ### WPIlib Sim Classes -WPILib provides sim classes such as ElevatorSim and SingledJointedArmSIm. These require parameters such as gear ratios, mass, and motor types so the simulation knows how to behave. Once we set up the simulation we can use it to test our code against a virtual mechanism. +WPILib provides sim classes such as ElevatorSim and SingledJointedArmSIm. These require parameters such as gear ratios, mass, and motor types so the simulation knows how to behave. +Once we set up the simulation we can use it to test our code against a virtual mechanism. Go [here](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/simulation/package-summary.html) to check out the specific classes and methods @@ -101,7 +107,8 @@ This is so we can easily test our code in sim and have minimal work to move it t
More details on Sim vs Real implementation -The real IO layer controls the actual motors, sensors, and hardware on the robot. Sim IO replaces those with the simulated versions that approximate how the robot component should behave. The code structure differs because the real code deals with initializing, configuring, and driving hardware like Talons or CANcoders, while sim code uses simulation classes, like ELevatorSIm, to mimic their behavior. +The real IO layer controls the actual motors, sensors, and hardware on the robot. Sim IO replaces those with the simulated versions that approximate how the robot component should behave. +The code structure differs because the real code deals with initializing, configuring, and driving hardware like Talons or CANcoders, while sim code uses simulation classes, like ELevatorSIm, to mimic their behavior. As you look through the code, you'll notice that real handles initializing motors, configurations, and hardware based commands, whereas sim uses methods from the sim classes. From 27598bae362957638a53af9f4421f76b1dc7cbe3 Mon Sep 17 00:00:00 2001 From: vivi-o Date: Thu, 28 Aug 2025 20:38:14 -0700 Subject: [PATCH 4/8] update links --- Docs/2_Architecture/2.8_Simulation.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Docs/2_Architecture/2.8_Simulation.md b/Docs/2_Architecture/2.8_Simulation.md index 2c37a48..68b6b1f 100644 --- a/Docs/2_Architecture/2.8_Simulation.md +++ b/Docs/2_Architecture/2.8_Simulation.md @@ -101,7 +101,7 @@ new ElevatorSim( ### sim vs real The final major tool is being able to swap between simulated inputs and outputs (IO) and real IO easily and correctly. -We will cover what this looks like with AdvantageKit [here](AdvantageKit.md), but at a high level, this means that we have both a sim and real version of each mechanism in our code. +We will cover what this looks like with AdvantageKit [here](https://github.com/HighlanderRobotics/Highlanders-Training/blob/c79d758fda0429e41651b35bf9bfec68248e90c5/Docs/2_Architecture/2.6_AdvantageKit.md#L4), but at a high level, this means that we have both a sim and real version of each mechanism in our code. This is so we can easily test our code in sim and have minimal work to move it to real hardware.
@@ -112,7 +112,7 @@ The code structure differs because the real code deals with initializing, config As you look through the code, you'll notice that real handles initializing motors, configurations, and hardware based commands, whereas sim uses methods from the sim classes. -if you want to take a closer look at what the specific code looks like follow along with [this tutorial](Docs/2_Architecture/2.9_KitbotExampleWalkthroughSim.md) for kitBot sim +if you want to take a closer look at what the specific code looks like follow along with [this tutorial](https://github.com/HighlanderRobotics/Highlanders-Training/blob/c79d758fda0429e41651b35bf9bfec68248e90c5/Docs/2_Architecture/2.9_KitbotExampleWalkthroughSim.md#L4) for kitBot sim ---
@@ -125,12 +125,11 @@ if you want to take a closer look at what the specific code looks like follow al ### Examples -- The [kitbot example code](../../Examples/KitbotDemoSim) - +- The [kitbot example code](../../Examples/KitbotDemoSim) ### Exercises - Download and install [AdvantageScope](https://github.com/Mechanical-Advantage/AdvantageScope). -- Follow [this tutorial](Docs/2_Architecture/2.9_KitbotExampleWalkthroughSim.md) to convert your kitbot code to AdvantageKit and simulation. +- Follow [this tutorial](https://github.com/HighlanderRobotics/Highlanders-Training/blob/c79d758fda0429e41651b35bf9bfec68248e90c5/Docs/2_Architecture/2.9_KitbotExampleWalkthroughSim.md#L4) to convert your kitbot code to AdvantageKit and simulation. ### Notes From 7a4be87fc4be347b8f3fbe00d7f524def4dc090d Mon Sep 17 00:00:00 2001 From: vivi-o Date: Thu, 28 Aug 2025 21:14:23 -0700 Subject: [PATCH 5/8] sim vs real updates --- Docs/2_Architecture/2.8_Simulation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Docs/2_Architecture/2.8_Simulation.md b/Docs/2_Architecture/2.8_Simulation.md index 68b6b1f..9be92e0 100644 --- a/Docs/2_Architecture/2.8_Simulation.md +++ b/Docs/2_Architecture/2.8_Simulation.md @@ -108,7 +108,7 @@ This is so we can easily test our code in sim and have minimal work to move it t More details on Sim vs Real implementation The real IO layer controls the actual motors, sensors, and hardware on the robot. Sim IO replaces those with the simulated versions that approximate how the robot component should behave. -The code structure differs because the real code deals with initializing, configuring, and driving hardware like Talons or CANcoders, while sim code uses simulation classes, like ELevatorSIm, to mimic their behavior. +The overall code structure is the same; however, the specific differs. To elaborate, in the real code, this means dealing with initializing, configuring, and driving hardware like Talons or CANcoders, while sim code uses simulation classes, like ElevatorSim, to mimic their behavior. As you look through the code, you'll notice that real handles initializing motors, configurations, and hardware based commands, whereas sim uses methods from the sim classes. From 9f826c9cb1a66d89d85e7f3a3ef75621483e18f2 Mon Sep 17 00:00:00 2001 From: vivi-o Date: Sun, 31 Aug 2025 00:39:56 -0700 Subject: [PATCH 6/8] updates, photos, and code snippets --- Docs/2_Architecture/2.8_Simulation.md | 62 ++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 7 deletions(-) diff --git a/Docs/2_Architecture/2.8_Simulation.md b/Docs/2_Architecture/2.8_Simulation.md index 9be92e0..f4737a5 100644 --- a/Docs/2_Architecture/2.8_Simulation.md +++ b/Docs/2_Architecture/2.8_Simulation.md @@ -59,23 +59,73 @@ It provides a variety of formats to visualize data. These applications include t Screenshot of Advantagescope This way we can run autonomous routines, drive around in sim, test mechanisms, and even run 3d calculations like localizing with april tags, all without requiring the robot. +Another major feature of AdvantageScope is the ability to log telemetry and replay runs. +This is helpful for collecting data, replaying matches, and comparing sim with the real results. +It is closely integrated with AdvantageKit, a logging framework also from Team 6328, but does not require it. + +- [general advantagescope documentation](https://docs.advantagescope.org/) + +### 3d modeling 3d modeling requires us to import and configure any 3d CAD robot models and field components we want to use. Our team prefers this approach because it's helpful to visualise and test the full robot and all its components. In the simulator, both 2D and 3D geometry types are supported, such as, Pose2d, Pose3d, Translation2d, and Translation3d. -It is closely integrated with AdvantageKit, a logging framework also from Team 6328, but does not require it. +Screenshot of Advantagescope 3d field -- [general advantagescope documentation](https://docs.advantagescope.org/) - [more details about the 3d field](https://docs.advantagescope.org/tab-reference/3d-field) - [custom assets](https://docs.advantagescope.org/more-features/custom-assets) - in order to implement these custom models CAD models with have to be converted into the gITF format, as cad isn't supported [tutorial](https://docs.advantagescope.org/more-features/gltf-convert) +### 2d mechanism modeling +Mechanism2d is an object which proves simple 2D visualization of mechanisms. +Setting up the mechanism 2d involves: +- creating a new Mechanism2d object +- defining a root node where the mechanism is anchored (this can be a pivot point or robot base) using MechanismRoot2d. +- Finally we append existing nodes or ligaments with MechanismLigament2d to add more components. +For instance, with Mechanism2d, we can create a shoulder mechanism and add the wrist to it as a ligament. +You can define linkages, arms, elevators, etc and update their state in code. +This can be displayed in Sim GUI, and is also compatible with AdvantageScopes 2D & 3D visualization tools + +example code: +```Java + // Mechanisms + private final LoggedMechanism2d elevatorMech2d = + new LoggedMechanism2d(3.0, 4.0); //width, height + private final LoggedMechanismRoot2d + elevatorRoot = elevatorMech2d.getRoot("Elevator", 21.5, 0.0); //name, x, y + private final LoggedMechanismLigament2d carriageLigament = + new LoggedMechanismLigament2d("Carriage", 0, ELEVATOR_ANGLE.getDegrees()); //name, length, angle + // Append carriage ligament to be based on elevator root + elevatorRoot.append(carriageLigament); +``` + +Screenshot of Advantagescope with mech 2d + +more details: +- [WPILib docs](https://docs.wpilib.org/en/stable/docs/software/dashboards/glass/mech2d-widget.html) +- [WPILib API Reference](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/smartdashboard/Mechanism2d.html) + ### MapleSim Our team also integrates MapleSim into the robot code. Maple sim supports more complex physics simulations. Maple sim allows us to represent motors, encoder, and sensors, instead of just modeling kinematics. -This lets us test and tune the robot behavior in a more realistic way. +This lets us test and tune the robot behavior in a more realistic way. It can simulate voltages, currents, and handle collisions with the field and other obstacles. + +example code: +```Java +//simulate drive motor with MapleSim + simulation.useDriveMotorController( + new MaplePhoenixUtil.TalonFXMotorControllerSim(driveTalon, true)); +//simulate steer motor with MapleSim and remote CANcoder + simulation.useSteerMotorController( + new MaplePhoenixUtil.TalonFXMotorControllerWithRemoteCancoderSim( + turnTalon, + swerveConstants.getTurnMotorInverted(), + cancoder, + false, + Angle.ofBaseUnits(moduleConstants.cancoderOffset().getRadians(), Radian))); +``` [more details](https://shenzhen-robotics-alliance.github.io/maple-sim/) @@ -104,18 +154,16 @@ The final major tool is being able to swap between simulated inputs and outputs We will cover what this looks like with AdvantageKit [here](https://github.com/HighlanderRobotics/Highlanders-Training/blob/c79d758fda0429e41651b35bf9bfec68248e90c5/Docs/2_Architecture/2.6_AdvantageKit.md#L4), but at a high level, this means that we have both a sim and real version of each mechanism in our code. This is so we can easily test our code in sim and have minimal work to move it to real hardware. -
-More details on Sim vs Real implementation +--- The real IO layer controls the actual motors, sensors, and hardware on the robot. Sim IO replaces those with the simulated versions that approximate how the robot component should behave. The overall code structure is the same; however, the specific differs. To elaborate, in the real code, this means dealing with initializing, configuring, and driving hardware like Talons or CANcoders, while sim code uses simulation classes, like ElevatorSim, to mimic their behavior. -As you look through the code, you'll notice that real handles initializing motors, configurations, and hardware based commands, whereas sim uses methods from the sim classes. +As you look through the code, you'll notice that real has hardware based commands, whereas sim uses methods from the sim classes. if you want to take a closer look at what the specific code looks like follow along with [this tutorial](https://github.com/HighlanderRobotics/Highlanders-Training/blob/c79d758fda0429e41651b35bf9bfec68248e90c5/Docs/2_Architecture/2.9_KitbotExampleWalkthroughSim.md#L4) for kitBot sim --- -
### Resources From e602a22c369f1c08ddb3082d971a6a699ba04abc Mon Sep 17 00:00:00 2001 From: vivi-o Date: Sun, 31 Aug 2025 00:43:52 -0700 Subject: [PATCH 7/8] slight change of order --- Docs/2_Architecture/2.8_Simulation.md | 39 +++++++++++++-------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/Docs/2_Architecture/2.8_Simulation.md b/Docs/2_Architecture/2.8_Simulation.md index f4737a5..7cb6b68 100644 --- a/Docs/2_Architecture/2.8_Simulation.md +++ b/Docs/2_Architecture/2.8_Simulation.md @@ -37,7 +37,6 @@ A state-space model is a set of matrix equations that describe how a system chan ---
- Like other simulated systems, the mechanism’s state is updated periodically with simulated inputs. For example, we can simulate the change in position of an elevator when a certain voltage is applied to its motor using this mathematical model. @@ -106,6 +105,25 @@ more details: - [WPILib docs](https://docs.wpilib.org/en/stable/docs/software/dashboards/glass/mech2d-widget.html) - [WPILib API Reference](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/smartdashboard/Mechanism2d.html) +### WPILib Sim Classes +WPILib provides sim classes such as ElevatorSim and SingledJointedArmSIm. These require parameters such as gear ratios, mass, and motor types so the simulation knows how to behave. +Once we set up the simulation we can use it to test our code against a virtual mechanism. + +Go [here](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/simulation/package-summary.html) to check out the specific classes and methods + +take a look at this quick example: +```Java +new ElevatorSim( + DCMotor.getKrakenX60Foc(1), //gear box: type of motor and number of motors + ElevatorSubsystem.GEAR_RATIO, //gearing: gear ratio + Units.lbsToKilograms(7.0 + (3.25 / 2)), //carriage mass: mass of elevator carriage + ElevatorSubsystem.DRUM_RADIUS_METERS, // drumRadiusMeters: radius of the drum the elevator spool is wrapped around + 0.0, // minHeightMeters: the minimum height + ElevatorSubsystem.MAX_EXTENSION_METERS, // maxHeightMeters: the maxium height + true, // simumateGravity: should gravity be simulated? + 0.0); //measurementStdDevs: standard deviation of measurements +``` + ### MapleSim Our team also integrates MapleSim into the robot code. Maple sim supports more complex physics simulations. @@ -129,25 +147,6 @@ example code: [more details](https://shenzhen-robotics-alliance.github.io/maple-sim/) -### WPIlib Sim Classes -WPILib provides sim classes such as ElevatorSim and SingledJointedArmSIm. These require parameters such as gear ratios, mass, and motor types so the simulation knows how to behave. -Once we set up the simulation we can use it to test our code against a virtual mechanism. - -Go [here](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/simulation/package-summary.html) to check out the specific classes and methods - -take a look at this quick example: -```Java -new ElevatorSim( - DCMotor.getKrakenX60Foc(1), //gear box: type of motor and number of motors - ElevatorSubsystem.GEAR_RATIO, //gearing: gear ratio - Units.lbsToKilograms(7.0 + (3.25 / 2)), //carriage mass: mass of elevator carriage - ElevatorSubsystem.DRUM_RADIUS_METERS, // drumRadiusMeters: radius of the drum the elevator spool is wrapped around - 0.0, // minHeightMeters: the minimum height - ElevatorSubsystem.MAX_EXTENSION_METERS, // maxHeightMeters: the maxium height - true, // simumateGravity: should gravity be simulated? - 0.0); //measurementStdDevs: standard deviation of measurements -``` - ### sim vs real The final major tool is being able to swap between simulated inputs and outputs (IO) and real IO easily and correctly. From 3dc5a31889c488246be76595f2e282748e0b04ad Mon Sep 17 00:00:00 2001 From: spellingcat <70864274+spellingcat@users.noreply.github.com> Date: Wed, 3 Sep 2025 23:32:55 -0700 Subject: [PATCH 8/8] minor edits --- Docs/2_Architecture/2.8_Simulation.md | 63 ++++++++++++++------------- 1 file changed, 33 insertions(+), 30 deletions(-) diff --git a/Docs/2_Architecture/2.8_Simulation.md b/Docs/2_Architecture/2.8_Simulation.md index 7cb6b68..d53b8fe 100644 --- a/Docs/2_Architecture/2.8_Simulation.md +++ b/Docs/2_Architecture/2.8_Simulation.md @@ -2,14 +2,14 @@ ## Simulation is the process of running our robot code on a computer other than the robot to test it without being limited by physical hardware -### overview +### Overview Generally speaking, simulation depends on sending the inputs we would like to test to a model of a system (mechanism) and analyzing the simulated results. There are several ways to do this, depending on what you’re simulating. This could be something small, like simulated readings of an encoder, or something more complex, like a physics simulation of an arm. Simulation is important for a couple of reasons—we can test something without risking breaking an actual physical part, as well as being able to concurrently develop code as those physical components are being built (which is often the case during the build season). -### sim GUI +### Sim GUI We have a number of tools at our disposal for simulation. One is WPILib’s built-in desktop simulation. @@ -53,40 +53,40 @@ Note that the topics covered by this book are largely far more advanced than hig Running a model is useful, but even more useful is being able to visualize the output of the model. There are several dashboards you can use to do this, but we mainly use AdvantageScope. [AdvantageScope](https://github.com/Mechanical-Advantage/AdvantageScope) is a tool developed by Team 6328 to visualize data from live robots, simulated robots, and robot logs. -It provides a variety of formats to visualize data. These applications include things like line graphs, 2d field modeling, 3d robot modeling, tables, timeline plots, custom widgets, and more. +It provides a variety of formats to visualize data. +These applications include things like line graphs, 2d field modeling, 3d robot modeling, tables, timeline plots, custom widgets, and more. Screenshot of Advantagescope -This way we can run autonomous routines, drive around in sim, test mechanisms, and even run 3d calculations like localizing with april tags, all without requiring the robot. +This way we can run autonomous routines, drive around in sim, test mechanisms, and even run 3d calculations like localizing with AprilTags, all without requiring the robot. Another major feature of AdvantageScope is the ability to log telemetry and replay runs. This is helpful for collecting data, replaying matches, and comparing sim with the real results. It is closely integrated with AdvantageKit, a logging framework also from Team 6328, but does not require it. -- [general advantagescope documentation](https://docs.advantagescope.org/) +You can find the docs [here.](https://docs.advantagescope.org/) -### 3d modeling -3d modeling requires us to import and configure any 3d CAD robot models and field components we want to use. +### 3d Modeling +3d modeling in AdvantageScope requires us to import and configure any 3d CAD robot models and field components we want to use. Our team prefers this approach because it's helpful to visualise and test the full robot and all its components. In the simulator, both 2D and 3D geometry types are supported, such as, Pose2d, Pose3d, Translation2d, and Translation3d. Screenshot of Advantagescope 3d field -- [more details about the 3d field](https://docs.advantagescope.org/tab-reference/3d-field) -- [custom assets](https://docs.advantagescope.org/more-features/custom-assets) -- in order to implement these custom models CAD models with have to be converted into the gITF format, as cad isn't supported [tutorial](https://docs.advantagescope.org/more-features/gltf-convert) +More details about the 3d field can be found [here](https://docs.advantagescope.org/tab-reference/3d-field), and more info about importing custom assets is [here.](https://docs.advantagescope.org/more-features/custom-assets) +In order to implement these custom CAD models, they have to be [converted into the gITF format.](https://docs.advantagescope.org/more-features/gltf-convert) -### 2d mechanism modeling -Mechanism2d is an object which proves simple 2D visualization of mechanisms. +### 2d Mechanism Modeling +Mechanism2d is an object which provides simple 2D visualization of mechanisms. Setting up the mechanism 2d involves: - creating a new Mechanism2d object - defining a root node where the mechanism is anchored (this can be a pivot point or robot base) using MechanismRoot2d. - Finally we append existing nodes or ligaments with MechanismLigament2d to add more components. For instance, with Mechanism2d, we can create a shoulder mechanism and add the wrist to it as a ligament. You can define linkages, arms, elevators, etc and update their state in code. -This can be displayed in Sim GUI, and is also compatible with AdvantageScopes 2D & 3D visualization tools +This can be displayed in the sim GUI, and is also compatible with AdvantageScope's 2D & 3D visualization tools. -example code: +Example code: ```Java // Mechanisms private final LoggedMechanism2d elevatorMech2d = @@ -101,17 +101,18 @@ example code: Screenshot of Advantagescope with mech 2d -more details: -- [WPILib docs](https://docs.wpilib.org/en/stable/docs/software/dashboards/glass/mech2d-widget.html) +More details: +- [WPILib Mech2d docs](https://docs.wpilib.org/en/stable/docs/software/dashboards/glass/mech2d-widget.html) - [WPILib API Reference](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/smartdashboard/Mechanism2d.html) ### WPILib Sim Classes -WPILib provides sim classes such as ElevatorSim and SingledJointedArmSIm. These require parameters such as gear ratios, mass, and motor types so the simulation knows how to behave. +WPILib provides sim classes such as ElevatorSim and SingledJointedArmSim. +These require parameters such as gear ratios, mass, and motor types so the simulation knows how to behave. Once we set up the simulation we can use it to test our code against a virtual mechanism. -Go [here](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/simulation/package-summary.html) to check out the specific classes and methods +Go [here](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/simulation/package-summary.html) to check out the specific WPILib sim classes and methods. -take a look at this quick example: +Take a look at this quick example: ```Java new ElevatorSim( DCMotor.getKrakenX60Foc(1), //gear box: type of motor and number of motors @@ -119,18 +120,19 @@ new ElevatorSim( Units.lbsToKilograms(7.0 + (3.25 / 2)), //carriage mass: mass of elevator carriage ElevatorSubsystem.DRUM_RADIUS_METERS, // drumRadiusMeters: radius of the drum the elevator spool is wrapped around 0.0, // minHeightMeters: the minimum height - ElevatorSubsystem.MAX_EXTENSION_METERS, // maxHeightMeters: the maxium height + ElevatorSubsystem.MAX_EXTENSION_METERS, // maxHeightMeters: the maximum height true, // simumateGravity: should gravity be simulated? 0.0); //measurementStdDevs: standard deviation of measurements ``` ### MapleSim Our team also integrates MapleSim into the robot code. -Maple sim supports more complex physics simulations. -Maple sim allows us to represent motors, encoder, and sensors, instead of just modeling kinematics. -This lets us test and tune the robot behavior in a more realistic way. It can simulate voltages, currents, and handle collisions with the field and other obstacles. +MapleSim supports more complex physics simulations. +MapleSim allows us to simulate more complex interactions between the robot and other things on the field (field elements, game pieces, other robots, etc). +This lets us test and tune the robot behavior in a more realistic way. +We mostly use this for a more accurate swerve simulation. -example code: +Example code: ```Java //simulate drive motor with MapleSim simulation.useDriveMotorController( @@ -145,22 +147,23 @@ example code: Angle.ofBaseUnits(moduleConstants.cancoderOffset().getRadians(), Radian))); ``` -[more details](https://shenzhen-robotics-alliance.github.io/maple-sim/) - -### sim vs real +The MapleSim docs are [here.](https://shenzhen-robotics-alliance.github.io/maple-sim/) +### Sim vs Real The final major tool is being able to swap between simulated inputs and outputs (IO) and real IO easily and correctly. We will cover what this looks like with AdvantageKit [here](https://github.com/HighlanderRobotics/Highlanders-Training/blob/c79d758fda0429e41651b35bf9bfec68248e90c5/Docs/2_Architecture/2.6_AdvantageKit.md#L4), but at a high level, this means that we have both a sim and real version of each mechanism in our code. This is so we can easily test our code in sim and have minimal work to move it to real hardware. --- -The real IO layer controls the actual motors, sensors, and hardware on the robot. Sim IO replaces those with the simulated versions that approximate how the robot component should behave. -The overall code structure is the same; however, the specific differs. To elaborate, in the real code, this means dealing with initializing, configuring, and driving hardware like Talons or CANcoders, while sim code uses simulation classes, like ElevatorSim, to mimic their behavior. +The real IO layer controls the actual motors, sensors, and hardware on the robot. +The sim IO replaces those with the simulated versions that approximate how the robot component should behave. +The overall code structure is the same; however, the specific implementation differs. +To elaborate, in the real code, this means dealing with initializing, configuring, and driving hardware like Talons or CANcoders, while sim code uses simulation classes, like ElevatorSim, to mimic their behavior. As you look through the code, you'll notice that real has hardware based commands, whereas sim uses methods from the sim classes. -if you want to take a closer look at what the specific code looks like follow along with [this tutorial](https://github.com/HighlanderRobotics/Highlanders-Training/blob/c79d758fda0429e41651b35bf9bfec68248e90c5/Docs/2_Architecture/2.9_KitbotExampleWalkthroughSim.md#L4) for kitBot sim +if you want to take a closer look at what the specific code looks like, follow along with [this tutorial](https://github.com/HighlanderRobotics/Highlanders-Training/blob/c79d758fda0429e41651b35bf9bfec68248e90c5/Docs/2_Architecture/2.9_KitbotExampleWalkthroughSim.md#L4) for adding sim capabilities to the kitbot. ---