Running a Simulation - Carleton-SRCL/SPOT GitHub Wiki

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 2023a and navigate to your SPOT working folder. It should look something like this:

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

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 is mostly empty to start, and simply runs the main GUI - though it does also initialize some parameters for the robotic arm. 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.0; 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:

run('GUI_v4_0_Main');

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

% As an example, here are the control parameters for 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                       = 2;
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;

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

Run the script, and the SPOT GUI should open.

Graphical User Interface Details

From the GUI, you can see and change most variables necessary for simulations and experiments. The GUI contains 5 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.

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

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:

Just selecting the diagram will load it into memory and will open the diagram. Once the diagram has been selected and loaded, the next step is to 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:

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.

Going back to the main application, the user must select what hardware is being used for the simulations and experiment by checking the boxes in the Active Hardware panel:

Having selected the desired hardware, the user can then click on the Open Initial Conditions App to modify the initial conditions of the simulation and experiment:

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.
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 click any of the Show ... buttons, you can visualize the initial conditions you have selected:

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:

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 using PD controllers.
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.

Finally, the users can tune the default control gains and thruster parameters in the Step #6: Auxiliary Parameters tab:

The current gains are somewhat tuned for 100 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. This panel also contains the nominal thruster force values - changing these values changes how much force is assumed to be coming from a single thruster.

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:

There are two panels in this tab: Simulation Settings 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. This panel also contains the option to add noise to the position states of the platforms. The last option is the ability to generate an animation of your simulation. This option will be unavailable until the user has run a simulation. Once a simulation has been performed, just check this box before pressing Play Animation 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, simply 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".

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:

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:

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, and is (for now) not all that flexible. The inspector only accepted data stored in structs; loading data of other types will not work. Here is the overview of the tab:

In this tab, you can load up to two files at the same time (usually one for simulation data and one for experimental data). More features may be added in the future. Once a data file has been loaded, the dropdown boxes for the x-axis and y-axis will be populated with the fields of the struct. Usually the x-axis is time, but you can select whichever parameter you want:

You can also export the contents of the viewer to a vector graphic PDF; just enter a name for the file and then click on Export to PDF. The PDF is saved to your working directory.

Next Step

You are now ready to book an experiment timeslot.

Click here to go HOME