# SolidWorks Add-in

> Install the syn.bike add-in for SolidWorks, link it to a saved bike, and sync geometry and linkage points into a part as global variables.

The add-in copies a bike you have saved in syn.bike into the active SolidWorks document as global variables: one for each geometry value, and an X and a Y for each linkage point. Build your sketches on those variables and the model follows the bike every time you sync.

The variables are listed on the [CAD Sync](https://syn.bike/docs/cad-sync.md) page, with the SolidWorks names in their own column.

## SolidWorks Add-in Requirements

- Windows with SolidWorks 2018 or later.
- Microsoft .NET Framework 4.8. Windows 10 version 1903 and later include it.
- A bike saved in your **Private** or **Team** database. See [Loading and Saving](https://syn.bike/docs/loading-and-saving-bikes.md).

## Install the Add-in

1. Open the [Downloads](https://syn.bike/downloads) page and, under **CAD Plugins**, click **Solidworks Plugin** to download the installer (an `.msi` file).
2. Run the installer. Windows asks for administrator approval.
3. Start SolidWorks, or restart it if it was open.

The same section of the Downloads page links an **Example Solidworks File**, a sample part (`skeleton.sldprt`).

### Find the Commands

With a part, assembly or drawing open, the add-in's commands are on the **Linkage Sync** tab of the CommandManager. The same commands are in the **Tools** menu.

| Command | What it does |
|---|---|
| **Setup Bike Link** | Links the add-in to a bike with a one-time password, then syncs it. |
| **Sync All Variables** | Downloads the saved bike and writes every variable that differs. |
| **Sync Changes** | Writes only what changed in the saved bike since the last download. |
| **Link Info** | Shows the linked bike, when the link expires, and the add-in version. |
| **Draw Linkage Points** | Adds a sketch of the linkage points, driven by the variables. |

If the tab is not there, open **Tools > Add-Ins**, find **syn Linkage** in the list, and tick both of its boxes: **Active Add-ins** loads it now, and **Start Up** loads it every time SolidWorks starts.

### Update the Add-in

When a new version is out, a box appears after a syn command finishes. It names the new version and yours, for example "syn Linkage 2.1.0 is available. You have 2.0.0."

- **Install update** downloads the installer and starts it. Windows asks for permission before the installer makes any changes.
- **Copy link** copies the download link, so you can paste it into any browser.
- **Skip this version** stops the box appearing for that version. You can still download it from the [Downloads](https://syn.bike/downloads) page.
- **Later** closes the box, and it comes back the next time SolidWorks starts.

Save your work and close SolidWorks before you click **Install** in the installer. The installer never closes SolidWorks for you. If SolidWorks stays open, the installer may ask you to close it, or Windows may finish the update the next time you restart your computer.

There is nothing to uninstall first. If the box says "Could not download the update. Copy the link, or open it in your browser.", use **Copy link** or **Open in browser** and run the installer you download.

### Uninstall the Add-in

To remove the add-in, uninstall **synSolidworks** from **Apps & features** in Windows Settings.

## Link a Bike

A link connects the add-in to one saved bike.

1. In syn.bike, load the bike and save it. Edits you have not saved are not synced.
2. Open the **Layout** tab, expand **Access Controls and Export**, and click **Setup CAD Sync**.
3. Click **Generate OTP**, then click the copy icon beside the password. It works once and expires after 3 minutes.
4. In SolidWorks, open the part you want the variables in and click **Setup Bike Link**.
5. Paste the password into **One Time Password**.
6. Tick **Use Configuration per Size** if you want one SolidWorks configuration for each size of the bike. Read [Sizes and Configurations](#sizes-and-configurations) before you tick it on a part that already has configurations.
7. Confirm the page with the green check mark. A dialog names the bike ("Successfully linked:") and the first sync starts. It can take up to a minute.

The link lasts 5 days and ends when you close SolidWorks. After either, generate a new password and run **Setup Bike Link** again. Your variables and sketches stay in the part.

Every sync writes into whichever document is active, so check which window is in front before you sync.

Saving the bike under a new **Version** creates a separate bike, which needs its own link.

If the web app shows a warning instead of a password, see [Set Up a Link From the Web App](https://syn.bike/docs/cad-sync.md#set-up-a-link-from-the-web-app). To see or remove links from the web app, see [Manage CAD Links](https://syn.bike/docs/cad-sync.md#manage-cad-links).

## Sync the Variables

**Sync All Variables** downloads the saved bike and writes it into the active document as global variables, which you can see under **Tools > Equations**. There are 32 linkage point variables (`syn_p0_x` to `syn_p15_y`) and 21 geometry variables such as `syn_reach` and `syn_hta`.

Only values that differ are written. A dialog then lists what changed as `variable: old > new`, or reads "Everything is already up to date, so nothing was written." A value you typed over by hand in the active configuration is set back to the bike's value.

The first time you sync into a part that has no linkage point variables, the add-in asks before writing anything:

> "Frame.SLDPRT" does not have the bike's syn variables yet. Sync them into this part now? Syncing can take up to a minute.

**Cancel** leaves the part untouched.

If a sketch is open when you sync, the values are written but the model is not rebuilt until you leave the sketch.

### Units in SolidWorks

The variables are plain numbers with no unit: lengths are millimeter values and angles are degree values. Keep the part's length unit set to millimeters (**Tools > Options > Document Properties > Units**). In a part set to inches, `syn_reach` = 475 would drive a dimension to 475 inches.

Linkage point values are the real coordinates relative to the bottom bracket, X positive toward the front of the bike and Y positive up, so most of them have a negative X. They are not shifted by the offsets that the Onshape sync applies.

### Sizes and Configurations

**Use Configuration per Size**, on the **Setup Bike Link** page, decides how a bike with more than one size is written. It is off each time SolidWorks starts.

- **Cleared**, or a bike with one size: the sync writes the geometry of the bike's first size.
- **Ticked**, and a bike with more than one size: each size becomes a SolidWorks configuration named after the size. Geometry variables get their own value in each configuration. Linkage point variables are the same in all of them.

> [!WARNING]
> The sync renames the part's existing configurations, in order, to the bike's size names: the first configuration takes the first size's name, the second takes the second, and so on. Configurations are added if the part has fewer than the bike has sizes. Turn this on only in a part whose configurations are meant to be the bike's sizes.

The sync adds a custom property named `syn_synced_values` to each size configuration. Leave it alone.

If you start with the box cleared and turn it on later, delete all the `syn_` variables in **Tools > Equations** and run **Sync All Variables**.

### Sync Changes

**Sync Changes** is the quicker command for the edit-save-sync loop. It writes only what changed in the saved bike since the add-in last downloaded it, and shows no summary when it succeeds.

If you work in two parts, or you are not sure a part is current, run **Sync All Variables** instead.

## Draw Linkage Points

**Draw Linkage Points** adds a sketch of the linkage points, each one dimensioned from the synced variables. When you sync, the sketch moves with the bike.

The sketch uses the values last synced into the part, so sync first if the bike has changed.

1. Open a part and close any sketch you are editing.
2. Click **Draw Linkage Points**.
3. Pick a plane or a flat face for the sketch. The Right Plane is selected already.
4. Confirm with the green check mark.

A dialog reports what was drawn, for example "Added 8 linkage points. Added 9 link lines and 2 frame circles."

Every run draws into a new sketch, so running it twice gives you two sets of points.

### What the Sketch Contains

- The points, at their real coordinates relative to the sketch origin, with the bottom bracket fixed at the origin. A point at (0, 0) that the linkage does not use is skipped.
- Lines joining the points of each link, following the bike's **Linkage Setup** in syn.bike.
- A 20 mm circle at each point where a link pivots on the frame.

The lines and circles are construction geometry, so they guide your design without becoming part of a feature's profile.

### The Offset Datum

SolidWorks dimensions cannot be negative, and most linkage points sit behind or below the bottom bracket. So every point except the bottom bracket is dimensioned from the offset datum, a construction point at `-syn_x_offset`, `-syn_y_offset`.

The command creates `syn_x_offset` (500 mm) and `syn_y_offset` (100 mm) if the part does not have them, and never overwrites them. Each must be a plain number of millimeters greater than 0.

If a point lies further behind the origin than `syn_x_offset`, or further below it than `syn_y_offset`, the command stops and names the point. Raise the variable in **Tools > Equations** and run the command again.

## Logs and Error Reports

If we ask for a log when a sync is slow or fails, it is at `%LOCALAPPDATA%\syn\solidworks-sync.log`. The add-in also sends error reports to syn.bike automatically. Neither contains coordinates or bike names.

## SolidWorks Add-in Troubleshooting

### SolidWorks Link Messages

| Message | Cause | What to do |
|---|---|---|
| "Please enter a valid OTP" | The password was mistyped, already used, or older than 3 minutes. The same message appears when the add-in cannot reach syn.bike. | Generate a new password and paste it in straight away. Check your internet connection if it keeps failing. |
| "Bike is not yet linked. Please setup bike link first." | No link in this SolidWorks session. Links do not survive a restart. | Run **Setup Bike Link**. |
| "Bike link has expired. Please setup bike link again." | The link is more than 5 days old. | Generate a new password and run **Setup Bike Link**. |

### SolidWorks Sync Messages

| Message | Cause | What to do |
|---|---|---|
| "Cannot set data to model." | There is no document the add-in can write to. | Open the part, make it the active window, and sync again. |
| "Unable to retrieve data" or "Unable to retrieve change data" | The connection dropped, or the link was removed in the web app. | Try again. If it keeps failing, generate a new password and run **Setup Bike Link**. |
| "Variables are missing. Please sync all data before attempting an update." | **Sync Changes** ran in a part that does not have all the variables. | Run **Sync All Variables** once. |
| "Size configurations need to be added. Please exit the sketch and sync again." | A per-size sync needs new configurations, and a sketch is open. | Close the sketch and sync again. |
| "3 values could not be written. This usually means the syn_ variables were created before size configurations were turned on." | The variables were created for a single size. | Delete all `syn_` variables in **Tools > Equations** and run **Sync All Variables**. |

### SolidWorks Drawing Messages

| Message | Cause | What to do |
|---|---|---|
| "Draw Linkage Points works in a part document. Open or switch to a part and run it again." | The active document is an assembly or drawing. | Switch to a part. |
| "This part's length unit is not millimetres." | A warning: the command carries on, and the points are drawn at the wrong scale. | Set the part's units to millimeters under **Tools > Options > Document Properties > Units**. |
| "syn_x_offset must be a plain number of millimetres, ..." | The offset variable holds an expression or a unit. The same message can name `syn_y_offset`. | In **Tools > Equations**, set it to a number, for example `"syn_x_offset" = 500`. |
| "syn_x_offset must be greater than 0 mm (it is 0 mm)." | The offset is zero or negative. The same message can name `syn_y_offset`. | Set it to a positive number. |
| "Some points sit beyond the offset datum, so their dimensions would be negative. Nothing was drawn." | A point is further behind or below the origin than the offsets allow. The message names the point and the value to exceed. | Raise `syn_x_offset` or `syn_y_offset` in **Tools > Equations**, then run the command again. |

Any other failure appears as "Something went wrong running that command:" followed by the detail from SolidWorks. Run the command again, and if it repeats, [send us](https://syn.bike/contact) `solidworks-sync.log`.
