Running a Simulation ‐ SPOT 4.1 PR.1 Hotfix.1 - Carleton-SRCL/SPOT GitHub Wiki

[!WARNING] The software will only work on MATLAB 2024b. This guide is intended for SPOT 4.1 Pre-Release.1 Hotfix.1 and will not apply for any previous versions.

Introduction

Assuming you have successfully completed the initial software setup on your Windows 10 or 11 PC, let's get set up to run a simulation. Simulations for SPOT are performed in MATLAB-Simulink, using fixed step solver. Note that simulations using variable step solvers are supported; you can switch between solvers via the GUI or using the Simulink Simulation Options.

If you are looking for a more detailed guide on the SPOT Simulink template, please check out this extensive wiki entry. Reading this will be helpful for anyone, but is not strictly required.

Getting Started

To get started, open up an instance of MATLAB 2024b and navigate to your SPOT working folder. It should look something like this:

image

To create a new project, run the Setup_Experiment.m script. This will open a prompt in which you can enter the name of your project (SPACES ARE NOT ALLOWED IN THE NAME). For this case, we will call the project "GitHubDemonstration".

image

Once "OK" has been clicked, all necessary files are copied from \SPOT\Template_Files\ and renamed according to the project name. While in your newly created project directory, open Run_Initializer.m. This script does a couple of important things: it starts the GUI, sets up some custom parameters for the robotic arm, sets up some PWM and thruster constants, and shows commented out code that would allow a user to circumvent using the GUI. You can add any additional variables for your unique simulations in this script. The default code is shown below:

  % The following script is the initializer for SPOT 4.1; in this script,
  % users define all initials parameters and/or constants required for
  % simulation and experiment.

  clear;
  clc;
  close all force;

  warning('off','all')

  %% Start the graphical user interface or set the appropriate variables:

  % No matter what, the GUI needs to be loaded
  appHandle = GUI_v4_1_Main;

  %% Place any custom variables or overwriting variables in this section

  % As an example, here are the control parameters the manipulator.
  % Set torque limits on joints

  Tz_lim_sharm                   = .1; % Shoulder Joint [Nm]

  Tz_lim_elarm                   = .1; % Elbow Joint [Nm]

  Tz_lim_wrarm                   = .1; % Wrist Joint [Nm]

  % Transpose Jacobian controller gains:

  Kp = [0.08 0 0
        0    0.08 0
        0    0    0.002];
  Kv = [0.05 0 0
        0    0.05 0
        0    0    0.005];

  % Initialize the PID gains for the ARM:

  Kp_sharm                       = 1.5;
  Kd_sharm                       = 1.0;

  Kp_elarm                       = 1.2;
  Kd_elarm                       = 0.8;

  Kp_wrarm                       = 1.0;
  Kd_wrarm                       = 0.6;

  % Define the model properties for the joint friction:
  % Based on https://ieeexplore.ieee.org/document/1511048

  %Shoulder
  Gamma1_sh = 0.005; 
  Gamma2_sh = 5;
  Gamma3_sh = 40;
  Gamma4_sh = 0.015; 
  Gamma5_sh = 800; 
  Gamma6_sh = 0.005;

  %Elbow
  Gamma1_el = 0.12; 
  Gamma2_el = 5;
  Gamma3_el = 10;
  Gamma4_el = 0.039; 
  Gamma5_el = 800;
  Gamma6_el = 0.000001;

  %Wrist
  Gamma1_wr = 0.025;
  Gamma2_wr = 5;
  Gamma3_wr = 40;
  Gamma4_wr = 0.029;
  Gamma5_wr = 800; 
  Gamma6_wr = 0.02;

  %% This section of the code contains parameters should not be modified

  % Set the PWM frequency
  PWMFreq = 5; %[Hz]

  % Set estimated thruster forces
  REDFXNominal   = 0.2825;
  REDFYNominal   = 0.2825;
  BLACKFXNominal = 0.2825;
  BLACKFYNominal = 0.2825;
  BLUEFXNominal  = 0.2825;
  BLUEFYNominal  = 0.2825;

  %% For those who want to run simulations without using the GUI:

  % % Set the diagram to run
  % appHandle.AvailableDiagramsDropDown.Value = "Template_v4_1_0_2024b_Jetson.slx";
  % 
  % % Ensure the diagram is loaded
  % open(appHandle.AvailableDiagramsDropDown.Value);
  % 
  % % Edit active platforms
  % appHandle.REDCheckBox.Value    = 1;
  % appHandle.BLACKCheckBox.Value  = 0;
  % appHandle.BLUECheckBox.Value   = 0;
  % appHandle.ARMCheckBox.Value    = 0;
  % 
  % appHandle.ConfirmSettings();
  % 
  % % Edit initial conditions
  % appHandle.SubAppInitialConditions.REDInitialX.Value  = 1.2;  % [m]
  % appHandle.SubAppInitialConditions.REDInitialY.Value  = 1.2;  % [m]
  % appHandle.SubAppInitialConditions.REDInitialTh.Value = 90;   % [deg]
  % 
  % appHandle.SubAppInitialConditions.UpdateInitialConditions();
  % 
  % % Edit mass properties
  % appHandle.SubAppMassProperties.OverridePropertiesCheckBox.Value = 1;
  % appHandle.SubAppMassProperties.MassRedEditField.Value = 12.035;    % [kg]
  % appHandle.SubAppMassProperties.InertiaRedEditField.Value = 0.19854;% [kgm2]
  % 
  % appHandle.SubAppMassProperties.UpdateMassProperties();
  % 
  % % Edit phase durations
  % appHandle.SubPhase1EditField.Value = 10;        % [s]
  % appHandle.SubPhase2EditField.Value = 5;        % [s]
  % appHandle.SubPhase3EditField.Value = 28;        % [s]
  % appHandle.SubPhase4EditField.Value = 115;        % [s]
  % appHandle.DurPhase0EditField.Value = 10;                  % [s]
  % appHandle.DurPhase1EditField.Value = 5;                  % [s]
  % appHandle.DurPhase2EditField.Value = 40;                  % [s]
  % appHandle.DurPhase4EditField.Value = 30;                  % [s]
  % appHandle.DurPhase5EditField.Value = 20;                  % [s] 
  % 
  % appHandle.UpdateTimes();
  % 
  % % Execute a simulation
  % appHandle.RunSimulationPublicFcn();
  % 
  % % Manipulate the simulation data
  % figure()
  % plot(dataClass.Time_s.Data, dataClass.RED_Px_m.Data,'-k')
  % grid on
  % hold on
  % axis tight
  % xlabel('Time [s]')
  % ylabel('Position - X [m]')

Run the script, and the SPOT GUI should open.

image

Graphical User Interface Details

From the GUI, you can see and change most variables necessary for simulations and experiments. The GUI contains 6 tabs:

  • Initialize Parameters: Contains all initializing parameters.
  • Setup & Run Simulations: Contains any options needed for simulations.
  • Setup & Run Experiments: Contains any options needed for experiments.
  • Direct Hardware Controls: Contains controls for the hardware, for use outside experiments (debugging, enabling flotation, etc...).
  • Data Inspector: Contains a tool that let's you import and plot data.
  • Computer Vision: Currently not available for PR.1, but will contain tools to interact with the computer vision systems.

There are also two toolbar options in the GUI, File, and Tools. At the moment, the File menu contains the following options:

image

The functionality of these options are as follows:

  • Lab Links: Contains links to the various lab sites (Google Photos, Youtube Channel, etc...).

  • Help: Contains links to the various YouTube videos made for the lab.

  • Save GUI State: This allows users to save the current parameters in the GUI for later use.

  • Load GUI State: This allows users to load in a saved state.

  • Reset GUI Parameters to Default: This allows users to load in the default parameters for the GUI. Default parameters are saved in the Resources folder, under SPOTGUI_DEFAULTS.

  • Override Current Default Parameters: This allows users to take the current GUI states and save them as the new default values. This will overwrite the values currently in the SPOTGUI_DEFAULTS.

Under the Tools menu there is only one options right now, which is Add Path to Custom Library. This allows users to manually add a path to a custom library. This should not be required if users follow the Wiki carefully, but may be useful for certain scenarios.

Initialize Parameters

The first tab contains various options that users need to set up for any simulations or experiments. Users start by loading in the Simulink diagram that they want to run by selecting it from the dropdown menu:

image

Just selecting the diagram will load it into memory and will open the diagram. Once the diagram has been selected and loaded, the user must select what hardware is being used for the simulations and experiment by checking the boxes in the Active Hardware panel:

image

Next, users should confirm that the mass properties are correct. This can be done by clicking on the Open Mass Properties App. This will open the sub-app for setting up the mass properties:

image

From this sub-app, you can enter the information you collected if you measured new mass properties for the system. Normally, these options should not change unless you make changes to the hardware. If you want to simply override the calculations, you can check the Override Properties checkbox and then manually enter the desired masses and inertias, or you may simply override the properties by defining your own mass properties in the initializer.

Going back to the main application, the user should then click on the Open Initial Conditions App to modify the initial conditions of the simulation and experiment:

image

In this sub-app, you can set the drop, initial, and home states for the three platforms. These are defined as follows:

  • Drop: This only applies to simulations, and represents the starting location of the platforms - in other words, where you place them on the table before starting an experiment. You are not required to place the platforms at this location when you start an experiment.

  • Initial: This is the location that the platforms will try to get to during Phase #2 of an experiment (see below for phase descriptions). Generally you want the initial and drop locations to be pretty close together.

  • Home: This is the location that the platforms will try to get to during Phase #4 and Phase #5 of the experiment; in other words, once the experiment phase is complete, where are the platforms going to go before shutting down.

You can also set the drop states for the arm attachment. There is no equivalent for the initial and home states for the arm - they are "hardcoded" into the diagram. Lastly, by clicking any of the Show ... buttons, you can visualize the initial conditions you have selected:

image

Once you are satisfied with the initial conditions, you can close the sub-app and return to the main app. Step #5 is to set the durations for the various experiment phases:

image

By default, the phases are as follows:

  • Phase #0: This phase is used to wait for data from the ground truth system.
  • Phase #1: This short phase is used to turn on the flotation.
  • Phase #2: During this phase, the platforms will all move to their initial locations as defined in the initial conditions app.
  • Phase #3: This is the main experiment phases. Users cannot directly edit the duration of this phase, and are instead required to edit the 4 sub-phases. Users can add sub-phases if desired, but will have to circumvent the use of the GUI to do so - this is generally reserved for more advanced users. If you require less than 4 sub-phases, you can set unused ones to a duration of 0 s.
  • Phase #4: During this phase, the platforms will all move to their home locations using PD controllers.
  • Phase #5: During this phase, the platforms will hold their home positions.

There is also a phase #6, but this phase is used to stop flotation and there is no duration associated. It simply runs from the end of phase #5 until the end of the experiment. In simulation, the diagram is stopped after phase #5. Users can also tune the default control gains in the Step #6: Control Law Tuning tab:

image

[!IMPORTANT] The current gains are somewhat tuned for 20 Hz experiments and a thruster PWM frequency of 5 Hz, so remember that if you change the sampling rate or PWM frequency you MUST also update gains.

The default controller is a Linear-Quadratic Regulator, but users can also tune the built in PD controller if desired. The parameters for the LQR represent the diagonals for the state weighting and control weighting matrices. Higher Q and lower R results in a more aggressive system with faster state correction, but potentially higher control effort. Lower Q and higher R produces a more conservative system with smoother control actions, but slower response and larger state deviations.

Finally, users must choose their Simulink Sampling rate in Step #7: Set Sampling Rate:

image

By default, the sampling rate is 20 Hz. This was selected as it provides the best system performance. But, users may set this to any value they want between 10-1000 Hz (higher may be possible, but remains untested).

[!IMPORTANT] The rate at which data is collected from the PhaseSpace ground truth system is fixed at exactly HALF of the Simulink sampling rate. This is due to a ongoing buffering bug within the PhaseSpace API. This is an active area of improvement, if you are a good C++ programmer and want to attempt to solve the problem, reach out to Professor Ulrich.

Setup & Run Simulations

Moving on to the Setup & Run Simulations tab, users can now run a simulation before they conduct any experiments. Here is an overview of the tab options:

image

There are three panels in this tab: Simulation Settings, Animation Options, and Run Simulation. In the Simulation Settings panel, users can change the solver type and the solver name. Fixed-step and variable-step are both supported - however, when running an experiment the solver type is automatically forced to fixed-step and the solver name is forced to be ode4. If you are running a variable-step simulation, you can change the basic performance settings in this tab.

In the Animation Options panel, users can change how the animation will look. These options will be unavailable until the user has run a simulation. Once a simulation has been performed, new options will become available:

image

Simply check any boxes of interest before pressing Play Animation to add the option to the display. In this panel you can also check the Create Video option before you hit Play to save a video of your simulation (while saving an animation, users cannot pause or stop the animation).

Once you are happy with your settings, click Start Simulation to run your Simulink diagram. Please be aware that sometimes simulations can take longer then expected due to the logic being used in the diagram. This is especially true if you are running simulations with the arm involved - if your arm controller is not robust enough, the simulation will have a tendency to "explode".

[!IMPORTANT] The robotic manipulator is a highly nonlinear system and simulations with the arm will NOT run unless you run the simulations at a very high sampling rate. The catch is that you will not be able to run experiments that these rates.

Once the simulation is complete, you'll have new options available to you. You can set the animation speed (which is a continuous slider from "fast" to "slow"), you can hit Play Animation to see the result of the simulation, you can Save Simulation Data to save your simulation data to the Saved Data directory, you can use the Animation Scrubber to scrub through the simulation to a specific point in time, and lastly you can use the Skip To feature to jump directly to a precise time.

When playing an animation, you will also see two additional options become available:

image

While playing an animation you can hit Pause Animation to stop the animation, and then Resume Animation to resume from the pause point. While the animation is running, you can also hit Stop Animation at any time to stop the animation. Doing so means the animation will start from the beginning if you click on Play Animation again.

When you select the Save Simulation Data button, the data will be saved to a struct, and a dialog box will indicate where the data was saved to:

image

This data can now be quickly analyzed using using the Data Inspector.

Data Inspector

The Data Inspector tab is intended to be used for quick data checking. The inspector accepts data stored in structs or timeseries; loading data of other types will not work. Here is the overview of the tab:

image

In this tab, you can load up to two files at the same time (usually one for simulation data and one for experimental data). Once a data file has been loaded, the dropdown boxes for the x-axis and y-axis will be populated with the parameter names. Usually the x-axis is time, but you can select whichever parameter you want. Users can also change the labels for the x and y axis using the text boxes above the corresponding dropdown menus.

image

If you have noisy data, you can also check the Filter Dataset #1 to filter the Y-axis data using a Butterworth low-pass filter. Overplotting can be enabled by checking the Allow Overplot checkbox. Clicking the Clear Figure button wipes the content of the figure. You can also export the contents of the viewer to a vector graphic PDF by clicking on Export to PDF. The PDF is saved to your working directory. Lastly, to the right of the figure you can Set Figure Ranges; use this if you want to specify a custom viewing window:

image

Next Step

If you have satisfactory simulation results, you are now ready to book an experiment timeslot.

Click here to go HOME