MATLAB setup

Requires the following resource:

  • MATLAB Simian GUI release zip file.

Setup steps:

  1. Unzip the archive with the MATLAB version of Simian GUI to the location where you want to use it. Refer to section Simian GUI contents for more information about its contents.

  2. Run the install.p script.

  3. Install your license as described in the License section.

Note In all code presented in the documentation, v2_0_0 must be substituted with the version number for the actual release that is used. It is recommended to use dynamic version numbers as explained here

Testing your setup

You can test your environment setup by running the following commands in MATLAB: 

form = simian.gui_v2_0_0.Form();

If you get a Form object, your environment is setup correctly. You should also be able to start the BallThrower example locally by running the following command:

simian.local_v2_0_0.Uiformio("simian.examples_v2_0_0.ballthrower");

If you get an error, you can check this against these error messages and solutions:

  • Unable to resolve the name simian.gui_v2_0_0.Form. Ensure that the the simian-gui folder is on the MATLAB path and that the version in the namespace corresponds with your Simian GUI version.
  • Unable to resolve the name simian.local_v2_0_0.Form. Ensure that the the simian-local folder is on the MATLAB path and that the version in the namespace corresponds with your Simian GUI version.
  • Unable to resolve the name 'simian.examples_v2_0_0.ballthrower' Ensure that the the simian-examples folder is on the MATLAB path and that the version in the namespace corresponds with your Simian GUI version.

Simian GUI contents

An overview of archive contents is shown in the figure below.

  • Documentation The documentation of Simian GUI.
    • index.html The main page of the documentation.
  • simian-examples Folder containing the included examples.
    • +simian
      • +examples_v2_0_0
        • @BallThrower Class implementing the ball throwing model.
        • +ballthrower The BallThrower application package. It contains the guiInit.m and guiEvent.m function files that define the user interface of the application.
  • simian-gui Folder containing the Simian GUI code.
    • +simian
      • +gui_v2_0_0 Simian GUI package where the name contains the version number. When you use Simian GUI you must ensure that the correct name is used. Refer to the deployment section for tips on making this easier.
    • java Utilities required for running Simian GUI.
    • utils Utilities required for running Simian GUI.
    • config.json File containing the version number of the front-end.
  • simian-local Folder containing the code to run Simian GUI locally.
    • +simian
      • +local_v2_0_0 Simian Local package where the name contains the version number. When you use Simian GUI you must ensure that the correct name is used. Refer to the deployment section for tips on making this easier.
    • html Folder containing the front-end build for uihtml.
  • Contents.m Simian GUI version number.
  • install.p Script that sets up Simian GUI for running applications locally.

Working with multiple releases

It is possible to work with, and deploy, multiple Simian GUI applications simultaneously, even if they use different Simian GUI releases. To facilitate this, the version numbers are included in the package namespace.

Therefore, the recommended approach is to dynamically select the Simian GUI package in your code.

  1. Create a function that returns the required version number, e.g.:

    function simianGui = getSimianGui()
    simianGui = "gui_v2_0_0";
end

  2. Use the function to import or call the correct version of Simian GUI:

    % Direct calls:
nr = simian.(getSimianGui()).component.Number("myKey");

% Importing:
import("simian." + getSimianGui() + ".*");
nr = component.Number("myKey");

In order to update to a new release of Simian GUI, you only have to update the string returned by this function. All other files remain unchanged.

Alternatively, when not referencing the package dynamically, all calls to Simian GUI need to be updated to the new version. This may lead to a large number of changes. Extra care is required when using version control and multiple braches are under development simultaneously.

In order to update your code to a newer Simian GUI release, use the updateVersion function included in the Simian GUI package. This function edits the version number in all m-files in a given folder and its sub-folders. For example: simian.gui_v2_0_0.updateVersion("C:\Applications\MyApp"). Save all m-files and make a back-up before you run this function!