Onshape Import

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. The Simscape™ Multibody™ smexportonshape function 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.

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 Multibody environment using the smexportonshape and smimport functions. The smexportonshape function converts the Onshape model into an intermediate representation comprising an XML file and a set of STEP files. The smimport function converts the XML file into the final Simscape Multibody model and a supporting data file.

Onshape CAD Import Workflow

About the Intermediate Files

The XML file provides the smimport function the data it needs in order to recreate the Onshape model in the Simscape Multibody environment. 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 smimport function. 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., smiData.Solid(2).mass.

What Can You Import?

You can use the smexportonshape and smimport functions 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 smexportonshape function 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 Try It: Import a STEP Geometry File.

User Authentication and Account Permissions

Before you can export an Onshape model, the smexportonshape function needs to authenticate your Onshape account and verify that the Simscape Multibody Exporter 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, the 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 smexportonshape function 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
Ball	Spherical Joint
Cylindrical	Cylindrical Joint
Fastened	Direct connection line
Parallel	Angle Constraint
Pin Slot	Pin Slot Joint
Planar	Planar Joint
Revolute	Revolute Joint
Slider	Prismatic 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

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

Zero-Mass Bodies

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 smexportonshape function throws a warning identifying all unsupported mates and relations, if any. Unsupported mates map into nothing in a Simscape Multibody model. For a list of Onshape mates that you can import, see Mapping to Simscape Multibody Blocks.

Physical Units

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.