# Dynamo
Speckle currently supports Dynamo versions from 2.1 to 2.8 for Autodesk Revit 2019, 2020 and 2021, as well versions of Dynamo Sandbox from 2.1 to 2.8 are supported.
# Getting Started
To install this connector and add your Speckle account proceed by following the instructions in Speckle Manager.
Once installed, the Dynamo Connector will appear under the Speckle 2
and Speckle 2 Dev Tools
tabs.
The Speckle 2
tab contains the main nodes necessary to operate with Speckle, including send/receive nodes, streams and accounts.
The Speckle 2 Dev Tools
tabs contain nodes for more advanced use-cases, as well as some handy tools for Speckle developers/hackers.
# Streams and URLs
In visual programming environments, Speckle Streams are now identified by their URLs (instead of their IDs). Across our Dynamo and Grasshopper connectors you'll see URLs in 3 different formats:
https://speckle.xyz/streams/3073b96e86
points to themain
branch on Stream3073b96e86
https://speckle.xyz/streams/3073b96e86/branches/dev
points to a branch nameddev
on Stream3073b96e86
https://speckle.xyz/streams/3073b96e86/commits/604bea8cc6
points to a specific commit604bea8cc6
on Stream3073b96e86
https://speckle.xyz/streams/3073b96e86/objects/df7b8bafccefa791d82939dd36541189
points to a specific objectdf7b8bafccefa791d82939dd36541189
on Stream3073b96e86
TIP
Unsure about what commits and branches are? No worries, you don't need to know what they are to use Speckle! But if you're curios, you can read about them in concepts.
We'll see how branch and commit URLs are used in the following sections.
# Sending Data
Let's look at how we would send some data in Dynamo. First, start by creating a new Send
node.
In order to select which stream to send data to, you just need to pass a stream URL to the stream
port.
Alternatively, you can also use one of the following nodes to create / retrieve existing streams:
NOTE
You cannot send data to a specific commit. Commits represent your stream in a specific point in time and cannot be edited.
# Adding objects
In order to select which objects to send in Dynamo, we just need to connect the desired node to the data
input in the Send
node. The sender will convert any supported Dynamo objects into a Speckle compatible format when necessary.
# Adding a commit message
It's good practice to add a "commit message" whenever you send you data, especially if working with others, this message should describe the changes being pushed.
You can add a commit message by passing some text to the message
port.
The commit message will be visible in Speckle Web where you will also be allowed to edit it.
# Sending
The only thing left to do is to press the Send button.
To view the data you just sent from Dynamo online, you can use the View Online
node. Just plug in the stream
, branch
or commit
URL and click the button.
TIP
The View Online node is especially useful as data cannot be easily copy/pasted from dynamo nodes
# Viewing a Stream online
To view the sent stream online you can just right click on the sender node:
# Sending to a specific branch
When using a stream URL, by default, the main
branch is used to send and receive data.
To send to a specific branch, simply use the branch URL, ie: https://speckle.xyz/streams/3073b96e86/branches/dev
.
# Receiving Data
Receiving data is very simple, you just need a Receive
node, and a stream URL.
When new data is pushed to this stream a notification will appear on the receive node.
# Auto Receiving
By using the toggle on the node, you can enable/disable auto receiving. If enabled, new data pushed to this stream will be pulled automatically as it's available.
# Receiving a specific branch
As mentioned earlier, when using a stream URL, by default, the main
branch is used to send and receive data.
To receive from a specific branch, simply use the branch URL, ie: https://speckle.xyz/streams/3073b96e86/branches/dev
.
# Receiving a specific commit
There are circumstances in which you will not want to always receive "new" data, but you'll instead want to only get a specific commit. To do so simply use the commit URL, ie: https://speckle.xyz/streams/3073b96e86/commits/604bea8cc6
NOTE
When receiving from a commit, the node will stop showing notifications about new activity on such stream and the auto receive toggle will be disabled.
# Receiving a specific object
Similarly to commits, you can also point the receive node to a specific object, to do so simply use the commit URL, ie: https://speckle.xyz/streams/3073b96e86/objects/df7b8bafccefa791d82939dd36541189
. Objects are immutable, so the data received using such a URL will always be consistent.
You can find the ID of an object from the Speckle Web interface:
# Viewing a Stream online
To view the received stream online you can just right click on the receiver node:
# Creating custom objects
A custom object is a Base Object with custom properties assigned to it. It's basically a custom data structure you can create to send data in a specific format that you define.
In Dynamo, we use dictionaries to represent custom objects since they are natively supported, so creating custom objects is as simple as creating a dictionary containing the keys and values you wish to include in the Base
object.
This dictionary will be automatically converted to a Base
object during the Send operation.
TIP
Learn more about the Speckle Base
object here 👈
# Nodes
# Send node
The Send node performs sending operations, usually to a Speckle Server, but also supports sending to a different data storage using transports. Whenever possible, the Send node wil try to convert any compatible objects into Speckle format.
There is also an switch you can toggle to enable the node to send automatically the data whenever it changes.
# Input
- Data: This port will accept almost anything you give it. If the objects provided are not
Base
objects, it will also perform the conversion to Speckle automatically. - Stream: Supports any generated stream from within the
Stream
component category, but also stream urls in text format. - Message: The message you want to attach to the commit when you send the data. Defaults to
"Dynamo push"
.
# Output
- Stream: The commit url pointing to the objects in the Speckle server.
# Receive node
The Receive node fetches data from a specified Stream
or any other valid Transport
. Whenever possible, the receiver node will try to convert all Speckle objects into compatible objects.
# Inputs
- Stream: Supports any generated stream from within the
Stream
component category, but also stream urls in text format.
# Outputs
- Data: The data that was received from the stream.
# Local Send node
The Local Send node performs sending operations directly to the users's local database.
# Inputs
- Data: The data to be sent locally. This port will accept almost anything you give it. If the objects provided are not
Base
objects, it will also perform the conversion to Speckle automatically.
# Outputs
- localDataId: The unique
id
for the data that was locally sent.
# Local receive node
The Local Receive node performs receive operations in the same way as the Receive node, the only difference is that data is received locally from the Speckle's user local database, instead of the server or any other transport.
# Inputs
- localDataId: The unique
id
for the data you want to fetch locally. This would be provided from a Local Send node
# Outputs
- Data: The data thas was received. This port will accept almost anything you give it. If the objects provided are not
Base
objects, it will also perform the conversion to Speckle automatically.
# Accounts node
The Accounts node provides a fast way of selecting different Speckle accounts.
Accounts must be set-up in your computer using the Speckle Manager. If no accounts are shown after setting up the solution
# Create stream
To create a new stream, right-click on the canvas and search for the Stream Create
node. This node has a custom UI that allows you to select a specific account to use, and a button to confirm the stream creation.
TIP
You can always, also create streams online form Speckle Web. From there you can also set their name, description and permissions.
Once created, the node will remember that stream. Meaning you will not be able to change the stream you created, or create a new one using the same node (just create a new Stream Create
node).
Select the appropriate account and press the blue button. If the stream creation was successful, the output of the node should be a stream url pointing to the newly created stream and linked to the specified account.
# Viewing the Stream online
To view the newly created stream online you can just right click on the node:
# Inputs
This node has no inputs, as the account selection is done using it's custom UI.
# Ouputs
- stream: A
Stream
object pointing to the newly created stream.
# Get stream
The Stream Get node will try to find an existing Stream
, given it's unique id
(or its stream url
) and a specific account to access that stream with.
# Inputs
- stream: Supports any generated stream from within the
Stream
component category, but also stream urls in text format. - account: A Speckle account, provided by the Accounts node. If no account is provided, the default account will be used.
# Outputs
- stream: A
Stream
object pointing to existing stream. If the stream doesn't exist, an error will be shown.
# List streams
The List Streams node returns a specified ammount of streams available in an account. For performance reasons, it has been limited to fetching a maximum of 20 streams.
# Inputs
- account: A Speckle account, provided by the Accounts node. If no account is provided, the default account will be used.
- limit: The number of streams to fetch from the server.
# Outputs
- streams: List of
Stream
objects available to the specified account.
# Stream details
The Stream Details node returns all relevant information related to a specific Stream
.
# Inputs
- stream: Supports any generated stream from within the
Stream
component category, but also stream urls in text format.
# Output
- stream: The unique
id
that identifies the stream. - name: The name of the stream.
- description: The description of the stream.
- createdAt: The date this stream was created.
- updatedAt: The date marking the last time the stream was updated.
- public: Boolean value indicating if the stream has link sharing enabled.
- collaborators: A list of collaborators that have access to this stream, as well as their roles.
- branches: A list of available branches for this stream.
# Stream update
The Stream Update node allows for updating the name, description and link sharing (which will make your data publicly available to read by anyone with the stream url)
# Inputs
- stream: Supports any generated stream from within the
Stream
component category, but also stream urls in text format. - name (optional): Text string with the new name for the stream.
- description (optional): Text string with the new description for the stream.
- isPublic: Boolean value to activate/deactivate this stream's link sharing.
# Output
- stream: A
Stream
url pointing to the updated stream.
# Dev tools
These nodes where developed exclusively for testing/development purposes. If you don't know what these are, you most likely won't ever need them.
# Convert to Speckle node
The Convert to Speckle node will convert any supported objects (such as lines, curves, meshes...) into Speckle ones.
This node was developed for testing/development purposes, as the Send/Receive nodes will already perform this conversion step automatically.
# Convert to Native node
The Convert to Native node will convert any supported Speckle objects into compatible objects.
This node was developed for testing/development purposes.
# Serialize Speckle objects node
The Serialize objects node will convert any Speckle object into JSON
formatted text.
# Deserialize Speckle objects node
The Deserialize objects node will convert a serialized speckle object in json format into Base
speckle objects.
# Server Transport
Creates a connection to a specific Speckle Server.
# SQLite Transport
Creates a connection to a specific SQLite database.
# Disk Transport
Creates a connection to a specific file in the computer's disk, where the data will be saved in JSON format.
# Memory Transport
Creates a connection to in-memory storage.
# Supported elements
Geometry | Send | Receive | Status |
---|---|---|---|
Point | x | x | Complete |
Line | x | x | Complete |
Plane | x | x | Complete |
Arc | x | x | Complete |
Circle | x | x | Complete |
Cuboid | As Box | x | Complete |
Ellipse | x | x | Complete |
Helix | As Spline | Complete | |
Polyline | As Rectangle, Polycurve, or Polygon | Complete | |
Polycurve | x | x | Complete |
Polygon | As Polyline | x | Complete |
Rectangle | As Polyline | x | Complete |
Spline | x | x | Complete |
Brep | x | x | Complete |
Mesh | x | x | Complete |
# Unsupported elements
Any geometric element not listed above are not supported.
← Grasshopper Unity →