smimport

Import a multibody model from a URDF or Simscape Multibody XML file

Syntax

[H,dataFileName] = smimport(multibodyDescriptionFile)

[H,dataFileName] = smimport(multibodyDescriptionFile,Name,Value)

Description

[H,dataFileName] = smimport(multibodyDescriptionFile) generates a Simscape™ Multibody™ model from a multibody description file conforming to the URDF XML specification or to the Simscape Multibody XML schema. Models generated from Simscape Multibody XML files are accompanied by data files that provide the block parameter values.

H is the model handle and dataFileName is the name of the supporting data file. By default, the model and data file are named after the URDF or XML multibody description file. If the name of the multibody description file does not conform to MATLAB^® naming rules, a modified version of the file name is used in its place.

multibodyDescriptionFile is the name of the multibody description file. The file path can be absolute or relative. If no path is given, the function searches for the file on the MATLAB path. The file extension is optional. In the absence of an extension, the function treats the file as a Simscape Multibody XML file.

The multibody description file details the structure and properties of the model to import. The file can be in URDF or Simscape Multibody XML formats. URDF files must conform to the URDF XML specification. Simscape Multibody XML files must conform to the Simscape Multibody XML schema.

You can use the Simscape Multibody Link CAD plug-in to generate a valid Simscape Multibody XML file from the following CAD applications:

• Autodesk Inventor^®

• PTC^® Creo™

• SolidWorks^®

The plug-in exports assemblies in two XML formats, one specific to Simscape Multibody models, the other to Simscape Multibody First Generation models. The smimport function accepts only XML files generated for Simscape Multibody models. For Simscape Multibody First Generation models, use mech_import instead.

The data file, which accompanies models generated from Simscape Multibody XML files, provides the numerical values of the block parameters in the form of a MATLAB data structure. Blocks in the imported model reference the MATLAB structure fields through the model workspace. The default structure name is smiData.

[H,dataFileName] = smimport(multibodyDescriptionFile,Name,Value) adds options for specifying a CAD import mode, a CAD model simplification mode, and various file names. Set ImportMode to dataFile in order to generate a new data file for a previously imported CAD assembly model. Specify PriorDataFile to catch unexpected changes to the XML multibody description file, such as part name changes or the addition and deletion of parts. Only the ModelName argument applies if importing from a URDF multibody description file.

Input Arguments

multibodyDescriptionFile — Multibody description file to import

custom string or character vector

Name, extension, and path of the multibody description file to import. The file must conform to the published URDF specification or the Simscape Multibody XML schema. The file extension and path are optional parts of the argument. In the absence of a file extension, the function treats the file as a Simscape Multibody XML file. In the absence of a file path, the function searches for the file on the MATLAB path.

Example: 'robotto.xml'

Data Types: char | string

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: smimport('sm_robot','ModelName','robotto','DataFileName','robottos_data_file');

'ModelSimplification' — Model topology simplification mode

none (default) | bringJointsToTop | groupRigidBodies

Model topology simplification mode to use during CAD import. Set ModelSimplification to:

• bringJointsToTop to group rigidly connected parts into subsystems and promote joints to the top level in the model hierarchy.

• groupRigidBodies to group rigidly connected parts into subsystems but leave joints in their original places in the model hierarchy.

• None to import the model as is, without simplification.

Joints brought to the top level of a model are renamed using generic names based on the joint type—for example, Revolute_Joint1. Subsystems of rigidly connected components that have been grouped together are given generic names based on the string RigidSubsystem—for example, RigidSubsystem1. This argument does not apply to multibody description files in URDF format.

Example: 'bringJointsToTop'

Data Types: char | string

'ImportMode' — Choice of model import or data file update function modes

modelAndDataFile (default) | dataFile

Option to generate a new model or update existing model data. Set ImportMode to modelAndDataFile to generate a new model and data file. Set ImportMode to dataFile to generate a new data file for a previously imported model. The function does not update the block diagram itself. If you do not specify ImportMode, the function runs in modelAndDataFile mode. This argument does not apply to multibody description files in URDF format.

Example: 'dataFile'

Data Types: char | string

'ModelName' — Name of the multibody model to generate

custom string or character vector

Name of the Simscape Multibody model to generate. The model is saved in SLX format. This argument is not valid when ImportMode is set to dataFile. If you do not specify ModelName, the model file is named after the multibody description file. If the multibody description file name is inconsistent with MATLAB naming rules, a modified version is used instead.

Example: 'robotto'

Data Types: char | string

'DataFileName' — Name of the parameter data file to generate

custom string or character vector

Name of the supporting parameter data file. The data file is an M file with the block parameter values referenced in the imported Simscape Multibody model. If you do not specify DataFileName, the data file is named after the multibody description file. If the multibody description file name is inconsistent with MATLAB naming rules, a modified version is used instead. This argument does not apply to multibody description files in URDF format.

Example: 'robottos_new_data'

Data Types: char | string

'PriorDataFile' — Name of the last used parameter data file

custom string or character vector

Name of the last parameter data file associated with a previously imported model. The prior data file helps to identify changes requiring special attention, such as new physical units, added and deleted components, and model topology changes. This argument is valid only when ImportMode is set to dataFile. This argument does not apply to multibody description files in URDF format.

Example: 'robottos_original_data'

Data Types: char | string

'VariableName' — Name of the MATLAB structure provided in the parameter data file

custom string or character vector

Name of the MATLAB data structure provided in the parameter data file. This structure contains the numerical values of all block parameters in the Simscape Multibody model. If you specify neither PriorDataFile nor VariableName, the data structure is named smiData. If you specify PriorDataFile but not VariableName, the data structure name is derived from the prior data file. This argument does not apply to multibody description files in URDF format.

Example: 'robottosData'

Data Types: char | string

Output Arguments

H — Model handle

double

Model handle returned as a double. Use the model handle to get or set model parameters, for example, using the get_param and set_param functions.

Data Types: double

dataFileName — Name of the parameter data file

character vector

Name of the parameter data file. The data file is an M file with the block parameter values referenced in the imported Simscape Multibody model. This output argument does not apply to models generated from URDF multibody description files.

Data Types: char

Examples

Import a CAD Robotic Arm Model

Import a model of a robotic arm from an XML multibody description file named sm_robot.xml. The XML file is part of your Simscape Multibody installation.

1. Import the model and store it in memory as Untitled. You can later save the model with your name of choice.

   smimport('sm_robot');

2. Update the diagram to assemble the model and visualize it in Mechanics Explorer. You can update the diagram from the Simulink^® menu bar by selecting Simulation > Update Diagram.

   

   The view convention of the source CAD platform differs from that of Simscape Multibody software, causing the model to appear on its side.

3. In the Mechanics Explorer tool strip, set the View convention parameter to Y up (XY Front) and select a standard viewpoint, such as the isometric view shown below.

   

   Selecting a standard view activates the new view convention. The visualization rotates to show the robot arm in the proper orientation.

4. Simulate the model. The robot arm lacks a control system and swings around under the influence of gravity.

   Build on the model by adding control subsystems to simulate useful tasks. Add internal mechanics and state targets at joints to dampen motion and configure the starting pose of the arm.

Import a CAD Robotic Model Using Custom File Names

Generate a CAD robotic arm model from the sm_robot.xml multibody description file included in your Simscape Multibody installation. Specify the model name as robotto and the data file name as robottos_data_file. At the MATLAB command prompt, enter the following code.

smimport('sm_robot','ModelName','robotto',...
'DataFileName','robottos_data_file');

Regenerate the Data File for a Previously Imported CAD Robotic Arm Model

Regenerate the data file for the previously imported CAD robotic arm model. Specify the data file name as robottos_new_data_file to avoid overwriting the original data file. At the MATLAB command prompt, enter the following code.

smimport('sm_robot','ImportMode','dataFile','DataFileName',...
'robottos_new_data_file','PriorDataFile','robottos_data_file');

Point the previously generated model to the new data file and reinitialize the model workspace using the following MATLAB code.

hws = get_param(bdroot,'modelworkspace');
hws.DataSource = 'MATLAB File';
hws.FileName = 'robotFileData';
hws.reload;

You can perform the same task using Model Explorer. In the Model Workspace pane for the imported model, enter the updated File Name parameter. Then, click the Reinitialize from Source button.

Import a URDF Humanoid Robot Model

Import a URDF model of a humanoid robot from the URDF model file sm_humanoid.urdf. The URDF file is part of the Simscape Multibody installation.

1. Import the model and store it in memory as Untitled. You can later save the model with your name of choice. The file extension is optional when importing XML files but required when importing URDF files.

   smimport('sm_humanoid.urdf');

   

2. Update the diagram to assemble the model and visualize it in Mechanics Explorer. You can update the diagram from the Simulink menu bar by selecting Simulation > Update Diagram.

   

3. Simulate the model. The robot arm lacks a control system and swings around under the influence of gravity. The shoulder line is the root body in the URDF model and it is fixed to the world frame in the imported model.

   Try modifying the model—for example, by removing the rigid connection between the shoulder line and the world frame and by adding control subsystems at the various joints. See the Humanoid Robot featured example for a version of the model with basic motion controls. You can open the example by entering sm_import_humanoid_urdf at the MATLAB command prompt.