What Is Onshape?
Onshape® is a third-party CAD application that you can import multibody models from. As with other CAD applications, you use Onshape software to model 3-D parts and articulated assemblies. Onshape is full-cloud software and does not rely on a local installation to run.
You must have an active Onshape account to use the software.
replaces the Simscape
Multibody Link plug-in as the CAD export
means. The plug-in is incompatible with Onshape and cannot be
used with Onshape models.
What’s in an Onshape Model?
Onshape models are similar in composition to other multibody models. Parts connect through mates such as Ball, Slider, and Revolute to form articulated linkages, mechanisms, and machines. The models are hierarchical, with parts and mates nested inside subassemblies that can in turn be nested inside larger subassemblies.
Each Onshape model exists in a cloud document. A document can have multiple Part Studio tabs, for modeling parts, and Assembly tabs, for mating parts. A Part Studio tab can have multiple parts and these can be modeled in the relative poses anticipated in the final assembly—for example, to form rigid groups during assembly without the aid of Fixed mates.
Rigid groups are unique to Onshape models and map into Simulink® Subsystem blocks with rigidly connected bodies enclosed.
A Word about Terminology
Onshape and Simscape Multibody models have different standard terms for what are often the same things. Parts in an Onshape model are bodies in a Simscape Multibody model. Mates and relations in an Onshape model are joints and constraints in a Simscape Multibody model. These terms are used interchangeably here.
Preparing a Model for Import
Consider fixing one part in each Onshape subassembly. The fixed part determines the location of the subassembly reference frame in the imported model. You must fix the reference part directly in the subassembly tab containing that part. Parts fixed in the root assembly tab—that containing all other subassemblies or bodies—have no impact on the location of the subassembly reference frames.
Ensure that your Onshape parts are free of geometry errors and that your mates have been fully defined. If no mate exists between two parts—that is, if they have six relative degrees of freedom—the imported model will show a 6-DOF Joint block between the corresponding body subsystems. Fix at least one part at the root assembly level to prevent such a block from being added between the assembly and the World frame.
Importing an Onshape Model
You import an Onshape model into the Simscape
smimport functions. The
converts the Onshape model into an intermediate representation
comprising an XML file and a set of STEP files. The
converts the XML file into the final Simscape
and a supporting data file.
Onshape CAD Import Workflow
About the Intermediate Files
The XML file provides the
the data it needs in order to recreate the Onshape model in the Simscape
This file is referred to as the multibody description file
and is required for model import.
The STEP files provide the imported model, once generated, the 3-D geometries it needs in order to render the bodies in the visualization panes of solid blocks and Mechanics Explorer. The files are referred to as geometry files and are optional for model import.
About the Imported Model
The geometry files are referenced in the solid blocks of the imported model. If the geometry files are missing, or if the paths to the files change, the body geometries no longer show in the visualization panes of the solid blocks and Mechanics Explorer. Simulation is unaffected provided that the model is otherwise still valid.
The remaining block parameters are specified in terms of MATLAB® variables
defined in the supporting data file generated by the
The variables are stored in a single data structure, with the data
field names and indices identifying the block parameters that the
variables correspond to—e.g.,
What Can You Import?
You can use the
to import the contents of Onshape Assembly tabs only. Part Studio
tabs lack the necessary information to generate a complete XML multibody
description file and cause the
to error. Other Onshape document tabs, such as Drawing and Folder,
present the same problem and cannot be exported.
If You Need to Import Single Parts
You can export part geometries directly from an Onshape document using the Onshape Export feature. This feature enables you to save geometries in various formats, but only two are compatible with Simscape Multibody models—STL and STEP. Once exported, the geometries can be individually imported into Simscape Multibody solid blocks. See Imported Solid Shapes.
User Authentication and Account Permissions
Before you can export an Onshape model, the
needs to authenticate your Onshape account and verify that the Simscape
app has access permission to your Onshape models.
Authentication occurs once per MATLAB session and is based
on a protocol known as OAuth2. So that you can validate your account,
smexportonshape function automatically opens
an Onshape log-in page on your first export attempt of a session.
You need give the Simscape
Multibody Exporter app access
permissions only once until these are revoked. So that you can set
the permissions for the app, the
automatically opens an Onshape application authorization page
on your first-ever export attempt.
You can revoke permissions at any time from the Onshape Applications page.
About the OAuth2 Protocol
OAuth2 is an authentication protocol that delegates the authentication process to the service hosting the account—in this case, Onshape. The oauth.net website describes the protocol as a valet key that gives third-party applications such as Simscape Multibody access to some, but not all, aspects of your account. In particular, Simscape Multibody can access your app permissions data, but it cannot see or store your private log-in credentials.
Mapping to Simscape Multibody Blocks
Simscape Multibody can map all Onshape mates but Tangent to equivalent blocks. The mappings are straightforward, with only slight differences between mate and block names standing out. The table shows the mappings used during model import.
|Onshape Mate||Simscape Multibody Block or Feature|
|Fastened||Direct connection line|
|Pin Slot||Pin Slot Joint|
Onshape relations such as Gear and Linear are not supported. All relations in your model are ignored during import. You can often model the ignored relations using Simscape Multibody blocks—for example, using the Common Gear Constraint block to model a Gear relation between two gears. You may need to create and carefully place new frames before adding such blocks.
Onshape Import Warnings and Errors
Invalid Assembly URLs
smexportonshape function expects the
URL of an Onshape Assembly tab as an argument. An Onshape document
often comprises Part Studio, Drawing, and other tabs. If you inadvertently
specify the URL for the wrong document tab—one not containing
an assembly—the function throws an error.
Onshape parts without assigned material translate into Simscape Multibody bodies with zero inertia. Such massless bodies can cause simulation to fail due to degenerate mass errors. A MATLAB warning identifies all massless bodies identified in your model, if any. You can manually specify the mass of a massless body after import using the Brick Solid block for that body. However, as a best practice, always try to assign a material to each body in an assembly before exporting it.
Unsupported Mates and Relations
Onshape mates such as Tangent and relations such as Gear
are not supported. The
throws a warning identifying all unsupported mates and relations,
if any. Unsupported mates map into nothing in a Simscape
For a list of Onshape mates that you can import, see Mapping to Simscape Multibody Blocks.
The block parameters in the imported model are in the default units of the Onshape model workspace. These units often include a mix derived from SI, CGS, and other unit systems. You can change the units for an entire model in your Onshape model workspace and for an individual block in your imported Simscape Multibody model.
Obtaining Onshape Models to Import
You can create a free account and create your own assembly model in—or import one into—your Onshape account. Many Onshape assembly models are public. You can import all such models into the Simscape Multibody environment.